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
@@ -14,6 +14,7 @@ For the complete component reference, see the [Components Library](../components
14
14
  | `IronAdmin::Layout::NavbarComponent` | Top navigation bar |
15
15
  | `IronAdmin::Layout::SidebarComponent` | Left sidebar navigation |
16
16
  | `IronAdmin::Layout::FlashComponent` | The request's flash messages, rendered by the shell above the page content |
17
+ | `IronAdmin::Layout::ThemeSwitcherComponent` | The theme switcher in the navbar, rendered when two or more themes are registered |
17
18
 
18
19
  ### UI Components
19
20
 
@@ -27,7 +28,7 @@ For the complete component reference, see the [Components Library](../components
27
28
  | `IronAdmin::Ui::DropdownComponent` | Dropdown menus |
28
29
  | `IronAdmin::Ui::TooltipComponent` | Hover tooltips |
29
30
  | `IronAdmin::Ui::PaginationComponent` | Pagination controls |
30
- | `IronAdmin::Ui::ScopesComponent` | Scope tabs |
31
+ | `IronAdmin::Ui::ScopesComponent` | Scope tabs. Takes `counts:` (see [Scope tab counts](#scope-tab-counts)) |
31
32
  | `IronAdmin::Ui::EmptyStateComponent` | Empty state placeholders |
32
33
 
33
34
  ### Form Components
@@ -93,19 +94,60 @@ Every flash message has `role="alert"`, whatever its type. The message arrives a
93
94
  in the page Turbo renders after the redirect, and screen readers announce an inserted
94
95
  `role="alert"` but not an inserted `role="status"`.
95
96
 
97
+ To show flash messages your own way, override the `flash` slot (see
98
+ [Overriding Components](#overriding-components)):
99
+
100
+ ```ruby
101
+ config.components.flash = "AdminFlashComponent"
102
+ ```
103
+
96
104
  A custom shell (`config.components.shell`) replaces the built-in one, so it has to render the
97
- component itself, before the page body, and wrap both in a `<main>` landmark:
105
+ `flash` slot itself, before the page body, and wrap both in a `<main>` landmark.
106
+ `iron_admin_component(:flash, ...)` builds the `flash` override, or `FlashComponent` when there
107
+ is none:
98
108
 
99
109
  ```haml
100
110
  -# app/components/admin_shell_component.html.haml
101
111
  %main#main-content
102
- = render IronAdmin::Layout::FlashComponent.new
112
+ = render helpers.iron_admin_component(:flash, flash: helpers.flash, current_user: @current_user)
103
113
  = content
104
114
  ```
105
115
 
106
116
  `FlashComponent.new(flash: { notice: "Saved" })` renders the messages you pass instead of the
107
117
  request's flash.
108
118
 
119
+ ## Scope tab counts
120
+
121
+ The index computes one hash of record counts before it renders, and the built-in scope tabs
122
+ use it. `@scope_counts` is set only on the index. `Ui::ScopesComponent` takes the same hash
123
+ as `counts:`. The keys are Strings. A scope's name in the DSL is a Symbol. Build the tab
124
+ label with `IronAdmin::ScopeCounts.label(scope, counts)` (it returns `"Active (12)"`, not
125
+ the number). Read the number with `counts[scope[:name].to_s]`. The default is `{}`, which
126
+ draws each tab's name and no number. A count of zero renders as zero. A scope with no entry
127
+ renders no number.
128
+
129
+ A request from the `records` Turbo frame (pagination inside that frame) gets an empty
130
+ `@scope_counts`. Render the tabs outside that frame, as the built-in index does. Tabs
131
+ drawn inside the frame have no numbers on those requests.
132
+
133
+ There is no `scopes` slot. The index draws its tabs itself, above the `records` frame. An
134
+ `index.html.haml` override that turns counts on still pays one query per counted scope, and
135
+ shows no numbers until it passes `counts: @scope_counts`. Pass the hash when you render the
136
+ component:
137
+
138
+ ```haml
139
+ = render IronAdmin::Ui::ScopesComponent.new(scopes: @resource_class.all_scopes,
140
+ current_scope: @current_scope,
141
+ base_path: resources_path(@resource_class.resource_name),
142
+ params: iron_admin_index_state,
143
+ counts: @scope_counts)
144
+ ```
145
+
146
+ A `ScopesComponent` subclass template can read `counts` and call `scope_label(scope)`
147
+ (`"Active (12)"`, `"Inactive (0)"` or `"Archived"`). In an `index.html.haml` override, use
148
+ `IronAdmin::ScopeCounts.label(scope, @scope_counts)`. What the number means, what it costs
149
+ and how to turn it on are in the [resources guide](resources.md#scopes).
150
+
109
151
  ## Overriding Components
110
152
 
111
153
  You can replace parts of the admin UI with your own ViewComponents. Each override fills a
@@ -124,9 +166,11 @@ Pages without overrides render exactly as before.
124
166
  | `shell` | The page shell around every admin page. Render `content` for the page body. | `current_user` | Global |
125
167
  | `navbar` | The top bar inside the built-in shell | `current_user`, `title` | Global |
126
168
  | `sidebar` | The navigation inside the built-in shell | `current_user` | Global |
127
- | `table` | The records table on index pages | `records`, `fields`, `resource_class`, `current_user`, `current_sort`, `current_direction`, `scope`, `query`, `base_url` | Global or per resource |
169
+ | `flash` | The flash messages above the page content inside the built-in shell | `flash`, `current_user` | Global |
170
+ | `theme_switcher` | The theme switcher inside the built-in navbar (only rendered when two or more themes are registered) | `themes`, `current_theme`, `current_user` | Global |
171
+ | `table` | The records table on index pages | `records`, `fields`, `resource_class`, `current_user`, `current_sort`, `current_direction`, `scope`, `query`, `base_url`, `bulk_actions` | Global or per resource |
128
172
  | `form` | The form on new and edit pages | `record`, `fields`, `resource_class`, `url`, `current_user` | Global or per resource |
129
- | `filter_bar` | The filters dropdown on index pages (only rendered when the resource has filters) | `filters`, `resource_class`, `form_url`, `scope`, `query`, `active_count`, `current_user` | Global or per resource |
173
+ | `filter_bar` | The filters dropdown on index pages (only rendered when the resource has filters) | `filters`, `resource_class`, `form_url`, `scope`, `query`, `active_count`, `current_user`, `current_sort`, `current_direction` | Global or per resource |
130
174
  | `search` | The search box on index pages (only rendered when the resource has searchable columns) | `resource_class`, `form_url`, `value`, `placeholder`, `hidden_params`, `current_user` | Global or per resource |
131
175
 
132
176
  The same list is available in code as `IronAdmin::Configuration::Components::SLOTS`.
@@ -150,8 +194,13 @@ The same list is available in code as `IronAdmin::Configuration::Components::SLO
150
194
  navbar, flash messages, the `<main id="main-content">` landmark and the "Skip to content"
151
195
  link it renders. `navbar` and `sidebar` overrides only apply inside the built-in shell.
152
196
  Render the page body inside your own `<main>` landmark, and to keep the flash messages,
153
- render `IronAdmin::Layout::FlashComponent` before the page body (see
154
- [Flash messages](#flash-messages)).
197
+ render the `flash` slot before the page body (see [Flash messages](#flash-messages)).
198
+ - `flash`: `flash` is the request's flash (`ActionDispatch::Flash::FlashHash`). The component
199
+ renders every message, so it decides which keys to show; the built-in one shows `notice`,
200
+ `success`, `alert`, `error`, `warning` and `info` (see [Flash Messages](#flash-messages)).
201
+ The shell renders the slot on every page, so return `false` from `render?` when there is no
202
+ message. Give each message `role="alert"`, as the built-in one does, so screen readers
203
+ announce it.
155
204
  - `navbar` / `sidebar`: the built-in shell keeps its mobile drawer (the `cp-sidebar`
156
205
  Stimulus controller). To keep the drawer working, give your sidebar
157
206
  `data-cp-sidebar-target="panel"` and your navbar a button with
@@ -164,13 +213,22 @@ The same list is available in code as `IronAdmin::Configuration::Components::SLO
164
213
  is closed, and the rest of the shell `inert` while it is open. Opening the drawer moves
165
214
  focus to the sidebar element with `data-cp-sidebar-target="closeButton"` (or else to the
166
215
  panel's first link or button), and closing it moves focus back to the toggle.
216
+ - `theme_switcher`: `themes` is an Array of `IronAdmin::Configuration::Theme`, the default
217
+ theme first, and `current_theme` is the theme of the request. Submit the choice to
218
+ `helpers.iron_admin.theme_path` with a POST request and the `theme` and `return_to` params,
219
+ as the built-in switcher does, or to a controller of yours. A custom `navbar` renders the
220
+ slot itself, with `helpers.iron_admin_component(:theme_switcher, themes: ..., current_theme:
221
+ IronAdmin.current_theme, current_user: @current_user)`. See
222
+ [The theme switcher](theming.md#the-theme-switcher-and-its-cookie).
167
223
  - `table`: IronAdmin still renders the scope tabs, search, filters, bulk-action bar and
168
224
  pagination around it. Only the bulk-action bar, the table and the pagination are inside
169
225
  the `records` Turbo frame; the scope tabs, search and filters sit outside it. The frame
170
226
  has `data-turbo-action="advance"`, so a link or form inside it that does not target
171
- `_top` updates the address bar and the browser history. If the resource has bulk actions,
172
- render a checkbox per row named `ids[]` with
227
+ `_top` updates the address bar and the browser history. `bulk_actions` is the list the
228
+ policy allows for the current user (on the index, `@permitted_bulk_actions`). When it
229
+ has any actions, render a checkbox per row named `ids[]` with
173
230
  `data-cp-bulk-select-target="checkbox"` and `data-action="change->cp-bulk-select#toggle"`.
231
+ When `bulk_actions` is empty, render no checkbox column.
174
232
  Give each one an `aria-label`, as the built-in table does with
175
233
  `iron_admin.resources.index.select_record` ("Select %{record}").
176
234
  `base_url` already includes the scope, the search query and the active filters, but never
@@ -180,6 +238,16 @@ The same list is available in code as `IronAdmin::Configuration::Components::SLO
180
238
  The bundled `IronAdmin::Resources::DataTableComponent` fits this slot as is.
181
239
  - `form`: submit to `url`, with the record's attributes under `record`
182
240
  (`form_with model: record, url: url, scope: :record`).
241
+ - `filter_bar`: submit the filters to `form_url` with a GET request, and add hidden fields
242
+ for `scope`, `query` (as `q`) and, when they are set, `current_sort` (as `sort`) and
243
+ `current_direction` (as `direction`), so applying filters keeps the scope, search and sort.
244
+ Render those hidden fields without an `id`, as for `search`. `active_count` is the number
245
+ of filters with a value. `IronAdmin::Filters::BarComponent` takes the same `scope:`,
246
+ `query:`, `active_count:`, `current_sort:` and `current_direction:` keywords. Build the
247
+ choices of a `:select` or `:boolean` filter with
248
+ `helpers.filter_options_for(resource_class, filter)`, which returns `[label, value]` pairs:
249
+ a filter's `:options` can be a callable, and a foreign key filter without options offers
250
+ the associated records that some row refers to.
183
251
  - `search`: submit `q` to `form_url` with a GET request, and add every `hidden_params`
184
252
  entry as a hidden field, so the current scope, filters and sort are kept. `hidden_params`
185
253
  carries `scope`, the active filters and, when they are set, `sort` and `direction`. Its
@@ -201,6 +269,8 @@ IronAdmin.configure do |config|
201
269
  config.components.navbar = "AdminNavbarComponent"
202
270
  config.components.sidebar = "AdminSidebarComponent"
203
271
  config.components.shell = "AdminShellComponent"
272
+ config.components.flash = "AdminFlashComponent"
273
+ config.components.theme_switcher = "AdminThemeSwitcherComponent"
204
274
  config.components.table = "AdminTableComponent"
205
275
  config.components.form = "AdminFormComponent"
206
276
  config.components.filter_bar = "AdminFilterBarComponent"
@@ -226,7 +296,7 @@ module IronAdmin
226
296
  end
227
297
  ```
228
298
 
229
- `component :navbar`, `:sidebar` and `:shell` raise `ArgumentError`, because those slots
299
+ `component :navbar`, `:sidebar`, `:flash` and `:shell` raise `ArgumentError`, because those slots
230
300
  apply to every page; set them in `config.components`. Any other name, such as `:index`,
231
301
  `:show` or `:row`, also raises `ArgumentError` and lists the valid slots.
232
302
 
@@ -253,8 +323,12 @@ end
253
323
  ```
254
324
 
255
325
  ```ruby
256
- class ProductResource < IronAdmin::Resource
257
- field :accent_color, type: :color_picker
326
+ module IronAdmin
327
+ module Resources
328
+ class ProductResource < IronAdmin::Resource
329
+ field :accent_color, type: :color_picker
330
+ end
331
+ end
258
332
  end
259
333
  ```
260
334
 
@@ -299,8 +373,9 @@ class AdminNavbarComponent < ViewComponent::Base
299
373
  @current_user = current_user
300
374
  end
301
375
 
376
+ # The theme of the current request (the default theme outside a request).
302
377
  def theme
303
- IronAdmin.configuration.theme
378
+ IronAdmin.current_theme
304
379
  end
305
380
  end
306
381
  ```
@@ -315,14 +390,21 @@ end
315
390
 
316
391
  ## Theme Integration
317
392
 
318
- Access theme properties in components via the `theme` method:
393
+ Read theme properties from `IronAdmin.current_theme`, as the `theme` method above does. It
394
+ returns the theme of the current request, so your component follows the theme switcher.
395
+ `IronAdmin.configuration.theme` always returns the default theme; don't render with it.
319
396
 
320
397
  ```ruby
321
398
  def card_classes
322
- "#{theme.card_bg} #{theme.card_border} #{theme.border_radius} #{theme.card_shadow}"
399
+ "#{theme.card_bg} #{theme.border_width} #{theme.card_border} #{theme.border_radius} #{theme.card_shadow}"
323
400
  end
324
401
  ```
325
402
 
403
+ A border needs `border_width` as well as the `card_border` color. To match the built-in
404
+ controls, build them with `IronAdmin::Form::ControlClasses`, for example
405
+ `IronAdmin::Form::ControlClasses.button(theme, :secondary)`. See
406
+ [Using the theme in your own components](theming.md#using-the-theme-in-your-own-components).
407
+
326
408
  ## Component Documentation
327
409
 
328
410
  For detailed documentation on each component including all options and examples:
@@ -72,7 +72,7 @@ end
72
72
 
73
73
  ## Complete Method Reference
74
74
 
75
- `Adapters::Base` defines 35 methods organized into 9 sections. All methods raise `NotImplementedError` by default except `resource_name` and `human_name` (which use `ActiveModel::Naming`).
75
+ The nine sections below name 37 methods. Most raise `NotImplementedError`. These have a default: `resource_name` and `human_name` (from `ActiveModel::Naming`); `primary_key` (`"id"`) and `polymorphic_inverse_classes` (an empty array); `find_by_keys` (calls `find_by`), `create_record` (builds and saves) and `update_record` (calls `update`); `after_commit` (runs the block now) and `cast_boolean`; `exact_count` (calls `count`, and returns nil, without logging, when `count` raises `NotImplementedError`). `primary_key`, `polymorphic_inverse_classes`, `find_by_keys`, `create_record` and `update_record` are not given their own headings.
76
76
 
77
77
  ### Schema Introspection (8 methods)
78
78
 
@@ -185,7 +185,7 @@ Returns ActionText rich text attribute names. Each name starts with `rich_text_`
185
185
 
186
186
  #### `resource_name` → `String`
187
187
 
188
- **Implemented in Base.** Returns the URL-friendly plural name (e.g., `"users"`). Uses `model_class.model_name.plural`. Override only if your model doesn't include `ActiveModel::Naming`.
188
+ **Implemented in Base.** Returns the model's plural (e.g., `"users"`), from `model_class.model_name.plural`. `IronAdmin::Resource.resource_name` uses that plural when the model is the one the class name implies, including an override of that same model, when the resource uses the HTTP adapter without an override, and when the class is anonymous. Otherwise the resource derives its name from the full class path under `IronAdmin::Resources` (`Shop::NoteResource` is `shop_notes`), unless it defines `def self.resource_name`. Override this method only if your model doesn't include `ActiveModel::Naming`.
189
189
 
190
190
  #### `human_name` → `String`
191
191
 
@@ -195,7 +195,7 @@ Returns ActionText rich text attribute names. Each name starts with `rich_text_`
195
195
 
196
196
  Returns the storage name (table, collection, endpoint path). Return `nil` if not applicable.
197
197
 
198
- ### Query Building (10 methods)
198
+ ### Query Building (10 methods, 1 optional)
199
199
 
200
200
  These methods build and manipulate query scopes. A "scope" is any chainable query object — an `ActiveRecord::Relation`, a `Mongoid::Criteria`, or your own query builder.
201
201
 
@@ -263,6 +263,16 @@ Extracts raw values for a single column from a scope.
263
263
 
264
264
  Counts records. When `scope` is `nil`, count all records.
265
265
 
266
+ #### `exact_count(scope = nil)` → `Integer` or `nil` (optional)
267
+
268
+ The number of records the relation lists, matching the index total, or `nil` when the adapter
269
+ cannot know it exactly. Unknown is not zero: scope tabs then show no number. The default calls
270
+ `count`, and returns nil without logging when `count` raises `NotImplementedError`, so an
271
+ adapter that never implements `count` does not take down an index that has counts on.
272
+ Override it when `count` is not that total. ActiveRecord counts rows with `count(:all)`
273
+ and turns a grouped Hash into its size. The HTTP adapter returns `meta.total`, or `nil` when
274
+ the response has none.
275
+
266
276
  ### Search (2 methods)
267
277
 
268
278
  #### `search_column(scope, column, query)` → `Scope`
@@ -311,7 +321,7 @@ end
311
321
 
312
322
  Runs the block once the current transaction commits, and never if it rolls back. IronAdmin writes audit entries and calls `on_action` through it, so a member action, bulk action or import that rolls back records nothing. `Adapters::Base` runs the block at once, which is right for a data source without transactions, where each write is kept as soon as it is made. If your `transaction` is atomic, override it to run the block after the commit. The ActiveRecord adapter uses `ActiveRecord.after_all_transactions_commit`.
313
323
 
314
- ### Scope Manipulation (1 method)
324
+ ### Scope Manipulation (3 methods)
315
325
 
316
326
  #### `unscope_column(scope, column)` → `Scope`
317
327
 
@@ -325,6 +335,14 @@ def unscope_column(scope, column)
325
335
  end
326
336
  ```
327
337
 
338
+ #### `supports_soft_delete_tabs?` → `Boolean`
339
+
340
+ Whether the `with_deleted` and `only_deleted` scope tabs can run on this adapter. `Adapters::Base` returns `false`, so a resource whose records have a `deleted_at` column gets the `:restore` action but no tabs. The ActiveRecord and Mongoid adapters return `true`. Return `true` only when `unscope_column` and `only_soft_deleted` both work.
341
+
342
+ #### `only_soft_deleted(scope, column)` → `Scope`
343
+
344
+ The scope without the column's condition, keeping only the records whose column is not nil. Backs the `only_deleted` tab. `Adapters::Base` raises `NotImplementedError`.
345
+
328
346
  ### Batch (1 method)
329
347
 
330
348
  #### `find_each(scope, &block)` → `void`
@@ -582,6 +600,7 @@ Use this checklist when building a new adapter:
582
600
  - [ ] `distinct_values(column)` — sorted, compact, unique
583
601
  - [ ] `pluck(scope, column)` — raw column values
584
602
  - [ ] `count(scope)` — defaults to `all` when scope is `nil`
603
+ - [ ] `exact_count(scope)` — optional; the index total, or `nil` when it is unknown. Defaults to `count`
585
604
 
586
605
  ### Search
587
606
  - [ ] `search_column(scope, column, query)` — case-insensitive, escaped
@@ -597,6 +616,7 @@ Use this checklist when building a new adapter:
597
616
  - [ ] `transaction(&block)` — atomic or yield
598
617
  - [ ] `after_commit(&block)` — optional; override when `transaction` is atomic
599
618
  - [ ] `unscope_column(scope, column)` — removes condition
619
+ - [ ] `supports_soft_delete_tabs?` / `only_soft_deleted(scope, column)` — optional; enable the soft-delete tabs
600
620
  - [ ] `find_each(scope, &block)` — batched or `.each`, in the scope's order
601
621
 
602
622
  ### Adapter-Agnostic
@@ -8,23 +8,27 @@ Create a dashboard class in `app/iron_admin/dashboards/`:
8
8
 
9
9
  ```ruby
10
10
  # app/iron_admin/dashboards/admin_dashboard.rb
11
- class AdminDashboard < IronAdmin::Dashboard
12
- metric :total_users, format: :number do
13
- User.count
11
+ module IronAdmin
12
+ module Dashboards
13
+ class AdminDashboard < IronAdmin::Dashboard
14
+ metric :total_users, format: :number do
15
+ User.count
16
+ end
17
+
18
+ metric :monthly_revenue, format: :currency do
19
+ Payment.where("created_at > ?", 30.days.ago).sum(:amount)
20
+ end
21
+
22
+ metric :conversion_rate, format: :percentage do
23
+ total = User.count
24
+ paying = User.joins(:subscriptions).distinct.count
25
+ total.zero? ? 0 : (paying.to_f / total * 100).round(1)
26
+ end
27
+
28
+ recent :users, limit: 5, scope: -> { where(active: true) }
29
+ recent :payments, limit: 10
30
+ end
14
31
  end
15
-
16
- metric :monthly_revenue, format: :currency do
17
- Payment.where("created_at > ?", 30.days.ago).sum(:amount)
18
- end
19
-
20
- metric :conversion_rate, format: :percentage do
21
- total = User.count
22
- paying = User.joins(:subscriptions).distinct.count
23
- total.zero? ? 0 : (paying.to_f / total * 100).round(1)
24
- end
25
-
26
- recent :users, limit: 5, scope: -> { where(active: true) }
27
- recent :payments, limit: 10
28
32
  end
29
33
  ```
30
34
 
@@ -51,20 +55,23 @@ end
51
55
  Metrics render using `IronAdmin::Dashboards::MetricCardComponent`. Customize the display in your views:
52
56
 
53
57
  ```haml
54
- = render IronAdmin::Dashboards::MetricCardComponent.new(
55
- name: :total_users,
58
+ = render IronAdmin::Dashboards::MetricCardComponent.new(name: :total_users,
56
59
  value: User.count,
57
- format: :number
58
- )
60
+ format: :number)
59
61
  ```
60
62
 
61
63
  ## Charts
62
64
 
63
- Define charts for visualizing trends:
65
+ Define charts for visualizing trends. The block must return a Hash of label => value.
66
+ groupdate is not a dependency. This reads one column from the last twelve months,
67
+ including the current month. `group_by` keeps the order of the rows, which is not
68
+ chronological. `"YYYY-MM"` keys sort in calendar order. A month with no rows is
69
+ missing; zero-fill those twelve months when the chart should still show them.
64
70
 
65
71
  ```ruby
66
72
  chart :signups_over_time, type: :line do
67
- # Return chart data
73
+ signups = User.where(created_at: 11.months.ago.beginning_of_month..).pluck(:created_at)
74
+ signups.group_by { |created_at| created_at.strftime("%Y-%m") }.transform_values(&:count).sort.to_h
68
75
  end
69
76
  ```
70
77
 
@@ -80,15 +87,31 @@ end
80
87
  Charts render using `IronAdmin::Dashboards::ChartComponent`:
81
88
 
82
89
  ```haml
83
- = render IronAdmin::Dashboards::ChartComponent.new(
84
- title: "Monthly Signups",
90
+ = render IronAdmin::Dashboards::ChartComponent.new(title: "Monthly Signups",
85
91
  type: :line,
86
92
  data: [45, 52, 38, 67, 89, 95],
87
93
  labels: ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
88
- height: 300
89
- )
94
+ height: 300)
90
95
  ```
91
96
 
97
+ ### Chart Colors
98
+
99
+ Charts take their colors from the current theme: `chart_colors` for slices (bar charts fill
100
+ every bar with its first color),
101
+ `chart_border_color` for lines, and `chart_grid_color` and `chart_text_color` for grid lines,
102
+ ticks and legends. These are CSS colors, not Tailwind classes, because Chart.js draws on a
103
+ canvas. A chart's own colors win over the theme, and a bar chart given its own colors fills its
104
+ bars with them one by one:
105
+
106
+ ```ruby
107
+ chart :revenue, type: :bar, colors: ["#0ea5e9", "#6366f1"] do
108
+ # ...
109
+ end
110
+ ```
111
+
112
+ The first color is also the line color of line, area and radar charts. Charts draw their text
113
+ in the page's font. See [Color scheme, dark themes and charts](theming.md#color-scheme-dark-themes-and-charts).
114
+
92
115
  ## Recent Records
93
116
 
94
117
  Show recent records from any resource:
@@ -97,7 +120,7 @@ Show recent records from any resource:
97
120
  recent :resource_name, limit: 5, scope: -> { custom_scope }
98
121
  ```
99
122
 
100
- The `resource_name` must match a registered resource's name (model's plural form).
123
+ The `resource_name` must match a registered resource's `resource_name`. A resource whose model is the one its class name implies uses the model's plural (`UserResource` is `users`, `Billing::InvoiceResource` is that model's plural), and so does an override of that same model. An override of a different model, an overridden `self.model`, or a class name that implies no model uses the full class path under `IronAdmin::Resources` (`Shop::NoteResource` is `shop_notes`). A resource that defines `def self.resource_name` keeps that name.
101
124
 
102
125
  **Access:** like the index page, the table is only rendered when the current user may read the
103
126
  resource (`policy` and `deny_actions`), and `config.tenant_scope` applies to it, after the
@@ -119,36 +142,39 @@ current user are left out.
119
142
  Recent records render using `IronAdmin::Dashboards::RecentTableComponent`:
120
143
 
121
144
  ```haml
122
- = render IronAdmin::Dashboards::RecentTableComponent.new(
123
- resource_name: :user,
145
+ = render IronAdmin::Dashboards::RecentTableComponent.new(resource_name: :user,
124
146
  records: User.limit(5),
125
- current_user: iron_admin_current_user
126
- )
147
+ current_user: iron_admin_current_user)
127
148
  ```
128
149
 
129
150
  `current_user:` is optional. Pass it so that fields with a `visible:` proc are checked for that
130
151
  user; without it, the procs receive `nil`. An unordered relation is listed newest first, so
131
152
  `User.order(created_at: :desc).limit(5)` is not needed, but still works.
132
153
 
154
+ Every cell keeps one line, so in a narrow card the table scrolls sideways, and the engine's
155
+ `cp-scroll-fade` class fades out the edge it can still scroll toward. The card is a size
156
+ container, so the table fits the card's own width wherever a layout puts it: in a card 64rem
157
+ wide or more (`@5xl`), association cells and the label column (`name`, `title` or `label`) wrap,
158
+ long text (`:textarea`, `:rich_text`, `:markdown`) is cut to one line with an ellipsis, and the
159
+ other columns, such as dates and emails, keep their line.
160
+
133
161
  ## Stats Grid
134
162
 
135
- Display multiple metrics in a responsive grid:
163
+ Display multiple metrics in a responsive grid. With `columns: 4` (the default), the grid keeps two
164
+ columns until the `xl` breakpoint, like the metric cards, because the sidebar leaves too little room
165
+ for four at `lg`:
136
166
 
137
167
  ```haml
138
168
  = render IronAdmin::Dashboards::StatsGridComponent.new(columns: 4) do |grid|
139
- - grid.with_stat(
140
- label: "Total Users",
169
+ - grid.with_stat(label: "Total Users",
141
170
  value: User.count,
142
171
  change: "+12%",
143
172
  change_type: :positive,
144
- icon: "users"
145
- )
146
- - grid.with_stat(
147
- label: "Revenue",
173
+ icon: "users")
174
+ - grid.with_stat(label: "Revenue",
148
175
  value: number_to_currency(Payment.sum(:amount)),
149
176
  change: "-3%",
150
- change_type: :negative
151
- )
177
+ change_type: :negative)
152
178
  - grid.with_stat(label: "Active Sessions", value: session_count)
153
179
  - grid.with_stat(label: "Conversion", value: "4.2%")
154
180
  ```
@@ -160,13 +186,11 @@ Show recent activity timeline:
160
186
  ```haml
161
187
  = render IronAdmin::Dashboards::ActivityFeedComponent.new(title: "Recent Activity") do |feed|
162
188
  - @activities.each do |activity|
163
- - feed.with_item(
164
- description: activity.description,
189
+ - feed.with_item(description: activity.description,
165
190
  timestamp: activity.created_at,
166
191
  icon: "user",
167
192
  icon_color: :blue,
168
- href: activity_path(activity)
169
- )
193
+ href: activity_path(activity))
170
194
  ```
171
195
 
172
196
  ## Quick Links
@@ -7,24 +7,36 @@ IronAdmin provides built-in CSV and JSON export.
7
7
  Enabled by default with CSV and JSON:
8
8
 
9
9
  ```ruby
10
- class UserResource < IronAdmin::Resource
11
- exports :csv, :json
10
+ module IronAdmin
11
+ module Resources
12
+ class UserResource < IronAdmin::Resource
13
+ exports :csv, :json
14
+ end
15
+ end
12
16
  end
13
17
  ```
14
18
 
15
19
  Only CSV:
16
20
 
17
21
  ```ruby
18
- class UserResource < IronAdmin::Resource
19
- exports :csv
22
+ module IronAdmin
23
+ module Resources
24
+ class UserResource < IronAdmin::Resource
25
+ exports :csv
26
+ end
27
+ end
20
28
  end
21
29
  ```
22
30
 
23
31
  Disable:
24
32
 
25
33
  ```ruby
26
- class SecretResource < IronAdmin::Resource
27
- exports
34
+ module IronAdmin
35
+ module Resources
36
+ class SecretResource < IronAdmin::Resource
37
+ exports
38
+ end
39
+ end
28
40
  end
29
41
  ```
30
42
 
@@ -33,8 +45,12 @@ A format the resource does not enable returns `404`.
33
45
  ## Custom Export Fields
34
46
 
35
47
  ```ruby
36
- class UserResource < IronAdmin::Resource
37
- export_fields :id, :name, :email, :role, :created_at
48
+ module IronAdmin
49
+ module Resources
50
+ class UserResource < IronAdmin::Resource
51
+ export_fields :id, :name, :email, :role, :created_at
52
+ end
53
+ end
38
54
  end
39
55
  ```
40
56