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
@@ -4,12 +4,15 @@ Core UI elements for building admin interfaces.
4
4
 
5
5
  ## BadgeComponent
6
6
 
7
- Displays status indicators with colored backgrounds.
7
+ Displays a status in the current theme's colors: the `badge_palette` classes of its color, a
8
+ dot from `badge_dot_palette` (none when that Hash is empty) and the `badge_shape` radius and
9
+ weight. An unknown color uses `:gray`, and a color with classes in `config.badge_colors` uses
10
+ them, without a dot (see [Badges, alerts and chips](../guides/theming.md#badges-alerts-and-chips)).
8
11
 
9
12
  ```ruby
10
13
  IronAdmin::Ui::BadgeComponent.new(
11
14
  text: "Active", # Required: display text
12
- color: :green, # Optional: :gray, :green, :red, :yellow, :blue, :indigo, :purple, :pink, :orange, :teal
15
+ color: :green, # Optional: a badge_palette key: :gray (default), :green, :red, :yellow, :blue, :indigo, :purple, :pink, :orange, :teal
13
16
  size: :md # Optional: :sm, :md, :lg
14
17
  )
15
18
  ```
@@ -48,14 +51,12 @@ IronAdmin::Ui::ButtonComponent.new(
48
51
  = render IronAdmin::Ui::ButtonComponent.new(text: "Save Changes", variant: :primary)
49
52
 
50
53
  -# Danger button with confirmation
51
- = render IronAdmin::Ui::ButtonComponent.new(
52
- text: "Delete",
54
+ = render IronAdmin::Ui::ButtonComponent.new(text: "Delete",
53
55
  variant: :danger,
54
56
  icon: "trash",
55
57
  method: :delete,
56
58
  href: resource_path(@record),
57
- confirm: "This action cannot be undone."
58
- )
59
+ confirm: "This action cannot be undone.")
59
60
 
60
61
  -# Icon-only button
61
62
  = render IronAdmin::Ui::ButtonComponent.new(icon: "pencil", variant: :ghost, size: :sm)
@@ -112,7 +113,8 @@ IronAdmin::Ui::AlertComponent.new(
112
113
  `role:` to override it. `IronAdmin::Layout::FlashComponent` passes `role: "alert"` for every
113
114
  flash message, because a message that arrives already written in a new page is not
114
115
  announced as a `status`.
115
- - The border radius comes from `theme.border_radius`.
116
+ - The colors come from the theme's `alert_palette` entry for the type (the `:info` entry for
117
+ an unknown type), and the border width and radius from `border_width` and `border_radius`.
116
118
  - With `dismissible: true`, the alert uses the `cp-alert` Stimulus controller
117
119
  (`data-controller="cp-alert"`), and its close button calls `cp-alert#dismiss`, which
118
120
  removes the alert. The button's accessible label is `iron_admin.alerts.dismiss`
@@ -121,16 +123,12 @@ IronAdmin::Ui::AlertComponent.new(
121
123
  **Example:**
122
124
 
123
125
  ```haml
124
- = render IronAdmin::Ui::AlertComponent.new(
125
- message: "Your changes have been saved.",
126
+ = render IronAdmin::Ui::AlertComponent.new(message: "Your changes have been saved.",
126
127
  type: :success,
127
- dismissible: true
128
- )
128
+ dismissible: true)
129
129
 
130
- = render IronAdmin::Ui::AlertComponent.new(
131
- message: "Please fix the errors below.",
132
- type: :error
133
- )
130
+ = render IronAdmin::Ui::AlertComponent.new(message: "Please fix the errors below.",
131
+ type: :error)
134
132
  ```
135
133
 
136
134
  ---
@@ -257,13 +255,34 @@ Tab-style scope navigation.
257
255
 
258
256
  ```ruby
259
257
  IronAdmin::Ui::ScopesComponent.new(
260
- scopes: scopes, # Required: array of scope hashes
261
- current_scope: "all", # Required: currently active scope
258
+ scopes: scopes, # Required: array of scope hashes
259
+ current_scope: "all", # Required: currently active scope
262
260
  base_path: "/admin/users", # Required: base URL
263
- params: {} # Optional: additional URL params
261
+ params: {}, # Optional: query params the tabs keep
262
+ counts: {} # Optional: record counts keyed by scope name
264
263
  )
265
264
  ```
266
265
 
266
+ `counts` is the hash the index computes before it renders (`@scope_counts`). `@scope_counts`
267
+ is set only on the index. The keys are Strings, while a scope's name in the DSL is a Symbol.
268
+ Build the tab label with `IronAdmin::ScopeCounts.label(scope, counts)` (it returns
269
+ `"Active (12)"`, not the number). Read the number with `counts[scope[:name].to_s]`.
270
+ A value of `0` renders as zero. A scope with no entry renders its name and no number.
271
+ The default is `{}`, so existing callers stay unchanged. A template override can read `counts`
272
+ and call `scope_label(scope)`, which returns `"Active (12)"`, `"Inactive (0)"` or `"Archived"`.
273
+ A request from the `records` Turbo frame gets an empty `@scope_counts`. Render the tabs
274
+ outside that frame, as the built-in index does.
275
+ An `index.html.haml` override that turns counts on still pays one query per counted scope, and
276
+ shows no numbers until it passes `counts: @scope_counts`.
277
+
278
+ Each tab links to `base_path` with `params` and its own `scope`. The `scope` and `page` in
279
+ `params` are dropped, so a tab starts back at the first page. Pass `iron_admin_index_state` to
280
+ keep the search, filters and sort, as the built-in index page does. It is a view helper of the
281
+ resource pages only (the views `IronAdmin::ResourcesController` renders; use
282
+ `helpers.iron_admin_index_state` in a component rendered there). On other pages, such as a tool
283
+ or the dashboard, pass the params to keep yourself, for example
284
+ `request.query_parameters.slice("q", "sort", "direction", "filters")`.
285
+
267
286
  **Example:**
268
287
 
269
288
  ```ruby
@@ -275,11 +294,12 @@ scopes = [
275
294
  ```
276
295
 
277
296
  ```haml
278
- = render IronAdmin::Ui::ScopesComponent.new(
279
- scopes: scopes,
297
+ -# In a view rendered by IronAdmin::ResourcesController
298
+ = render IronAdmin::Ui::ScopesComponent.new(scopes: scopes,
280
299
  current_scope: params[:scope] || "all",
281
- base_path: request.path
282
- )
300
+ base_path: request.path,
301
+ params: iron_admin_index_state,
302
+ counts: @scope_counts)
283
303
  ```
284
304
 
285
305
  ---
@@ -301,9 +321,7 @@ IronAdmin::Ui::EmptyStateComponent.new(
301
321
  **Example:**
302
322
 
303
323
  ```haml
304
- = render IronAdmin::Ui::EmptyStateComponent.new(
305
- title: "No records found",
324
+ = render IronAdmin::Ui::EmptyStateComponent.new(title: "No records found",
306
325
  description: "Try adjusting your search or filters.",
307
- icon: "magnifying-glass"
308
- )
326
+ icon: "magnifying-glass")
309
327
  ```
@@ -60,7 +60,7 @@ end
60
60
 
61
61
  ## Step 4: Configure Authentication
62
62
 
63
- Edit `config/initializers/iron_admin.rb`:
63
+ The generated initializer denies every admin request with `403` until you replace its `authenticate` block. Edit `config/initializers/iron_admin.rb`:
64
64
 
65
65
  ```ruby
66
66
  IronAdmin.configure do |config|
@@ -135,6 +135,10 @@ Understanding how the CSS pipeline works will help you troubleshoot any styling
135
135
  5. The engine's layout references `stylesheet_link_tag "tailwind"`, which serves
136
136
  this compiled CSS file.
137
137
 
138
+ Classes you write yourself, such as the properties of a theme in
139
+ `config/initializers/iron_admin.rb`, must be in a file your build scans. See
140
+ [Tailwind: literal classes and source scanning](../guides/theming.md#tailwind-literal-classes-and-source-scanning).
141
+
138
142
  ### Manual setup (without the generator)
139
143
 
140
144
  If you didn't use the install generator, or the import line is missing:
@@ -36,6 +36,11 @@ IronAdmin.configure do |config|
36
36
  end
37
37
  ```
38
38
 
39
+ An app built with `bin/rails generate authentication` does not store the user id in
40
+ `session[:user_id]`. IronAdmin controllers inherit from `ActionController::Base`, so
41
+ the host's `Authentication` concern and `Current.user` are not available in this block.
42
+ Use the [Rails 8 authentication generator example](../guides/authentication.md#with-the-rails-8-authentication-generator).
43
+
39
44
  ## 3. Generate Resources
40
45
 
41
46
  ```bash
@@ -50,24 +55,28 @@ IronAdmin infers all fields from your database schema automatically. No configur
50
55
 
51
56
  ```ruby
52
57
  # app/iron_admin/resources/user_resource.rb
53
- class UserResource < IronAdmin::Resource
54
- field :role, type: :badge, colors: { admin: :purple, user: :blue }
55
- field :email, type: :text
58
+ module IronAdmin
59
+ module Resources
60
+ class UserResource < IronAdmin::Resource
61
+ field :role, type: :badge, colors: { admin: :purple, user: :blue }
62
+ field :email, type: :text
56
63
 
57
- searchable :name, :email
58
- filter :role, type: :select, options: User.roles.keys
59
- filter :created_at, type: :date_range
64
+ searchable :name, :email
65
+ filter :role, type: :select, options: User.roles.keys
66
+ filter :created_at, type: :date_range
60
67
 
61
- scope :admins, -> { where(role: :admin) }
62
- scope :recent, -> { where("created_at > ?", 7.days.ago) }
68
+ scope :admins, -> { where(role: :admin) }
69
+ scope :recent, -> { where("created_at > ?", 7.days.ago) }
63
70
 
64
- index_fields :id, :name, :email, :role, :created_at
65
- form_fields :name, :email, :role
71
+ index_fields :id, :name, :email, :role, :created_at
72
+ form_fields :name, :email, :role
66
73
 
67
- menu priority: 1, icon: "users", group: "People"
74
+ menu priority: 1, icon: "users", group: "People"
68
75
 
69
- action :lock, icon: "lock-closed", confirm: true do |record|
70
- record.update!(locked_at: Time.current)
76
+ action :lock, icon: "lock-closed", confirm: true do |record|
77
+ record.update!(locked_at: Time.current)
78
+ end
79
+ end
71
80
  end
72
81
  end
73
82
  ```
@@ -76,17 +85,21 @@ end
76
85
 
77
86
  ```ruby
78
87
  # app/iron_admin/dashboards/admin_dashboard.rb
79
- class AdminDashboard < IronAdmin::Dashboard
80
- metric :total_users, format: :number do
81
- User.count
82
- end
83
-
84
- metric :monthly_revenue, format: :currency do
85
- Payment.where("created_at > ?", 30.days.ago).sum(:amount)
88
+ module IronAdmin
89
+ module Dashboards
90
+ class AdminDashboard < IronAdmin::Dashboard
91
+ metric :total_users, format: :number do
92
+ User.count
93
+ end
94
+
95
+ metric :monthly_revenue, format: :currency do
96
+ Payment.where("created_at > ?", 30.days.ago).sum(:amount)
97
+ end
98
+
99
+ recent :users, limit: 5, scope: -> { order(created_at: :desc) }
100
+ recent :payments, limit: 5
101
+ end
86
102
  end
87
-
88
- recent :users, limit: 5, scope: -> { order(created_at: :desc) }
89
- recent :payments, limit: 5
90
103
  end
91
104
  ```
92
105
 
@@ -45,6 +45,23 @@ config.current_user do |controller|
45
45
  end
46
46
  ```
47
47
 
48
+ Devise defines `current_user` on every controller. A helper that exists only on the host application's `ApplicationController` is not available in the block: IronAdmin controllers inherit from `ActionController::Base`, not from that class, so calling it raises `NoMethodError` on every admin request. `controller.cookies` is private; read cookies with `controller.request.cookie_jar`. The `unless` above redirects a signed-out visitor, because `nil` is not an admin. Making `current_user&.admin?` itself the block's value would let that visitor in: add `|| false`, since `nil` allows the request.
49
+
50
+ ### With the Rails 8 authentication generator
51
+
52
+ ```ruby
53
+ config.authenticate do |controller|
54
+ # || false: a signed-out visitor makes &.admin? nil, and nil allows the request.
55
+ Session.find_by(id: controller.request.cookie_jar.signed[:session_id])&.user&.admin? || false
56
+ end
57
+
58
+ config.current_user do |controller|
59
+ Session.find_by(id: controller.request.cookie_jar.signed[:session_id])&.user
60
+ end
61
+ ```
62
+
63
+ `Current.user` is not set in IronAdmin requests, because the host's `Authentication` concern does not run there.
64
+
48
65
  ### Multi-Environment Redirects
49
66
 
50
67
  ```ruby
@@ -61,19 +78,49 @@ config.authenticate do |controller|
61
78
  end
62
79
  ```
63
80
 
81
+ ### Block value
82
+
83
+ Redirect or render inside the block to choose the response. To deny the request with `403`, make `false` the block's last value. HTML gets the error page without the admin shell, and any other format gets a bare `403`. `nil`, `true` and any other value allow the request. A block that already redirected or rendered keeps that response, whatever its value is.
84
+
85
+ Do not use `return` inside the block. The block runs from the controller, and `return` leaves the method that defined the block, which in an initializer raises `LocalJumpError`. To stop early, use `next false`.
86
+
87
+ A block that ends with `redirect_to ... unless ...` has the value `nil` when it does not redirect, so the request continues.
88
+
89
+ The initializer from `rails generate iron_admin:install` writes a block whose value is `false`, so a fresh install answers every admin request with `403` until you replace it with one of the recipes above. With no `authenticate` block at all, the admin answers every request; that is a valid setup only when a route constraint protects the mount (for example Devise's `authenticate :user do ... end` around `mount`). In production, IronAdmin logs a warning at boot when no block is set.
90
+
91
+ ```ruby
92
+ config.authenticate do |controller|
93
+ # || false: a signed-out visitor makes &.admin? nil, and nil allows the request.
94
+ User.find_by(id: controller.session[:user_id])&.admin? || false
95
+ end
96
+ ```
97
+
64
98
  ## The `current_user` Helper
65
99
 
66
100
  The user returned by `config.current_user` is available as `iron_admin_current_user` in all IronAdmin controllers and views.
67
101
 
68
102
  ## Policies
69
103
 
70
- Per-resource access control:
104
+ Per-resource access control. A resource without a `policy` block follows `config.default_policy`: `:allow` (the default) lets every user the `authenticate` block admits run every CRUD, custom and bulk action, and `:deny` denies them all, so each resource needs a policy that allows what its users may do. Once `authenticate` admits users other than administrators, set `:deny`:
105
+
106
+ ```ruby
107
+ IronAdmin.configure do |config|
108
+ config.default_policy = :deny
109
+ end
110
+ ```
111
+
112
+ In development, IronAdmin logs at boot the resources that have no policy while `default_policy` is `:allow`. The default becomes `:deny` in 1.0.
113
+
71
114
 
72
115
  ```ruby
73
- class UserResource < IronAdmin::Resource
74
- policy do
75
- allow :read, :create, :update
76
- deny :destroy, if: ->(user) { !user.superadmin? }
116
+ module IronAdmin
117
+ module Resources
118
+ class UserResource < IronAdmin::Resource
119
+ policy do
120
+ allow :read, :create, :update
121
+ deny :destroy, if: ->(user) { !user&.superadmin? }
122
+ end
123
+ end
77
124
  end
78
125
  end
79
126
  ```
@@ -83,8 +130,8 @@ end
83
130
  | Action | Covers |
84
131
  |--------|--------|
85
132
  | `:read` | Index, show, CSV/JSON export, `belongs_to` autocomplete, global search results, and the sidebar link |
86
- | `:create` | New, create, and imports (including import rows that update an existing record matched by `import_upsert_key`) |
87
- | `:update` | Edit and update |
133
+ | `:create` | New, create, opening imports, and each import row that creates a record |
134
+ | `:update` | Edit, update, and each import row that updates an existing record matched by `import_upsert_key` |
88
135
  | `:destroy` | Destroy |
89
136
 
90
137
  You can use either the CRUD action names (`:read`, `:create`, `:update`, `:destroy`) or the controller action names (`:index`, `:show`, `:new`, `:edit`, `:delete`). They are mapped in both directions, in `policy` and in `deny_actions`:
@@ -106,7 +153,7 @@ end
106
153
 
107
154
  Once a resource has a `policy` block, every CRUD action must be allowed explicitly. If `:read` is not allowed, the resource's index and show pages return `403`, and the resource is hidden from the sidebar and from global search. The New, Import, Edit, and Delete buttons are only shown when the policy (and `deny_actions`) allows the action.
108
155
 
109
- Policy `if:` conditions run on every admin page, not only on the resource's own pages: the sidebar and global search check `:read` for every resource. Make sure each condition handles every user it can receive, including `nil` when no `current_user` block is configured.
156
+ Policy `if:` conditions run on every admin page, not only on the resource's own pages: the sidebar and global search check `:read` for every resource. Make sure each condition handles every user it can receive, including `nil` when no `current_user` block is configured. In an `allow ... if:` rule, a proc that returns `nil` does not allow the action, so `nil` denies there. In a `deny ... if:` rule, `nil` means the deny does not apply. In `config.authenticate`, `nil` allows the request.
110
157
 
111
158
  ### Conditional Policies
112
159
 
@@ -117,8 +164,8 @@ Policy `if:` conditions run on every admin page, not only on the resource's own
117
164
  ```ruby
118
165
  policy do
119
166
  allow :read
120
- allow :update, if: ->(user) { user.admin? || user.manager? }
121
- deny :destroy, if: ->(user) { !user.superadmin? }
167
+ allow :update, if: ->(user) { user&.admin? || user&.manager? }
168
+ deny :destroy, if: ->(user) { !user&.superadmin? }
122
169
  end
123
170
  ```
124
171
 
@@ -127,23 +174,29 @@ end
127
174
  Custom actions and bulk actions are **allowed by default**, even when a policy is defined. This separates custom action authorization from CRUD policy. To restrict a custom action, add an `allow` rule with a condition:
128
175
 
129
176
  ```ruby
130
- class UserResource < IronAdmin::Resource
131
- action :lock do |record|
132
- record.update!(locked_at: Time.current)
133
- end
134
-
135
- bulk_action :archive do |records|
136
- records.update_all(archived: true)
137
- end
138
-
139
- policy do
140
- allow :read, :update
141
- allow :lock, if: ->(user) { user.admin? } # Restrict the custom action
142
- allow :archive, if: ->(user) { user.admin? } # Restrict the bulk action
177
+ module IronAdmin
178
+ module Resources
179
+ class UserResource < IronAdmin::Resource
180
+ action :lock do |record|
181
+ record.update!(locked_at: Time.current)
182
+ end
183
+
184
+ bulk_action :archive do |records|
185
+ records.update_all(archived: true)
186
+ end
187
+
188
+ policy do
189
+ allow :read, :update
190
+ allow :lock, if: ->(user) { user&.admin? } # Restrict the custom action
191
+ allow :archive, if: ->(user) { user&.admin? } # Restrict the bulk action
192
+ end
193
+ end
143
194
  end
144
195
  end
145
196
  ```
146
197
 
198
+ The index evaluates every bulk action's `if:` condition on each render, with the current user. That user is `nil` when the `current_user` block returns `nil`, or when no `current_user` block is configured, so the condition has to be nil-safe (`user&.admin?`). A condition that raises is logged and that action is hidden; the index still renders. The index hides the bulk actions the policy denies.
199
+
147
200
  The show page only shows the buttons of member actions the current user may run. An action
148
201
  the policy denies is hidden, and running it anyway returns `403`.
149
202
 
@@ -152,8 +205,12 @@ the policy denies is hidden, and running it anyway returns `403`.
152
205
  For simple cases:
153
206
 
154
207
  ```ruby
155
- class AuditLogResource < IronAdmin::Resource
156
- deny_actions :create, :update, :delete
208
+ module IronAdmin
209
+ module Resources
210
+ class AuditLogResource < IronAdmin::Resource
211
+ deny_actions :create, :update, :delete
212
+ end
213
+ end
157
214
  end
158
215
  ```
159
216
 
@@ -161,24 +218,37 @@ end
161
218
 
162
219
  ### Forbidden and Not Found Pages
163
220
 
164
- When a browser request ends in `403 Forbidden` (a policy or `deny_actions` denial, or a
165
- failing action `condition`) or `404 Not Found` (a missing or soft-deleted record, an unknown
166
- resource, action or tool, or an import or export format the resource does not enable),
167
- IronAdmin renders a page inside the admin layout. It shows a title, a message, and a link
168
- back to the resource index when the user may read the resource, or to the dashboard
169
- otherwise. Turbo form submissions also accept HTML and get the page. JSON and CSV requests,
170
- and requests that accept only Turbo Streams, get the bare status code with an empty body.
221
+ A policy denial, a `deny_actions` denial, a failing action `condition`, or a `404 Not Found`
222
+ (a missing or soft-deleted record, an unknown resource, action or tool, or an import or export
223
+ format the resource does not enable) renders a page inside the admin layout. It shows a title,
224
+ a message, and a link back to the resource index when the user may read the resource, or to the
225
+ dashboard otherwise. Turbo form submissions also accept HTML and get the page. JSON and CSV
226
+ requests, and requests that accept only Turbo Streams, get the bare status code with an empty
227
+ body. On these pages `@resource_class` is set when the URL named a registered resource.
228
+
229
+ An `authenticate` block whose value is `false` uses the same error template and the same bare
230
+ status for other formats, but not the admin layout. HTML gets `layouts/iron_admin/minimal`:
231
+ the document head, the stylesheets and the theme classes, without the sidebar, the navbar, the
232
+ search or the theme switcher, and without a link back into the admin. `@resource_class` is not
233
+ set, because the block runs before the controller looks up the resource. The shell is left out
234
+ on purpose. It checks `:read` for every resource, and a condition such as
235
+ `->(user) { user.admin? }` raises `NoMethodError` for a signed-out visitor, which would turn
236
+ the 403 into a 500. A host can replace that layout with `app/views/layouts/iron_admin/minimal.html.haml`.
171
237
 
172
238
  To change the page, add your own template to the host app:
173
239
 
174
240
  ```haml
175
241
  -# app/views/iron_admin/shared/error.html.haml (or error.html.erb)
176
242
  %h1= error == :forbidden ? "Access denied" : "Not found"
177
- = link_to "Dashboard", root_path
243
+ - if iron_admin_error_navigation?
244
+ = link_to "Dashboard", root_path
178
245
  ```
179
246
 
180
- The template receives the local `error` (`:forbidden` or `:not_found`), and `@resource_class`
181
- is set when the URL named a registered resource. The texts of the built-in page come from
247
+ The template receives only the local `error` (`:forbidden` or `:not_found`).
248
+ `iron_admin_error_navigation?` is true for policy denials and 404s, and false when an
249
+ `authenticate` block denies the request. Keep any link into the admin, and any call that runs
250
+ a policy, behind that helper: the built-in template does. A host template that declares strict
251
+ locals for `error` only still renders. The texts of the built-in page come from
182
252
  these translation keys:
183
253
 
184
254
  | Key | Default |
@@ -195,10 +265,14 @@ these translation keys:
195
265
  Control field visibility and editability per user:
196
266
 
197
267
  ```ruby
198
- class UserResource < IronAdmin::Resource
199
- field :salary, visible: ->(user) { user.admin? || user.hr? }
200
- field :role, readonly: ->(user) { !user.admin? }
201
- field :ssn, visible: ->(user) { user.admin? }
268
+ module IronAdmin
269
+ module Resources
270
+ class UserResource < IronAdmin::Resource
271
+ field :salary, visible: ->(user) { user&.admin? || user&.hr? }
272
+ field :role, readonly: ->(user) { !user&.admin? }
273
+ field :ssn, visible: ->(user) { user&.admin? }
274
+ end
275
+ end
202
276
  end
203
277
  ```
204
278
 
@@ -242,6 +316,49 @@ rails db:migrate
242
316
  View audit logs at `/admin/audit`. The page filters entries by resource, action and date. The
243
317
  Action filter lists the actions logged so far, custom resource actions included.
244
318
 
319
+ #### Audit Log per Tenant
320
+
321
+ Audit entries carry no tenant of their own, so `config.tenant_scope` cannot filter them. In a
322
+ multi-tenant app, give each entry the current tenant's key with `config.audit_tenant`. The block
323
+ runs in the controller and receives it:
324
+
325
+ ```ruby
326
+ IronAdmin.configure do |config|
327
+ config.audit_tenant { |_controller| Current.organization&.id }
328
+ end
329
+ ```
330
+
331
+ Each change made in the admin then stores that key (as a String) in `tenant_key`, and the audit
332
+ page, with its Resource and Action filters, lists only the entries of the current key. When the
333
+ block returns `nil`, the page lists nothing, and entries logged without a key (before the block
334
+ was set) never appear. With `config.audit_storage = :database`, the table needs a `tenant_key`
335
+ column: `rails generate iron_admin:install_audit` includes it, and an existing table needs the
336
+ migration in [UPGRADING.md](../../UPGRADING.md). Without the column the audit page raises
337
+ `IronAdmin::ConfigurationError`. Without `audit_tenant`, the audit page is global: every user the
338
+ `authenticate` block admits reads every tenant's entries.
339
+
340
+ #### User Labels
341
+
342
+ Database storage keeps each user as an identifier, the user's id as a string, so by default
343
+ the User column shows ids such as `1`. (Memory storage keeps the user object and shows its
344
+ `email` or `name`.) To show a label instead, with either storage, configure `audit_user_labels`:
345
+
346
+ ```ruby
347
+ IronAdmin.configure do |config|
348
+ config.audit_user_labels do |identifiers|
349
+ User.where(id: identifiers).pluck(:id, :email).to_h
350
+ end
351
+ end
352
+ ```
353
+
354
+ The block receives the distinct identifiers of every entry on the page and is called once per
355
+ page, so a single query labels all of them. It returns a hash of labels keyed by identifier
356
+ (string or integer keys). With memory storage, a label from the block replaces the user's
357
+ `email` or `name`. A user missing from the hash, such as a deleted user, and a blank label keep
358
+ the default: the identifier with database storage, the `email` or `name` with memory storage.
359
+ If the block raises, the error is logged as `[IronAdmin] ...` and the page shows those
360
+ defaults, so the audit log stays readable. An entry logged without a user shows "Unknown".
361
+
245
362
  The built-in audit log:
246
363
  - Stores the last 1000 entries in memory (or unlimited in database)
247
364
  - Records user, action, resource, record ID, changes, and IP address
@@ -281,12 +398,33 @@ end
281
398
 
282
399
  ## Multi-Tenant Support
283
400
 
284
- Automatically scope all queries to the current tenant:
401
+ Automatically scope all queries to the current tenant.
402
+
403
+ `Current.organization` is the host application's current attributes, not
404
+ `IronAdmin::RequestContext`. Nothing in an admin request sets it: the host's
405
+ controller callbacks do not run here. Set it for the request with an
406
+ `around_action` on `IronAdmin::ApplicationController`, installed from
407
+ `to_prepare`, the same way as the locale. Guard a missing organization.
408
+ Calling `id` on nil raises `NoMethodError` and the request returns 500.
285
409
 
286
410
  ```ruby
411
+ # config/initializers/iron_admin.rb
412
+ Rails.application.config.to_prepare do
413
+ IronAdmin::ApplicationController.class_eval do
414
+ around_action :set_iron_admin_tenant
415
+
416
+ private
417
+
418
+ def set_iron_admin_tenant(&action)
419
+ Current.set(organization: iron_admin_current_user&.organization, &action)
420
+ end
421
+ end
422
+ end
423
+
287
424
  IronAdmin.configure do |config|
288
425
  config.tenant_scope do |scope|
289
- scope.where(organization_id: Current.organization.id)
426
+ organization = Current.organization
427
+ organization ? scope.where(organization_id: organization.id) : scope
290
428
  end
291
429
  end
292
430
  ```
@@ -297,4 +435,6 @@ The tenant scope is applied to:
297
435
  - Export queries (CSV/JSON)
298
436
  - Bulk action record validation
299
437
 
300
- This ensures users can only access records belonging to their tenant.
438
+ This ensures users can only access records belonging to their tenant. The audit log page is not
439
+ a resource query: keep it per tenant with `config.audit_tenant` (see
440
+ [Audit Log per Tenant](#audit-log-per-tenant)).