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/resources.md
CHANGED
|
@@ -11,31 +11,51 @@ rails generate iron_admin:resource User
|
|
|
11
11
|
Creates `app/iron_admin/resources/user_resource.rb`:
|
|
12
12
|
|
|
13
13
|
```ruby
|
|
14
|
-
|
|
14
|
+
module IronAdmin
|
|
15
|
+
module Resources
|
|
16
|
+
class UserResource < IronAdmin::Resource
|
|
17
|
+
end
|
|
18
|
+
end
|
|
15
19
|
end
|
|
16
20
|
```
|
|
17
21
|
|
|
18
22
|
By convention, `UserResource` maps to the `User` model. To override:
|
|
19
23
|
|
|
20
24
|
```ruby
|
|
21
|
-
|
|
22
|
-
|
|
25
|
+
module IronAdmin
|
|
26
|
+
module Resources
|
|
27
|
+
class UserResource < IronAdmin::Resource
|
|
28
|
+
self.model_class_override = Account
|
|
29
|
+
end
|
|
30
|
+
end
|
|
23
31
|
end
|
|
24
32
|
```
|
|
25
33
|
|
|
34
|
+
The admin URL is `resource_name`. A resource whose model is the one its class name implies (`UserResource` → `User`, `Billing::InvoiceResource` → `Billing::Invoice`) keeps the model's plural, so those names and URLs stay. An override of that same model is the same case: `InvoiceResource` with `self.model_class_override = ::Invoice` keeps `Invoice`'s plural, including a custom `model_name`. Setting the override to a different model derives the name from the full class path under `IronAdmin::Resources`, so a `UserResource` that points at `Account` is still `/admin/users`, not `/admin/accounts`. A namespaced override keeps the namespace: `Shop::NoteResource` is `/admin/shop_notes` and `Archive::NoteResource` is `/admin/archive_notes`. A resource that overrides `self.model` is named the same way, so it does not take the model's plural and hide the canonical resource. To choose a name, define the reader. There is no writer:
|
|
35
|
+
|
|
36
|
+
```ruby
|
|
37
|
+
def self.resource_name = "archived_notes"
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Two resources that still compute the same name: the first one registered answers that URL and the other is logged.
|
|
41
|
+
|
|
26
42
|
## Fields
|
|
27
43
|
|
|
28
44
|
Fields are automatically inferred from the database schema. Override specific fields:
|
|
29
45
|
|
|
30
46
|
```ruby
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
47
|
+
module IronAdmin
|
|
48
|
+
module Resources
|
|
49
|
+
class UserResource < IronAdmin::Resource
|
|
50
|
+
field :status, type: :badge, colors: { active: :green, suspended: :red }
|
|
51
|
+
field :bio, type: :textarea
|
|
52
|
+
field :role, type: :select, choices: %w[user admin]
|
|
53
|
+
field :secret, visible: false
|
|
54
|
+
field :email, readonly: true
|
|
55
|
+
field :admin_notes, visible: ->(user) { user.admin? }
|
|
56
|
+
field :salary, readonly: ->(user) { !user.admin? }
|
|
57
|
+
end
|
|
58
|
+
end
|
|
39
59
|
end
|
|
40
60
|
```
|
|
41
61
|
|
|
@@ -52,10 +72,14 @@ end
|
|
|
52
72
|
### Controlling Field Visibility per View
|
|
53
73
|
|
|
54
74
|
```ruby
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
75
|
+
module IronAdmin
|
|
76
|
+
module Resources
|
|
77
|
+
class UserResource < IronAdmin::Resource
|
|
78
|
+
index_fields :id, :name, :email, :role, :created_at
|
|
79
|
+
form_fields :role, :name, :email
|
|
80
|
+
export_fields :id, :name, :email, :role
|
|
81
|
+
end
|
|
82
|
+
end
|
|
59
83
|
end
|
|
60
84
|
```
|
|
61
85
|
|
|
@@ -66,8 +90,12 @@ not resolve to a field (for example a has_many such as `:comments`) are ignored.
|
|
|
66
90
|
## Search
|
|
67
91
|
|
|
68
92
|
```ruby
|
|
69
|
-
|
|
70
|
-
|
|
93
|
+
module IronAdmin
|
|
94
|
+
module Resources
|
|
95
|
+
class UserResource < IronAdmin::Resource
|
|
96
|
+
searchable :name, :email
|
|
97
|
+
end
|
|
98
|
+
end
|
|
71
99
|
end
|
|
72
100
|
```
|
|
73
101
|
|
|
@@ -100,10 +128,14 @@ one character at a time.
|
|
|
100
128
|
## Filters
|
|
101
129
|
|
|
102
130
|
```ruby
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
131
|
+
module IronAdmin
|
|
132
|
+
module Resources
|
|
133
|
+
class UserResource < IronAdmin::Resource
|
|
134
|
+
filter :role, type: :select, options: User.roles.keys
|
|
135
|
+
filter :created_at, type: :date_range
|
|
136
|
+
filter :email_verified, type: :boolean
|
|
137
|
+
end
|
|
138
|
+
end
|
|
107
139
|
end
|
|
108
140
|
```
|
|
109
141
|
|
|
@@ -113,6 +145,26 @@ they are declared. A `:select` filter without `options` offers the enum values w
|
|
|
113
145
|
is an enum, and the column's distinct values otherwise, so `filter :role, type: :select` on an
|
|
114
146
|
enum is enough.
|
|
115
147
|
|
|
148
|
+
On the foreign key of a `belongs_to` association, a `:select` filter without `options` offers
|
|
149
|
+
the associated records that some row refers to, labelled like the form's belongs_to select (the
|
|
150
|
+
association's `display:` option, else `name`, `title`, `email`, `label` or `slug`) and limited by
|
|
151
|
+
`tenant_scope`, so `filter :category_id, type: :select` lists category names, not ids. Each
|
|
152
|
+
option's value is the key the foreign key stores: the association's `primary_key:`, else the
|
|
153
|
+
associated record's primary key. The filter keeps offering the column's distinct values when
|
|
154
|
+
the resource has no `belongs_to` field for the column or that field is not visible to the
|
|
155
|
+
current user, so it never shows the labels of an association the resource hides, and when the
|
|
156
|
+
association is declared `autocomplete: true`, so it never loads a table too large for the form to
|
|
157
|
+
list (give that filter `options:` to label it).
|
|
158
|
+
|
|
159
|
+
`options` takes `[label, value]` pairs or bare values, which are labelled by humanizing them.
|
|
160
|
+
It can also be a callable that takes no arguments: IronAdmin calls it each time the index
|
|
161
|
+
renders, so the choices can come from the database without querying when the resource loads.
|
|
162
|
+
Use one to limit the choices of a foreign key filter on a large table:
|
|
163
|
+
|
|
164
|
+
```ruby
|
|
165
|
+
filter :category_id, type: :select, options: -> { Category.where(active: true).order(:name).pluck(:name, :id) }
|
|
166
|
+
```
|
|
167
|
+
|
|
116
168
|
Remove a filter, whether declared or auto-inferred:
|
|
117
169
|
|
|
118
170
|
```ruby
|
|
@@ -140,9 +192,13 @@ on a field the current user cannot see is neither shown nor applied, so a filter
|
|
|
140
192
|
String and number filters provide an operator dropdown alongside the input:
|
|
141
193
|
|
|
142
194
|
```ruby
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
195
|
+
module IronAdmin
|
|
196
|
+
module Resources
|
|
197
|
+
class ProductResource < IronAdmin::Resource
|
|
198
|
+
filter :name, type: :string # contains, equals, starts_with, ends_with
|
|
199
|
+
filter :price, type: :number # equals, greater_than, less_than, between
|
|
200
|
+
end
|
|
201
|
+
end
|
|
146
202
|
end
|
|
147
203
|
```
|
|
148
204
|
|
|
@@ -159,7 +215,11 @@ class Order < ApplicationRecord
|
|
|
159
215
|
end
|
|
160
216
|
|
|
161
217
|
# No filter definition needed - auto-generated from enum
|
|
162
|
-
|
|
218
|
+
module IronAdmin
|
|
219
|
+
module Resources
|
|
220
|
+
class OrderResource < IronAdmin::Resource
|
|
221
|
+
end
|
|
222
|
+
end
|
|
163
223
|
end
|
|
164
224
|
```
|
|
165
225
|
|
|
@@ -172,11 +232,63 @@ and takes the enum values when it has no `options`.
|
|
|
172
232
|
Scopes are predefined query filters shown as tabs:
|
|
173
233
|
|
|
174
234
|
```ruby
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
235
|
+
module IronAdmin
|
|
236
|
+
module Resources
|
|
237
|
+
class UserResource < IronAdmin::Resource
|
|
238
|
+
scope :all, -> { all }, default: true
|
|
239
|
+
scope :admins, -> { where(role: :admin) }
|
|
240
|
+
scope :recent, -> { where("created_at > ?", 7.days.ago) }
|
|
241
|
+
scope :locked, -> { where.not(locked_at: nil) }
|
|
242
|
+
end
|
|
243
|
+
end
|
|
244
|
+
end
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Switching tabs keeps the search, the active filters and the sort, and starts back at the first
|
|
248
|
+
page.
|
|
249
|
+
|
|
250
|
+
A scope body that returns `nil` or `false`, such as
|
|
251
|
+
`scope :mine, -> { where(user_id: Current.user.id) if Current.user }`, lists every record, as
|
|
252
|
+
Active Record's own `scope` does. Its tab shows no count.
|
|
253
|
+
|
|
254
|
+
A tab can show how many records it would list. That number is the index for that tab: the
|
|
255
|
+
tenant scope, the current filters, that tab's own scope and the current search. It ignores the
|
|
256
|
+
tab you are on and the page you are on. Zero is shown as zero. A scope with `count: false`
|
|
257
|
+
shows no number, and neither does a count the adapter cannot know (an HTTP response with no
|
|
258
|
+
exact total is left blank, not shown as zero). A count that raises is logged and omitted,
|
|
259
|
+
so the other tabs still render. On PostgreSQL a failing count inside an open transaction,
|
|
260
|
+
including a transactional test, aborts the transaction, and a later query on the page raises
|
|
261
|
+
`PG::InFailedSqlTransaction`. Each counted scope on an HTTP resource sends one
|
|
262
|
+
more unpaginated list request on every index view, even when the response has no
|
|
263
|
+
`meta.total`. Without `meta.total` the tab shows its name and no number. Set
|
|
264
|
+
`scope_counts false` on an HTTP resource whose API returns no total.
|
|
265
|
+
|
|
266
|
+
Each counted scope costs one query on the index. On ActiveRecord, the `with_deleted` and
|
|
267
|
+
`only_deleted` tabs are counted too, one query each. Only `scope_counts false` on the resource
|
|
268
|
+
turns those off. Other adapters do not count those two tabs. With the feature off, the index
|
|
269
|
+
runs no extra query. It is off unless you turn it on:
|
|
270
|
+
|
|
271
|
+
```ruby
|
|
272
|
+
IronAdmin.configure do |config|
|
|
273
|
+
config.scope_counts = true
|
|
274
|
+
end
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
A resource overrides the global setting. `scope_counts` (or `scope_counts true`) turns its
|
|
278
|
+
counts on when the global setting is off, and `scope_counts false` turns them off when the
|
|
279
|
+
global setting is on.
|
|
280
|
+
Leave the call out to follow the global setting.
|
|
281
|
+
|
|
282
|
+
```ruby
|
|
283
|
+
module IronAdmin
|
|
284
|
+
module Resources
|
|
285
|
+
class UserResource < IronAdmin::Resource
|
|
286
|
+
scope_counts true
|
|
287
|
+
|
|
288
|
+
scope :active, -> { where(active: true) }, default: true
|
|
289
|
+
scope :archived, -> { where(archived: true) }, count: false
|
|
290
|
+
end
|
|
291
|
+
end
|
|
180
292
|
end
|
|
181
293
|
```
|
|
182
294
|
|
|
@@ -184,15 +296,22 @@ end
|
|
|
184
296
|
|
|
185
297
|
IronAdmin auto-detects models with a `deleted_at` column and provides:
|
|
186
298
|
|
|
187
|
-
- **Auto-registered scopes**: `with_deleted` and `only_deleted
|
|
299
|
+
- **Auto-registered scopes**: `with_deleted` and `only_deleted`, on ActiveRecord and Mongoid
|
|
300
|
+
resources. An HTTP resource does not get them (its adapter cannot drop the condition). With
|
|
301
|
+
scope counts on, ActiveRecord counts both tabs, one query each. `scope_counts false` on the
|
|
302
|
+
resource is what turns them off. A Mongoid resource does not count them.
|
|
188
303
|
- **Auto-registered restore action**: Restores soft-deleted records
|
|
189
304
|
|
|
190
305
|
```ruby
|
|
191
306
|
# If your model has deleted_at column, these are auto-registered:
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
307
|
+
module IronAdmin
|
|
308
|
+
module Resources
|
|
309
|
+
class PostResource < IronAdmin::Resource
|
|
310
|
+
# Auto: scope :with_deleted, -> { unscoped }
|
|
311
|
+
# Auto: scope :only_deleted, -> { only_deleted }
|
|
312
|
+
# Auto: action :restore { |r| r.update(deleted_at: nil) }
|
|
313
|
+
end
|
|
314
|
+
end
|
|
196
315
|
end
|
|
197
316
|
```
|
|
198
317
|
|
|
@@ -206,23 +325,28 @@ show page says "Action was not completed" followed by the validation errors.
|
|
|
206
325
|
### Record Actions
|
|
207
326
|
|
|
208
327
|
```ruby
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
328
|
+
module IronAdmin
|
|
329
|
+
module Resources
|
|
330
|
+
class UserResource < IronAdmin::Resource
|
|
331
|
+
action :lock, icon: "lock-closed", confirm: true do |record|
|
|
332
|
+
record.update!(locked_at: Time.current)
|
|
333
|
+
end
|
|
334
|
+
|
|
335
|
+
action :send_reset, icon: "envelope" do |record|
|
|
336
|
+
AuthMailer.password_reset(record).deliver_later
|
|
337
|
+
end
|
|
338
|
+
|
|
339
|
+
action :purge_sessions, confirm: true, confirm_message: "Sign this user out everywhere?" do |record|
|
|
340
|
+
record.sessions.delete_all
|
|
341
|
+
end
|
|
342
|
+
end
|
|
220
343
|
end
|
|
221
344
|
end
|
|
222
345
|
```
|
|
223
346
|
|
|
224
347
|
With `confirm: true`, the button asks for confirmation first. The dialog shows the action's
|
|
225
348
|
`confirm_message`, or `iron_admin.resources.action.confirm` ("Are you sure?") when it has none.
|
|
349
|
+
An action with form fields asks when its form is submitted instead (see [Action Forms](#action-forms)).
|
|
226
350
|
|
|
227
351
|
The show page lists the actions the current user can run on that record: the ones the policy
|
|
228
352
|
allows (see [Custom Action Authorization](authentication.md#custom-action-authorization)),
|
|
@@ -250,18 +374,25 @@ again." (`iron_admin.errors.unexpected`).
|
|
|
250
374
|
|
|
251
375
|
### Action Forms
|
|
252
376
|
|
|
253
|
-
Actions can collect user input before executing by specifying `form_fields:`.
|
|
377
|
+
Actions can collect user input before executing by specifying `form_fields:`. A two-argument
|
|
378
|
+
block receives the record and the submitted values, keyed by field name.
|
|
254
379
|
|
|
255
380
|
```ruby
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
381
|
+
module IronAdmin
|
|
382
|
+
module Resources
|
|
383
|
+
class OrderResource < IronAdmin::Resource
|
|
384
|
+
action :reject,
|
|
385
|
+
icon: "x-circle",
|
|
386
|
+
confirm: true,
|
|
387
|
+
form_fields: [
|
|
388
|
+
action_field(:reason, type: :textarea, required: true),
|
|
389
|
+
action_field(:notify_customer, type: :boolean, default: true)
|
|
390
|
+
] do |record, params|
|
|
391
|
+
record.reject!(reason: params[:reason])
|
|
392
|
+
Mailer.rejection(record).deliver_later if params[:notify_customer]
|
|
393
|
+
end
|
|
264
394
|
end
|
|
395
|
+
end
|
|
265
396
|
end
|
|
266
397
|
```
|
|
267
398
|
|
|
@@ -272,27 +403,66 @@ ActionField options:
|
|
|
272
403
|
| Option | Type | Description |
|
|
273
404
|
|--------|------|-------------|
|
|
274
405
|
| `type` | Symbol | Input type (see list above) |
|
|
406
|
+
| `label` | String | Label of the input (defaults to the humanized name); a `:boolean` field's label is the text beside its checkbox |
|
|
275
407
|
| `required` | Boolean | Whether the field must be filled |
|
|
276
|
-
| `default` | Object |
|
|
277
|
-
| `
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
408
|
+
| `default` | Object | Value of the input when the form opens |
|
|
409
|
+
| `placeholder` | String | Placeholder of the input |
|
|
410
|
+
| `options` | Array | Options for `:select` type |
|
|
411
|
+
|
|
412
|
+
The flow:
|
|
413
|
+
|
|
414
|
+
1. **Link.** On the show page (and in `ActionsComponent`), an action with form fields is a link
|
|
415
|
+
to its form, `GET /admin/:resource/:id/actions/:name/form`, styled like the other action
|
|
416
|
+
buttons. Actions without form fields stay buttons that run the action right away.
|
|
417
|
+
2. **Form.** The form page loads the record the way the action does: the policy, the action's
|
|
418
|
+
`condition`, the tenant scope and soft-deleted rows (only `restore` reaches them) apply,
|
|
419
|
+
so a user who cannot run the action gets a 403 or a 404 instead of the form. The form
|
|
420
|
+
names the record it applies to by model, id and label ("Applies to Article #16 (Slow
|
|
421
|
+
news).", or "Applies to License #3." for a record without a `name`, `title`, `email`,
|
|
422
|
+
`label` or `slug`). Cancel goes back to the record, as a whole-page visit.
|
|
423
|
+
3. **Submit.** Execute posts the values to the action. With `confirm: true`, the confirmation
|
|
424
|
+
(`confirm_message`, or `iron_admin.resources.action.confirm`) is asked when the form is
|
|
425
|
+
submitted, not before it opens. After the action, the browser goes to the record and shows
|
|
426
|
+
the result as a flash message, as for any action.
|
|
427
|
+
|
|
428
|
+
**Required fields.** The browser asks for a `required: true` field before it submits. The
|
|
429
|
+
server checks it too: when a required field is blank (or a direct POST leaves it out), the
|
|
430
|
+
action does not run, and the form comes back (422) with the values that were typed and "can't
|
|
431
|
+
be blank" (`errors.messages.blank`) under the field. A required `:boolean` must be checked:
|
|
432
|
+
an unchecked box, or a direct POST that sends `"0"` or `"false"`, counts as blank. Optional
|
|
433
|
+
fields can be left blank; the block then gets `nil` (or an empty string) for them, and a
|
|
434
|
+
boolean that is not checked is missing from `params`.
|
|
435
|
+
|
|
436
|
+
**Bulk actions** take form fields too. In the index's bulk bar, the button of a bulk action
|
|
437
|
+
with form fields takes the selected ids to `GET /admin/:resource/bulk_actions/:name/form`.
|
|
438
|
+
That form says how many records it applies to, carries the ids and the index's scope, search,
|
|
439
|
+
filters, sort and page, and asks for the confirmation on submit. The selection is checked as
|
|
440
|
+
the bulk action checks it: with no ids, or with an id that is gone or outside the tenant
|
|
441
|
+
scope, the form sends the user back to the index with the same alert. After Execute, the
|
|
442
|
+
index comes back with the state it was run from.
|
|
281
443
|
|
|
282
444
|
### Bulk Actions
|
|
283
445
|
|
|
284
446
|
```ruby
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
447
|
+
module IronAdmin
|
|
448
|
+
module Resources
|
|
449
|
+
class UserResource < IronAdmin::Resource
|
|
450
|
+
bulk_action :delete_many do |records|
|
|
451
|
+
records.each(&:destroy!)
|
|
452
|
+
end
|
|
453
|
+
|
|
454
|
+
bulk_action :lock_all do |records|
|
|
455
|
+
records.update_all(locked_at: Time.current)
|
|
456
|
+
end
|
|
457
|
+
end
|
|
292
458
|
end
|
|
293
459
|
end
|
|
294
460
|
```
|
|
295
461
|
|
|
462
|
+
With `confirm: true`, the bulk bar's button asks for confirmation before the action runs, with the
|
|
463
|
+
action's `confirm_message` or `iron_admin.resources.action.confirm` ("Are you sure?"). A bulk action
|
|
464
|
+
with form fields asks when its form is submitted instead (see [Action Forms](#action-forms)).
|
|
465
|
+
|
|
296
466
|
Bulk actions validate that all selected records are accessible to the current user (respecting tenant scope). After a bulk action, the index comes back with the scope, search, filters, sort and page it was run from.
|
|
297
467
|
|
|
298
468
|
Like a record action, a bulk action whose block returns `false` is rolled back and logs nothing.
|
|
@@ -302,8 +472,12 @@ instead of "Bulk action completed".
|
|
|
302
472
|
## CRUD Restrictions
|
|
303
473
|
|
|
304
474
|
```ruby
|
|
305
|
-
|
|
306
|
-
|
|
475
|
+
module IronAdmin
|
|
476
|
+
module Resources
|
|
477
|
+
class AuditLogResource < IronAdmin::Resource
|
|
478
|
+
deny_actions :create, :update, :delete
|
|
479
|
+
end
|
|
480
|
+
end
|
|
307
481
|
end
|
|
308
482
|
```
|
|
309
483
|
|
|
@@ -315,11 +489,15 @@ their buttons.
|
|
|
315
489
|
## Associations
|
|
316
490
|
|
|
317
491
|
```ruby
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
492
|
+
module IronAdmin
|
|
493
|
+
module Resources
|
|
494
|
+
class UserResource < IronAdmin::Resource
|
|
495
|
+
has_many :licenses, display: :license_key
|
|
496
|
+
has_many :subscriptions
|
|
497
|
+
belongs_to :organization
|
|
498
|
+
has_one :profile
|
|
499
|
+
end
|
|
500
|
+
end
|
|
323
501
|
end
|
|
324
502
|
```
|
|
325
503
|
|
|
@@ -328,8 +506,12 @@ link to the associated resource's index. To make that link open the index filter
|
|
|
328
506
|
parent's records, declare a filter on the foreign key in the associated resource:
|
|
329
507
|
|
|
330
508
|
```ruby
|
|
331
|
-
|
|
332
|
-
|
|
509
|
+
module IronAdmin
|
|
510
|
+
module Resources
|
|
511
|
+
class LicenseResource < IronAdmin::Resource
|
|
512
|
+
filter :user_id, type: :select
|
|
513
|
+
end
|
|
514
|
+
end
|
|
333
515
|
end
|
|
334
516
|
```
|
|
335
517
|
|
|
@@ -341,8 +523,12 @@ opens the unfiltered index.
|
|
|
341
523
|
IronAdmin auto-detects polymorphic `belongs_to` associations. You can also declare them explicitly with the `types` option to specify which models are allowed:
|
|
342
524
|
|
|
343
525
|
```ruby
|
|
344
|
-
|
|
345
|
-
|
|
526
|
+
module IronAdmin
|
|
527
|
+
module Resources
|
|
528
|
+
class CommentResource < IronAdmin::Resource
|
|
529
|
+
belongs_to :commentable, polymorphic: true, types: [Article, Photo, Video]
|
|
530
|
+
end
|
|
531
|
+
end
|
|
346
532
|
end
|
|
347
533
|
```
|
|
348
534
|
|
|
@@ -355,8 +541,12 @@ The `FieldInferrer` automatically detects polymorphic associations when a model
|
|
|
355
541
|
`has_and_belongs_to_many` associations are supported with a checkbox UI on forms and badge display on show pages:
|
|
356
542
|
|
|
357
543
|
```ruby
|
|
358
|
-
|
|
359
|
-
|
|
544
|
+
module IronAdmin
|
|
545
|
+
module Resources
|
|
546
|
+
class ArticleResource < IronAdmin::Resource
|
|
547
|
+
has_and_belongs_to_many :tags
|
|
548
|
+
end
|
|
549
|
+
end
|
|
360
550
|
end
|
|
361
551
|
```
|
|
362
552
|
|
|
@@ -369,8 +559,12 @@ IronAdmin automatically preloads associations to prevent N+1 queries:
|
|
|
369
559
|
- Custom preloads can be added:
|
|
370
560
|
|
|
371
561
|
```ruby
|
|
372
|
-
|
|
373
|
-
|
|
562
|
+
module IronAdmin
|
|
563
|
+
module Resources
|
|
564
|
+
class OrderResource < IronAdmin::Resource
|
|
565
|
+
preload :customer, :line_items, :shipping_address
|
|
566
|
+
end
|
|
567
|
+
end
|
|
374
568
|
end
|
|
375
569
|
```
|
|
376
570
|
|
|
@@ -379,11 +573,15 @@ end
|
|
|
379
573
|
For `belongs_to` fields with many options (>100 records), IronAdmin automatically uses an autocomplete component instead of a dropdown:
|
|
380
574
|
|
|
381
575
|
```ruby
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
576
|
+
module IronAdmin
|
|
577
|
+
module Resources
|
|
578
|
+
class OrderResource < IronAdmin::Resource
|
|
579
|
+
field :customer_id, type: :belongs_to,
|
|
580
|
+
association: :customer,
|
|
581
|
+
display: :name
|
|
582
|
+
# Autocomplete is used automatically if Customer has >100 records
|
|
583
|
+
end
|
|
584
|
+
end
|
|
387
585
|
end
|
|
388
586
|
```
|
|
389
587
|
|
|
@@ -392,18 +590,22 @@ end
|
|
|
392
590
|
For `has_many` and `has_one` associations, you can enable inline nested editing directly on the parent form. The model must declare `accepts_nested_attributes_for` for the association.
|
|
393
591
|
|
|
394
592
|
```ruby
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
593
|
+
module IronAdmin
|
|
594
|
+
module Resources
|
|
595
|
+
class OrderResource < IronAdmin::Resource
|
|
596
|
+
# has_many with nested editing
|
|
597
|
+
has_many :line_items, nested: true, allow_destroy: true
|
|
398
598
|
|
|
399
|
-
|
|
400
|
-
|
|
599
|
+
# Explicit field selection
|
|
600
|
+
has_many :addresses, nested: true, fields: [:street, :city, :zip]
|
|
401
601
|
|
|
402
|
-
|
|
403
|
-
|
|
602
|
+
# With drag-and-drop ordering (via Stimulus)
|
|
603
|
+
has_many :sections, nested: true, position_field: :position
|
|
404
604
|
|
|
405
|
-
|
|
406
|
-
|
|
605
|
+
# has_one nested
|
|
606
|
+
has_one :profile, nested: true
|
|
607
|
+
end
|
|
608
|
+
end
|
|
407
609
|
end
|
|
408
610
|
```
|
|
409
611
|
|
|
@@ -421,17 +623,25 @@ Nested forms use the existing `create` and `update` endpoints -- no additional r
|
|
|
421
623
|
## Menu Configuration
|
|
422
624
|
|
|
423
625
|
```ruby
|
|
424
|
-
|
|
425
|
-
|
|
626
|
+
module IronAdmin
|
|
627
|
+
module Resources
|
|
628
|
+
class UserResource < IronAdmin::Resource
|
|
629
|
+
menu priority: 1, icon: "users", group: "People"
|
|
630
|
+
end
|
|
631
|
+
end
|
|
426
632
|
end
|
|
427
633
|
```
|
|
428
634
|
|
|
429
635
|
## Exports
|
|
430
636
|
|
|
431
637
|
```ruby
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
638
|
+
module IronAdmin
|
|
639
|
+
module Resources
|
|
640
|
+
class UserResource < IronAdmin::Resource
|
|
641
|
+
exports :csv, :json
|
|
642
|
+
export_fields :id, :name, :email, :role, :created_at
|
|
643
|
+
end
|
|
644
|
+
end
|
|
435
645
|
end
|
|
436
646
|
```
|
|
437
647
|
|
|
@@ -449,9 +659,13 @@ format that is not enabled returns `404`. See [Export](export.md).
|
|
|
449
659
|
## Imports
|
|
450
660
|
|
|
451
661
|
```ruby
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
662
|
+
module IronAdmin
|
|
663
|
+
module Resources
|
|
664
|
+
class UserResource < IronAdmin::Resource
|
|
665
|
+
imports :csv, :json
|
|
666
|
+
import_upsert_key :email
|
|
667
|
+
end
|
|
668
|
+
end
|
|
455
669
|
end
|
|
456
670
|
```
|
|
457
671
|
|
|
@@ -461,10 +675,14 @@ and the other import options.
|
|
|
461
675
|
## Policies
|
|
462
676
|
|
|
463
677
|
```ruby
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
678
|
+
module IronAdmin
|
|
679
|
+
module Resources
|
|
680
|
+
class UserResource < IronAdmin::Resource
|
|
681
|
+
policy do
|
|
682
|
+
allow :read, :update
|
|
683
|
+
deny :destroy, if: ->(user) { !user&.superadmin? }
|
|
684
|
+
end
|
|
685
|
+
end
|
|
468
686
|
end
|
|
469
687
|
end
|
|
470
688
|
```
|
|
@@ -477,9 +695,13 @@ Replace the index table, the new/edit form, the filter bar or the search box of
|
|
|
477
695
|
resource with your own ViewComponent:
|
|
478
696
|
|
|
479
697
|
```ruby
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
698
|
+
module IronAdmin
|
|
699
|
+
module Resources
|
|
700
|
+
class UserResource < IronAdmin::Resource
|
|
701
|
+
component :table, CustomUserTableComponent
|
|
702
|
+
component :form, "CustomUserFormComponent"
|
|
703
|
+
end
|
|
704
|
+
end
|
|
483
705
|
end
|
|
484
706
|
```
|
|
485
707
|
|