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.
Files changed (210) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +129 -1
  3. data/README.md +48 -1
  4. data/UPGRADING.md +495 -8
  5. data/app/assets/tailwind/iron_admin/engine.css +79 -4
  6. data/app/components/iron_admin/dashboards/activity_feed_component/item_component.html.haml +6 -9
  7. data/app/components/iron_admin/dashboards/activity_feed_component.html.haml +6 -5
  8. data/app/components/iron_admin/dashboards/activity_feed_component.rb +21 -24
  9. data/app/components/iron_admin/dashboards/chart_component.html.haml +3 -5
  10. data/app/components/iron_admin/dashboards/chart_component.rb +86 -24
  11. data/app/components/iron_admin/dashboards/concerns/themed_card.rb +39 -0
  12. data/app/components/iron_admin/dashboards/metric_card_component.html.haml +8 -7
  13. data/app/components/iron_admin/dashboards/metric_card_component.rb +2 -0
  14. data/app/components/iron_admin/dashboards/progress_component.html.haml +11 -7
  15. data/app/components/iron_admin/dashboards/progress_component.rb +11 -6
  16. data/app/components/iron_admin/dashboards/quick_links_component/link_component.html.haml +8 -9
  17. data/app/components/iron_admin/dashboards/quick_links_component.html.haml +6 -5
  18. data/app/components/iron_admin/dashboards/quick_links_component.rb +4 -12
  19. data/app/components/iron_admin/dashboards/recent_table_component.html.haml +15 -10
  20. data/app/components/iron_admin/dashboards/recent_table_component.rb +49 -0
  21. data/app/components/iron_admin/dashboards/stats_grid_component/stat_component.html.haml +13 -14
  22. data/app/components/iron_admin/dashboards/stats_grid_component.html.haml +1 -0
  23. data/app/components/iron_admin/dashboards/stats_grid_component.rb +9 -11
  24. data/app/components/iron_admin/filters/bar_component.html.haml +8 -6
  25. data/app/components/iron_admin/filters/bar_component.rb +56 -9
  26. data/app/components/iron_admin/filters/control_styles.rb +82 -0
  27. data/app/components/iron_admin/filters/date_range_component.html.haml +9 -4
  28. data/app/components/iron_admin/filters/date_range_component.rb +10 -6
  29. data/app/components/iron_admin/filters/search_component.html.haml +4 -4
  30. data/app/components/iron_admin/filters/search_component.rb +3 -5
  31. data/app/components/iron_admin/filters/select_filter_component.html.haml +1 -1
  32. data/app/components/iron_admin/filters/select_filter_component.rb +5 -16
  33. data/app/components/iron_admin/form/belongs_to_autocomplete_component.html.haml +9 -5
  34. data/app/components/iron_admin/form/belongs_to_autocomplete_component.rb +10 -8
  35. data/app/components/iron_admin/form/belongs_to_component.html.haml +2 -2
  36. data/app/components/iron_admin/form/belongs_to_component.rb +4 -18
  37. data/app/components/iron_admin/form/checkbox_component.rb +2 -3
  38. data/app/components/iron_admin/form/concerns/form_input_behavior.rb +1 -1
  39. data/app/components/iron_admin/form/control_classes.rb +108 -0
  40. data/app/components/iron_admin/form/date_picker_component.rb +3 -7
  41. data/app/components/iron_admin/form/field_wrapper_component.html.haml +3 -3
  42. data/app/components/iron_admin/form/field_wrapper_component.rb +3 -3
  43. data/app/components/iron_admin/form/nested_form_component.html.haml +4 -5
  44. data/app/components/iron_admin/form/nested_form_component.rb +12 -2
  45. data/app/components/iron_admin/form/select_component.html.haml +1 -1
  46. data/app/components/iron_admin/form/select_component.rb +2 -16
  47. data/app/components/iron_admin/form/text_input_component.rb +1 -5
  48. data/app/components/iron_admin/form/textarea_component.rb +1 -5
  49. data/app/components/iron_admin/layout/flash_component.html.haml +1 -1
  50. data/app/components/iron_admin/layout/flash_component.rb +4 -3
  51. data/app/components/iron_admin/layout/navbar_component.html.haml +15 -9
  52. data/app/components/iron_admin/layout/navbar_component.rb +29 -1
  53. data/app/components/iron_admin/layout/shell_component.html.haml +4 -4
  54. data/app/components/iron_admin/layout/shell_component.rb +16 -3
  55. data/app/components/iron_admin/layout/sidebar_component.html.haml +21 -25
  56. data/app/components/iron_admin/layout/sidebar_component.rb +76 -1
  57. data/app/components/iron_admin/layout/theme_switcher_component.html.haml +15 -0
  58. data/app/components/iron_admin/layout/theme_switcher_component.rb +74 -0
  59. data/app/components/iron_admin/resources/actions_component.html.haml +15 -8
  60. data/app/components/iron_admin/resources/actions_component.rb +34 -2
  61. data/app/components/iron_admin/resources/breadcrumb_component.html.haml +3 -3
  62. data/app/components/iron_admin/resources/breadcrumb_component.rb +8 -7
  63. data/app/components/iron_admin/resources/bulk_actions_component.html.haml +9 -8
  64. data/app/components/iron_admin/resources/bulk_actions_component.rb +47 -4
  65. data/app/components/iron_admin/resources/data_table_component.html.haml +15 -15
  66. data/app/components/iron_admin/resources/data_table_component.rb +34 -3
  67. data/app/components/iron_admin/resources/related_list_component.html.haml +7 -7
  68. data/app/components/iron_admin/resources/related_list_component.rb +26 -2
  69. data/app/components/iron_admin/resources/show_field_component.html.haml +3 -3
  70. data/app/components/iron_admin/resources/show_field_component.rb +10 -4
  71. data/app/components/iron_admin/resources/styles.rb +136 -0
  72. data/app/components/iron_admin/ui/alert_component.html.haml +2 -2
  73. data/app/components/iron_admin/ui/alert_component.rb +27 -31
  74. data/app/components/iron_admin/ui/badge_component.rb +40 -20
  75. data/app/components/iron_admin/ui/button_component.rb +37 -11
  76. data/app/components/iron_admin/ui/card_component.rb +3 -3
  77. data/app/components/iron_admin/ui/dropdown_component.html.haml +1 -1
  78. data/app/components/iron_admin/ui/dropdown_component.rb +34 -13
  79. data/app/components/iron_admin/ui/empty_state_component.html.haml +4 -5
  80. data/app/components/iron_admin/ui/empty_state_component.rb +2 -2
  81. data/app/components/iron_admin/ui/modal_component.html.haml +5 -5
  82. data/app/components/iron_admin/ui/modal_component.rb +6 -4
  83. data/app/components/iron_admin/ui/pagination_component.html.haml +14 -14
  84. data/app/components/iron_admin/ui/pagination_component.rb +26 -9
  85. data/app/components/iron_admin/ui/scopes_component.html.haml +2 -2
  86. data/app/components/iron_admin/ui/scopes_component.rb +44 -11
  87. data/app/components/iron_admin/ui/tooltip_component.rb +11 -4
  88. data/app/controllers/iron_admin/application_controller.rb +58 -4
  89. data/app/controllers/iron_admin/audit_controller.rb +30 -6
  90. data/app/controllers/iron_admin/concerns/action_executable.rb +37 -0
  91. data/app/controllers/iron_admin/concerns/assignable_references.rb +149 -0
  92. data/app/controllers/iron_admin/concerns/authorizable.rb +11 -0
  93. data/app/controllers/iron_admin/concerns/blank_password_filterable.rb +21 -0
  94. data/app/controllers/iron_admin/concerns/event_emittable.rb +47 -7
  95. data/app/controllers/iron_admin/concerns/filterable.rb +34 -9
  96. data/app/controllers/iron_admin/concerns/nested_permittable.rb +5 -3
  97. data/app/controllers/iron_admin/concerns/nested_tenant_check.rb +159 -0
  98. data/app/controllers/iron_admin/concerns/polymorphic_references.rb +131 -0
  99. data/app/controllers/iron_admin/concerns/scopeable.rb +54 -7
  100. data/app/controllers/iron_admin/concerns/searchable.rb +3 -3
  101. data/app/controllers/iron_admin/concerns/tenant_assignable.rb +118 -0
  102. data/app/controllers/iron_admin/concerns/tenant_containment.rb +146 -0
  103. data/app/controllers/iron_admin/exports_controller.rb +2 -2
  104. data/app/controllers/iron_admin/imports_controller.rb +1 -1
  105. data/app/controllers/iron_admin/resources_controller.rb +48 -41
  106. data/app/controllers/iron_admin/search_controller.rb +1 -2
  107. data/app/controllers/iron_admin/themes_controller.rb +50 -0
  108. data/app/controllers/iron_admin/tools_controller.rb +58 -5
  109. data/app/helpers/iron_admin/action_form_helper.rb +19 -0
  110. data/app/helpers/iron_admin/application_helper.rb +93 -16
  111. data/app/helpers/iron_admin/assignable_records_helper.rb +32 -0
  112. data/app/helpers/iron_admin/component_overrides_helper.rb +9 -4
  113. data/app/helpers/iron_admin/field_display_helper.rb +88 -43
  114. data/app/helpers/iron_admin/related_records_helper.rb +51 -0
  115. data/app/helpers/iron_admin/theme_helper.rb +56 -46
  116. data/app/javascript/iron_admin/controllers/cp_bulk_select_controller.js +12 -0
  117. data/app/javascript/iron_admin/controllers/cp_chart_controller.js +4 -0
  118. data/app/javascript/iron_admin/controllers/cp_disclosure_controller.js +19 -0
  119. data/app/javascript/iron_admin/controllers/cp_search_shortcut_controller.js +39 -0
  120. data/app/javascript/iron_admin/index.js +4 -0
  121. data/app/views/iron_admin/audit/index.html.haml +78 -81
  122. data/app/views/iron_admin/dashboard/index.html.haml +10 -9
  123. data/app/views/iron_admin/form/_action_field.html.haml +50 -0
  124. data/app/views/iron_admin/form/_nested_row.html.haml +18 -13
  125. data/app/views/iron_admin/imports/new.html.haml +14 -13
  126. data/app/views/iron_admin/imports/preview.html.haml +24 -21
  127. data/app/views/iron_admin/resources/_form.html.haml +70 -68
  128. data/app/views/iron_admin/resources/action_form.html.haml +16 -59
  129. data/app/views/iron_admin/resources/bulk_action_form.html.haml +20 -58
  130. data/app/views/iron_admin/resources/edit.html.haml +3 -3
  131. data/app/views/iron_admin/resources/index.html.haml +87 -74
  132. data/app/views/iron_admin/resources/new.html.haml +2 -2
  133. data/app/views/iron_admin/resources/show.html.haml +53 -41
  134. data/app/views/iron_admin/search/index.html.haml +17 -9
  135. data/app/views/iron_admin/shared/_pagination.html.haml +13 -10
  136. data/app/views/iron_admin/shared/error.html.haml +16 -12
  137. data/app/views/iron_admin/tools/action_form.html.haml +9 -55
  138. data/app/views/iron_admin/tools/show.html.haml +4 -5
  139. data/app/views/layouts/iron_admin/_document_head.html.haml +24 -0
  140. data/app/views/layouts/iron_admin/application.html.haml +4 -17
  141. data/app/views/layouts/iron_admin/minimal.html.haml +7 -0
  142. data/config/importmap.rb +2 -0
  143. data/config/locales/en.yml +23 -0
  144. data/config/routes.rb +1 -0
  145. data/docs/FAQ.md +87 -37
  146. data/docs/README.md +8 -2
  147. data/docs/components/README.md +6 -2
  148. data/docs/components/dashboard-components.md +24 -35
  149. data/docs/components/filter-components.md +44 -92
  150. data/docs/components/form-components.md +16 -32
  151. data/docs/components/resource-components.md +46 -27
  152. data/docs/components/ui-components.md +44 -26
  153. data/docs/getting-started/installation.md +5 -1
  154. data/docs/getting-started/quick-start.md +36 -23
  155. data/docs/guides/authentication.md +182 -42
  156. data/docs/guides/components.md +97 -15
  157. data/docs/guides/custom-adapters.md +24 -4
  158. data/docs/guides/dashboard.md +68 -44
  159. data/docs/guides/export.md +24 -8
  160. data/docs/guides/extending.md +206 -51
  161. data/docs/guides/fields.md +229 -70
  162. data/docs/guides/imports.md +33 -18
  163. data/docs/guides/resources.md +333 -111
  164. data/docs/guides/theming.md +930 -58
  165. data/docs/guides/troubleshooting.md +7 -3
  166. data/docs/plugin-system-design.md +8 -7
  167. data/docs/reference/configuration.md +51 -16
  168. data/docs/reference/routes.md +1 -0
  169. data/docs/reference/theme-properties.md +101 -38
  170. data/lib/generators/iron_admin/install/templates/initializer.rb.tt +7 -2
  171. data/lib/generators/iron_admin/install_audit/templates/create_iron_admin_audit_entries.rb.tt +2 -0
  172. data/lib/iron_admin/action_field.rb +11 -0
  173. data/lib/iron_admin/adapters/active_record.rb +95 -0
  174. data/lib/iron_admin/adapters/base.rb +107 -0
  175. data/lib/iron_admin/adapters/http/query.rb +21 -0
  176. data/lib/iron_admin/adapters/http.rb +84 -4
  177. data/lib/iron_admin/adapters/mongoid.rb +96 -2
  178. data/lib/iron_admin/audit_log.rb +64 -6
  179. data/lib/iron_admin/authentication_warning.rb +31 -0
  180. data/lib/iron_admin/concerns/filter_definable.rb +15 -1
  181. data/lib/iron_admin/concerns/nestable.rb +25 -0
  182. data/lib/iron_admin/concerns/scope_countable.rb +56 -0
  183. data/lib/iron_admin/concerns/soft_deletable.rb +28 -9
  184. data/lib/iron_admin/configuration/components.rb +14 -3
  185. data/lib/iron_admin/configuration/theme/neutral_defaults.rb +179 -0
  186. data/lib/iron_admin/configuration/theme.rb +292 -87
  187. data/lib/iron_admin/configuration.rb +340 -45
  188. data/lib/iron_admin/dashboard.rb +22 -38
  189. data/lib/iron_admin/engine.rb +16 -2
  190. data/lib/iron_admin/errors.rb +3 -0
  191. data/lib/iron_admin/field.rb +78 -17
  192. data/lib/iron_admin/field_inferrer.rb +61 -3
  193. data/lib/iron_admin/field_override_warning.rb +67 -0
  194. data/lib/iron_admin/import/import_preview.rb +56 -7
  195. data/lib/iron_admin/import/importer.rb +91 -14
  196. data/lib/iron_admin/import/tenant_precheck.rb +67 -0
  197. data/lib/iron_admin/plugin/registration.rb +64 -0
  198. data/lib/iron_admin/plugin_registry.rb +3 -2
  199. data/lib/iron_admin/policy.rb +22 -12
  200. data/lib/iron_admin/policy_coverage_warning.rb +46 -0
  201. data/lib/iron_admin/request_context.rb +18 -0
  202. data/lib/iron_admin/resource.rb +218 -77
  203. data/lib/iron_admin/resource_registry.rb +86 -13
  204. data/lib/iron_admin/scope_counts.rb +73 -0
  205. data/lib/iron_admin/tenant_scope.rb +30 -0
  206. data/lib/iron_admin/tool.rb +61 -12
  207. data/lib/iron_admin/tool_context.rb +10 -6
  208. data/lib/iron_admin/version.rb +1 -1
  209. data/lib/iron_admin.rb +29 -2
  210. metadata +37 -7
@@ -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
- class UserResource < IronAdmin::Resource
24
- field :status, type: :badge, colors: {
25
- active: :green,
26
- suspended: :red,
27
- pending: :yellow
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
- class SalaryResource < IronAdmin::Resource
47
- field :amount, visible: ->(user) { user.admin? || user.hr? }
48
- field :department, readonly: ->(user) { !user.admin? }
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
- ## Badge Colors
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
- Available keys: `:green`, `:red`, `:yellow`, `:blue`, `:indigo`, `:purple`, `:pink`, `:orange`, `:teal`, `:gray`
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
- Add custom colors:
85
+ To show one, set `visible: true`. It stays read-only unless you also set `readonly: false`:
64
86
 
65
87
  ```ruby
66
- IronAdmin.configure do |config|
67
- config.badge_colors[:cyan] = "bg-cyan-100 text-cyan-800"
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 automatically assigns colors to common status values without configuration:
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`, `published`, `enabled`, `approved`, `success` | Green |
78
- | `pending`, `draft`, `waiting`, `processing` | Yellow |
79
- | `completed`, `done`, `finished` | Blue |
80
- | `failed`, `error`, `rejected`, `cancelled`, `disabled` | Red |
81
- | `inactive`, `archived`, `suspended` | Gray |
82
- | `admin`, `superuser`, `owner` | Purple |
83
- | `user`, `member`, `subscriber` | Blue |
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
- class OrderResource < IronAdmin::Resource
90
- # No colors needed - auto-detected from value
91
- field :status, type: :badge
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 blue badge
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: :green # Override default blue
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
- class UserResource < IronAdmin::Resource
153
- field :avatar, type: :file
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
- class ProductResource < IronAdmin::Resource
169
- field :images, type: :files
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
- class ArticleResource < IronAdmin::Resource
185
- field :body, type: :rich_text
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
- class UserResource < IronAdmin::Resource
195
- field :password, type: :password
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
- class ArticleResource < IronAdmin::Resource
205
- field :tags, type: :tags
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
- class PostResource < IronAdmin::Resource
215
- field :body, type: :markdown
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 is displayed.
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
- class ThemeResource < IronAdmin::Resource
225
- field :primary_color, type: :color
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
- class ProductResource < IronAdmin::Resource
242
- field :price, type: :currency
243
- # Or with a custom symbol:
244
- field :price, type: :currency, symbol: "EUR"
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
- class UserResource < IronAdmin::Resource
254
- field :active, type: :boolean
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
- class EventResource < IronAdmin::Resource
264
- field :start_date, type: :date
265
- field :starts_at, type: :datetime
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, dates are displayed in human-readable format (e.g., "January 15, 2026") and datetimes include the time component.
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
- class CommentResource < IronAdmin::Resource
285
- belongs_to :commentable, polymorphic: true, types: [Article, Photo, Video]
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
- IronAdmin::FieldTypeRegistry.register(:star_rating) do
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 { "&#9733;" }.join.html_safe
426
+ value.to_i.clamp(0, 5).times.map { "&#9733;" }.join.html_safe
300
427
  end
301
428
 
302
429
  index_display do |record, field|
303
- value = record.public_send(field.name)
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
- # Optional: specify a custom ViewComponent for the form
308
- form_component MyApp::StarRatingComponent
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
- # Or a partial path:
311
- # form_partial "shared/star_rating_input"
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
- Then use it in a resource:
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
- class ReviewResource < IronAdmin::Resource
319
- field :rating, type: :star_rating
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 `form_component` or `form_partial` controls the form input.
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.
@@ -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
- class UserResource < IronAdmin::Resource
12
- imports :csv, :json
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
- class UserResource < IronAdmin::Resource
24
- imports :csv
25
- import_fields :email, :name, :role # Columns that can be imported
26
- import_upsert_key :email # Update the record with the same email
27
- import_options max_rows: 1_000, preview_rows: 10
28
-
29
- import_transform do |attributes, context|
30
- attributes.merge(invited_by_id: context.current_user.id)
31
- end
32
-
33
- import_validate do |attributes|
34
- "Role is not allowed" if attributes[:role] == "superadmin"
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. Each row is validated like the
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, dates and times in the default formats of the show page ("Oct 20, 2026",
120
- "Oct 20, 2026 at 10:00 AM"), whatever the locale, and JSON for hash and array values.
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`