iron_admin 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +129 -1
  3. data/README.md +48 -1
  4. data/UPGRADING.md +495 -8
  5. data/app/assets/tailwind/iron_admin/engine.css +79 -4
  6. data/app/components/iron_admin/dashboards/activity_feed_component/item_component.html.haml +6 -9
  7. data/app/components/iron_admin/dashboards/activity_feed_component.html.haml +6 -5
  8. data/app/components/iron_admin/dashboards/activity_feed_component.rb +21 -24
  9. data/app/components/iron_admin/dashboards/chart_component.html.haml +3 -5
  10. data/app/components/iron_admin/dashboards/chart_component.rb +86 -24
  11. data/app/components/iron_admin/dashboards/concerns/themed_card.rb +39 -0
  12. data/app/components/iron_admin/dashboards/metric_card_component.html.haml +8 -7
  13. data/app/components/iron_admin/dashboards/metric_card_component.rb +2 -0
  14. data/app/components/iron_admin/dashboards/progress_component.html.haml +11 -7
  15. data/app/components/iron_admin/dashboards/progress_component.rb +11 -6
  16. data/app/components/iron_admin/dashboards/quick_links_component/link_component.html.haml +8 -9
  17. data/app/components/iron_admin/dashboards/quick_links_component.html.haml +6 -5
  18. data/app/components/iron_admin/dashboards/quick_links_component.rb +4 -12
  19. data/app/components/iron_admin/dashboards/recent_table_component.html.haml +15 -10
  20. data/app/components/iron_admin/dashboards/recent_table_component.rb +49 -0
  21. data/app/components/iron_admin/dashboards/stats_grid_component/stat_component.html.haml +13 -14
  22. data/app/components/iron_admin/dashboards/stats_grid_component.html.haml +1 -0
  23. data/app/components/iron_admin/dashboards/stats_grid_component.rb +9 -11
  24. data/app/components/iron_admin/filters/bar_component.html.haml +8 -6
  25. data/app/components/iron_admin/filters/bar_component.rb +56 -9
  26. data/app/components/iron_admin/filters/control_styles.rb +82 -0
  27. data/app/components/iron_admin/filters/date_range_component.html.haml +9 -4
  28. data/app/components/iron_admin/filters/date_range_component.rb +10 -6
  29. data/app/components/iron_admin/filters/search_component.html.haml +4 -4
  30. data/app/components/iron_admin/filters/search_component.rb +3 -5
  31. data/app/components/iron_admin/filters/select_filter_component.html.haml +1 -1
  32. data/app/components/iron_admin/filters/select_filter_component.rb +5 -16
  33. data/app/components/iron_admin/form/belongs_to_autocomplete_component.html.haml +9 -5
  34. data/app/components/iron_admin/form/belongs_to_autocomplete_component.rb +10 -8
  35. data/app/components/iron_admin/form/belongs_to_component.html.haml +2 -2
  36. data/app/components/iron_admin/form/belongs_to_component.rb +4 -18
  37. data/app/components/iron_admin/form/checkbox_component.rb +2 -3
  38. data/app/components/iron_admin/form/concerns/form_input_behavior.rb +1 -1
  39. data/app/components/iron_admin/form/control_classes.rb +108 -0
  40. data/app/components/iron_admin/form/date_picker_component.rb +3 -7
  41. data/app/components/iron_admin/form/field_wrapper_component.html.haml +3 -3
  42. data/app/components/iron_admin/form/field_wrapper_component.rb +3 -3
  43. data/app/components/iron_admin/form/nested_form_component.html.haml +4 -5
  44. data/app/components/iron_admin/form/nested_form_component.rb +12 -2
  45. data/app/components/iron_admin/form/select_component.html.haml +1 -1
  46. data/app/components/iron_admin/form/select_component.rb +2 -16
  47. data/app/components/iron_admin/form/text_input_component.rb +1 -5
  48. data/app/components/iron_admin/form/textarea_component.rb +1 -5
  49. data/app/components/iron_admin/layout/flash_component.html.haml +1 -1
  50. data/app/components/iron_admin/layout/flash_component.rb +4 -3
  51. data/app/components/iron_admin/layout/navbar_component.html.haml +15 -9
  52. data/app/components/iron_admin/layout/navbar_component.rb +29 -1
  53. data/app/components/iron_admin/layout/shell_component.html.haml +4 -4
  54. data/app/components/iron_admin/layout/shell_component.rb +16 -3
  55. data/app/components/iron_admin/layout/sidebar_component.html.haml +21 -25
  56. data/app/components/iron_admin/layout/sidebar_component.rb +76 -1
  57. data/app/components/iron_admin/layout/theme_switcher_component.html.haml +15 -0
  58. data/app/components/iron_admin/layout/theme_switcher_component.rb +74 -0
  59. data/app/components/iron_admin/resources/actions_component.html.haml +15 -8
  60. data/app/components/iron_admin/resources/actions_component.rb +34 -2
  61. data/app/components/iron_admin/resources/breadcrumb_component.html.haml +3 -3
  62. data/app/components/iron_admin/resources/breadcrumb_component.rb +8 -7
  63. data/app/components/iron_admin/resources/bulk_actions_component.html.haml +9 -8
  64. data/app/components/iron_admin/resources/bulk_actions_component.rb +47 -4
  65. data/app/components/iron_admin/resources/data_table_component.html.haml +15 -15
  66. data/app/components/iron_admin/resources/data_table_component.rb +34 -3
  67. data/app/components/iron_admin/resources/related_list_component.html.haml +7 -7
  68. data/app/components/iron_admin/resources/related_list_component.rb +26 -2
  69. data/app/components/iron_admin/resources/show_field_component.html.haml +3 -3
  70. data/app/components/iron_admin/resources/show_field_component.rb +10 -4
  71. data/app/components/iron_admin/resources/styles.rb +136 -0
  72. data/app/components/iron_admin/ui/alert_component.html.haml +2 -2
  73. data/app/components/iron_admin/ui/alert_component.rb +27 -31
  74. data/app/components/iron_admin/ui/badge_component.rb +40 -20
  75. data/app/components/iron_admin/ui/button_component.rb +37 -11
  76. data/app/components/iron_admin/ui/card_component.rb +3 -3
  77. data/app/components/iron_admin/ui/dropdown_component.html.haml +1 -1
  78. data/app/components/iron_admin/ui/dropdown_component.rb +34 -13
  79. data/app/components/iron_admin/ui/empty_state_component.html.haml +4 -5
  80. data/app/components/iron_admin/ui/empty_state_component.rb +2 -2
  81. data/app/components/iron_admin/ui/modal_component.html.haml +5 -5
  82. data/app/components/iron_admin/ui/modal_component.rb +6 -4
  83. data/app/components/iron_admin/ui/pagination_component.html.haml +14 -14
  84. data/app/components/iron_admin/ui/pagination_component.rb +26 -9
  85. data/app/components/iron_admin/ui/scopes_component.html.haml +2 -2
  86. data/app/components/iron_admin/ui/scopes_component.rb +44 -11
  87. data/app/components/iron_admin/ui/tooltip_component.rb +11 -4
  88. data/app/controllers/iron_admin/application_controller.rb +58 -4
  89. data/app/controllers/iron_admin/audit_controller.rb +30 -6
  90. data/app/controllers/iron_admin/concerns/action_executable.rb +37 -0
  91. data/app/controllers/iron_admin/concerns/assignable_references.rb +149 -0
  92. data/app/controllers/iron_admin/concerns/authorizable.rb +11 -0
  93. data/app/controllers/iron_admin/concerns/blank_password_filterable.rb +21 -0
  94. data/app/controllers/iron_admin/concerns/event_emittable.rb +47 -7
  95. data/app/controllers/iron_admin/concerns/filterable.rb +34 -9
  96. data/app/controllers/iron_admin/concerns/nested_permittable.rb +5 -3
  97. data/app/controllers/iron_admin/concerns/nested_tenant_check.rb +159 -0
  98. data/app/controllers/iron_admin/concerns/polymorphic_references.rb +131 -0
  99. data/app/controllers/iron_admin/concerns/scopeable.rb +54 -7
  100. data/app/controllers/iron_admin/concerns/searchable.rb +3 -3
  101. data/app/controllers/iron_admin/concerns/tenant_assignable.rb +118 -0
  102. data/app/controllers/iron_admin/concerns/tenant_containment.rb +146 -0
  103. data/app/controllers/iron_admin/exports_controller.rb +2 -2
  104. data/app/controllers/iron_admin/imports_controller.rb +1 -1
  105. data/app/controllers/iron_admin/resources_controller.rb +48 -41
  106. data/app/controllers/iron_admin/search_controller.rb +1 -2
  107. data/app/controllers/iron_admin/themes_controller.rb +50 -0
  108. data/app/controllers/iron_admin/tools_controller.rb +58 -5
  109. data/app/helpers/iron_admin/action_form_helper.rb +19 -0
  110. data/app/helpers/iron_admin/application_helper.rb +93 -16
  111. data/app/helpers/iron_admin/assignable_records_helper.rb +32 -0
  112. data/app/helpers/iron_admin/component_overrides_helper.rb +9 -4
  113. data/app/helpers/iron_admin/field_display_helper.rb +88 -43
  114. data/app/helpers/iron_admin/related_records_helper.rb +51 -0
  115. data/app/helpers/iron_admin/theme_helper.rb +56 -46
  116. data/app/javascript/iron_admin/controllers/cp_bulk_select_controller.js +12 -0
  117. data/app/javascript/iron_admin/controllers/cp_chart_controller.js +4 -0
  118. data/app/javascript/iron_admin/controllers/cp_disclosure_controller.js +19 -0
  119. data/app/javascript/iron_admin/controllers/cp_search_shortcut_controller.js +39 -0
  120. data/app/javascript/iron_admin/index.js +4 -0
  121. data/app/views/iron_admin/audit/index.html.haml +78 -81
  122. data/app/views/iron_admin/dashboard/index.html.haml +10 -9
  123. data/app/views/iron_admin/form/_action_field.html.haml +50 -0
  124. data/app/views/iron_admin/form/_nested_row.html.haml +18 -13
  125. data/app/views/iron_admin/imports/new.html.haml +14 -13
  126. data/app/views/iron_admin/imports/preview.html.haml +24 -21
  127. data/app/views/iron_admin/resources/_form.html.haml +70 -68
  128. data/app/views/iron_admin/resources/action_form.html.haml +16 -59
  129. data/app/views/iron_admin/resources/bulk_action_form.html.haml +20 -58
  130. data/app/views/iron_admin/resources/edit.html.haml +3 -3
  131. data/app/views/iron_admin/resources/index.html.haml +87 -74
  132. data/app/views/iron_admin/resources/new.html.haml +2 -2
  133. data/app/views/iron_admin/resources/show.html.haml +53 -41
  134. data/app/views/iron_admin/search/index.html.haml +17 -9
  135. data/app/views/iron_admin/shared/_pagination.html.haml +13 -10
  136. data/app/views/iron_admin/shared/error.html.haml +16 -12
  137. data/app/views/iron_admin/tools/action_form.html.haml +9 -55
  138. data/app/views/iron_admin/tools/show.html.haml +4 -5
  139. data/app/views/layouts/iron_admin/_document_head.html.haml +24 -0
  140. data/app/views/layouts/iron_admin/application.html.haml +4 -17
  141. data/app/views/layouts/iron_admin/minimal.html.haml +7 -0
  142. data/config/importmap.rb +2 -0
  143. data/config/locales/en.yml +23 -0
  144. data/config/routes.rb +1 -0
  145. data/docs/FAQ.md +87 -37
  146. data/docs/README.md +8 -2
  147. data/docs/components/README.md +6 -2
  148. data/docs/components/dashboard-components.md +24 -35
  149. data/docs/components/filter-components.md +44 -92
  150. data/docs/components/form-components.md +16 -32
  151. data/docs/components/resource-components.md +46 -27
  152. data/docs/components/ui-components.md +44 -26
  153. data/docs/getting-started/installation.md +5 -1
  154. data/docs/getting-started/quick-start.md +36 -23
  155. data/docs/guides/authentication.md +182 -42
  156. data/docs/guides/components.md +97 -15
  157. data/docs/guides/custom-adapters.md +24 -4
  158. data/docs/guides/dashboard.md +68 -44
  159. data/docs/guides/export.md +24 -8
  160. data/docs/guides/extending.md +206 -51
  161. data/docs/guides/fields.md +229 -70
  162. data/docs/guides/imports.md +33 -18
  163. data/docs/guides/resources.md +333 -111
  164. data/docs/guides/theming.md +930 -58
  165. data/docs/guides/troubleshooting.md +7 -3
  166. data/docs/plugin-system-design.md +8 -7
  167. data/docs/reference/configuration.md +51 -16
  168. data/docs/reference/routes.md +1 -0
  169. data/docs/reference/theme-properties.md +101 -38
  170. data/lib/generators/iron_admin/install/templates/initializer.rb.tt +7 -2
  171. data/lib/generators/iron_admin/install_audit/templates/create_iron_admin_audit_entries.rb.tt +2 -0
  172. data/lib/iron_admin/action_field.rb +11 -0
  173. data/lib/iron_admin/adapters/active_record.rb +95 -0
  174. data/lib/iron_admin/adapters/base.rb +107 -0
  175. data/lib/iron_admin/adapters/http/query.rb +21 -0
  176. data/lib/iron_admin/adapters/http.rb +84 -4
  177. data/lib/iron_admin/adapters/mongoid.rb +96 -2
  178. data/lib/iron_admin/audit_log.rb +64 -6
  179. data/lib/iron_admin/authentication_warning.rb +31 -0
  180. data/lib/iron_admin/concerns/filter_definable.rb +15 -1
  181. data/lib/iron_admin/concerns/nestable.rb +25 -0
  182. data/lib/iron_admin/concerns/scope_countable.rb +56 -0
  183. data/lib/iron_admin/concerns/soft_deletable.rb +28 -9
  184. data/lib/iron_admin/configuration/components.rb +14 -3
  185. data/lib/iron_admin/configuration/theme/neutral_defaults.rb +179 -0
  186. data/lib/iron_admin/configuration/theme.rb +292 -87
  187. data/lib/iron_admin/configuration.rb +340 -45
  188. data/lib/iron_admin/dashboard.rb +22 -38
  189. data/lib/iron_admin/engine.rb +16 -2
  190. data/lib/iron_admin/errors.rb +3 -0
  191. data/lib/iron_admin/field.rb +78 -17
  192. data/lib/iron_admin/field_inferrer.rb +61 -3
  193. data/lib/iron_admin/field_override_warning.rb +67 -0
  194. data/lib/iron_admin/import/import_preview.rb +56 -7
  195. data/lib/iron_admin/import/importer.rb +91 -14
  196. data/lib/iron_admin/import/tenant_precheck.rb +67 -0
  197. data/lib/iron_admin/plugin/registration.rb +64 -0
  198. data/lib/iron_admin/plugin_registry.rb +3 -2
  199. data/lib/iron_admin/policy.rb +22 -12
  200. data/lib/iron_admin/policy_coverage_warning.rb +46 -0
  201. data/lib/iron_admin/request_context.rb +18 -0
  202. data/lib/iron_admin/resource.rb +218 -77
  203. data/lib/iron_admin/resource_registry.rb +86 -13
  204. data/lib/iron_admin/scope_counts.rb +73 -0
  205. data/lib/iron_admin/tenant_scope.rb +30 -0
  206. data/lib/iron_admin/tool.rb +61 -12
  207. data/lib/iron_admin/tool_context.rb +10 -6
  208. data/lib/iron_admin/version.rb +1 -1
  209. data/lib/iron_admin.rb +29 -2
  210. metadata +37 -7
@@ -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
- class UserResource < IronAdmin::Resource
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
- class UserResource < IronAdmin::Resource
22
- self.model_class_override = Account
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
- class UserResource < IronAdmin::Resource
32
- field :status, type: :badge, colors: { active: :green, suspended: :red }
33
- field :bio, type: :textarea
34
- field :role, type: :select, choices: %w[user admin]
35
- field :secret, visible: false
36
- field :email, readonly: true
37
- field :admin_notes, visible: ->(user) { user.admin? }
38
- field :salary, readonly: ->(user) { !user.admin? }
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
- class UserResource < IronAdmin::Resource
56
- index_fields :id, :name, :email, :role, :created_at
57
- form_fields :role, :name, :email
58
- export_fields :id, :name, :email, :role
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
- class UserResource < IronAdmin::Resource
70
- searchable :name, :email
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
- class UserResource < IronAdmin::Resource
104
- filter :role, type: :select, options: User.roles.keys
105
- filter :created_at, type: :date_range
106
- filter :email_verified, type: :boolean
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
- class ProductResource < IronAdmin::Resource
144
- filter :name, type: :string # contains, equals, starts_with, ends_with
145
- filter :price, type: :number # equals, greater_than, less_than, between
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
- class OrderResource < IronAdmin::Resource
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
- class UserResource < IronAdmin::Resource
176
- scope :all, -> { all }, default: true
177
- scope :admins, -> { where(role: :admin) }
178
- scope :recent, -> { where("created_at > ?", 7.days.ago) }
179
- scope :locked, -> { where.not(locked_at: nil) }
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
- class PostResource < IronAdmin::Resource
193
- # Auto: scope :with_deleted, -> { unscoped }
194
- # Auto: scope :only_deleted, -> { only_deleted }
195
- # Auto: action :restore { |r| r.update(deleted_at: nil) }
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
- class UserResource < IronAdmin::Resource
210
- action :lock, icon: "lock-closed", confirm: true do |record|
211
- record.update!(locked_at: Time.current)
212
- end
213
-
214
- action :send_reset, icon: "envelope" do |record|
215
- AuthMailer.password_reset(record).deliver_later
216
- end
217
-
218
- action :purge_sessions, confirm: true, confirm_message: "Sign this user out everywhere?" do |record|
219
- record.sessions.delete_all
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:`. The form is displayed in a modal when the action is triggered.
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
- class OrderResource < IronAdmin::Resource
257
- action :reject,
258
- form_fields: [
259
- action_field(:reason, type: :textarea, required: true),
260
- action_field(:notify_customer, type: :boolean, default: true)
261
- ] do |record, params|
262
- record.reject!(reason: params[:reason])
263
- Mailer.rejection(record).deliver_later if params[:notify_customer]
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 | Default value for the input |
277
- | `choices` | Array | Options for `:select` type |
278
-
279
- Action forms work with both record actions and bulk actions. After Execute, the browser goes to
280
- the record (or, for a bulk action, back to the index) and shows the result as a flash message.
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
- class UserResource < IronAdmin::Resource
286
- bulk_action :delete_many do |records|
287
- records.each(&:destroy!)
288
- end
289
-
290
- bulk_action :lock_all do |records|
291
- records.update_all(locked_at: Time.current)
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
- class AuditLogResource < IronAdmin::Resource
306
- deny_actions :create, :update, :delete
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
- class UserResource < IronAdmin::Resource
319
- has_many :licenses, display: :license_key
320
- has_many :subscriptions
321
- belongs_to :organization
322
- has_one :profile
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
- class LicenseResource < IronAdmin::Resource
332
- filter :user_id, type: :select
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
- class CommentResource < IronAdmin::Resource
345
- belongs_to :commentable, polymorphic: true, types: [Article, Photo, Video]
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
- class ArticleResource < IronAdmin::Resource
359
- has_and_belongs_to_many :tags
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
- class OrderResource < IronAdmin::Resource
373
- preload :customer, :line_items, :shipping_address
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
- class OrderResource < IronAdmin::Resource
383
- field :customer_id, type: :belongs_to,
384
- association: :customer,
385
- display: :name
386
- # Autocomplete is used automatically if Customer has >100 records
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
- class OrderResource < IronAdmin::Resource
396
- # has_many with nested editing
397
- has_many :line_items, nested: true, allow_destroy: true
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
- # Explicit field selection
400
- has_many :addresses, nested: true, fields: [:street, :city, :zip]
599
+ # Explicit field selection
600
+ has_many :addresses, nested: true, fields: [:street, :city, :zip]
401
601
 
402
- # With drag-and-drop ordering (via Stimulus)
403
- has_many :sections, nested: true, position_field: :position
602
+ # With drag-and-drop ordering (via Stimulus)
603
+ has_many :sections, nested: true, position_field: :position
404
604
 
405
- # has_one nested
406
- has_one :profile, nested: true
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
- class UserResource < IronAdmin::Resource
425
- menu priority: 1, icon: "users", group: "People"
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
- class UserResource < IronAdmin::Resource
433
- exports :csv, :json
434
- export_fields :id, :name, :email, :role, :created_at
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
- class UserResource < IronAdmin::Resource
453
- imports :csv, :json
454
- import_upsert_key :email
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
- class UserResource < IronAdmin::Resource
465
- policy do
466
- allow :read, :update
467
- deny :destroy, if: ->(user) { !user.superadmin? }
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
- class UserResource < IronAdmin::Resource
481
- component :table, CustomUserTableComponent
482
- component :form, "CustomUserFormComponent"
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