iron_admin 0.7.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +129 -1
- data/README.md +48 -1
- data/UPGRADING.md +495 -8
- data/app/assets/tailwind/iron_admin/engine.css +79 -4
- data/app/components/iron_admin/dashboards/activity_feed_component/item_component.html.haml +6 -9
- data/app/components/iron_admin/dashboards/activity_feed_component.html.haml +6 -5
- data/app/components/iron_admin/dashboards/activity_feed_component.rb +21 -24
- data/app/components/iron_admin/dashboards/chart_component.html.haml +3 -5
- data/app/components/iron_admin/dashboards/chart_component.rb +86 -24
- data/app/components/iron_admin/dashboards/concerns/themed_card.rb +39 -0
- data/app/components/iron_admin/dashboards/metric_card_component.html.haml +8 -7
- data/app/components/iron_admin/dashboards/metric_card_component.rb +2 -0
- data/app/components/iron_admin/dashboards/progress_component.html.haml +11 -7
- data/app/components/iron_admin/dashboards/progress_component.rb +11 -6
- data/app/components/iron_admin/dashboards/quick_links_component/link_component.html.haml +8 -9
- data/app/components/iron_admin/dashboards/quick_links_component.html.haml +6 -5
- data/app/components/iron_admin/dashboards/quick_links_component.rb +4 -12
- data/app/components/iron_admin/dashboards/recent_table_component.html.haml +15 -10
- data/app/components/iron_admin/dashboards/recent_table_component.rb +49 -0
- data/app/components/iron_admin/dashboards/stats_grid_component/stat_component.html.haml +13 -14
- data/app/components/iron_admin/dashboards/stats_grid_component.html.haml +1 -0
- data/app/components/iron_admin/dashboards/stats_grid_component.rb +9 -11
- data/app/components/iron_admin/filters/bar_component.html.haml +8 -6
- data/app/components/iron_admin/filters/bar_component.rb +56 -9
- data/app/components/iron_admin/filters/control_styles.rb +82 -0
- data/app/components/iron_admin/filters/date_range_component.html.haml +9 -4
- data/app/components/iron_admin/filters/date_range_component.rb +10 -6
- data/app/components/iron_admin/filters/search_component.html.haml +4 -4
- data/app/components/iron_admin/filters/search_component.rb +3 -5
- data/app/components/iron_admin/filters/select_filter_component.html.haml +1 -1
- data/app/components/iron_admin/filters/select_filter_component.rb +5 -16
- data/app/components/iron_admin/form/belongs_to_autocomplete_component.html.haml +9 -5
- data/app/components/iron_admin/form/belongs_to_autocomplete_component.rb +10 -8
- data/app/components/iron_admin/form/belongs_to_component.html.haml +2 -2
- data/app/components/iron_admin/form/belongs_to_component.rb +4 -18
- data/app/components/iron_admin/form/checkbox_component.rb +2 -3
- data/app/components/iron_admin/form/concerns/form_input_behavior.rb +1 -1
- data/app/components/iron_admin/form/control_classes.rb +108 -0
- data/app/components/iron_admin/form/date_picker_component.rb +3 -7
- data/app/components/iron_admin/form/field_wrapper_component.html.haml +3 -3
- data/app/components/iron_admin/form/field_wrapper_component.rb +3 -3
- data/app/components/iron_admin/form/nested_form_component.html.haml +4 -5
- data/app/components/iron_admin/form/nested_form_component.rb +12 -2
- data/app/components/iron_admin/form/select_component.html.haml +1 -1
- data/app/components/iron_admin/form/select_component.rb +2 -16
- data/app/components/iron_admin/form/text_input_component.rb +1 -5
- data/app/components/iron_admin/form/textarea_component.rb +1 -5
- data/app/components/iron_admin/layout/flash_component.html.haml +1 -1
- data/app/components/iron_admin/layout/flash_component.rb +4 -3
- data/app/components/iron_admin/layout/navbar_component.html.haml +15 -9
- data/app/components/iron_admin/layout/navbar_component.rb +29 -1
- data/app/components/iron_admin/layout/shell_component.html.haml +4 -4
- data/app/components/iron_admin/layout/shell_component.rb +16 -3
- data/app/components/iron_admin/layout/sidebar_component.html.haml +21 -25
- data/app/components/iron_admin/layout/sidebar_component.rb +76 -1
- data/app/components/iron_admin/layout/theme_switcher_component.html.haml +15 -0
- data/app/components/iron_admin/layout/theme_switcher_component.rb +74 -0
- data/app/components/iron_admin/resources/actions_component.html.haml +15 -8
- data/app/components/iron_admin/resources/actions_component.rb +34 -2
- data/app/components/iron_admin/resources/breadcrumb_component.html.haml +3 -3
- data/app/components/iron_admin/resources/breadcrumb_component.rb +8 -7
- data/app/components/iron_admin/resources/bulk_actions_component.html.haml +9 -8
- data/app/components/iron_admin/resources/bulk_actions_component.rb +47 -4
- data/app/components/iron_admin/resources/data_table_component.html.haml +15 -15
- data/app/components/iron_admin/resources/data_table_component.rb +34 -3
- data/app/components/iron_admin/resources/related_list_component.html.haml +7 -7
- data/app/components/iron_admin/resources/related_list_component.rb +26 -2
- data/app/components/iron_admin/resources/show_field_component.html.haml +3 -3
- data/app/components/iron_admin/resources/show_field_component.rb +10 -4
- data/app/components/iron_admin/resources/styles.rb +136 -0
- data/app/components/iron_admin/ui/alert_component.html.haml +2 -2
- data/app/components/iron_admin/ui/alert_component.rb +27 -31
- data/app/components/iron_admin/ui/badge_component.rb +40 -20
- data/app/components/iron_admin/ui/button_component.rb +37 -11
- data/app/components/iron_admin/ui/card_component.rb +3 -3
- data/app/components/iron_admin/ui/dropdown_component.html.haml +1 -1
- data/app/components/iron_admin/ui/dropdown_component.rb +34 -13
- data/app/components/iron_admin/ui/empty_state_component.html.haml +4 -5
- data/app/components/iron_admin/ui/empty_state_component.rb +2 -2
- data/app/components/iron_admin/ui/modal_component.html.haml +5 -5
- data/app/components/iron_admin/ui/modal_component.rb +6 -4
- data/app/components/iron_admin/ui/pagination_component.html.haml +14 -14
- data/app/components/iron_admin/ui/pagination_component.rb +26 -9
- data/app/components/iron_admin/ui/scopes_component.html.haml +2 -2
- data/app/components/iron_admin/ui/scopes_component.rb +44 -11
- data/app/components/iron_admin/ui/tooltip_component.rb +11 -4
- data/app/controllers/iron_admin/application_controller.rb +58 -4
- data/app/controllers/iron_admin/audit_controller.rb +30 -6
- data/app/controllers/iron_admin/concerns/action_executable.rb +37 -0
- data/app/controllers/iron_admin/concerns/assignable_references.rb +149 -0
- data/app/controllers/iron_admin/concerns/authorizable.rb +11 -0
- data/app/controllers/iron_admin/concerns/blank_password_filterable.rb +21 -0
- data/app/controllers/iron_admin/concerns/event_emittable.rb +47 -7
- data/app/controllers/iron_admin/concerns/filterable.rb +34 -9
- data/app/controllers/iron_admin/concerns/nested_permittable.rb +5 -3
- data/app/controllers/iron_admin/concerns/nested_tenant_check.rb +159 -0
- data/app/controllers/iron_admin/concerns/polymorphic_references.rb +131 -0
- data/app/controllers/iron_admin/concerns/scopeable.rb +54 -7
- data/app/controllers/iron_admin/concerns/searchable.rb +3 -3
- data/app/controllers/iron_admin/concerns/tenant_assignable.rb +118 -0
- data/app/controllers/iron_admin/concerns/tenant_containment.rb +146 -0
- data/app/controllers/iron_admin/exports_controller.rb +2 -2
- data/app/controllers/iron_admin/imports_controller.rb +1 -1
- data/app/controllers/iron_admin/resources_controller.rb +48 -41
- data/app/controllers/iron_admin/search_controller.rb +1 -2
- data/app/controllers/iron_admin/themes_controller.rb +50 -0
- data/app/controllers/iron_admin/tools_controller.rb +58 -5
- data/app/helpers/iron_admin/action_form_helper.rb +19 -0
- data/app/helpers/iron_admin/application_helper.rb +93 -16
- data/app/helpers/iron_admin/assignable_records_helper.rb +32 -0
- data/app/helpers/iron_admin/component_overrides_helper.rb +9 -4
- data/app/helpers/iron_admin/field_display_helper.rb +88 -43
- data/app/helpers/iron_admin/related_records_helper.rb +51 -0
- data/app/helpers/iron_admin/theme_helper.rb +56 -46
- data/app/javascript/iron_admin/controllers/cp_bulk_select_controller.js +12 -0
- data/app/javascript/iron_admin/controllers/cp_chart_controller.js +4 -0
- data/app/javascript/iron_admin/controllers/cp_disclosure_controller.js +19 -0
- data/app/javascript/iron_admin/controllers/cp_search_shortcut_controller.js +39 -0
- data/app/javascript/iron_admin/index.js +4 -0
- data/app/views/iron_admin/audit/index.html.haml +78 -81
- data/app/views/iron_admin/dashboard/index.html.haml +10 -9
- data/app/views/iron_admin/form/_action_field.html.haml +50 -0
- data/app/views/iron_admin/form/_nested_row.html.haml +18 -13
- data/app/views/iron_admin/imports/new.html.haml +14 -13
- data/app/views/iron_admin/imports/preview.html.haml +24 -21
- data/app/views/iron_admin/resources/_form.html.haml +70 -68
- data/app/views/iron_admin/resources/action_form.html.haml +16 -59
- data/app/views/iron_admin/resources/bulk_action_form.html.haml +20 -58
- data/app/views/iron_admin/resources/edit.html.haml +3 -3
- data/app/views/iron_admin/resources/index.html.haml +87 -74
- data/app/views/iron_admin/resources/new.html.haml +2 -2
- data/app/views/iron_admin/resources/show.html.haml +53 -41
- data/app/views/iron_admin/search/index.html.haml +17 -9
- data/app/views/iron_admin/shared/_pagination.html.haml +13 -10
- data/app/views/iron_admin/shared/error.html.haml +16 -12
- data/app/views/iron_admin/tools/action_form.html.haml +9 -55
- data/app/views/iron_admin/tools/show.html.haml +4 -5
- data/app/views/layouts/iron_admin/_document_head.html.haml +24 -0
- data/app/views/layouts/iron_admin/application.html.haml +4 -17
- data/app/views/layouts/iron_admin/minimal.html.haml +7 -0
- data/config/importmap.rb +2 -0
- data/config/locales/en.yml +23 -0
- data/config/routes.rb +1 -0
- data/docs/FAQ.md +87 -37
- data/docs/README.md +8 -2
- data/docs/components/README.md +6 -2
- data/docs/components/dashboard-components.md +24 -35
- data/docs/components/filter-components.md +44 -92
- data/docs/components/form-components.md +16 -32
- data/docs/components/resource-components.md +46 -27
- data/docs/components/ui-components.md +44 -26
- data/docs/getting-started/installation.md +5 -1
- data/docs/getting-started/quick-start.md +36 -23
- data/docs/guides/authentication.md +182 -42
- data/docs/guides/components.md +97 -15
- data/docs/guides/custom-adapters.md +24 -4
- data/docs/guides/dashboard.md +68 -44
- data/docs/guides/export.md +24 -8
- data/docs/guides/extending.md +206 -51
- data/docs/guides/fields.md +229 -70
- data/docs/guides/imports.md +33 -18
- data/docs/guides/resources.md +333 -111
- data/docs/guides/theming.md +930 -58
- data/docs/guides/troubleshooting.md +7 -3
- data/docs/plugin-system-design.md +8 -7
- data/docs/reference/configuration.md +51 -16
- data/docs/reference/routes.md +1 -0
- data/docs/reference/theme-properties.md +101 -38
- data/lib/generators/iron_admin/install/templates/initializer.rb.tt +7 -2
- data/lib/generators/iron_admin/install_audit/templates/create_iron_admin_audit_entries.rb.tt +2 -0
- data/lib/iron_admin/action_field.rb +11 -0
- data/lib/iron_admin/adapters/active_record.rb +95 -0
- data/lib/iron_admin/adapters/base.rb +107 -0
- data/lib/iron_admin/adapters/http/query.rb +21 -0
- data/lib/iron_admin/adapters/http.rb +84 -4
- data/lib/iron_admin/adapters/mongoid.rb +96 -2
- data/lib/iron_admin/audit_log.rb +64 -6
- data/lib/iron_admin/authentication_warning.rb +31 -0
- data/lib/iron_admin/concerns/filter_definable.rb +15 -1
- data/lib/iron_admin/concerns/nestable.rb +25 -0
- data/lib/iron_admin/concerns/scope_countable.rb +56 -0
- data/lib/iron_admin/concerns/soft_deletable.rb +28 -9
- data/lib/iron_admin/configuration/components.rb +14 -3
- data/lib/iron_admin/configuration/theme/neutral_defaults.rb +179 -0
- data/lib/iron_admin/configuration/theme.rb +292 -87
- data/lib/iron_admin/configuration.rb +340 -45
- data/lib/iron_admin/dashboard.rb +22 -38
- data/lib/iron_admin/engine.rb +16 -2
- data/lib/iron_admin/errors.rb +3 -0
- data/lib/iron_admin/field.rb +78 -17
- data/lib/iron_admin/field_inferrer.rb +61 -3
- data/lib/iron_admin/field_override_warning.rb +67 -0
- data/lib/iron_admin/import/import_preview.rb +56 -7
- data/lib/iron_admin/import/importer.rb +91 -14
- data/lib/iron_admin/import/tenant_precheck.rb +67 -0
- data/lib/iron_admin/plugin/registration.rb +64 -0
- data/lib/iron_admin/plugin_registry.rb +3 -2
- data/lib/iron_admin/policy.rb +22 -12
- data/lib/iron_admin/policy_coverage_warning.rb +46 -0
- data/lib/iron_admin/request_context.rb +18 -0
- data/lib/iron_admin/resource.rb +218 -77
- data/lib/iron_admin/resource_registry.rb +86 -13
- data/lib/iron_admin/scope_counts.rb +73 -0
- data/lib/iron_admin/tenant_scope.rb +30 -0
- data/lib/iron_admin/tool.rb +61 -12
- data/lib/iron_admin/tool_context.rb +10 -6
- data/lib/iron_admin/version.rb +1 -1
- data/lib/iron_admin.rb +29 -2
- metadata +37 -7
|
@@ -4,12 +4,15 @@ Core UI elements for building admin interfaces.
|
|
|
4
4
|
|
|
5
5
|
## BadgeComponent
|
|
6
6
|
|
|
7
|
-
Displays status
|
|
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
|
|
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
|
-
|
|
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,
|
|
261
|
-
current_scope: "all",
|
|
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:
|
|
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
|
-
|
|
279
|
-
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
58
|
-
|
|
59
|
-
|
|
64
|
+
searchable :name, :email
|
|
65
|
+
filter :role, type: :select, options: User.roles.keys
|
|
66
|
+
filter :created_at, type: :date_range
|
|
60
67
|
|
|
61
|
-
|
|
62
|
-
|
|
68
|
+
scope :admins, -> { where(role: :admin) }
|
|
69
|
+
scope :recent, -> { where("created_at > ?", 7.days.ago) }
|
|
63
70
|
|
|
64
|
-
|
|
65
|
-
|
|
71
|
+
index_fields :id, :name, :email, :role, :created_at
|
|
72
|
+
form_fields :name, :email, :role
|
|
66
73
|
|
|
67
|
-
|
|
74
|
+
menu priority: 1, icon: "users", group: "People"
|
|
68
75
|
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
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
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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,
|
|
87
|
-
| `:update` | Edit and
|
|
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
|
|
121
|
-
deny :destroy, if: ->(user) { !user
|
|
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
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
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
|
-
|
|
156
|
-
|
|
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
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
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
|
-
|
|
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`)
|
|
181
|
-
is
|
|
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
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
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
|
-
|
|
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)).
|