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
@@ -6,10 +6,10 @@ IronAdmin is designed to be extended at every level.
6
6
 
7
7
  1. **Configuration blocks** - Authentication, current user, audit logging
8
8
  2. **Resource DSL** - Fields, filters, scopes, actions, policies
9
- 3. **Component overrides** - Replace the shell, navbar, sidebar, index table, form, filter bar, search box or a field type's form input with your own ViewComponent (see [Components](components.md#overriding-components))
9
+ 3. **Component overrides** - Replace the shell, navbar, sidebar, flash messages, index table, form, filter bar, search box or a field type's form input with your own ViewComponent (see [Components](components.md#overriding-components))
10
10
  4. **Custom field types** - Register new field renderers
11
11
  5. **Dashboard customization** - Metrics, charts, recent records
12
- 6. **Theme system** - 40+ CSS class properties
12
+ 6. **Theme system** - Named themes with 96 properties, picked per request
13
13
  7. **Route mounting** - Mount at any path
14
14
 
15
15
  ## MongoDB / Mongoid Support
@@ -68,6 +68,7 @@ end
68
68
  ```
69
69
 
70
70
  The HTTP adapter:
71
+ - Each counted scope sends one more unpaginated list request on every index view, even when the response has no `meta.total`. Without `meta.total` the tab shows its name and no number. Set `scope_counts false` on an HTTP resource whose API returns no total.
71
72
  - Auto-discovers fields from the first API response (convention-over-configuration)
72
73
  - Infers resource path from name (`ProductResource` → `GET /products`)
73
74
  - Full CRUD via standard REST verbs
@@ -78,29 +79,46 @@ The HTTP adapter:
78
79
  ## Custom Resources with Business Logic
79
80
 
80
81
  ```ruby
81
- class SubscriptionResource < IronAdmin::Resource
82
- action :cancel, icon: "x-circle", confirm: true do |record|
83
- Billing::CancelSubscriptionService.call(subscription: record)
84
- end
82
+ module IronAdmin
83
+ module Resources
84
+ class SubscriptionResource < IronAdmin::Resource
85
+ action :cancel, icon: "x-circle", confirm: true do |record|
86
+ Billing::CancelSubscriptionService.call(subscription: record)
87
+ end
85
88
 
86
- bulk_action :pause_all do |records|
87
- records.each { |sub| sub.update!(status: :paused) }
89
+ bulk_action :pause_all do |records|
90
+ records.each { |sub| sub.update!(status: :paused) }
91
+ end
92
+ end
88
93
  end
89
94
  end
90
95
  ```
91
96
 
92
97
  ## Subclassing the Base Controller
93
98
 
99
+ Assigning `Time.zone` leaves that zone on the thread, so the next request served
100
+ by the same Puma thread renders in the previous admin user's zone. `Time.zone = ""`
101
+ raises `ArgumentError`. `ActiveSupport::TimeZone[nil]` raises `ArgumentError` too,
102
+ so a missing user or a nil zone returns 500 if it is passed straight in.
103
+
104
+ Scope the request with `around_action` and `Time.use_zone`. Stringify the name
105
+ first: a blank or unknown name makes `ActiveSupport::TimeZone[]` return nil, and
106
+ the callback then uses `Time.zone_default`. `Time.use_zone` restores the previous
107
+ zone when the action returns. `to_prepare` runs again when the controller class
108
+ is reloaded, and installs the callback on the reloaded class.
109
+
94
110
  ```ruby
95
111
  # config/initializers/iron_admin.rb
96
112
  Rails.application.config.to_prepare do
97
113
  IronAdmin::ApplicationController.class_eval do
98
- before_action :set_timezone
114
+ around_action :switch_iron_admin_time_zone
99
115
 
100
116
  private
101
117
 
102
- def set_timezone
103
- Time.zone = iron_admin_current_user&.timezone || "UTC"
118
+ def switch_iron_admin_time_zone(&action)
119
+ name = iron_admin_current_user&.timezone
120
+ zone = ActiveSupport::TimeZone[name.to_s] || Time.zone_default
121
+ Time.use_zone(zone, &action)
104
122
  end
105
123
  end
106
124
  end
@@ -126,39 +144,67 @@ app/views/iron_admin/
126
144
  index.html.haml
127
145
  dashboard/
128
146
  index.html.haml
129
- layouts/
130
- application.html.haml
147
+ app/views/layouts/iron_admin/
148
+ application.html.haml
149
+ minimal.html.haml
150
+ _document_head.html.haml
131
151
  ```
132
152
 
133
- Rails uses your app's views over the engine's views automatically.
153
+ Rails uses your app's views over the engine's views automatically. Layouts live under
154
+ `app/views/layouts`, not under `app/views/iron_admin`.
134
155
 
135
156
  An override replaces the engine's markup, so copy it from the IronAdmin version you run and
136
157
  keep what the controllers rely on:
137
158
 
138
159
  - `iron_admin/shared/error.html.haml` is the page for HTML `403` and `404` responses. It
139
- receives the local `error` (`:forbidden` or `:not_found`); `@resource_class` is set when
140
- the URL named a registered resource.
160
+ receives only the local `error` (`:forbidden` or `:not_found`). Policy denials and 404s
161
+ render it inside the admin layout (`layouts/iron_admin/application`), with `@resource_class`
162
+ set when the URL named a registered resource. An `authenticate` block whose value is `false`
163
+ renders it in `layouts/iron_admin/minimal`, with `iron_admin_error_navigation?` false and no
164
+ `@resource_class`. Links into the admin and policy calls belong behind that helper.
141
165
  - `iron_admin/resources/show.html.haml`: loop over `@member_actions` (the member actions the
142
166
  controller would run for this record) rather than `@resource_class.defined_actions`, and
143
167
  show the Edit button only when `@record_reachable` is true.
168
+ - `iron_admin/resources/index.html.haml`: render the bulk bar and the row checkboxes from
169
+ `@permitted_bulk_actions`. When that list is empty, render neither. Pass
170
+ `authenticity_token: form_authenticity_token` to the bulk `form_tag`.
144
171
  - `iron_admin/imports/new.html.haml`: the upload form needs `data: { turbo: false }`.
145
172
  - `iron_admin/imports/preview.html.haml`: keep the import form that posts `import_format`
146
173
  and `import_data` back to `resource_import_path`. See the [imports guide](imports.md).
147
174
 
148
175
  ## Extending the Resource Class
149
176
 
150
- ```ruby
151
- class ApplicationResource < IronAdmin::Resource
152
- exports :csv, :json
177
+ A subclass of `IronAdmin::Resource` is registered as a resource. `ApplicationResource`
178
+ is registered as "applications", and every admin page that renders the sidebar then
179
+ raises `uninitialized constant Application` while building that resource's model.
180
+ Share the behavior with a module. A module is not a resource, so it is not registered.
153
181
 
154
- def self.inherited(subclass)
155
- super
156
- subclass.menu group: "General" unless subclass.menu_options[:group]
182
+ ```ruby
183
+ # app/iron_admin/resources/shared_resource.rb
184
+ module IronAdmin
185
+ module Resources
186
+ module SharedResource
187
+ def self.included(resource_class)
188
+ resource_class.exports :csv, :json
189
+ resource_class.menu group: "General" unless resource_class.menu_options[:group]
190
+ end
191
+ end
157
192
  end
158
193
  end
194
+ ```
159
195
 
160
- class UserResource < ApplicationResource
161
- menu group: "People"
196
+ `menu` replaces the whole options hash. When a resource sets its own menu, repeat `group:`:
197
+
198
+ ```ruby
199
+ # app/iron_admin/resources/user_resource.rb
200
+ module IronAdmin
201
+ module Resources
202
+ class UserResource < IronAdmin::Resource
203
+ include SharedResource
204
+
205
+ menu icon: "users", group: "People"
206
+ end
207
+ end
162
208
  end
163
209
  ```
164
210
 
@@ -178,34 +224,86 @@ The `FieldTypeRegistry` allows you to register custom field types that integrate
178
224
 
179
225
  ### Registering a Custom Field Type
180
226
 
227
+ The form input is a component override. Assign a String to `config.components.fields`:
228
+ it is stored as that String and constantized when the form renders, so the next
229
+ request uses the reloaded class. The [components guide](components.md#field-input-overrides)
230
+ documents the override. It wins over `form_component`, and it does not change the
231
+ show or index pages.
232
+
233
+ Register `display` and `index_display` once, from the initializer, and do not call
234
+ a reloadable constant from those blocks. `IronAdmin.register_field_type` calls
235
+ `FieldTypeRegistry.register`. The registry is not cleared on reload and raises
236
+ `ArgumentError` (`Field type :star_rating is already registered`) on a second register.
237
+
238
+ Do not pass the component to `form_component`. Rails 8 does not autoload constants
239
+ while initializers run, so `form_component MyApp::StarRatingComponent` raises
240
+ `NameError` (`uninitialized constant MyApp`) at boot. `form_component` stores the
241
+ class. A String raises `NoMethodError` (`undefined method 'new' for an instance of String`)
242
+ when the form renders. A class captured at boot stays that class after a reload, and
243
+ breaks as soon as it calls a sibling constant that has been reloaded.
244
+
181
245
  ```ruby
182
246
  # config/initializers/iron_admin.rb
183
- IronAdmin::FieldTypeRegistry.register(:star_rating) do
184
- # Required: how to display on show pages
247
+ IronAdmin.configure do |config|
248
+ config.components.fields[:star_rating] = "MyApp::StarRatingComponent"
249
+ end
250
+
251
+ IronAdmin.register_field_type(:star_rating) do
185
252
  display do |record, field|
186
253
  value = record.public_send(field.name)
187
- value.to_i.times.map { "&#9733;" }.join.html_safe
254
+ value.to_i.clamp(0, 5).times.map { "&#9733;" }.join.html_safe
188
255
  end
189
256
 
190
- # Optional: how to display on index pages (falls back to display if omitted)
191
257
  index_display do |record, field|
192
- value = record.public_send(field.name)
193
- "#{value}/5"
258
+ "#{record.public_send(field.name)}/5"
259
+ end
260
+ end
261
+ ```
262
+
263
+ The display block draws one character per unit of the stored value and does not
264
+ stop. Clamp it. The input's `max` is checked only by the browser. Reject a value
265
+ outside the scale on the model: `validates :rating, inclusion: { in: 1..5 }`.
266
+
267
+ The component takes `form:`, `field:` and `record:`. `StarScale` is defined in the
268
+ same file, so loading the component defines it. The String above is constantized
269
+ on each render, which picks up the reloaded component and that sibling.
270
+
271
+ ```ruby
272
+ # app/components/my_app/star_rating_component.rb
273
+ module MyApp
274
+ module StarScale
275
+ def self.max
276
+ 5
277
+ end
194
278
  end
195
279
 
196
- # Optional: ViewComponent class for the form input
197
- form_component MyApp::StarRatingComponent
280
+ class StarRatingComponent < ViewComponent::Base
281
+ def initialize(form:, field:, record:)
282
+ super()
283
+ @form = form
284
+ @field = field
285
+ @record = record
286
+ end
198
287
 
199
- # Or use a partial path instead of a component:
200
- # form_partial "shared/star_rating_input"
288
+ def call
289
+ @form.number_field(@field.name, min: 1, max: StarScale.max)
290
+ end
291
+ end
201
292
  end
202
293
  ```
203
294
 
295
+ A partial is the other form option: `form_partial "shared/star_rating_input"`.
296
+
204
297
  ### Using a Custom Field Type
205
298
 
206
299
  ```ruby
207
- class ReviewResource < IronAdmin::Resource
208
- field :rating, type: :star_rating
300
+ # app/iron_admin/resources/review_resource.rb
301
+ module IronAdmin
302
+ module Resources
303
+ class ReviewResource < IronAdmin::Resource
304
+ field :rating, type: :star_rating
305
+ end
306
+ end
209
307
  end
210
308
  ```
211
309
 
@@ -213,10 +311,10 @@ end
213
311
 
214
312
  | Method | Description |
215
313
  |--------|-------------|
216
- | `display { \|record, field\| ... }` | Block that returns HTML for the show page |
217
- | `index_display { \|record, field\| ... }` | Block that returns HTML for the index table cell |
218
- | `form_component(klass)` | ViewComponent class to render on forms |
219
- | `form_partial(path)` | Partial path to render on forms (alternative to `form_component`) |
314
+ | `display { \|record, field\| ... }` | Block that returns HTML for the show page. Do not call a reloadable constant from it. |
315
+ | `index_display { \|record, field\| ... }` | Block that returns HTML for the index table cell. Falls back to `display`. |
316
+ | `form_component(klass)` | Stores a component class for the form. A String has no `new`, and a class captured at boot stays stale after a reload. Use `config.components.fields` with a class name instead. |
317
+ | `form_partial(path)` | Partial path to render on forms |
220
318
 
221
319
  The `FieldTypeRegistry` raises `ArgumentError` if you attempt to register a type name that is already registered. Use `FieldTypeRegistry.registered?(:type_name)` to check before registering.
222
320
 
@@ -313,10 +411,38 @@ success alerts, `ctx.flash[:alert]` and `ctx.flash[:error]` as error alerts, and
313
411
  `ctx.flash[:warning]` and `ctx.flash[:info]` as warning and info alerts. Other keys are not
314
412
  shown. See [Flash Messages](components.md#flash-messages).
315
413
 
316
- **Authorization:** The `condition:` proc receives the current user. If it returns false, the action returns 403 (an error page for browser requests) and is hidden from the UI.
414
+ **Authorization:** `tool_access` restricts the whole tool. Its condition receives the current user; when it returns `false` or `nil`, the tool page, every action, every action form and the legacy dispatch return 403, and the sidebar hides the tool. Subclasses inherit it. A tool without `tool_access` follows `config.default_policy`: open while it is `:allow` (the default), 403 when it is `:deny`.
415
+
416
+ ```ruby
417
+ module IronAdmin
418
+ module Tools
419
+ class CacheManagerTool < IronAdmin::Tool
420
+ tool_access ->(user) { user&.admin? }
421
+
422
+ tool_action :clear_all, confirm: true
423
+
424
+ def clear_all(ctx)
425
+ Rails.cache.clear
426
+ end
427
+ end
428
+ end
429
+ end
430
+ ```
431
+
432
+ An action's `condition:` proc also receives the current user and applies on top of `tool_access`. If it returns false, the action returns 403 (an error page for browser requests) and is hidden from the UI.
317
433
 
318
434
  **Form fields:** Actions with `form_fields:` render a form page before execution. Supported types: `:text`, `:textarea`, `:number`, `:boolean`, `:date`, `:datetime`, `:select`.
319
435
 
436
+ Declare every action the tool should run with `tool_action`. A tool is affected when it, or any tool it inherits from, declares at least one action: it only dispatches those names. `POST /admin/tools/:tool/:action` to any other name, including a public method defined on a subclass, returns 404 and does not call the method. A declared action also appears as a button on the default tool page. Make helpers that are not actions `private`.
437
+
438
+ A tool that declares no `tool_action`, and inherits none, still dispatches its own public methods. That fallback is deprecated and removed in 1.0. Each dispatch warns once per tool class and method through `IronAdmin.deprecator` (registered as `:iron_admin` on `Rails.application.deprecators`). Declare those methods with `tool_action` before 1.0. Set `strict_tool_actions` inside `IronAdmin.configure` to turn the fallback off for every tool (default `false`); undeclared names then return 404:
439
+
440
+ ```ruby
441
+ IronAdmin.configure do |config|
442
+ config.strict_tool_actions = true
443
+ end
444
+ ```
445
+
320
446
  ### Menu Options
321
447
 
322
448
  | Option | Type | Description |
@@ -438,12 +564,41 @@ Place the file in your host app's `config/locales/` directory. Rails will automa
438
564
 
439
565
  ### Setting the Locale
440
566
 
441
- IronAdmin uses the standard Rails `I18n.locale`. Set it in your application controller or via a `before_action` in the IronAdmin configuration:
567
+ IronAdmin uses the standard Rails `I18n.locale`. There is no `config.before_action`
568
+ (`NoMethodError` at boot). Controllers inherit from `ActionController::Base`, so a
569
+ `before_action` in the host `ApplicationController` does not run here either.
570
+
571
+ Assigning `I18n.locale` leaves that locale on the thread, so the next request
572
+ served by the same Puma thread renders in the admin user's locale. A blank or
573
+ unavailable locale raises `I18n::InvalidLocale` (Rails enforces available locales
574
+ by default) and the request returns 500.
575
+
576
+ Scope the request with `around_action` and `I18n.with_locale`.
577
+ `I18n.locale_available?` is false for a blank or unknown locale, and the callback
578
+ then uses `I18n.default_locale`. The current user is expected to respond to
579
+ `locale` with a value `I18n` considers available, such as a Symbol listed in
580
+ `I18n.available_locales`. `I18n.with_locale` restores the previous locale when the
581
+ action returns. `to_prepare` runs again when the controller class is reloaded, and
582
+ installs the callback on the reloaded class. Responses rendered by `rescue_from`
583
+ (the 404 and the 400) and the authentication-denied page still use the default
584
+ locale: `rescue_from` runs after this callback restores it, and
585
+ `authenticate_iron_admin_user!` is a `before_action` that runs first and stops
586
+ the chain. `prepend_around_action` would wrap that `before_action`, so the denied
587
+ page would use the user's locale; the `rescue_from` pages would still use the default.
442
588
 
443
589
  ```ruby
444
- IronAdmin.configure do |config|
445
- config.before_action do
446
- I18n.locale = iron_admin_current_user&.locale || :en
590
+ # config/initializers/iron_admin.rb
591
+ Rails.application.config.to_prepare do
592
+ IronAdmin::ApplicationController.class_eval do
593
+ around_action :switch_iron_admin_locale
594
+
595
+ private
596
+
597
+ def switch_iron_admin_locale(&action)
598
+ locale = iron_admin_current_user&.locale
599
+ locale = I18n.default_locale unless I18n.locale_available?(locale)
600
+ I18n.with_locale(locale, &action)
601
+ end
447
602
  end
448
603
  end
449
604
  ```
@@ -457,14 +612,14 @@ See the [Building a Custom Adapter](custom-adapters.md) guide for the complete r
457
612
  ## Testing Resources
458
613
 
459
614
  ```ruby
460
- RSpec.describe UserResource do
461
- it "maps to User model" do
462
- expect(UserResource.model).to eq(User)
615
+ RSpec.describe IronAdmin::Resources::UserResource do
616
+ it "maps to the User model" do
617
+ expect(described_class.model).to eq(User)
463
618
  end
464
619
 
465
- it "resolves fields from schema" do
466
- fields = UserResource.resolved_fields
467
- expect(fields.map(&:name)).to include(:email, :name)
620
+ it "resolves fields from the schema" do
621
+ names = described_class.resolved_fields.map(&:name)
622
+ expect(names).to include(:email, :name)
468
623
  end
469
624
  end
470
625
  ```