iron_admin 0.7.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +129 -1
- data/README.md +48 -1
- data/UPGRADING.md +495 -8
- data/app/assets/tailwind/iron_admin/engine.css +79 -4
- data/app/components/iron_admin/dashboards/activity_feed_component/item_component.html.haml +6 -9
- data/app/components/iron_admin/dashboards/activity_feed_component.html.haml +6 -5
- data/app/components/iron_admin/dashboards/activity_feed_component.rb +21 -24
- data/app/components/iron_admin/dashboards/chart_component.html.haml +3 -5
- data/app/components/iron_admin/dashboards/chart_component.rb +86 -24
- data/app/components/iron_admin/dashboards/concerns/themed_card.rb +39 -0
- data/app/components/iron_admin/dashboards/metric_card_component.html.haml +8 -7
- data/app/components/iron_admin/dashboards/metric_card_component.rb +2 -0
- data/app/components/iron_admin/dashboards/progress_component.html.haml +11 -7
- data/app/components/iron_admin/dashboards/progress_component.rb +11 -6
- data/app/components/iron_admin/dashboards/quick_links_component/link_component.html.haml +8 -9
- data/app/components/iron_admin/dashboards/quick_links_component.html.haml +6 -5
- data/app/components/iron_admin/dashboards/quick_links_component.rb +4 -12
- data/app/components/iron_admin/dashboards/recent_table_component.html.haml +15 -10
- data/app/components/iron_admin/dashboards/recent_table_component.rb +49 -0
- data/app/components/iron_admin/dashboards/stats_grid_component/stat_component.html.haml +13 -14
- data/app/components/iron_admin/dashboards/stats_grid_component.html.haml +1 -0
- data/app/components/iron_admin/dashboards/stats_grid_component.rb +9 -11
- data/app/components/iron_admin/filters/bar_component.html.haml +8 -6
- data/app/components/iron_admin/filters/bar_component.rb +56 -9
- data/app/components/iron_admin/filters/control_styles.rb +82 -0
- data/app/components/iron_admin/filters/date_range_component.html.haml +9 -4
- data/app/components/iron_admin/filters/date_range_component.rb +10 -6
- data/app/components/iron_admin/filters/search_component.html.haml +4 -4
- data/app/components/iron_admin/filters/search_component.rb +3 -5
- data/app/components/iron_admin/filters/select_filter_component.html.haml +1 -1
- data/app/components/iron_admin/filters/select_filter_component.rb +5 -16
- data/app/components/iron_admin/form/belongs_to_autocomplete_component.html.haml +9 -5
- data/app/components/iron_admin/form/belongs_to_autocomplete_component.rb +10 -8
- data/app/components/iron_admin/form/belongs_to_component.html.haml +2 -2
- data/app/components/iron_admin/form/belongs_to_component.rb +4 -18
- data/app/components/iron_admin/form/checkbox_component.rb +2 -3
- data/app/components/iron_admin/form/concerns/form_input_behavior.rb +1 -1
- data/app/components/iron_admin/form/control_classes.rb +108 -0
- data/app/components/iron_admin/form/date_picker_component.rb +3 -7
- data/app/components/iron_admin/form/field_wrapper_component.html.haml +3 -3
- data/app/components/iron_admin/form/field_wrapper_component.rb +3 -3
- data/app/components/iron_admin/form/nested_form_component.html.haml +4 -5
- data/app/components/iron_admin/form/nested_form_component.rb +12 -2
- data/app/components/iron_admin/form/select_component.html.haml +1 -1
- data/app/components/iron_admin/form/select_component.rb +2 -16
- data/app/components/iron_admin/form/text_input_component.rb +1 -5
- data/app/components/iron_admin/form/textarea_component.rb +1 -5
- data/app/components/iron_admin/layout/flash_component.html.haml +1 -1
- data/app/components/iron_admin/layout/flash_component.rb +4 -3
- data/app/components/iron_admin/layout/navbar_component.html.haml +15 -9
- data/app/components/iron_admin/layout/navbar_component.rb +29 -1
- data/app/components/iron_admin/layout/shell_component.html.haml +4 -4
- data/app/components/iron_admin/layout/shell_component.rb +16 -3
- data/app/components/iron_admin/layout/sidebar_component.html.haml +21 -25
- data/app/components/iron_admin/layout/sidebar_component.rb +76 -1
- data/app/components/iron_admin/layout/theme_switcher_component.html.haml +15 -0
- data/app/components/iron_admin/layout/theme_switcher_component.rb +74 -0
- data/app/components/iron_admin/resources/actions_component.html.haml +15 -8
- data/app/components/iron_admin/resources/actions_component.rb +34 -2
- data/app/components/iron_admin/resources/breadcrumb_component.html.haml +3 -3
- data/app/components/iron_admin/resources/breadcrumb_component.rb +8 -7
- data/app/components/iron_admin/resources/bulk_actions_component.html.haml +9 -8
- data/app/components/iron_admin/resources/bulk_actions_component.rb +47 -4
- data/app/components/iron_admin/resources/data_table_component.html.haml +15 -15
- data/app/components/iron_admin/resources/data_table_component.rb +34 -3
- data/app/components/iron_admin/resources/related_list_component.html.haml +7 -7
- data/app/components/iron_admin/resources/related_list_component.rb +26 -2
- data/app/components/iron_admin/resources/show_field_component.html.haml +3 -3
- data/app/components/iron_admin/resources/show_field_component.rb +10 -4
- data/app/components/iron_admin/resources/styles.rb +136 -0
- data/app/components/iron_admin/ui/alert_component.html.haml +2 -2
- data/app/components/iron_admin/ui/alert_component.rb +27 -31
- data/app/components/iron_admin/ui/badge_component.rb +40 -20
- data/app/components/iron_admin/ui/button_component.rb +37 -11
- data/app/components/iron_admin/ui/card_component.rb +3 -3
- data/app/components/iron_admin/ui/dropdown_component.html.haml +1 -1
- data/app/components/iron_admin/ui/dropdown_component.rb +34 -13
- data/app/components/iron_admin/ui/empty_state_component.html.haml +4 -5
- data/app/components/iron_admin/ui/empty_state_component.rb +2 -2
- data/app/components/iron_admin/ui/modal_component.html.haml +5 -5
- data/app/components/iron_admin/ui/modal_component.rb +6 -4
- data/app/components/iron_admin/ui/pagination_component.html.haml +14 -14
- data/app/components/iron_admin/ui/pagination_component.rb +26 -9
- data/app/components/iron_admin/ui/scopes_component.html.haml +2 -2
- data/app/components/iron_admin/ui/scopes_component.rb +44 -11
- data/app/components/iron_admin/ui/tooltip_component.rb +11 -4
- data/app/controllers/iron_admin/application_controller.rb +58 -4
- data/app/controllers/iron_admin/audit_controller.rb +30 -6
- data/app/controllers/iron_admin/concerns/action_executable.rb +37 -0
- data/app/controllers/iron_admin/concerns/assignable_references.rb +149 -0
- data/app/controllers/iron_admin/concerns/authorizable.rb +11 -0
- data/app/controllers/iron_admin/concerns/blank_password_filterable.rb +21 -0
- data/app/controllers/iron_admin/concerns/event_emittable.rb +47 -7
- data/app/controllers/iron_admin/concerns/filterable.rb +34 -9
- data/app/controllers/iron_admin/concerns/nested_permittable.rb +5 -3
- data/app/controllers/iron_admin/concerns/nested_tenant_check.rb +159 -0
- data/app/controllers/iron_admin/concerns/polymorphic_references.rb +131 -0
- data/app/controllers/iron_admin/concerns/scopeable.rb +54 -7
- data/app/controllers/iron_admin/concerns/searchable.rb +3 -3
- data/app/controllers/iron_admin/concerns/tenant_assignable.rb +118 -0
- data/app/controllers/iron_admin/concerns/tenant_containment.rb +146 -0
- data/app/controllers/iron_admin/exports_controller.rb +2 -2
- data/app/controllers/iron_admin/imports_controller.rb +1 -1
- data/app/controllers/iron_admin/resources_controller.rb +48 -41
- data/app/controllers/iron_admin/search_controller.rb +1 -2
- data/app/controllers/iron_admin/themes_controller.rb +50 -0
- data/app/controllers/iron_admin/tools_controller.rb +58 -5
- data/app/helpers/iron_admin/action_form_helper.rb +19 -0
- data/app/helpers/iron_admin/application_helper.rb +93 -16
- data/app/helpers/iron_admin/assignable_records_helper.rb +32 -0
- data/app/helpers/iron_admin/component_overrides_helper.rb +9 -4
- data/app/helpers/iron_admin/field_display_helper.rb +88 -43
- data/app/helpers/iron_admin/related_records_helper.rb +51 -0
- data/app/helpers/iron_admin/theme_helper.rb +56 -46
- data/app/javascript/iron_admin/controllers/cp_bulk_select_controller.js +12 -0
- data/app/javascript/iron_admin/controllers/cp_chart_controller.js +4 -0
- data/app/javascript/iron_admin/controllers/cp_disclosure_controller.js +19 -0
- data/app/javascript/iron_admin/controllers/cp_search_shortcut_controller.js +39 -0
- data/app/javascript/iron_admin/index.js +4 -0
- data/app/views/iron_admin/audit/index.html.haml +78 -81
- data/app/views/iron_admin/dashboard/index.html.haml +10 -9
- data/app/views/iron_admin/form/_action_field.html.haml +50 -0
- data/app/views/iron_admin/form/_nested_row.html.haml +18 -13
- data/app/views/iron_admin/imports/new.html.haml +14 -13
- data/app/views/iron_admin/imports/preview.html.haml +24 -21
- data/app/views/iron_admin/resources/_form.html.haml +70 -68
- data/app/views/iron_admin/resources/action_form.html.haml +16 -59
- data/app/views/iron_admin/resources/bulk_action_form.html.haml +20 -58
- data/app/views/iron_admin/resources/edit.html.haml +3 -3
- data/app/views/iron_admin/resources/index.html.haml +87 -74
- data/app/views/iron_admin/resources/new.html.haml +2 -2
- data/app/views/iron_admin/resources/show.html.haml +53 -41
- data/app/views/iron_admin/search/index.html.haml +17 -9
- data/app/views/iron_admin/shared/_pagination.html.haml +13 -10
- data/app/views/iron_admin/shared/error.html.haml +16 -12
- data/app/views/iron_admin/tools/action_form.html.haml +9 -55
- data/app/views/iron_admin/tools/show.html.haml +4 -5
- data/app/views/layouts/iron_admin/_document_head.html.haml +24 -0
- data/app/views/layouts/iron_admin/application.html.haml +4 -17
- data/app/views/layouts/iron_admin/minimal.html.haml +7 -0
- data/config/importmap.rb +2 -0
- data/config/locales/en.yml +23 -0
- data/config/routes.rb +1 -0
- data/docs/FAQ.md +87 -37
- data/docs/README.md +8 -2
- data/docs/components/README.md +6 -2
- data/docs/components/dashboard-components.md +24 -35
- data/docs/components/filter-components.md +44 -92
- data/docs/components/form-components.md +16 -32
- data/docs/components/resource-components.md +46 -27
- data/docs/components/ui-components.md +44 -26
- data/docs/getting-started/installation.md +5 -1
- data/docs/getting-started/quick-start.md +36 -23
- data/docs/guides/authentication.md +182 -42
- data/docs/guides/components.md +97 -15
- data/docs/guides/custom-adapters.md +24 -4
- data/docs/guides/dashboard.md +68 -44
- data/docs/guides/export.md +24 -8
- data/docs/guides/extending.md +206 -51
- data/docs/guides/fields.md +229 -70
- data/docs/guides/imports.md +33 -18
- data/docs/guides/resources.md +333 -111
- data/docs/guides/theming.md +930 -58
- data/docs/guides/troubleshooting.md +7 -3
- data/docs/plugin-system-design.md +8 -7
- data/docs/reference/configuration.md +51 -16
- data/docs/reference/routes.md +1 -0
- data/docs/reference/theme-properties.md +101 -38
- data/lib/generators/iron_admin/install/templates/initializer.rb.tt +7 -2
- data/lib/generators/iron_admin/install_audit/templates/create_iron_admin_audit_entries.rb.tt +2 -0
- data/lib/iron_admin/action_field.rb +11 -0
- data/lib/iron_admin/adapters/active_record.rb +95 -0
- data/lib/iron_admin/adapters/base.rb +107 -0
- data/lib/iron_admin/adapters/http/query.rb +21 -0
- data/lib/iron_admin/adapters/http.rb +84 -4
- data/lib/iron_admin/adapters/mongoid.rb +96 -2
- data/lib/iron_admin/audit_log.rb +64 -6
- data/lib/iron_admin/authentication_warning.rb +31 -0
- data/lib/iron_admin/concerns/filter_definable.rb +15 -1
- data/lib/iron_admin/concerns/nestable.rb +25 -0
- data/lib/iron_admin/concerns/scope_countable.rb +56 -0
- data/lib/iron_admin/concerns/soft_deletable.rb +28 -9
- data/lib/iron_admin/configuration/components.rb +14 -3
- data/lib/iron_admin/configuration/theme/neutral_defaults.rb +179 -0
- data/lib/iron_admin/configuration/theme.rb +292 -87
- data/lib/iron_admin/configuration.rb +340 -45
- data/lib/iron_admin/dashboard.rb +22 -38
- data/lib/iron_admin/engine.rb +16 -2
- data/lib/iron_admin/errors.rb +3 -0
- data/lib/iron_admin/field.rb +78 -17
- data/lib/iron_admin/field_inferrer.rb +61 -3
- data/lib/iron_admin/field_override_warning.rb +67 -0
- data/lib/iron_admin/import/import_preview.rb +56 -7
- data/lib/iron_admin/import/importer.rb +91 -14
- data/lib/iron_admin/import/tenant_precheck.rb +67 -0
- data/lib/iron_admin/plugin/registration.rb +64 -0
- data/lib/iron_admin/plugin_registry.rb +3 -2
- data/lib/iron_admin/policy.rb +22 -12
- data/lib/iron_admin/policy_coverage_warning.rb +46 -0
- data/lib/iron_admin/request_context.rb +18 -0
- data/lib/iron_admin/resource.rb +218 -77
- data/lib/iron_admin/resource_registry.rb +86 -13
- data/lib/iron_admin/scope_counts.rb +73 -0
- data/lib/iron_admin/tenant_scope.rb +30 -0
- data/lib/iron_admin/tool.rb +61 -12
- data/lib/iron_admin/tool_context.rb +10 -6
- data/lib/iron_admin/version.rb +1 -1
- data/lib/iron_admin.rb +29 -2
- metadata +37 -7
data/docs/guides/fields.md
CHANGED
|
@@ -20,17 +20,29 @@ IronAdmin automatically infers field types from your model's schema (ActiveRecor
|
|
|
20
20
|
## Overriding Fields
|
|
21
21
|
|
|
22
22
|
```ruby
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
23
|
+
module IronAdmin
|
|
24
|
+
module Resources
|
|
25
|
+
class UserResource < IronAdmin::Resource
|
|
26
|
+
field :status, type: :badge, colors: {
|
|
27
|
+
active: :green,
|
|
28
|
+
suspended: :red,
|
|
29
|
+
pending: :yellow
|
|
30
|
+
}
|
|
31
|
+
end
|
|
32
|
+
end
|
|
29
33
|
end
|
|
30
34
|
```
|
|
31
35
|
|
|
32
36
|
Overrides merge with inferred fields. You only need to specify the fields you want to change.
|
|
33
37
|
|
|
38
|
+
A `belongs_to` foreign key column is inferred as a field named after the association (`organization`, not `organization_id`). An override under either name applies to it; when both exist, the association name wins:
|
|
39
|
+
|
|
40
|
+
```ruby
|
|
41
|
+
field :organization_id, readonly: ->(user) { !user&.admin? } # same as field :organization, readonly: ...
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
In development and test, IronAdmin logs a warning at boot for each `field` name that matches no field, since its options are ignored.
|
|
45
|
+
|
|
34
46
|
## Field Properties
|
|
35
47
|
|
|
36
48
|
| Property | Type | Description |
|
|
@@ -43,9 +55,13 @@ Overrides merge with inferred fields. You only need to specify the fields you wa
|
|
|
43
55
|
## Dynamic Visibility and Readonly
|
|
44
56
|
|
|
45
57
|
```ruby
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
58
|
+
module IronAdmin
|
|
59
|
+
module Resources
|
|
60
|
+
class SalaryResource < IronAdmin::Resource
|
|
61
|
+
field :amount, visible: ->(user) { user.admin? || user.hr? }
|
|
62
|
+
field :department, readonly: ->(user) { !user.admin? }
|
|
63
|
+
end
|
|
64
|
+
end
|
|
49
65
|
end
|
|
50
66
|
```
|
|
51
67
|
|
|
@@ -55,44 +71,66 @@ Visibility and readonly rules are enforced across:
|
|
|
55
71
|
- Form fields (readonly fields are not rendered, and values submitted for them are not assigned on create or update; the `<name>_purge` remove-file parameter of a readonly `:file` field is still honored)
|
|
56
72
|
- CSV/JSON exports
|
|
57
73
|
- Search queries
|
|
74
|
+
- Sorting (`?sort=` on a field the user cannot see falls back to the default column)
|
|
75
|
+
- Nested attributes (a hidden field of a nested association is not permitted)
|
|
76
|
+
- Audit changes (a hidden field's values are logged as `[FILTERED]`)
|
|
77
|
+
- Auto-inferred filters
|
|
58
78
|
|
|
59
|
-
|
|
79
|
+
An override keeps the inferred visibility and readonly rule unless it sets them: `field :encrypted_password, label: "Hash"` stays hidden.
|
|
80
|
+
|
|
81
|
+
### Credential Columns
|
|
60
82
|
|
|
61
|
-
|
|
83
|
+
Columns that store credentials are inferred hidden and read-only, so their values are not shown, searched, exported, sorted or editable: `encrypted_password`, `password_digest`, `reset_password_token`, `confirmation_token`, `unlock_token`, `remember_token`, `invitation_token`, `authentication_token`, `otp_secret`, `encrypted_otp_secret`, `encrypted_otp_secret_iv`, `encrypted_otp_secret_salt`, `otp_backup_codes`, and any `*_password_digest` column (`IronAdmin::FieldInferrer::CREDENTIAL_COLUMNS` and `CREDENTIAL_PATTERN`). Other names, such as `variation_digest` or `api_token_expires_at`, are inferred as usual.
|
|
62
84
|
|
|
63
|
-
|
|
85
|
+
To show one, set `visible: true`. It stays read-only unless you also set `readonly: false`:
|
|
64
86
|
|
|
65
87
|
```ruby
|
|
66
|
-
IronAdmin
|
|
67
|
-
|
|
88
|
+
module IronAdmin
|
|
89
|
+
module Resources
|
|
90
|
+
class UserResource < IronAdmin::Resource
|
|
91
|
+
field :confirmation_token, visible: ->(user) { user&.admin? }
|
|
92
|
+
end
|
|
93
|
+
end
|
|
68
94
|
end
|
|
69
95
|
```
|
|
70
96
|
|
|
97
|
+
## Badge Colors
|
|
98
|
+
|
|
99
|
+
A `:badge` field shows its value as a badge. The color of a value comes from, in this order:
|
|
100
|
+
the field's `colors:` option, `config.badge_colors`, and else `:gray`. The classes of each color
|
|
101
|
+
come from the current theme's `badge_palette`, with a dot from `badge_dot_palette` (see
|
|
102
|
+
[Badges, alerts and chips](theming.md#badges-alerts-and-chips)). Its color names are `:green`,
|
|
103
|
+
`:red`, `:yellow`, `:blue`, `:indigo`, `:purple`, `:pink`, `:orange`, `:teal` and `:gray`.
|
|
104
|
+
|
|
71
105
|
### Default Badge Colors for Common Status Values
|
|
72
106
|
|
|
73
|
-
IronAdmin
|
|
107
|
+
IronAdmin assigns colors to common status values without configuration
|
|
108
|
+
(`IronAdmin::Configuration::DEFAULT_BADGE_COLORS`):
|
|
74
109
|
|
|
75
110
|
| Status Value | Color |
|
|
76
111
|
|--------------|-------|
|
|
77
|
-
| `active`, `
|
|
78
|
-
| `pending
|
|
79
|
-
| `
|
|
80
|
-
| `failed`, `error`, `rejected`, `
|
|
81
|
-
| `inactive`, `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `guest`, `visitor` | Gray |
|
|
112
|
+
| `active`, `enabled`, `completed`, `done`, `success`, `approved`, `accepted`, `published` | Green |
|
|
113
|
+
| `pending` | Yellow |
|
|
114
|
+
| `processing`, `in_progress` | Blue |
|
|
115
|
+
| `failed`, `error`, `cancelled`, `canceled`, `rejected`, `declined`, `expired`, `suspended`, `blocked` | Red |
|
|
116
|
+
| `inactive`, `disabled`, `unpublished`, `draft`, `archived` | Gray |
|
|
117
|
+
| `true`, `"true"`, `"yes"` | Green |
|
|
118
|
+
| `false`, `"false"`, `"no"` | Red |
|
|
85
119
|
|
|
86
120
|
Example:
|
|
87
121
|
|
|
88
122
|
```ruby
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
123
|
+
module IronAdmin
|
|
124
|
+
module Resources
|
|
125
|
+
class OrderResource < IronAdmin::Resource
|
|
126
|
+
# No colors needed - auto-detected from value
|
|
127
|
+
field :status, type: :badge
|
|
128
|
+
end
|
|
129
|
+
end
|
|
92
130
|
end
|
|
93
131
|
|
|
94
132
|
# Order with status "pending" will show a yellow badge
|
|
95
|
-
# Order with status "completed" will show a
|
|
133
|
+
# Order with status "completed" will show a green badge
|
|
96
134
|
```
|
|
97
135
|
|
|
98
136
|
Override auto-detected colors by providing explicit colors:
|
|
@@ -100,10 +138,36 @@ Override auto-detected colors by providing explicit colors:
|
|
|
100
138
|
```ruby
|
|
101
139
|
field :status, type: :badge, colors: {
|
|
102
140
|
pending: :orange, # Override default yellow
|
|
103
|
-
completed: :
|
|
141
|
+
completed: :blue # Override default green
|
|
104
142
|
}
|
|
105
143
|
```
|
|
106
144
|
|
|
145
|
+
Map more values for every badge field with `config.badge_colors` (add entries; assigning a new
|
|
146
|
+
Hash replaces the defaults):
|
|
147
|
+
|
|
148
|
+
```ruby
|
|
149
|
+
IronAdmin.configure do |config|
|
|
150
|
+
config.badge_colors["on_hold"] = "orange"
|
|
151
|
+
end
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
To add a color, such as `field :tier, type: :badge, colors: { vip: :cyan }`, add it to the
|
|
155
|
+
theme's `badge_palette` and `badge_dot_palette`. Each theme has its own palettes, so a dark
|
|
156
|
+
theme can give the color its own classes:
|
|
157
|
+
|
|
158
|
+
```ruby
|
|
159
|
+
IronAdmin.configure do |config|
|
|
160
|
+
config.theme do |t|
|
|
161
|
+
t.badge_palette[:cyan] = "bg-cyan-50 text-cyan-700 ring-1 ring-inset ring-cyan-600/20"
|
|
162
|
+
t.badge_dot_palette[:cyan] = "bg-cyan-500"
|
|
163
|
+
end
|
|
164
|
+
end
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
An entry in `config.badge_colors` that maps a color name Symbol to classes, such as
|
|
168
|
+
`config.badge_colors[:cyan] = "bg-cyan-100 text-cyan-800"`, also defines a color. It wins over
|
|
169
|
+
the palettes, uses the same classes in every theme, and its badges have no dot.
|
|
170
|
+
|
|
107
171
|
## Name-Convention Fields
|
|
108
172
|
|
|
109
173
|
IronAdmin auto-infers certain field types based on column naming patterns:
|
|
@@ -149,8 +213,12 @@ class User < ApplicationRecord
|
|
|
149
213
|
has_one_attached :avatar
|
|
150
214
|
end
|
|
151
215
|
|
|
152
|
-
|
|
153
|
-
|
|
216
|
+
module IronAdmin
|
|
217
|
+
module Resources
|
|
218
|
+
class UserResource < IronAdmin::Resource
|
|
219
|
+
field :avatar, type: :file
|
|
220
|
+
end
|
|
221
|
+
end
|
|
154
222
|
end
|
|
155
223
|
```
|
|
156
224
|
|
|
@@ -165,8 +233,12 @@ class Product < ApplicationRecord
|
|
|
165
233
|
has_many_attached :images
|
|
166
234
|
end
|
|
167
235
|
|
|
168
|
-
|
|
169
|
-
|
|
236
|
+
module IronAdmin
|
|
237
|
+
module Resources
|
|
238
|
+
class ProductResource < IronAdmin::Resource
|
|
239
|
+
field :images, type: :files
|
|
240
|
+
end
|
|
241
|
+
end
|
|
170
242
|
end
|
|
171
243
|
```
|
|
172
244
|
|
|
@@ -181,18 +253,26 @@ class Article < ApplicationRecord
|
|
|
181
253
|
has_rich_text :body
|
|
182
254
|
end
|
|
183
255
|
|
|
184
|
-
|
|
185
|
-
|
|
256
|
+
module IronAdmin
|
|
257
|
+
module Resources
|
|
258
|
+
class ArticleResource < IronAdmin::Resource
|
|
259
|
+
field :body, type: :rich_text
|
|
260
|
+
end
|
|
261
|
+
end
|
|
186
262
|
end
|
|
187
263
|
```
|
|
188
264
|
|
|
189
|
-
On forms, a Trix WYSIWYG editor is rendered. On show pages, the rich text content is displayed with HTML formatting.
|
|
265
|
+
On forms, a Trix WYSIWYG editor is rendered. On show pages, the rich text content is displayed with HTML formatting. On index pages and dashboard recent tables it is shown as plain text, truncated like long text fields (see [Index Text Truncation](#index-text-truncation)): no HTML from the content is rendered, and attachments appear as their caption or `[filename]`.
|
|
190
266
|
|
|
191
267
|
## Password Field
|
|
192
268
|
|
|
193
269
|
```ruby
|
|
194
|
-
|
|
195
|
-
|
|
270
|
+
module IronAdmin
|
|
271
|
+
module Resources
|
|
272
|
+
class UserResource < IronAdmin::Resource
|
|
273
|
+
field :password, type: :password
|
|
274
|
+
end
|
|
275
|
+
end
|
|
196
276
|
end
|
|
197
277
|
```
|
|
198
278
|
|
|
@@ -201,8 +281,12 @@ Renders a password input with masking on forms. Leaving it blank on an edit form
|
|
|
201
281
|
## Tags Field
|
|
202
282
|
|
|
203
283
|
```ruby
|
|
204
|
-
|
|
205
|
-
|
|
284
|
+
module IronAdmin
|
|
285
|
+
module Resources
|
|
286
|
+
class ArticleResource < IronAdmin::Resource
|
|
287
|
+
field :tags, type: :tags
|
|
288
|
+
end
|
|
289
|
+
end
|
|
206
290
|
end
|
|
207
291
|
```
|
|
208
292
|
|
|
@@ -211,18 +295,26 @@ On forms, renders a tag input where users can type and press Enter to add tags,
|
|
|
211
295
|
## Markdown Field
|
|
212
296
|
|
|
213
297
|
```ruby
|
|
214
|
-
|
|
215
|
-
|
|
298
|
+
module IronAdmin
|
|
299
|
+
module Resources
|
|
300
|
+
class PostResource < IronAdmin::Resource
|
|
301
|
+
field :body, type: :markdown
|
|
302
|
+
end
|
|
303
|
+
end
|
|
216
304
|
end
|
|
217
305
|
```
|
|
218
306
|
|
|
219
|
-
Renders a monospace text area on forms with a markdown placeholder. On show pages, the raw markdown content
|
|
307
|
+
Renders a monospace text area on forms with a markdown placeholder. On show pages, the content is rendered as HTML with [Redcarpet](https://github.com/vmg/redcarpet) when the app bundles it (raw HTML in the markdown is filtered out), and shown as plain text otherwise. Rendered markdown and rich text use Trix's content styles (`trix-content`) for headings, lists, quotes and code when the app loads Action Text.
|
|
220
308
|
|
|
221
309
|
## Color Field
|
|
222
310
|
|
|
223
311
|
```ruby
|
|
224
|
-
|
|
225
|
-
|
|
312
|
+
module IronAdmin
|
|
313
|
+
module Resources
|
|
314
|
+
class ThemeResource < IronAdmin::Resource
|
|
315
|
+
field :primary_color, type: :color
|
|
316
|
+
end
|
|
317
|
+
end
|
|
226
318
|
end
|
|
227
319
|
```
|
|
228
320
|
|
|
@@ -238,10 +330,14 @@ For columns that store other CSS color formats (names such as `red`, `rgb(...)`,
|
|
|
238
330
|
## Currency Field
|
|
239
331
|
|
|
240
332
|
```ruby
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
333
|
+
module IronAdmin
|
|
334
|
+
module Resources
|
|
335
|
+
class ProductResource < IronAdmin::Resource
|
|
336
|
+
field :price, type: :currency
|
|
337
|
+
# Or with a custom symbol:
|
|
338
|
+
field :price, type: :currency, symbol: "EUR"
|
|
339
|
+
end
|
|
340
|
+
end
|
|
245
341
|
end
|
|
246
342
|
```
|
|
247
343
|
|
|
@@ -250,8 +346,12 @@ On show and index pages, displays the value formatted with a currency symbol pre
|
|
|
250
346
|
## Boolean Field
|
|
251
347
|
|
|
252
348
|
```ruby
|
|
253
|
-
|
|
254
|
-
|
|
349
|
+
module IronAdmin
|
|
350
|
+
module Resources
|
|
351
|
+
class UserResource < IronAdmin::Resource
|
|
352
|
+
field :active, type: :boolean
|
|
353
|
+
end
|
|
354
|
+
end
|
|
255
355
|
end
|
|
256
356
|
```
|
|
257
357
|
|
|
@@ -260,17 +360,21 @@ Boolean fields are auto-inferred from boolean database columns. On show and inde
|
|
|
260
360
|
## Date and DateTime Fields
|
|
261
361
|
|
|
262
362
|
```ruby
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
363
|
+
module IronAdmin
|
|
364
|
+
module Resources
|
|
365
|
+
class EventResource < IronAdmin::Resource
|
|
366
|
+
field :start_date, type: :date
|
|
367
|
+
field :starts_at, type: :datetime
|
|
368
|
+
end
|
|
369
|
+
end
|
|
266
370
|
end
|
|
267
371
|
```
|
|
268
372
|
|
|
269
|
-
Date and datetime fields are auto-inferred from their database column types. On show and index pages,
|
|
373
|
+
Date and datetime fields are auto-inferred from their database column types. On show and index pages, a date uses the field's `format:` or `"%b %d, %Y"` (`Jan 15, 2026`). A datetime uses `format:` or `"%b %d, %Y at %l:%M %p"`, then squeezes the extra space (`Jan 15, 2026 at 2:05 PM`). `format:` is a strftime string. A Proc is not called: a datetime raises `NoMethodError`, and a `Date` raises `TypeError`. Other field types ignore `format:`. The import preview uses `format:` only when it is a String.
|
|
270
374
|
|
|
271
375
|
## Index Text Truncation
|
|
272
376
|
|
|
273
|
-
On index pages, `:text` and `:textarea` fields that exceed 50 characters are automatically truncated with an ellipsis. The full text is available via a tooltip on hover.
|
|
377
|
+
On index pages, `:text` and `:textarea` fields that exceed 50 characters are automatically truncated with an ellipsis. The full text is available via a tooltip on hover. `:rich_text` fields are reduced to their plain text first, then truncated the same way.
|
|
274
378
|
|
|
275
379
|
## Polymorphic Belongs To
|
|
276
380
|
|
|
@@ -281,8 +385,12 @@ class Comment < ApplicationRecord
|
|
|
281
385
|
belongs_to :commentable, polymorphic: true
|
|
282
386
|
end
|
|
283
387
|
|
|
284
|
-
|
|
285
|
-
|
|
388
|
+
module IronAdmin
|
|
389
|
+
module Resources
|
|
390
|
+
class CommentResource < IronAdmin::Resource
|
|
391
|
+
belongs_to :commentable, polymorphic: true, types: [Article, Photo, Video]
|
|
392
|
+
end
|
|
393
|
+
end
|
|
286
394
|
end
|
|
287
395
|
```
|
|
288
396
|
|
|
@@ -290,34 +398,85 @@ On forms, a type selector dropdown and an ID selector are rendered. On show and
|
|
|
290
398
|
|
|
291
399
|
## Custom Field Types (FieldTypeRegistry)
|
|
292
400
|
|
|
293
|
-
You can register custom field types using the `FieldTypeRegistry` API
|
|
401
|
+
You can register custom field types using the `FieldTypeRegistry` API. The form
|
|
402
|
+
input is a String on `config.components.fields`. IronAdmin constantizes that String
|
|
403
|
+
when the form renders, so a reload is picked up on the next request. See
|
|
404
|
+
[Field input overrides](components.md#field-input-overrides). The override wins over
|
|
405
|
+
`form_component` and does not change show or index pages.
|
|
406
|
+
|
|
407
|
+
Register `display` and `index_display` once. Those blocks must not call a constant
|
|
408
|
+
Zeitwerk can reload. The registry raises `ArgumentError`
|
|
409
|
+
(`Field type :star_rating is already registered`) on a second `register`.
|
|
410
|
+
|
|
411
|
+
`form_component` is the wrong place for this class. Rails 8 does not autoload
|
|
412
|
+
constants while initializers run, so naming `MyApp::StarRatingComponent` there
|
|
413
|
+
raises `NameError` (`uninitialized constant MyApp`) at boot. `form_component`
|
|
414
|
+
stores the class: a String has no `new`, and a class captured at boot goes stale
|
|
415
|
+
after a reload as soon as it calls a sibling constant.
|
|
294
416
|
|
|
295
417
|
```ruby
|
|
296
|
-
|
|
418
|
+
# config/initializers/iron_admin.rb
|
|
419
|
+
IronAdmin.configure do |config|
|
|
420
|
+
config.components.fields[:star_rating] = "MyApp::StarRatingComponent"
|
|
421
|
+
end
|
|
422
|
+
|
|
423
|
+
IronAdmin.register_field_type(:star_rating) do
|
|
297
424
|
display do |record, field|
|
|
298
425
|
value = record.public_send(field.name)
|
|
299
|
-
value.to_i.times.map { "★" }.join.html_safe
|
|
426
|
+
value.to_i.clamp(0, 5).times.map { "★" }.join.html_safe
|
|
300
427
|
end
|
|
301
428
|
|
|
302
429
|
index_display do |record, field|
|
|
303
|
-
|
|
304
|
-
"#{value}/5"
|
|
430
|
+
"#{record.public_send(field.name)}/5"
|
|
305
431
|
end
|
|
432
|
+
end
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
The display block draws one character per unit of the stored value and does not
|
|
436
|
+
stop. Clamp it. The input's `max` is checked only by the browser. Reject a value
|
|
437
|
+
outside the scale on the model: `validates :rating, inclusion: { in: 1..5 }`.
|
|
306
438
|
|
|
307
|
-
|
|
308
|
-
|
|
439
|
+
The component takes `form:`, `field:` and `record:`. `StarScale` sits in the same
|
|
440
|
+
file. The String is constantized on each render, so the form uses the reloaded
|
|
441
|
+
component and that sibling.
|
|
309
442
|
|
|
310
|
-
|
|
311
|
-
|
|
443
|
+
```ruby
|
|
444
|
+
# app/components/my_app/star_rating_component.rb
|
|
445
|
+
module MyApp
|
|
446
|
+
module StarScale
|
|
447
|
+
def self.max
|
|
448
|
+
5
|
|
449
|
+
end
|
|
450
|
+
end
|
|
451
|
+
|
|
452
|
+
class StarRatingComponent < ViewComponent::Base
|
|
453
|
+
def initialize(form:, field:, record:)
|
|
454
|
+
super()
|
|
455
|
+
@form = form
|
|
456
|
+
@field = field
|
|
457
|
+
@record = record
|
|
458
|
+
end
|
|
459
|
+
|
|
460
|
+
def call
|
|
461
|
+
@form.number_field(@field.name, min: 1, max: StarScale.max)
|
|
462
|
+
end
|
|
463
|
+
end
|
|
312
464
|
end
|
|
313
465
|
```
|
|
314
466
|
|
|
315
|
-
|
|
467
|
+
A partial is the other form option: `form_partial "shared/star_rating_input"`.
|
|
468
|
+
|
|
469
|
+
Then use the type in a resource:
|
|
316
470
|
|
|
317
471
|
```ruby
|
|
318
|
-
|
|
319
|
-
|
|
472
|
+
# app/iron_admin/resources/review_resource.rb
|
|
473
|
+
module IronAdmin
|
|
474
|
+
module Resources
|
|
475
|
+
class ReviewResource < IronAdmin::Resource
|
|
476
|
+
field :rating, type: :star_rating
|
|
477
|
+
end
|
|
478
|
+
end
|
|
320
479
|
end
|
|
321
480
|
```
|
|
322
481
|
|
|
323
|
-
The `display` block controls show page rendering, `index_display` controls index table rendering (falls back to `display` if not provided), and `
|
|
482
|
+
The `display` block controls show page rendering, `index_display` controls index table rendering (falls back to `display` if not provided), and `config.components.fields` controls the form input.
|
data/docs/guides/imports.md
CHANGED
|
@@ -8,8 +8,12 @@ a preview, and then import it.
|
|
|
8
8
|
Imports are off by default. Enable them per resource with the formats to accept:
|
|
9
9
|
|
|
10
10
|
```ruby
|
|
11
|
-
|
|
12
|
-
|
|
11
|
+
module IronAdmin
|
|
12
|
+
module Resources
|
|
13
|
+
class UserResource < IronAdmin::Resource
|
|
14
|
+
imports :csv, :json
|
|
15
|
+
end
|
|
16
|
+
end
|
|
13
17
|
end
|
|
14
18
|
```
|
|
15
19
|
|
|
@@ -20,18 +24,22 @@ follow the `:create` permission: a policy that does not allow `:create`, or
|
|
|
20
24
|
## Import Options
|
|
21
25
|
|
|
22
26
|
```ruby
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
27
|
+
module IronAdmin
|
|
28
|
+
module Resources
|
|
29
|
+
class UserResource < IronAdmin::Resource
|
|
30
|
+
imports :csv
|
|
31
|
+
import_fields :email, :name, :role # Columns that can be imported
|
|
32
|
+
import_upsert_key :email # Update the record with the same email
|
|
33
|
+
import_options max_rows: 1_000, preview_rows: 10
|
|
34
|
+
|
|
35
|
+
import_transform do |attributes, context|
|
|
36
|
+
attributes.merge(invited_by_id: context.current_user.id)
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
import_validate do |attributes|
|
|
40
|
+
"Role is not allowed" if attributes[:role] == "superadmin"
|
|
41
|
+
end
|
|
42
|
+
end
|
|
35
43
|
end
|
|
36
44
|
end
|
|
37
45
|
```
|
|
@@ -40,7 +48,7 @@ end
|
|
|
40
48
|
|--------|-------------|
|
|
41
49
|
| `imports :csv, :json` | Formats the upload form accepts |
|
|
42
50
|
| `import_fields` | Fields a file can set, in the order the upload form and the preview list them. By default, every field except `id`, `created_at` and `updated_at`, in column order. Fields hidden from or readonly for the current user, associations, `:file`, `:files` and `:rich_text` fields are never imported. |
|
|
43
|
-
| `import_upsert_key` | Fields that identify an existing record. A row whose values match a record (within the tenant scope) updates it; other rows create records. |
|
|
51
|
+
| `import_upsert_key` | Fields that identify an existing record. A row whose values match a record (within the tenant scope) updates it; other rows create records. Each row needs the permission for what it does: `:update` for a row that updates, `:create` for a row that creates. A denied row is reported as an error, in the preview and in the import, and the other rows still import. |
|
|
44
52
|
| `import_transform` | Block that receives the row's attributes (and, with two parameters, a context with `current_user` and `controller`) and returns the attributes to save |
|
|
45
53
|
| `import_validate` | Block that returns an error message, or an array of them, for an invalid row |
|
|
46
54
|
| `import_options max_rows:` | Largest number of rows a file may have (default 5,000) |
|
|
@@ -56,7 +64,11 @@ an array of objects, or an object with a `records` array.
|
|
|
56
64
|
and the list of importable fields. The form posts the file to
|
|
57
65
|
`POST /admin/:resource_name/import/preview` as a full-page request (`data-turbo="false"`).
|
|
58
66
|
2. **Preview.** The preview page shows how the headers map to fields and the first
|
|
59
|
-
`preview_rows` rows, with their values as they will be saved
|
|
67
|
+
`preview_rows` rows, with their values as they will be saved, formatted as the show page
|
|
68
|
+
displays each field: "Yes" or "No" for a boolean, a strftime `format:` for a date or datetime,
|
|
69
|
+
the symbol and precision of a `:currency` field, the humanized value of a `:badge` or
|
|
70
|
+
`:radio` field, and a mask for `:password` and `:hidden` fields. The import saves the values
|
|
71
|
+
from the file, not these texts. Each row is validated like the
|
|
60
72
|
real import: the `import_validate` block, and the model validations against the record an
|
|
61
73
|
upsert would update, so a row that updates an existing record is not reported as "has
|
|
62
74
|
already been taken". A file with more than `max_rows` rows is rejected here, with the alert
|
|
@@ -116,8 +128,11 @@ on:
|
|
|
116
128
|
with `multipart: true` and the hidden fields `import_format` (`@import_format`) and
|
|
117
129
|
`import_data` (`@import_data`). Without it the page has no Import button.
|
|
118
130
|
- `@preview.cell_text(row, field_name)` returns the text of a preview cell: blank for missing
|
|
119
|
-
values,
|
|
120
|
-
|
|
131
|
+
values, the field formatting described in step 2 (`@preview.fields` holds the field of each
|
|
132
|
+
mapped column), otherwise dates and times in the default formats of the show page
|
|
133
|
+
("Oct 20, 2026", "Oct 20, 2026 at 10:00 AM"), whatever the locale, and JSON for hash and
|
|
134
|
+
array values. Boolean labels come from `iron_admin.fields.boolean_true` and
|
|
135
|
+
`iron_admin.fields.boolean_false`, as on the show page.
|
|
121
136
|
|
|
122
137
|
The texts come from the `iron_admin.imports` translation keys. `iron_admin.imports.preview.summary`
|
|
123
138
|
("%{count} rows detected.") and `iron_admin.imports.preview.import_button`
|