iron_admin 0.7.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +129 -1
- data/README.md +48 -1
- data/UPGRADING.md +495 -8
- data/app/assets/tailwind/iron_admin/engine.css +79 -4
- data/app/components/iron_admin/dashboards/activity_feed_component/item_component.html.haml +6 -9
- data/app/components/iron_admin/dashboards/activity_feed_component.html.haml +6 -5
- data/app/components/iron_admin/dashboards/activity_feed_component.rb +21 -24
- data/app/components/iron_admin/dashboards/chart_component.html.haml +3 -5
- data/app/components/iron_admin/dashboards/chart_component.rb +86 -24
- data/app/components/iron_admin/dashboards/concerns/themed_card.rb +39 -0
- data/app/components/iron_admin/dashboards/metric_card_component.html.haml +8 -7
- data/app/components/iron_admin/dashboards/metric_card_component.rb +2 -0
- data/app/components/iron_admin/dashboards/progress_component.html.haml +11 -7
- data/app/components/iron_admin/dashboards/progress_component.rb +11 -6
- data/app/components/iron_admin/dashboards/quick_links_component/link_component.html.haml +8 -9
- data/app/components/iron_admin/dashboards/quick_links_component.html.haml +6 -5
- data/app/components/iron_admin/dashboards/quick_links_component.rb +4 -12
- data/app/components/iron_admin/dashboards/recent_table_component.html.haml +15 -10
- data/app/components/iron_admin/dashboards/recent_table_component.rb +49 -0
- data/app/components/iron_admin/dashboards/stats_grid_component/stat_component.html.haml +13 -14
- data/app/components/iron_admin/dashboards/stats_grid_component.html.haml +1 -0
- data/app/components/iron_admin/dashboards/stats_grid_component.rb +9 -11
- data/app/components/iron_admin/filters/bar_component.html.haml +8 -6
- data/app/components/iron_admin/filters/bar_component.rb +56 -9
- data/app/components/iron_admin/filters/control_styles.rb +82 -0
- data/app/components/iron_admin/filters/date_range_component.html.haml +9 -4
- data/app/components/iron_admin/filters/date_range_component.rb +10 -6
- data/app/components/iron_admin/filters/search_component.html.haml +4 -4
- data/app/components/iron_admin/filters/search_component.rb +3 -5
- data/app/components/iron_admin/filters/select_filter_component.html.haml +1 -1
- data/app/components/iron_admin/filters/select_filter_component.rb +5 -16
- data/app/components/iron_admin/form/belongs_to_autocomplete_component.html.haml +9 -5
- data/app/components/iron_admin/form/belongs_to_autocomplete_component.rb +10 -8
- data/app/components/iron_admin/form/belongs_to_component.html.haml +2 -2
- data/app/components/iron_admin/form/belongs_to_component.rb +4 -18
- data/app/components/iron_admin/form/checkbox_component.rb +2 -3
- data/app/components/iron_admin/form/concerns/form_input_behavior.rb +1 -1
- data/app/components/iron_admin/form/control_classes.rb +108 -0
- data/app/components/iron_admin/form/date_picker_component.rb +3 -7
- data/app/components/iron_admin/form/field_wrapper_component.html.haml +3 -3
- data/app/components/iron_admin/form/field_wrapper_component.rb +3 -3
- data/app/components/iron_admin/form/nested_form_component.html.haml +4 -5
- data/app/components/iron_admin/form/nested_form_component.rb +12 -2
- data/app/components/iron_admin/form/select_component.html.haml +1 -1
- data/app/components/iron_admin/form/select_component.rb +2 -16
- data/app/components/iron_admin/form/text_input_component.rb +1 -5
- data/app/components/iron_admin/form/textarea_component.rb +1 -5
- data/app/components/iron_admin/layout/flash_component.html.haml +1 -1
- data/app/components/iron_admin/layout/flash_component.rb +4 -3
- data/app/components/iron_admin/layout/navbar_component.html.haml +15 -9
- data/app/components/iron_admin/layout/navbar_component.rb +29 -1
- data/app/components/iron_admin/layout/shell_component.html.haml +4 -4
- data/app/components/iron_admin/layout/shell_component.rb +16 -3
- data/app/components/iron_admin/layout/sidebar_component.html.haml +21 -25
- data/app/components/iron_admin/layout/sidebar_component.rb +76 -1
- data/app/components/iron_admin/layout/theme_switcher_component.html.haml +15 -0
- data/app/components/iron_admin/layout/theme_switcher_component.rb +74 -0
- data/app/components/iron_admin/resources/actions_component.html.haml +15 -8
- data/app/components/iron_admin/resources/actions_component.rb +34 -2
- data/app/components/iron_admin/resources/breadcrumb_component.html.haml +3 -3
- data/app/components/iron_admin/resources/breadcrumb_component.rb +8 -7
- data/app/components/iron_admin/resources/bulk_actions_component.html.haml +9 -8
- data/app/components/iron_admin/resources/bulk_actions_component.rb +47 -4
- data/app/components/iron_admin/resources/data_table_component.html.haml +15 -15
- data/app/components/iron_admin/resources/data_table_component.rb +34 -3
- data/app/components/iron_admin/resources/related_list_component.html.haml +7 -7
- data/app/components/iron_admin/resources/related_list_component.rb +26 -2
- data/app/components/iron_admin/resources/show_field_component.html.haml +3 -3
- data/app/components/iron_admin/resources/show_field_component.rb +10 -4
- data/app/components/iron_admin/resources/styles.rb +136 -0
- data/app/components/iron_admin/ui/alert_component.html.haml +2 -2
- data/app/components/iron_admin/ui/alert_component.rb +27 -31
- data/app/components/iron_admin/ui/badge_component.rb +40 -20
- data/app/components/iron_admin/ui/button_component.rb +37 -11
- data/app/components/iron_admin/ui/card_component.rb +3 -3
- data/app/components/iron_admin/ui/dropdown_component.html.haml +1 -1
- data/app/components/iron_admin/ui/dropdown_component.rb +34 -13
- data/app/components/iron_admin/ui/empty_state_component.html.haml +4 -5
- data/app/components/iron_admin/ui/empty_state_component.rb +2 -2
- data/app/components/iron_admin/ui/modal_component.html.haml +5 -5
- data/app/components/iron_admin/ui/modal_component.rb +6 -4
- data/app/components/iron_admin/ui/pagination_component.html.haml +14 -14
- data/app/components/iron_admin/ui/pagination_component.rb +26 -9
- data/app/components/iron_admin/ui/scopes_component.html.haml +2 -2
- data/app/components/iron_admin/ui/scopes_component.rb +44 -11
- data/app/components/iron_admin/ui/tooltip_component.rb +11 -4
- data/app/controllers/iron_admin/application_controller.rb +58 -4
- data/app/controllers/iron_admin/audit_controller.rb +30 -6
- data/app/controllers/iron_admin/concerns/action_executable.rb +37 -0
- data/app/controllers/iron_admin/concerns/assignable_references.rb +149 -0
- data/app/controllers/iron_admin/concerns/authorizable.rb +11 -0
- data/app/controllers/iron_admin/concerns/blank_password_filterable.rb +21 -0
- data/app/controllers/iron_admin/concerns/event_emittable.rb +47 -7
- data/app/controllers/iron_admin/concerns/filterable.rb +34 -9
- data/app/controllers/iron_admin/concerns/nested_permittable.rb +5 -3
- data/app/controllers/iron_admin/concerns/nested_tenant_check.rb +159 -0
- data/app/controllers/iron_admin/concerns/polymorphic_references.rb +131 -0
- data/app/controllers/iron_admin/concerns/scopeable.rb +54 -7
- data/app/controllers/iron_admin/concerns/searchable.rb +3 -3
- data/app/controllers/iron_admin/concerns/tenant_assignable.rb +118 -0
- data/app/controllers/iron_admin/concerns/tenant_containment.rb +146 -0
- data/app/controllers/iron_admin/exports_controller.rb +2 -2
- data/app/controllers/iron_admin/imports_controller.rb +1 -1
- data/app/controllers/iron_admin/resources_controller.rb +48 -41
- data/app/controllers/iron_admin/search_controller.rb +1 -2
- data/app/controllers/iron_admin/themes_controller.rb +50 -0
- data/app/controllers/iron_admin/tools_controller.rb +58 -5
- data/app/helpers/iron_admin/action_form_helper.rb +19 -0
- data/app/helpers/iron_admin/application_helper.rb +93 -16
- data/app/helpers/iron_admin/assignable_records_helper.rb +32 -0
- data/app/helpers/iron_admin/component_overrides_helper.rb +9 -4
- data/app/helpers/iron_admin/field_display_helper.rb +88 -43
- data/app/helpers/iron_admin/related_records_helper.rb +51 -0
- data/app/helpers/iron_admin/theme_helper.rb +56 -46
- data/app/javascript/iron_admin/controllers/cp_bulk_select_controller.js +12 -0
- data/app/javascript/iron_admin/controllers/cp_chart_controller.js +4 -0
- data/app/javascript/iron_admin/controllers/cp_disclosure_controller.js +19 -0
- data/app/javascript/iron_admin/controllers/cp_search_shortcut_controller.js +39 -0
- data/app/javascript/iron_admin/index.js +4 -0
- data/app/views/iron_admin/audit/index.html.haml +78 -81
- data/app/views/iron_admin/dashboard/index.html.haml +10 -9
- data/app/views/iron_admin/form/_action_field.html.haml +50 -0
- data/app/views/iron_admin/form/_nested_row.html.haml +18 -13
- data/app/views/iron_admin/imports/new.html.haml +14 -13
- data/app/views/iron_admin/imports/preview.html.haml +24 -21
- data/app/views/iron_admin/resources/_form.html.haml +70 -68
- data/app/views/iron_admin/resources/action_form.html.haml +16 -59
- data/app/views/iron_admin/resources/bulk_action_form.html.haml +20 -58
- data/app/views/iron_admin/resources/edit.html.haml +3 -3
- data/app/views/iron_admin/resources/index.html.haml +87 -74
- data/app/views/iron_admin/resources/new.html.haml +2 -2
- data/app/views/iron_admin/resources/show.html.haml +53 -41
- data/app/views/iron_admin/search/index.html.haml +17 -9
- data/app/views/iron_admin/shared/_pagination.html.haml +13 -10
- data/app/views/iron_admin/shared/error.html.haml +16 -12
- data/app/views/iron_admin/tools/action_form.html.haml +9 -55
- data/app/views/iron_admin/tools/show.html.haml +4 -5
- data/app/views/layouts/iron_admin/_document_head.html.haml +24 -0
- data/app/views/layouts/iron_admin/application.html.haml +4 -17
- data/app/views/layouts/iron_admin/minimal.html.haml +7 -0
- data/config/importmap.rb +2 -0
- data/config/locales/en.yml +23 -0
- data/config/routes.rb +1 -0
- data/docs/FAQ.md +87 -37
- data/docs/README.md +8 -2
- data/docs/components/README.md +6 -2
- data/docs/components/dashboard-components.md +24 -35
- data/docs/components/filter-components.md +44 -92
- data/docs/components/form-components.md +16 -32
- data/docs/components/resource-components.md +46 -27
- data/docs/components/ui-components.md +44 -26
- data/docs/getting-started/installation.md +5 -1
- data/docs/getting-started/quick-start.md +36 -23
- data/docs/guides/authentication.md +182 -42
- data/docs/guides/components.md +97 -15
- data/docs/guides/custom-adapters.md +24 -4
- data/docs/guides/dashboard.md +68 -44
- data/docs/guides/export.md +24 -8
- data/docs/guides/extending.md +206 -51
- data/docs/guides/fields.md +229 -70
- data/docs/guides/imports.md +33 -18
- data/docs/guides/resources.md +333 -111
- data/docs/guides/theming.md +930 -58
- data/docs/guides/troubleshooting.md +7 -3
- data/docs/plugin-system-design.md +8 -7
- data/docs/reference/configuration.md +51 -16
- data/docs/reference/routes.md +1 -0
- data/docs/reference/theme-properties.md +101 -38
- data/lib/generators/iron_admin/install/templates/initializer.rb.tt +7 -2
- data/lib/generators/iron_admin/install_audit/templates/create_iron_admin_audit_entries.rb.tt +2 -0
- data/lib/iron_admin/action_field.rb +11 -0
- data/lib/iron_admin/adapters/active_record.rb +95 -0
- data/lib/iron_admin/adapters/base.rb +107 -0
- data/lib/iron_admin/adapters/http/query.rb +21 -0
- data/lib/iron_admin/adapters/http.rb +84 -4
- data/lib/iron_admin/adapters/mongoid.rb +96 -2
- data/lib/iron_admin/audit_log.rb +64 -6
- data/lib/iron_admin/authentication_warning.rb +31 -0
- data/lib/iron_admin/concerns/filter_definable.rb +15 -1
- data/lib/iron_admin/concerns/nestable.rb +25 -0
- data/lib/iron_admin/concerns/scope_countable.rb +56 -0
- data/lib/iron_admin/concerns/soft_deletable.rb +28 -9
- data/lib/iron_admin/configuration/components.rb +14 -3
- data/lib/iron_admin/configuration/theme/neutral_defaults.rb +179 -0
- data/lib/iron_admin/configuration/theme.rb +292 -87
- data/lib/iron_admin/configuration.rb +340 -45
- data/lib/iron_admin/dashboard.rb +22 -38
- data/lib/iron_admin/engine.rb +16 -2
- data/lib/iron_admin/errors.rb +3 -0
- data/lib/iron_admin/field.rb +78 -17
- data/lib/iron_admin/field_inferrer.rb +61 -3
- data/lib/iron_admin/field_override_warning.rb +67 -0
- data/lib/iron_admin/import/import_preview.rb +56 -7
- data/lib/iron_admin/import/importer.rb +91 -14
- data/lib/iron_admin/import/tenant_precheck.rb +67 -0
- data/lib/iron_admin/plugin/registration.rb +64 -0
- data/lib/iron_admin/plugin_registry.rb +3 -2
- data/lib/iron_admin/policy.rb +22 -12
- data/lib/iron_admin/policy_coverage_warning.rb +46 -0
- data/lib/iron_admin/request_context.rb +18 -0
- data/lib/iron_admin/resource.rb +218 -77
- data/lib/iron_admin/resource_registry.rb +86 -13
- data/lib/iron_admin/scope_counts.rb +73 -0
- data/lib/iron_admin/tenant_scope.rb +30 -0
- data/lib/iron_admin/tool.rb +61 -12
- data/lib/iron_admin/tool_context.rb +10 -6
- data/lib/iron_admin/version.rb +1 -1
- data/lib/iron_admin.rb +29 -2
- metadata +37 -7
data/docs/guides/extending.md
CHANGED
|
@@ -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** -
|
|
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
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
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
|
-
|
|
87
|
-
|
|
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
|
-
|
|
114
|
+
around_action :switch_iron_admin_time_zone
|
|
99
115
|
|
|
100
116
|
private
|
|
101
117
|
|
|
102
|
-
def
|
|
103
|
-
|
|
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
|
-
|
|
130
|
-
|
|
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`)
|
|
140
|
-
the
|
|
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
|
-
|
|
151
|
-
|
|
152
|
-
|
|
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
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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
|
-
|
|
161
|
-
|
|
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
|
|
184
|
-
|
|
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 { "★" }.join.html_safe
|
|
254
|
+
value.to_i.clamp(0, 5).times.map { "★" }.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
|
-
|
|
193
|
-
|
|
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
|
-
|
|
197
|
-
|
|
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
|
-
|
|
200
|
-
|
|
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
|
-
|
|
208
|
-
|
|
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)` |
|
|
219
|
-
| `form_partial(path)` | Partial path to render on forms
|
|
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:**
|
|
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`.
|
|
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
|
-
|
|
445
|
-
|
|
446
|
-
|
|
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(
|
|
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
|
-
|
|
467
|
-
expect(
|
|
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
|
```
|