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/UPGRADING.md
CHANGED
|
@@ -1,3 +1,473 @@
|
|
|
1
|
+
# Upgrading to IronAdmin 0.8.0 (themes and the Neutral look)
|
|
2
|
+
|
|
3
|
+
Version 0.8.0 adds named themes that people pick from the navbar, and replaces the default look with **Neutral**, a minimal light look. The Ruby, Rails and dependency requirements are the same as in 0.7.0, and the DSLs and configuration options keep working. Every admin page looks different, though, and apps that customized the theme, override views, or render their own components should read sections 2 to 6. An `authenticate` block whose value is exactly `false` now denies the request (section 9). A tool that declares actions, or inherits them from a base tool, and also defines other public methods should read section 10. Sections 11 to 15 cover the new access controls: the generated `authenticate` block, `config.default_policy`, `tool_access`, import rows that update, and the audit log per tenant. Section 16 (credential columns are hidden by default) and section 17 (`field :<association>_id` overrides now apply) change what existing resources show. Section 18 explains that `config.tenant_scope` now also runs on related records, the association selects and new records. The [theming guide](docs/guides/theming.md) documents the theme system and every property.
|
|
4
|
+
|
|
5
|
+
## What changed
|
|
6
|
+
|
|
7
|
+
### 1. The default look is Neutral
|
|
8
|
+
|
|
9
|
+
Every page is restyled:
|
|
10
|
+
|
|
11
|
+
- **Colors:** zinc grays instead of gray, a light `zinc-50` sidebar with a thin border instead of the `gray-900` sidebar, a black primary button, and indigo only as the accent (links, focus outlines, the current sidebar link, charts).
|
|
12
|
+
- **Type:** Inter, loaded from Google Fonts (see section 5). Page titles are `text-xl font-semibold` (they were `text-2xl` in the heading weight, `font-bold`), and card titles `text-sm font-semibold` (they were `text-lg`).
|
|
13
|
+
- **Sizes:** buttons, inputs and selects are 36px high (`h-9`), the navbar is 56px (`h-14`) and its search box shows a ⌘K hint, and sidebar icons are 16px.
|
|
14
|
+
- **Surfaces:** cards and panels have a 1px `zinc-200` border, `rounded-lg` corners and `shadow-xs`; buttons and inputs have `rounded-md` corners. Inputs, selects and textareas are outlined in `zinc-500` at 80%, which keeps 3:1 contrast on white (WCAG 1.4.11), and in `red-500` when their value failed validation.
|
|
15
|
+
- **Tables:** header cells are sentence case (no `uppercase tracking-wider`), cells are `px-4 py-2.5` (they were `px-6 py-4`), and number and currency columns use tabular digits.
|
|
16
|
+
- **Badges:** tinted, `rounded-md`, with a colored dot, in every place a badge appears (`:badge` fields, the audit log, `BadgeComponent`). The default badge size is `px-2 py-0.5 text-xs` (it was `px-2.5 py-0.5 text-sm`).
|
|
17
|
+
- **Dashboard:** metric cards put the label on top, the figure below and the icon in a small tile. The chart palette is indigo, teal and muted fuchsia, amber, sky and rose, each with 3:1 contrast or more on white and ordered so that neighboring slices stay apart. Bar charts fill every bar with the first chart color (a chart's own `colors:` still colors its bars one by one), pie and doughnut slices are separated by white gaps (`chart_slice_border_color`; a dark theme sets its card color there), a last chart alone in its row spans the whole row, and charts draw their text in the page font.
|
|
18
|
+
- **Page padding:** every page, the dashboard, error, new and edit pages included, uses `px-4 sm:px-6 lg:px-8 py-6` (it was `p-4 sm:p-6 lg:p-8`). The flash messages start at `pt-6`.
|
|
19
|
+
- **Other details:** an empty value on a show page shows a muted dash ("Not set" for screen readers) instead of an empty row, every cell of the dashboard's recent tables keeps one line (the table scrolls sideways; in a card 64rem wide or more, associations and the label column wrap and long text is cut with an ellipsis), tables and tab rows wider than their frame fade out at the edge they can scroll toward (`cp-scroll-fade`), the audit log dates its entries like the other pages ("Oct 28, 2026 at 1:17 AM"), search results are in the link color, the filter panel's Clear link is a secondary button, a false boolean shows a muted x icon instead of a red one, the navbar search placeholder reads "Search…" (its `aria-label`, "Search across all resources", did not change), the navbar hides the current user's name on phones (below `sm`) and truncates a long one, and the bulk-action, member-action and filter controls are secondary buttons.
|
|
20
|
+
|
|
21
|
+
**Action required:**
|
|
22
|
+
|
|
23
|
+
- Rebuild your Tailwind CSS after upgrading (`bin/rails tailwindcss:build`). The new look uses classes that only a fresh build contains. If you commit `app/assets/builds/tailwind.css`, commit the rebuilt file too.
|
|
24
|
+
- Update screenshots, visual regression baselines, and system specs or host CSS that select the old classes (`.p-8`, `.p-4`, `.text-2xl` titles, `.uppercase` headers, `rounded-full` badges and progress bars, `bg-gray-900` in the sidebar) or the old search placeholder.
|
|
25
|
+
- To keep the 0.7 look, see section 4.
|
|
26
|
+
|
|
27
|
+
### 2. The theme values you set are kept
|
|
28
|
+
|
|
29
|
+
`config.theme` still configures the default theme, and every property you set keeps your value. The properties you did not set take their Neutral values. Most apps that customized a few properties get a mix: for example, an app that only set `sidebar_bg = "bg-slate-900"` now gets Neutral's dark `zinc-900` text on its dark sidebar.
|
|
30
|
+
|
|
31
|
+
**Action required:** Look at the admin panel after upgrading. For each group you customized, set the whole group (see [Change whole groups](docs/guides/theming.md#change-whole-groups)):
|
|
32
|
+
|
|
33
|
+
- sidebar: `sidebar_bg`, `sidebar_border`, `sidebar_title`, `sidebar_link`, `sidebar_link_hover`, `sidebar_link_active` and `sidebar_group_label`. The current page's link uses `sidebar_link_active` instead of `sidebar_link` and `sidebar_link_hover`, so give it a text color;
|
|
34
|
+
- navbar: `navbar_bg`, `navbar_border`, `navbar_search_bg`, `navbar_search_focus_bg` and `navbar_text`;
|
|
35
|
+
- buttons and focus: `btn_*`, `focus_ring` and `control_radius`;
|
|
36
|
+
- cards and tables: `card_*`, `table_*` and `main_bg`.
|
|
37
|
+
|
|
38
|
+
### 3. Typography, border width and radius moved into theme properties
|
|
39
|
+
|
|
40
|
+
In 0.7, templates hard-coded part of each element's style and the theme added colors. In 0.8 the theme owns the colors and also the typography, border width, radii and shadows. If you set one of the 0.7 properties in this table to change more than its color, set its 0.8 property too:
|
|
41
|
+
|
|
42
|
+
| Element | 0.7 | 0.8 |
|
|
43
|
+
|---------|-----|-----|
|
|
44
|
+
| Page titles (h1) | `text-2xl` in the template, plus `heading_weight` and `font_family` | `page_title` (size, weight, tracking, color) and `heading_font`. `heading_weight` now only styles the sidebar brand and `cp_heading` |
|
|
45
|
+
| Card and section titles (h2) | `text-lg font-semibold` in the template | `card_title` and `heading_font` |
|
|
46
|
+
| Radius of buttons, inputs, selects, checkboxes and dropdown items | `border_radius` | `control_radius` (`rounded-md`) and `checkbox_radius`. `border_radius` keeps cards, panels, alerts, dropdowns and modals |
|
|
47
|
+
| Border width | `border` in the templates | `border_width` |
|
|
48
|
+
| Table header cells | `px-6 py-3 text-xs font-medium uppercase tracking-wider` plus `muted_text` | `table_cell_padding`, `table_header_text` and `label_transform` |
|
|
49
|
+
| Table body cells | `px-6 py-4` | `table_cell_padding` |
|
|
50
|
+
| Sidebar group labels | `text-xs font-semibold uppercase tracking-wider` | `text-xs font-medium`, `label_transform` and `sidebar_group_label` |
|
|
51
|
+
| Metric cards | `text-sm font-medium text-gray-500` label, `text-3xl font-bold` figure, indigo icon tile | `metric_label`, `metric_value` and `metric_icon` |
|
|
52
|
+
| Shadow of dropdowns, the filter panel and modals | `card_shadow` with `-lg` or `-xl` appended | `popover_shadow` |
|
|
53
|
+
| Shadow of inputs and buttons | `shadow-sm` | `control_shadow` |
|
|
54
|
+
| Badges | `BadgeComponent::COLORS`, `Configuration::BADGE_COLOR_CLASSES`, `rounded-full font-medium` | `badge_palette`, `badge_dot_palette` and `badge_shape` |
|
|
55
|
+
| Alerts and flash messages | the colors in `AlertComponent::TYPES` | `alert_palette` |
|
|
56
|
+
| Placeholders, errors, icons and secondary surfaces | gray, red and green classes in the templates | `placeholder_text`, `input_error`, `error_text`, `success_text`, `icon_muted`, `surface_muted`, `item_hover`, `chip` and others |
|
|
57
|
+
| Focus | `focus_ring` was defined but never rendered; `ButtonComponent` added `focus:ring-2` | `focus_ring` draws the keyboard focus outline of everything but text inputs and primary buttons; `btn_primary` carries the primary button's own outline |
|
|
58
|
+
|
|
59
|
+
The `cp_` helpers changed with them:
|
|
60
|
+
|
|
61
|
+
- `cp_btn_primary`, `cp_btn_secondary`, `cp_btn_danger` and `cp_btn_ghost` return complete 36px buttons (height, padding, radius, colors, shadow and focus), and `cp_btn_primary_lg` returns the same as `cp_btn_primary`.
|
|
62
|
+
- `cp_input_class`, `cp_select_class`, `cp_textarea_class` and `cp_file_input_class` take `error: true` for an invalid value, and `cp_input_class` takes `padding:` for an input with an icon. There is a new `cp_radio_class`.
|
|
63
|
+
- `cp_card` includes the border (`border_width` and `card_border`), and `cp_heading` uses `heading_font` when the theme sets one.
|
|
64
|
+
|
|
65
|
+
**Action required:**
|
|
66
|
+
|
|
67
|
+
- If you set `heading_weight` (or `font_family`) to style page titles, set `page_title` (and `heading_font` for a title font).
|
|
68
|
+
- If you set `border_radius` for square or round buttons and inputs, also set `control_radius` (and `checkbox_radius`).
|
|
69
|
+
- If you set `card_shadow`, also set `popover_shadow` for floating surfaces.
|
|
70
|
+
- If you set `focus_ring`, check that it draws a visible outline with `focus-visible:` variants, since 0.8 renders it on buttons, links and menu items. If you set `btn_primary`, include its `focus-visible:` outline classes.
|
|
71
|
+
- If you want uppercase table headers back, set `label_transform = "uppercase tracking-wider"`.
|
|
72
|
+
- In views you override (`app/views/iron_admin/...`), remove the padding, height or radius classes you combine with `cp_btn_*` and `cp_input_class`: the helpers set them now, and two classes for the same CSS property have no reliable winner in Tailwind v4.
|
|
73
|
+
- Code that reads `AlertComponent::TYPES[type][:bg]` (or `:border`, `:text`) gets `nil`: `TYPES` now holds only the icon of each type. Read `IronAdmin.current_theme.alert_palette` instead. `BadgeComponent::COLORS` now holds the Neutral badge classes, and `Configuration::BADGE_COLOR_CLASSES` keeps the 0.7 classes but IronAdmin no longer reads it.
|
|
74
|
+
|
|
75
|
+
### 4. Restoring the 0.7 look
|
|
76
|
+
|
|
77
|
+
This initializer brings back the 0.7 colors, type, borders and radii: the first part sets the 0.7 default values of the properties 0.7 had, and the second sets new properties to what 0.7 hard-coded. The structure stays Neutral: control heights, the navbar height, spacing and the layout of metric cards don't go back.
|
|
78
|
+
|
|
79
|
+
```ruby
|
|
80
|
+
# config/initializers/iron_admin.rb
|
|
81
|
+
IronAdmin.configure do |config|
|
|
82
|
+
config.theme do |t|
|
|
83
|
+
# The 0.7 default values
|
|
84
|
+
t.btn_primary = "bg-indigo-600 text-white hover:bg-indigo-700 focus:ring-2 focus:ring-indigo-500/20 focus:ring-offset-1"
|
|
85
|
+
t.btn_secondary = "bg-white text-gray-700 border border-gray-300 hover:bg-gray-50 hover:border-gray-400"
|
|
86
|
+
t.btn_danger = "bg-red-600 text-white hover:bg-red-700"
|
|
87
|
+
t.btn_ghost = "bg-gray-100 text-gray-700 hover:bg-gray-200"
|
|
88
|
+
t.link = "text-indigo-600 hover:text-indigo-900"
|
|
89
|
+
t.link_muted = "text-gray-500 hover:text-gray-700"
|
|
90
|
+
t.input_border = "border-gray-300 hover:border-gray-400"
|
|
91
|
+
t.input_focus = "focus:border-indigo-500 focus:ring-2 focus:ring-indigo-500/20"
|
|
92
|
+
t.checkbox_checked = "checked:border-indigo-600 checked:bg-indigo-600 focus:ring-2 focus:ring-indigo-500/20"
|
|
93
|
+
t.scope_active = "border-indigo-600 text-indigo-600"
|
|
94
|
+
t.scope_inactive = "border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300"
|
|
95
|
+
t.badge_count = "bg-indigo-600 text-white"
|
|
96
|
+
t.sidebar_bg = "bg-gray-900"
|
|
97
|
+
t.sidebar_title = "text-white"
|
|
98
|
+
t.sidebar_link = "text-gray-300"
|
|
99
|
+
t.sidebar_link_hover = "hover:bg-gray-800 hover:text-white"
|
|
100
|
+
t.sidebar_link_active = "bg-gray-800 text-white"
|
|
101
|
+
t.sidebar_group_label = "text-gray-400"
|
|
102
|
+
t.navbar_bg = "bg-white"
|
|
103
|
+
t.navbar_border = "border-gray-200"
|
|
104
|
+
t.navbar_search_bg = "bg-gray-50"
|
|
105
|
+
t.navbar_search_focus_bg = "focus:bg-white"
|
|
106
|
+
t.table_header_bg = "bg-gray-50"
|
|
107
|
+
t.table_row_hover = "hover:bg-gray-50"
|
|
108
|
+
t.table_border = "divide-gray-200"
|
|
109
|
+
t.card_bg = "bg-white"
|
|
110
|
+
t.card_border = "border-gray-200"
|
|
111
|
+
t.card_shadow = "shadow"
|
|
112
|
+
t.font_family = ""
|
|
113
|
+
t.heading_weight = "font-bold"
|
|
114
|
+
t.body_text = "text-gray-900"
|
|
115
|
+
t.muted_text = "text-gray-500"
|
|
116
|
+
t.label_text = "text-gray-700"
|
|
117
|
+
t.main_bg = "bg-gray-50"
|
|
118
|
+
t.border_radius = "rounded-lg"
|
|
119
|
+
t.chart_colors = %w[
|
|
120
|
+
rgba(99,102,241,0.8) rgba(59,130,246,0.8) rgba(16,185,129,0.8)
|
|
121
|
+
rgba(245,158,11,0.8) rgba(239,68,68,0.8) rgba(139,92,246,0.8)
|
|
122
|
+
]
|
|
123
|
+
t.chart_border_color = "rgb(99, 102, 241)"
|
|
124
|
+
# 0.7 never rendered its focus_ring ("focus:border-indigo-500 focus:ring-2 focus:ring-indigo-500/20").
|
|
125
|
+
# 0.8 draws the keyboard focus of buttons, links and menu items with it, so keep a visible outline.
|
|
126
|
+
t.focus_ring = "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-500"
|
|
127
|
+
|
|
128
|
+
# New properties, set to what 0.7 hard-coded
|
|
129
|
+
t.font_stylesheet_url = nil
|
|
130
|
+
t.page_title = "text-2xl font-bold text-gray-900"
|
|
131
|
+
t.card_title = "text-lg font-semibold text-gray-900"
|
|
132
|
+
t.label_transform = "uppercase tracking-wider"
|
|
133
|
+
t.table_header_text = "text-xs font-medium text-gray-500"
|
|
134
|
+
t.table_cell_padding = "px-6 py-4"
|
|
135
|
+
t.control_radius = "rounded-lg"
|
|
136
|
+
t.control_shadow = "shadow-sm"
|
|
137
|
+
t.checkbox_border = "border-gray-300"
|
|
138
|
+
t.checkbox_radius = "rounded"
|
|
139
|
+
t.input_error = "border-red-400 focus:border-red-500 focus:ring-2 focus:ring-red-500/20"
|
|
140
|
+
t.placeholder_text = "placeholder:text-gray-400"
|
|
141
|
+
t.disabled_text = "text-gray-300"
|
|
142
|
+
t.sidebar_border = ""
|
|
143
|
+
t.navbar_text = "text-gray-600"
|
|
144
|
+
t.kbd = "border-gray-200 bg-white text-gray-500"
|
|
145
|
+
t.skip_link = "focus:bg-white focus:text-gray-900 focus:shadow-lg focus:ring-2 focus:ring-indigo-500"
|
|
146
|
+
t.popover_shadow = "shadow-lg"
|
|
147
|
+
t.rich_text_editor = "" # Trix's own look
|
|
148
|
+
t.rich_text_toolbar = ""
|
|
149
|
+
t.surface_muted = "bg-gray-50"
|
|
150
|
+
t.item_hover = "hover:bg-gray-50"
|
|
151
|
+
t.item_active = "bg-gray-100"
|
|
152
|
+
t.icon_muted = "text-gray-400"
|
|
153
|
+
t.overlay_bg = "bg-gray-900/50"
|
|
154
|
+
t.error_text = "text-red-600"
|
|
155
|
+
t.success_text = "text-green-600"
|
|
156
|
+
t.alert_palette = {
|
|
157
|
+
success: "bg-green-50 border-green-200 text-green-800",
|
|
158
|
+
error: "bg-red-50 border-red-200 text-red-800",
|
|
159
|
+
warning: "bg-yellow-50 border-yellow-200 text-yellow-800",
|
|
160
|
+
info: "bg-blue-50 border-blue-200 text-blue-800",
|
|
161
|
+
}
|
|
162
|
+
t.badge_palette = IronAdmin::Configuration::BADGE_COLOR_CLASSES.dup
|
|
163
|
+
t.badge_dot_palette = {}
|
|
164
|
+
t.badge_shape = "rounded-full font-medium"
|
|
165
|
+
t.chip = "bg-indigo-50 text-indigo-700"
|
|
166
|
+
t.danger_item = "text-red-600 hover:bg-red-50"
|
|
167
|
+
t.tooltip = "bg-gray-900 text-white"
|
|
168
|
+
t.code_block = "bg-gray-900 text-gray-100"
|
|
169
|
+
t.progress_track = "bg-gray-200"
|
|
170
|
+
t.pagination_active = "bg-indigo-50 border-indigo-500 text-indigo-600"
|
|
171
|
+
t.metric_label = "text-sm font-medium text-gray-500"
|
|
172
|
+
t.metric_value = "text-3xl font-bold text-gray-900"
|
|
173
|
+
t.metric_icon = "bg-indigo-50 text-indigo-600"
|
|
174
|
+
t.chart_grid_color = "rgba(0, 0, 0, 0.1)" # Chart.js's own defaults
|
|
175
|
+
t.chart_text_color = "#666"
|
|
176
|
+
end
|
|
177
|
+
end
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
`Configuration::BADGE_COLOR_CLASSES` still holds the 0.7 badge classes, and the engine's Tailwind sources include it, so those classes compile.
|
|
181
|
+
|
|
182
|
+
### 5. Inter is loaded from Google Fonts
|
|
183
|
+
|
|
184
|
+
Neutral sets `font_stylesheet_url` to Inter on Google Fonts (`display=swap`, so text shows in a fallback font until Inter arrives), and the layout links it with preconnect tags. Every admin page view therefore makes the visitor's browser contact `fonts.googleapis.com` and `fonts.gstatic.com`, which sends Google the visitor's IP address and user agent. In 0.7 the admin panel made no third-party request.
|
|
185
|
+
|
|
186
|
+
**Action required:**
|
|
187
|
+
|
|
188
|
+
- If your app sends a Content Security Policy, allow `https://fonts.googleapis.com` in `style-src` and `https://fonts.gstatic.com` in `font-src`, or the browser blocks the font (the page still works, in the fallback font).
|
|
189
|
+
- If your privacy policy or the law that applies to you does not allow the request, turn it off for every theme. Pages then use Inter where it is installed, and the system UI font elsewhere:
|
|
190
|
+
|
|
191
|
+
```ruby
|
|
192
|
+
IronAdmin.configure do |config|
|
|
193
|
+
# ... config.theme and config.register_theme blocks ...
|
|
194
|
+
config.themes.each_value { |theme| theme.font_stylesheet_url = nil }
|
|
195
|
+
end
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
To keep Inter without Google, host the font and point `font_stylesheet_url` at your own stylesheet (see [Fonts](docs/guides/theming.md#fonts)).
|
|
199
|
+
|
|
200
|
+
### 6. Read `IronAdmin.current_theme` in custom components
|
|
201
|
+
|
|
202
|
+
Each request now has a theme, resolved before authentication. `IronAdmin.current_theme` returns it (and the default theme outside a request). `IronAdmin.configuration.theme` still exists and returns the default theme, so a custom component that reads it keeps the default look while the rest of the page shows another theme.
|
|
203
|
+
|
|
204
|
+
**Action required:** In your components, overridden views and helpers, replace `IronAdmin.configuration.theme` with `IronAdmin.current_theme`. Views that use `IronAdmin::ThemeHelper#t` already get the request's theme. To find the reads: `grep -rn "configuration.theme" app/`. If you register no theme, both return the same theme, but switching now keeps your components ready for themes. A card built from theme properties also needs `border_width` with `card_border` to draw its border.
|
|
205
|
+
|
|
206
|
+
### 7. Named themes, the theme switcher and its route
|
|
207
|
+
|
|
208
|
+
None of this changes an app that registers no theme: with a single theme, the navbar shows no switcher. When you register one (`config.register_theme`), the navbar shows a theme switcher that posts to the new route `POST /admin/theme` (`themes#update`) and stores the choice in the `iron_admin_theme` cookie. `config.default_theme` and `config.theme_resolver` choose which theme a request gets. See the [theming guide](docs/guides/theming.md#registering-more-themes).
|
|
209
|
+
|
|
210
|
+
**Action required:**
|
|
211
|
+
|
|
212
|
+
- `/admin/theme` is now an engine path, like `/admin/search` and `/admin/audit`. A resource whose `resource_name` is `theme` would lose its `POST` route to it; resources named after a plural model (`themes`) are not affected.
|
|
213
|
+
- If your app ships its own IronAdmin translations, add `iron_admin.theme_switcher.button_label` ("Theme: %{theme}"), `iron_admin.theme_switcher.menu_label` ("Themes"), `iron_admin.theme_switcher.unknown` ("That theme is not available.") and `iron_admin.fields.tags_remove` ("Remove %{tag}").
|
|
214
|
+
- If you replaced the engine's JavaScript entry point or import map pins, register and pin the new Stimulus controllers `cp-disclosure` (`iron_admin/controllers/cp_disclosure_controller`) and `cp-search-shortcut` (`iron_admin/controllers/cp_search_shortcut_controller`).
|
|
215
|
+
- If your custom navbar (`config.components.navbar`) should offer the switcher, render the new `theme_switcher` slot (see [Replacing or hiding the switcher](docs/guides/theming.md#replacing-or-hiding-the-switcher)).
|
|
216
|
+
|
|
217
|
+
### 8. Other changes since 0.7.0
|
|
218
|
+
|
|
219
|
+
0.8.0 also ships the fixes and additions listed in the [CHANGELOG](CHANGELOG.md). These can affect host code or specs:
|
|
220
|
+
|
|
221
|
+
- The titles of the dashboard widgets (`ChartComponent`, `ProgressComponent`, `RecentTableComponent`, `ActivityFeedComponent`, `QuickLinksComponent`) and of `NestedFormComponent` are `h2` instead of `h3`.
|
|
222
|
+
- A blank resource or tool name in the URL, such as `/admin/%20`, returns a bare `400 Bad Request` instead of the not found page.
|
|
223
|
+
- A `:select` filter without `options` on the foreign key of a `belongs_to` association offers the associated records by label instead of the raw ids.
|
|
224
|
+
- Scope tabs keep the search, the filters and the sort, and go back to the first page.
|
|
225
|
+
- The import preview formats each cell as the show page does ("Yes"/"No", dates, currency, masked secrets).
|
|
226
|
+
- With database storage, audit entries without a user show "Unknown" in the User column.
|
|
227
|
+
- Show page rows align their label to the top of the row (`sm:items-start`), the audit log's Clear link is a secondary button, the import preview table's frame is a focusable region, both import pages use the `max-w-7xl` page frame (the upload card is `max-w-3xl`), a valid preview row's status is a green badge, and `:markdown` and `:rich_text` values on show pages are wrapped in `trix-content` instead of `prose prose-sm max-w-none`.
|
|
228
|
+
- The rich text editor's label has an id (`record_<field>_label`) that the editor's `aria-labelledby` points to, the box around the editor has a `cp-rich-text-field` class, and the editor's text is `text-sm`.
|
|
229
|
+
- Actions and bulk actions with `form_fields:` open their form (0.6.0 and 0.7.0 ran them straight from the button). On the show page and in `ActionsComponent` such an action is a link (`a[href$="/form"]`) instead of a `button_to` form; in the index bulk bar its button has `formaction` set to the bulk form and `formmethod="get"`, and in `BulkActionsComponent` its form uses `GET`. A `confirm: true` action with form fields asks on the form's submit instead of on the show page.
|
|
230
|
+
- An action whose `required: true` field is blank, or missing from a direct POST, does not run: the response is the form again with status 422 instead of a redirect. `GET /admin/:resource/bulk_actions/:name/form` without `ids[]` redirects to the index with "No records selected", and with an id out of reach with "Some records are not accessible", as the bulk action does.
|
|
231
|
+
- A required `:boolean` action field must be checked: its checkbox (in resource and tool action forms) has the `required` attribute, and a POST to a resource or bulk action that sends `"0"`, `"false"` or `"off"` for it gets the 422 form.
|
|
232
|
+
- A member action's form says which record it applies to, in a muted `p` at the top of the form ("Applies to Article #16 (Slow news).").
|
|
233
|
+
- A `:boolean` action field has one label, the text beside its checkbox, now a `<label for>` with the required mark instead of a `<span>`; the label above the checkbox is gone (resource, bulk and tool action forms).
|
|
234
|
+
- A `confirm: true` bulk action without form fields asks before it runs: its button in the index bulk bar and in `BulkActionsComponent` has `data-turbo-confirm` (0.6.0 and 0.7.0 ran it without asking).
|
|
235
|
+
- **Who is affected:** a resource whose model is not the one its class name implies. `UserResource` stays at `/admin/users`, and so does `Billing::InvoiceResource` at its model's plural. An override of that same model stays too, including when the model has a custom `model_name` (`InvoiceResource` with `self.model_class_override = ::Invoice`). What changes for the others is `resource_name` and everything built from it: links, redirects, `live_stream_name`, the live row ids and the export filename. For some of them the served URL moves as well, because 0.7 took the registry key from the last segment of the class name when `resource_name` could not be read at load. The name comes from the full class path under `IronAdmin::Resources`:
|
|
236
|
+
|
|
237
|
+
```ruby
|
|
238
|
+
name.delete_prefix("IronAdmin::Resources::").delete_suffix("Resource").underscore.tr("/", "_").pluralize
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
- A namespaced resource with an override. `IronAdmin::Resources::Shop::NoteResource` was served at `/admin/notes` and is served at `/admin/shop_notes`. `Archive::NoteResource` moves from `/admin/notes` to `/admin/archive_notes`. Links that used the override model's plural move with `resource_name`.
|
|
242
|
+
- A resource that overrides `self.model`. On 0.7 `ExpiredLicenseResource` (`def self.model = ::License`) was served at `/admin/expired_licenses`, and only its links and redirects pointed at `/admin/licenses`. 0.8 keeps `/admin/expired_licenses` and points the links and redirects there. `LicenseResource` stays at `/admin/licenses`.
|
|
243
|
+
- An HTTP resource. A namespaced one was served at the last segment: `IronAdmin::Resources::Shop::ProductResource` at `/admin/products`, while its links already used the adapter plural `/admin/shop_products`. 0.8 serves it at `/admin/shop_products`. A non-namespaced HTTP resource stays, `ProductResource` at `/admin/products`.
|
|
244
|
+
- A resource with a custom `def self.resource_name`. 0.7 registered it before that method existed, so `NoteResource` with `def self.resource_name = "archived_notes"` was served at `/admin/notes` and its links pointed at `/admin/archived_notes`. 0.8 serves it at `/admin/archived_notes`.
|
|
245
|
+
|
|
246
|
+
`AutoNoteResource` was already served at `/admin/auto_notes` in 0.7. What pointed at `/admin/notes` was `resource_name`: the links and the redirects. There is no `resource_name=` writer.
|
|
247
|
+
- Before 0.8, the last class registered under a name replaced the previous one. The first class now keeps the name. A class whose name matches the stored class is a reload: it replaces that entry and is not logged as a collision. Two different classes that share a name keep the first, and the collision is logged once when the registry finalizes. Do not call `ResourceRegistry.reset!` in a host spec: it empties the registry for the rest of the run. Give the stub the replaced class's `name`, so the registry treats it as a reload, and register the original again in an `after` hook:
|
|
248
|
+
|
|
249
|
+
```ruby
|
|
250
|
+
stub = Class.new(IronAdmin::Resource) do
|
|
251
|
+
def self.name = "IronAdmin::Resources::UserResource"
|
|
252
|
+
def self.resource_name = "users"
|
|
253
|
+
end
|
|
254
|
+
IronAdmin::ResourceRegistry.register(stub)
|
|
255
|
+
|
|
256
|
+
# after
|
|
257
|
+
IronAdmin::ResourceRegistry.register(IronAdmin::Resources::UserResource)
|
|
258
|
+
```
|
|
259
|
+
- The index renders only the bulk actions the current user may run (`@permitted_bulk_actions`), and it hides the ones the policy denies. It evaluates every bulk action's `if:` condition on each render, with the current user, which is `nil` when the `current_user` block returns `nil`, or when no `current_user` block is configured. Write the condition nil-safe (`user&.admin?`). A condition that raises is logged and that action is hidden; posting the action still runs the condition. A host that overrides `index.html.haml` must render the bulk bar and the checkboxes from `@permitted_bulk_actions`, render neither when that list is empty, and pass `authenticity_token: form_authenticity_token` to the bulk `form_tag`. The `table` slot passes that same list as `bulk_actions:`. A custom table renders a checkbox per row only when `bulk_actions` has actions, and renders no checkbox column when it is empty.
|
|
260
|
+
|
|
261
|
+
**Action required:** Update host CSS and system specs that select these titles as `h3`, expect a `404` for a blank name, or expect raw ids in foreign key filters or raw values in the import preview. Update specs and scripts that post to an action with form fields while leaving a required field blank, or that click its show page button and expect the action to run. System specs that click the bulk bar button of a `confirm: true` bulk action without form fields now get a confirmation dialog to accept. Make bulk action `if:` conditions nil-safe (`user&.admin?`): the index evaluates every one of them on each render, with the current user, which is `nil` when the `current_user` block returns `nil`, or when no `current_user` block is configured. A host that overrides the index must render the bulk bar and the checkboxes from `@permitted_bulk_actions` (neither when it is empty) and pass `authenticity_token: form_authenticity_token` to the bulk `form_tag`. A custom `table` component receives that list as `bulk_actions:` and renders checkboxes only when it has actions. Specs that swap a resource with `ResourceRegistry.register` must not call `ResourceRegistry.reset!`. Give the stub the replaced class's `name`, so the registry treats it as a reload, and register the original again in an `after` hook. If your app ships its own IronAdmin translations, add `iron_admin.resources.bulk_action_form.selected` (`one: "Applies to 1 selected record."`, `other: "Applies to %{count} selected records."`), `iron_admin.resources.action_form.record` (`"Applies to %{model} #%{id}."`) and `iron_admin.resources.action_form.record_with_label` (`"Applies to %{model} #%{id} (%{label})."`).
|
|
262
|
+
|
|
263
|
+
### 9. An authenticate block whose value is false now denies access
|
|
264
|
+
|
|
265
|
+
`config.authenticate` runs before every admin request. Redirect or render inside the block to choose the response. If the block's value is exactly `false` and it has not already responded, IronAdmin now responds with `403`. HTML gets the error page in a minimal layout: the stylesheets and the theme classes, without the admin shell (no sidebar, navbar, search or theme switcher) and without a link back into the admin. Any other format gets a bare `403`. Before 0.8.0 the value was ignored, so the request continued.
|
|
266
|
+
|
|
267
|
+
Make `false` the last value of the block. To stop early, write `next false`. Do not write `return` inside the block. The block runs from the controller, and `return` leaves the method that defined the block, which in an initializer raises `LocalJumpError`.
|
|
268
|
+
|
|
269
|
+
`nil`, `true` and any other value still allow the request. A block that ends with `redirect_to ... unless ...` has the value `nil` when it does not redirect. The initializer generated by `rails generate iron_admin:install` leaves the block body commented out, so its value is `nil` and it is not affected. A block that already redirected or rendered keeps that response.
|
|
270
|
+
|
|
271
|
+
**Who is affected:**
|
|
272
|
+
|
|
273
|
+
1. **Access checks** such as `current_user&.admin?` or `user_signed_in?`. Before 0.8.0 they never denied anyone, so anyone who reached `/admin` could use it. 0.8.0 enforces them. Do not end these blocks with `nil`: that turns the check off and opens the admin to everyone.
|
|
274
|
+
|
|
275
|
+
With Devise the block can keep `controller.current_user&.admin? || false`. Otherwise use a session lookup. A signed-out visitor makes `&.admin?` return `nil`, and `nil` allows the request, so end the check with `|| false`:
|
|
276
|
+
|
|
277
|
+
```ruby
|
|
278
|
+
config.authenticate do |controller|
|
|
279
|
+
# || false: a signed-out visitor makes &.admin? nil, and nil allows the request.
|
|
280
|
+
User.find_by(id: controller.session[:user_id])&.admin? || false
|
|
281
|
+
end
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
IronAdmin controllers inherit from `ActionController::Base`, not from the host's `ApplicationController`, so `controller.current_user` exists only when the host defines it on every controller, as Devise does. Elsewhere it raises `NoMethodError` on every admin request. `controller.cookies` is private; use `controller.request.cookie_jar`.
|
|
285
|
+
|
|
286
|
+
2. **Blocks whose last expression is `false` as a status, not a decision.** A failed `save` or `update`, a failed `Rails.cache.write`, or an assignment such as `Current.impersonating = false`. These allowed the request before 0.8.0 and should keep allowing it. End the block with `nil`.
|
|
287
|
+
|
|
288
|
+
**Action required:**
|
|
289
|
+
|
|
290
|
+
- For an access check, do not add `nil`. Check the audit log and the access logs for who used the admin while the check was ignored, and update specs that reached the admin as a non-admin and now get `403`.
|
|
291
|
+
- Mind `|| false` for signed-out visitors, as in the example above.
|
|
292
|
+
- For a status `false` (case 2), end the block with `nil` to keep the old behavior:
|
|
293
|
+
|
|
294
|
+
```ruby
|
|
295
|
+
config.authenticate do |controller|
|
|
296
|
+
controller.redirect_to "/login" unless controller.session[:user_id]
|
|
297
|
+
Current.impersonating = false
|
|
298
|
+
nil
|
|
299
|
+
end
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
- If you override `iron_admin/shared/error`, `layouts/iron_admin/application` or its head: the error template now also renders for an authentication denial, inside `layouts/iron_admin/minimal`. It still receives only the local `error`. `iron_admin_error_navigation?` is false on that page; keep links into the admin and policy calls behind it. The minimal layout's head comes from `layouts/iron_admin/_document_head`, so a host that changed the head of the application layout should override `minimal` or `_document_head` too.
|
|
303
|
+
|
|
304
|
+
### 10. Tools that declare actions only run those actions
|
|
305
|
+
|
|
306
|
+
A tool that declares one or more `tool_action`s used to run any other public method defined on that tool when a request posted the method's name to `/admin/tools/:tool/:action`. That request did not check a `condition:`. It now returns 404 and does not call the method. Authentication and CSRF still apply, as they did before.
|
|
307
|
+
|
|
308
|
+
You are affected when the tool, or any tool it inherits from, declares a `tool_action`. A subclass then only runs declared actions, including actions declared on the base class. Its own public methods that are not declared return 404, with no deprecation warning. The 0.7 guide told you to declare shared actions once on a base tool; that base declaration is what makes every subclass affected.
|
|
309
|
+
|
|
310
|
+
Something is affected if it posts a method name that is not a declared action: a button in a custom tool view, a script, or a request spec.
|
|
311
|
+
|
|
312
|
+
**Action required:** Declare all of a tool's actions at once, each with the same `condition:` as the tool's other actions. Declaring only the method named in a deprecation warning turns the tool's other public methods into silent 404s, because a tool that declares one action dispatches only declared actions. A declared action also appears as a button on the default tool page. Make helpers that are not actions `private`.
|
|
313
|
+
|
|
314
|
+
```ruby
|
|
315
|
+
module IronAdmin
|
|
316
|
+
module Tools
|
|
317
|
+
class BaseTool < IronAdmin::Tool
|
|
318
|
+
tool_action :refresh, condition: ->(user) { user&.admin? }
|
|
319
|
+
|
|
320
|
+
def refresh
|
|
321
|
+
end
|
|
322
|
+
end
|
|
323
|
+
|
|
324
|
+
class ReportsTool < BaseTool
|
|
325
|
+
tool_action :export_csv, condition: ->(user) { user&.admin? }
|
|
326
|
+
|
|
327
|
+
def export_csv
|
|
328
|
+
end
|
|
329
|
+
|
|
330
|
+
private
|
|
331
|
+
|
|
332
|
+
def filename_for(report)
|
|
333
|
+
end
|
|
334
|
+
end
|
|
335
|
+
end
|
|
336
|
+
end
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
A tool that declares no `tool_action`, and inherits none, still runs its own public methods. That fallback is deprecated and removed in 1.0. Each dispatch warns once per tool class and method through `IronAdmin.deprecator`, which is registered as `:iron_admin` on `Rails.application.deprecators`. Declare all of a tool's actions at once with `tool_action` before 1.0.
|
|
340
|
+
|
|
341
|
+
`config.active_support.deprecation` is a Rails setting in the environment files (`config/environments/*.rb`). It applies to every deprecator registered on `Rails.application.deprecators`, including `:iron_admin`, so it silences them or makes them raise. Assigning it inside `IronAdmin.configure` raises `NoMethodError`, because that `config` is IronAdmin's configuration. To change only IronAdmin's warnings, set the deprecator in `config/initializers/iron_admin.rb`:
|
|
342
|
+
|
|
343
|
+
```ruby
|
|
344
|
+
Rails.application.deprecators[:iron_admin].behavior = :log
|
|
345
|
+
# or
|
|
346
|
+
Rails.application.deprecators[:iron_admin].silenced = true
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
To turn the fallback off now, set `strict_tool_actions` in an initializer. Undeclared names then return 404 for every tool:
|
|
350
|
+
|
|
351
|
+
```ruby
|
|
352
|
+
# config/initializers/iron_admin.rb
|
|
353
|
+
IronAdmin.configure do |config|
|
|
354
|
+
config.strict_tool_actions = true
|
|
355
|
+
end
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
### 11. A fresh install denies every request until authentication is wired
|
|
359
|
+
|
|
360
|
+
`rails generate iron_admin:install` now writes an `authenticate` block whose value is `false`, so a new install answers every admin request with `403` until you replace the block with your app's authentication. Initializers that already exist do not change. In production, IronAdmin logs a warning at boot when no `authenticate` block is configured, because the admin then answers every request unless a route constraint protects the mount (for example Devise's `authenticate :user do ... end` around `mount`).
|
|
361
|
+
|
|
362
|
+
**Action required:** None for existing apps. A script or test that runs the generator and expects the admin to answer `200` must replace the generated block first.
|
|
363
|
+
|
|
364
|
+
### 12. `config.default_policy` for resources without a policy
|
|
365
|
+
|
|
366
|
+
A resource without a `policy` block still allows every CRUD, custom and bulk action to every user the `authenticate` block admits. `config.default_policy = :deny` denies them all instead, and also closes tools that declare no `tool_access` (section 13). The default stays `:allow` in 0.8 and becomes `:deny` in 1.0. In development, IronAdmin logs at boot the resources that have no policy while the setting is `:allow`.
|
|
367
|
+
|
|
368
|
+
**Action recommended:** When `authenticate` admits users other than administrators, add a policy to every resource and set:
|
|
369
|
+
|
|
370
|
+
```ruby
|
|
371
|
+
# config/initializers/iron_admin.rb
|
|
372
|
+
IronAdmin.configure do |config|
|
|
373
|
+
config.default_policy = :deny
|
|
374
|
+
end
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
### 13. Tools can restrict who opens them
|
|
378
|
+
|
|
379
|
+
`tool_access ->(user) { ... }` on a tool guards the tool page, every action (including actions declared without `condition:`), its action forms and the legacy dispatch of undeclared methods, and the sidebar hides the tool from users it denies. A tool without it follows `config.default_policy`.
|
|
380
|
+
|
|
381
|
+
**Action recommended:** Add `tool_access` to tools that run dangerous operations:
|
|
382
|
+
|
|
383
|
+
```ruby
|
|
384
|
+
module IronAdmin
|
|
385
|
+
module Tools
|
|
386
|
+
class CacheManagerTool < IronAdmin::Tool
|
|
387
|
+
tool_access ->(user) { user&.admin? }
|
|
388
|
+
end
|
|
389
|
+
end
|
|
390
|
+
end
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
### 14. An import row that updates a record needs `:update`
|
|
394
|
+
|
|
395
|
+
With `import_upsert_key`, a row that matches an existing record updates it. That row now needs the `:update` permission, and a row that creates a record needs `:create`. A denied row is reported as an error in the preview and counted as failed; the other rows still import. Before, the whole import was checked once with `:create`, so a user allowed only to create could update every matched record.
|
|
396
|
+
|
|
397
|
+
**Action required:** If a policy allows `:create` but not `:update` and its users relied on imports updating records, allow `:update` for them.
|
|
398
|
+
|
|
399
|
+
### 15. Keeping the audit log per tenant
|
|
400
|
+
|
|
401
|
+
`/admin/audit` lists every entry to every user the `authenticate` block admits. In a multi-tenant app, set `config.audit_tenant` so each logged change stores the current tenant's key and the page lists only the current tenant's entries:
|
|
402
|
+
|
|
403
|
+
```ruby
|
|
404
|
+
# config/initializers/iron_admin.rb
|
|
405
|
+
IronAdmin.configure do |config|
|
|
406
|
+
config.audit_tenant { |_controller| Current.organization&.id }
|
|
407
|
+
end
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
Entries logged before the block was set have no key and no longer appear on the page. With `config.audit_storage = :database`, an existing `iron_admin_audit_entries` table needs the column, or the audit page raises `IronAdmin::ConfigurationError`:
|
|
411
|
+
|
|
412
|
+
```ruby
|
|
413
|
+
class AddTenantKeyToIronAdminAuditEntries < ActiveRecord::Migration[8.0]
|
|
414
|
+
def change
|
|
415
|
+
add_column :iron_admin_audit_entries, :tenant_key, :string
|
|
416
|
+
add_index :iron_admin_audit_entries, :tenant_key
|
|
417
|
+
end
|
|
418
|
+
end
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
### 16. Credential columns are hidden by default
|
|
422
|
+
|
|
423
|
+
IronAdmin now infers well-known credential columns as hidden and read-only: `encrypted_password`, `password_digest`, `reset_password_token`, `confirmation_token`, `unlock_token`, `remember_token`, `invitation_token`, `authentication_token`, `otp_secret`, `encrypted_otp_secret`, `encrypted_otp_secret_iv`, `encrypted_otp_secret_salt`, `otp_backup_codes`, and any `*_password_digest` column. They disappear from the index, the show page, the form, exports, search, sorting and filters. A hidden field is also no longer sortable, writable through nested attributes, or logged in audit changes, whatever made it hidden.
|
|
424
|
+
|
|
425
|
+
**Action required:** Only if an admin page relied on showing one of these columns. Show it again with `visible:`; it stays read-only unless you also pass `readonly: false`:
|
|
426
|
+
|
|
427
|
+
```ruby
|
|
428
|
+
module IronAdmin
|
|
429
|
+
module Resources
|
|
430
|
+
class UserResource < IronAdmin::Resource
|
|
431
|
+
field :confirmation_token, visible: ->(user) { user&.admin? }
|
|
432
|
+
end
|
|
433
|
+
end
|
|
434
|
+
end
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
### 17. `field :<association>_id` now applies to the association field
|
|
438
|
+
|
|
439
|
+
A `field` override named after a `belongs_to` foreign key (`field :organization_id, ...`) used to be ignored, because the inferred field is named after the association (`:organization`). It now applies. If a resource declared such an override and relied on it doing nothing, its options (for example `readonly:` or `visible: false`) now take effect. In development and test, IronAdmin logs at boot every `field` name that still matches no field.
|
|
440
|
+
|
|
441
|
+
**Action required:** Review `field :*_id` overrides on `belongs_to` foreign keys; each now changes that association's field.
|
|
442
|
+
|
|
443
|
+
### 18. The tenant scope also applies to related records and to new records
|
|
444
|
+
|
|
445
|
+
`config.tenant_scope` now also filters the related records on show pages (the `has_one`, many-to-many and `has_many` panels) and the options of the polymorphic, many-to-many and nested selects, and new records are built inside it. The block therefore runs on every model the admin queries, as it already did for `belongs_to` selects and each resource's own index. A block that adds a condition only some models have (for example `scope.where(organization_id: ...)` when a related model has no `organization_id`) now raises on those pages.
|
|
446
|
+
|
|
447
|
+
Every create and update also checks, inside a transaction, that the saved record and its nested rows are still inside the tenant scope; a write that would leave it is rolled back with `422`, and such an import row fails. With an `IN` list, a range or a join in the block, new records get no tenant column automatically, so the form must submit a value inside the scope. On Mongoid and HTTP resources, which have no transactions, the check runs before the write: Mongoid matches the tenant selector in memory, and an HTTP resource whose tenant block is not a plain equality cannot be checked, so its creates and updates are rejected with `422` while a tenant scope is configured.
|
|
448
|
+
|
|
449
|
+
**Action required:** Make the block return the scope unchanged for models that have no tenant column:
|
|
450
|
+
|
|
451
|
+
```ruby
|
|
452
|
+
IronAdmin.configure do |config|
|
|
453
|
+
config.tenant_scope do |scope|
|
|
454
|
+
organization = Current.organization
|
|
455
|
+
next scope unless organization && scope.model.column_names.include?("organization_id")
|
|
456
|
+
|
|
457
|
+
scope.where(organization_id: organization.id)
|
|
458
|
+
end
|
|
459
|
+
end
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
## What does NOT change
|
|
463
|
+
|
|
464
|
+
- **Requirements** — Ruby >= 3.3, Rails >= 8.0.4 and the same dependency floors as 0.7.0.
|
|
465
|
+
- **Configuration** — `IronAdmin.configure` blocks work as before, except an `authenticate` block whose value is exactly `false` (section 9). `config.theme` still yields and returns the default theme, and the 38 theme properties of 0.7 keep their names and meaning.
|
|
466
|
+
- **DSLs and routes** — No DSL method was removed or renamed. The only new route is `POST /admin/theme`.
|
|
467
|
+
- **Database** — No new migrations.
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
1
471
|
# Upgrading to IronAdmin 0.7.0 (Ruby 3.3+ / Rails 8.0.4+)
|
|
2
472
|
|
|
3
473
|
Version 0.7.0 raises the minimum Ruby and Rails versions and declares dependency floors that match the APIs IronAdmin actually uses. It also closes several authorization and data-handling gaps, and makes component overrides take effect. The resource, dashboard, tool and policy DSLs keep their methods, but some requests that used to succeed now return `403` or `404`, and some markup changed. Read every section before upgrading.
|
|
@@ -136,19 +606,26 @@ For an action without a `tool_action` declaration, `POST /admin/tools/:tool/:act
|
|
|
136
606
|
**Action required:** Declare shared actions with `tool_action`. Declarations are inherited, so declaring the action once on the base class covers every subclass. Declared actions also get a button on the default tool page.
|
|
137
607
|
|
|
138
608
|
```ruby
|
|
139
|
-
# Before:
|
|
609
|
+
# Before (0.6):
|
|
610
|
+
# /admin/tools/reports/refresh ran the inherited method
|
|
140
611
|
class BaseTool < IronAdmin::Tool
|
|
141
612
|
def refresh; end
|
|
142
613
|
end
|
|
143
614
|
|
|
144
615
|
class ReportsTool < BaseTool
|
|
145
616
|
end
|
|
617
|
+
```
|
|
146
618
|
|
|
619
|
+
```ruby
|
|
147
620
|
# After: declare it (once on the base class is enough)
|
|
148
|
-
|
|
149
|
-
|
|
621
|
+
module IronAdmin
|
|
622
|
+
module Tools
|
|
623
|
+
class BaseTool < IronAdmin::Tool
|
|
624
|
+
tool_action :refresh
|
|
150
625
|
|
|
151
|
-
|
|
626
|
+
def refresh; end
|
|
627
|
+
end
|
|
628
|
+
end
|
|
152
629
|
end
|
|
153
630
|
```
|
|
154
631
|
|
|
@@ -477,8 +954,12 @@ If you have a custom adapter (not using the built-in `:active_record` or `:mongo
|
|
|
477
954
|
To use IronAdmin with MongoDB, add `mongoid` to your Gemfile and configure resources:
|
|
478
955
|
|
|
479
956
|
```ruby
|
|
480
|
-
|
|
481
|
-
|
|
957
|
+
module IronAdmin
|
|
958
|
+
module Resources
|
|
959
|
+
class ArticleResource < IronAdmin::Resource
|
|
960
|
+
self.adapter_class = :mongoid
|
|
961
|
+
end
|
|
962
|
+
end
|
|
482
963
|
end
|
|
483
964
|
```
|
|
484
965
|
|
|
@@ -551,11 +1032,14 @@ mv app/iron_admin/*_dashboard.rb app/iron_admin/dashboards/
|
|
|
551
1032
|
Wrap each resource class in the `IronAdmin::Resources` module:
|
|
552
1033
|
|
|
553
1034
|
```ruby
|
|
554
|
-
# Before (
|
|
1035
|
+
# Before (0.4):
|
|
1036
|
+
# app/iron_admin/user_resource.rb
|
|
555
1037
|
class UserResource < IronAdmin::Resource
|
|
556
1038
|
# ...
|
|
557
1039
|
end
|
|
1040
|
+
```
|
|
558
1041
|
|
|
1042
|
+
```ruby
|
|
559
1043
|
# After (app/iron_admin/resources/user_resource.rb)
|
|
560
1044
|
module IronAdmin
|
|
561
1045
|
module Resources
|
|
@@ -571,11 +1055,14 @@ end
|
|
|
571
1055
|
Wrap each dashboard class in the `IronAdmin::Dashboards` module:
|
|
572
1056
|
|
|
573
1057
|
```ruby
|
|
574
|
-
# Before (
|
|
1058
|
+
# Before (0.4):
|
|
1059
|
+
# app/iron_admin/admin_dashboard.rb
|
|
575
1060
|
class AdminDashboard < IronAdmin::Dashboard
|
|
576
1061
|
# ...
|
|
577
1062
|
end
|
|
1063
|
+
```
|
|
578
1064
|
|
|
1065
|
+
```ruby
|
|
579
1066
|
# After (app/iron_admin/dashboards/admin_dashboard.rb)
|
|
580
1067
|
module IronAdmin
|
|
581
1068
|
module Dashboards
|