iron_admin 0.7.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +129 -1
- data/README.md +48 -1
- data/UPGRADING.md +495 -8
- data/app/assets/tailwind/iron_admin/engine.css +79 -4
- data/app/components/iron_admin/dashboards/activity_feed_component/item_component.html.haml +6 -9
- data/app/components/iron_admin/dashboards/activity_feed_component.html.haml +6 -5
- data/app/components/iron_admin/dashboards/activity_feed_component.rb +21 -24
- data/app/components/iron_admin/dashboards/chart_component.html.haml +3 -5
- data/app/components/iron_admin/dashboards/chart_component.rb +86 -24
- data/app/components/iron_admin/dashboards/concerns/themed_card.rb +39 -0
- data/app/components/iron_admin/dashboards/metric_card_component.html.haml +8 -7
- data/app/components/iron_admin/dashboards/metric_card_component.rb +2 -0
- data/app/components/iron_admin/dashboards/progress_component.html.haml +11 -7
- data/app/components/iron_admin/dashboards/progress_component.rb +11 -6
- data/app/components/iron_admin/dashboards/quick_links_component/link_component.html.haml +8 -9
- data/app/components/iron_admin/dashboards/quick_links_component.html.haml +6 -5
- data/app/components/iron_admin/dashboards/quick_links_component.rb +4 -12
- data/app/components/iron_admin/dashboards/recent_table_component.html.haml +15 -10
- data/app/components/iron_admin/dashboards/recent_table_component.rb +49 -0
- data/app/components/iron_admin/dashboards/stats_grid_component/stat_component.html.haml +13 -14
- data/app/components/iron_admin/dashboards/stats_grid_component.html.haml +1 -0
- data/app/components/iron_admin/dashboards/stats_grid_component.rb +9 -11
- data/app/components/iron_admin/filters/bar_component.html.haml +8 -6
- data/app/components/iron_admin/filters/bar_component.rb +56 -9
- data/app/components/iron_admin/filters/control_styles.rb +82 -0
- data/app/components/iron_admin/filters/date_range_component.html.haml +9 -4
- data/app/components/iron_admin/filters/date_range_component.rb +10 -6
- data/app/components/iron_admin/filters/search_component.html.haml +4 -4
- data/app/components/iron_admin/filters/search_component.rb +3 -5
- data/app/components/iron_admin/filters/select_filter_component.html.haml +1 -1
- data/app/components/iron_admin/filters/select_filter_component.rb +5 -16
- data/app/components/iron_admin/form/belongs_to_autocomplete_component.html.haml +9 -5
- data/app/components/iron_admin/form/belongs_to_autocomplete_component.rb +10 -8
- data/app/components/iron_admin/form/belongs_to_component.html.haml +2 -2
- data/app/components/iron_admin/form/belongs_to_component.rb +4 -18
- data/app/components/iron_admin/form/checkbox_component.rb +2 -3
- data/app/components/iron_admin/form/concerns/form_input_behavior.rb +1 -1
- data/app/components/iron_admin/form/control_classes.rb +108 -0
- data/app/components/iron_admin/form/date_picker_component.rb +3 -7
- data/app/components/iron_admin/form/field_wrapper_component.html.haml +3 -3
- data/app/components/iron_admin/form/field_wrapper_component.rb +3 -3
- data/app/components/iron_admin/form/nested_form_component.html.haml +4 -5
- data/app/components/iron_admin/form/nested_form_component.rb +12 -2
- data/app/components/iron_admin/form/select_component.html.haml +1 -1
- data/app/components/iron_admin/form/select_component.rb +2 -16
- data/app/components/iron_admin/form/text_input_component.rb +1 -5
- data/app/components/iron_admin/form/textarea_component.rb +1 -5
- data/app/components/iron_admin/layout/flash_component.html.haml +1 -1
- data/app/components/iron_admin/layout/flash_component.rb +4 -3
- data/app/components/iron_admin/layout/navbar_component.html.haml +15 -9
- data/app/components/iron_admin/layout/navbar_component.rb +29 -1
- data/app/components/iron_admin/layout/shell_component.html.haml +4 -4
- data/app/components/iron_admin/layout/shell_component.rb +16 -3
- data/app/components/iron_admin/layout/sidebar_component.html.haml +21 -25
- data/app/components/iron_admin/layout/sidebar_component.rb +76 -1
- data/app/components/iron_admin/layout/theme_switcher_component.html.haml +15 -0
- data/app/components/iron_admin/layout/theme_switcher_component.rb +74 -0
- data/app/components/iron_admin/resources/actions_component.html.haml +15 -8
- data/app/components/iron_admin/resources/actions_component.rb +34 -2
- data/app/components/iron_admin/resources/breadcrumb_component.html.haml +3 -3
- data/app/components/iron_admin/resources/breadcrumb_component.rb +8 -7
- data/app/components/iron_admin/resources/bulk_actions_component.html.haml +9 -8
- data/app/components/iron_admin/resources/bulk_actions_component.rb +47 -4
- data/app/components/iron_admin/resources/data_table_component.html.haml +15 -15
- data/app/components/iron_admin/resources/data_table_component.rb +34 -3
- data/app/components/iron_admin/resources/related_list_component.html.haml +7 -7
- data/app/components/iron_admin/resources/related_list_component.rb +26 -2
- data/app/components/iron_admin/resources/show_field_component.html.haml +3 -3
- data/app/components/iron_admin/resources/show_field_component.rb +10 -4
- data/app/components/iron_admin/resources/styles.rb +136 -0
- data/app/components/iron_admin/ui/alert_component.html.haml +2 -2
- data/app/components/iron_admin/ui/alert_component.rb +27 -31
- data/app/components/iron_admin/ui/badge_component.rb +40 -20
- data/app/components/iron_admin/ui/button_component.rb +37 -11
- data/app/components/iron_admin/ui/card_component.rb +3 -3
- data/app/components/iron_admin/ui/dropdown_component.html.haml +1 -1
- data/app/components/iron_admin/ui/dropdown_component.rb +34 -13
- data/app/components/iron_admin/ui/empty_state_component.html.haml +4 -5
- data/app/components/iron_admin/ui/empty_state_component.rb +2 -2
- data/app/components/iron_admin/ui/modal_component.html.haml +5 -5
- data/app/components/iron_admin/ui/modal_component.rb +6 -4
- data/app/components/iron_admin/ui/pagination_component.html.haml +14 -14
- data/app/components/iron_admin/ui/pagination_component.rb +26 -9
- data/app/components/iron_admin/ui/scopes_component.html.haml +2 -2
- data/app/components/iron_admin/ui/scopes_component.rb +44 -11
- data/app/components/iron_admin/ui/tooltip_component.rb +11 -4
- data/app/controllers/iron_admin/application_controller.rb +58 -4
- data/app/controllers/iron_admin/audit_controller.rb +30 -6
- data/app/controllers/iron_admin/concerns/action_executable.rb +37 -0
- data/app/controllers/iron_admin/concerns/assignable_references.rb +149 -0
- data/app/controllers/iron_admin/concerns/authorizable.rb +11 -0
- data/app/controllers/iron_admin/concerns/blank_password_filterable.rb +21 -0
- data/app/controllers/iron_admin/concerns/event_emittable.rb +47 -7
- data/app/controllers/iron_admin/concerns/filterable.rb +34 -9
- data/app/controllers/iron_admin/concerns/nested_permittable.rb +5 -3
- data/app/controllers/iron_admin/concerns/nested_tenant_check.rb +159 -0
- data/app/controllers/iron_admin/concerns/polymorphic_references.rb +131 -0
- data/app/controllers/iron_admin/concerns/scopeable.rb +54 -7
- data/app/controllers/iron_admin/concerns/searchable.rb +3 -3
- data/app/controllers/iron_admin/concerns/tenant_assignable.rb +118 -0
- data/app/controllers/iron_admin/concerns/tenant_containment.rb +146 -0
- data/app/controllers/iron_admin/exports_controller.rb +2 -2
- data/app/controllers/iron_admin/imports_controller.rb +1 -1
- data/app/controllers/iron_admin/resources_controller.rb +48 -41
- data/app/controllers/iron_admin/search_controller.rb +1 -2
- data/app/controllers/iron_admin/themes_controller.rb +50 -0
- data/app/controllers/iron_admin/tools_controller.rb +58 -5
- data/app/helpers/iron_admin/action_form_helper.rb +19 -0
- data/app/helpers/iron_admin/application_helper.rb +93 -16
- data/app/helpers/iron_admin/assignable_records_helper.rb +32 -0
- data/app/helpers/iron_admin/component_overrides_helper.rb +9 -4
- data/app/helpers/iron_admin/field_display_helper.rb +88 -43
- data/app/helpers/iron_admin/related_records_helper.rb +51 -0
- data/app/helpers/iron_admin/theme_helper.rb +56 -46
- data/app/javascript/iron_admin/controllers/cp_bulk_select_controller.js +12 -0
- data/app/javascript/iron_admin/controllers/cp_chart_controller.js +4 -0
- data/app/javascript/iron_admin/controllers/cp_disclosure_controller.js +19 -0
- data/app/javascript/iron_admin/controllers/cp_search_shortcut_controller.js +39 -0
- data/app/javascript/iron_admin/index.js +4 -0
- data/app/views/iron_admin/audit/index.html.haml +78 -81
- data/app/views/iron_admin/dashboard/index.html.haml +10 -9
- data/app/views/iron_admin/form/_action_field.html.haml +50 -0
- data/app/views/iron_admin/form/_nested_row.html.haml +18 -13
- data/app/views/iron_admin/imports/new.html.haml +14 -13
- data/app/views/iron_admin/imports/preview.html.haml +24 -21
- data/app/views/iron_admin/resources/_form.html.haml +70 -68
- data/app/views/iron_admin/resources/action_form.html.haml +16 -59
- data/app/views/iron_admin/resources/bulk_action_form.html.haml +20 -58
- data/app/views/iron_admin/resources/edit.html.haml +3 -3
- data/app/views/iron_admin/resources/index.html.haml +87 -74
- data/app/views/iron_admin/resources/new.html.haml +2 -2
- data/app/views/iron_admin/resources/show.html.haml +53 -41
- data/app/views/iron_admin/search/index.html.haml +17 -9
- data/app/views/iron_admin/shared/_pagination.html.haml +13 -10
- data/app/views/iron_admin/shared/error.html.haml +16 -12
- data/app/views/iron_admin/tools/action_form.html.haml +9 -55
- data/app/views/iron_admin/tools/show.html.haml +4 -5
- data/app/views/layouts/iron_admin/_document_head.html.haml +24 -0
- data/app/views/layouts/iron_admin/application.html.haml +4 -17
- data/app/views/layouts/iron_admin/minimal.html.haml +7 -0
- data/config/importmap.rb +2 -0
- data/config/locales/en.yml +23 -0
- data/config/routes.rb +1 -0
- data/docs/FAQ.md +87 -37
- data/docs/README.md +8 -2
- data/docs/components/README.md +6 -2
- data/docs/components/dashboard-components.md +24 -35
- data/docs/components/filter-components.md +44 -92
- data/docs/components/form-components.md +16 -32
- data/docs/components/resource-components.md +46 -27
- data/docs/components/ui-components.md +44 -26
- data/docs/getting-started/installation.md +5 -1
- data/docs/getting-started/quick-start.md +36 -23
- data/docs/guides/authentication.md +182 -42
- data/docs/guides/components.md +97 -15
- data/docs/guides/custom-adapters.md +24 -4
- data/docs/guides/dashboard.md +68 -44
- data/docs/guides/export.md +24 -8
- data/docs/guides/extending.md +206 -51
- data/docs/guides/fields.md +229 -70
- data/docs/guides/imports.md +33 -18
- data/docs/guides/resources.md +333 -111
- data/docs/guides/theming.md +930 -58
- data/docs/guides/troubleshooting.md +7 -3
- data/docs/plugin-system-design.md +8 -7
- data/docs/reference/configuration.md +51 -16
- data/docs/reference/routes.md +1 -0
- data/docs/reference/theme-properties.md +101 -38
- data/lib/generators/iron_admin/install/templates/initializer.rb.tt +7 -2
- data/lib/generators/iron_admin/install_audit/templates/create_iron_admin_audit_entries.rb.tt +2 -0
- data/lib/iron_admin/action_field.rb +11 -0
- data/lib/iron_admin/adapters/active_record.rb +95 -0
- data/lib/iron_admin/adapters/base.rb +107 -0
- data/lib/iron_admin/adapters/http/query.rb +21 -0
- data/lib/iron_admin/adapters/http.rb +84 -4
- data/lib/iron_admin/adapters/mongoid.rb +96 -2
- data/lib/iron_admin/audit_log.rb +64 -6
- data/lib/iron_admin/authentication_warning.rb +31 -0
- data/lib/iron_admin/concerns/filter_definable.rb +15 -1
- data/lib/iron_admin/concerns/nestable.rb +25 -0
- data/lib/iron_admin/concerns/scope_countable.rb +56 -0
- data/lib/iron_admin/concerns/soft_deletable.rb +28 -9
- data/lib/iron_admin/configuration/components.rb +14 -3
- data/lib/iron_admin/configuration/theme/neutral_defaults.rb +179 -0
- data/lib/iron_admin/configuration/theme.rb +292 -87
- data/lib/iron_admin/configuration.rb +340 -45
- data/lib/iron_admin/dashboard.rb +22 -38
- data/lib/iron_admin/engine.rb +16 -2
- data/lib/iron_admin/errors.rb +3 -0
- data/lib/iron_admin/field.rb +78 -17
- data/lib/iron_admin/field_inferrer.rb +61 -3
- data/lib/iron_admin/field_override_warning.rb +67 -0
- data/lib/iron_admin/import/import_preview.rb +56 -7
- data/lib/iron_admin/import/importer.rb +91 -14
- data/lib/iron_admin/import/tenant_precheck.rb +67 -0
- data/lib/iron_admin/plugin/registration.rb +64 -0
- data/lib/iron_admin/plugin_registry.rb +3 -2
- data/lib/iron_admin/policy.rb +22 -12
- data/lib/iron_admin/policy_coverage_warning.rb +46 -0
- data/lib/iron_admin/request_context.rb +18 -0
- data/lib/iron_admin/resource.rb +218 -77
- data/lib/iron_admin/resource_registry.rb +86 -13
- data/lib/iron_admin/scope_counts.rb +73 -0
- data/lib/iron_admin/tenant_scope.rb +30 -0
- data/lib/iron_admin/tool.rb +61 -12
- data/lib/iron_admin/tool_context.rb +10 -6
- data/lib/iron_admin/version.rb +1 -1
- data/lib/iron_admin.rb +29 -2
- metadata +37 -7
data/docs/guides/theming.md
CHANGED
|
@@ -1,102 +1,974 @@
|
|
|
1
1
|
# Theming
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Every admin page is drawn from a **theme**, an `IronAdmin::Configuration::Theme`. Its
|
|
4
|
+
properties hold Tailwind CSS classes, plus a few CSS colors for charts, a font stylesheet URL
|
|
5
|
+
and a color scheme. IronAdmin ships one theme, **Neutral**, and uses it by default. You can:
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
- change the default theme's properties with `config.theme`,
|
|
8
|
+
- register more named themes with `config.register_theme`,
|
|
9
|
+
- choose which theme each request uses with `config.theme_resolver`. By default the resolver
|
|
10
|
+
reads a cookie that the theme switcher in the navbar sets.
|
|
11
|
+
|
|
12
|
+

|
|
13
|
+
|
|
14
|
+
The [Meridian Magazine demo](https://github.com/rubylab-app/meridian_magazine) registers three
|
|
15
|
+
themes beside Neutral: Midnight, Editorial and Brutalist. Each is one `config.register_theme`
|
|
16
|
+
block, and the switcher in its navbar moves between the four.
|
|
17
|
+
|
|
18
|
+
Sections:
|
|
19
|
+
|
|
20
|
+
- [Neutral, the default look](#neutral-the-default-look)
|
|
21
|
+
- [Customizing the default theme](#customizing-the-default-theme)
|
|
22
|
+
- [Theme properties](#theme-properties)
|
|
23
|
+
- [Registering more themes](#registering-more-themes)
|
|
24
|
+
- [Themes from plugins](#themes-from-plugins)
|
|
25
|
+
- [Choosing the default theme](#choosing-the-default-theme)
|
|
26
|
+
- [Picking a theme per request](#picking-a-theme-per-request)
|
|
27
|
+
- [The theme switcher and its cookie](#the-theme-switcher-and-its-cookie)
|
|
28
|
+
- [Using the theme in your own components](#using-the-theme-in-your-own-components)
|
|
29
|
+
- [Fonts](#fonts)
|
|
30
|
+
- [Color scheme, dark themes and charts](#color-scheme-dark-themes-and-charts)
|
|
31
|
+
- [Badges, alerts and chips](#badges-alerts-and-chips)
|
|
32
|
+
- [Rich text](#rich-text)
|
|
33
|
+
- [Tailwind: literal classes and source scanning](#tailwind-literal-classes-and-source-scanning)
|
|
34
|
+
- [For contributors: the theme guards](#for-contributors-the-theme-guards)
|
|
35
|
+
|
|
36
|
+
## Neutral, the default look
|
|
37
|
+
|
|
38
|
+
Neutral is a minimal light look in the style of current developer tools:
|
|
39
|
+
|
|
40
|
+
- a `zinc-50` page and sidebar, with a white navbar and white cards, panels and tables,
|
|
41
|
+
- 1px `zinc-200` borders on cards and panels, input outlines that keep 3:1 contrast
|
|
42
|
+
(`zinc-500` at 80%), 8px corners on cards and panels (`rounded-lg`), 6px corners on
|
|
43
|
+
buttons and inputs (`rounded-md`), and almost no shadow (`shadow-xs`),
|
|
44
|
+
- the [Inter](https://rsms.me/inter/) typeface, loaded from Google Fonts (see [Fonts](#fonts)),
|
|
45
|
+
- a black primary button and an indigo accent for links, focus outlines, the current sidebar
|
|
46
|
+
link and charts,
|
|
47
|
+
- compact tables: `px-4 py-2.5` cells, sentence-case headers, and tabular digits in number and
|
|
48
|
+
currency columns,
|
|
49
|
+
- tinted badges with a colored dot,
|
|
50
|
+
- 36px buttons and inputs, and a 56px navbar whose search box takes the focus on ⌘K (Ctrl K on
|
|
51
|
+
platforms other than Apple's), except in a rich text field, where the shortcut adds a link.
|
|
52
|
+
|
|
53
|
+
Neutral's text colors meet WCAG AA contrast on the backgrounds they are drawn on.
|
|
54
|
+
|
|
55
|
+
## Customizing the default theme
|
|
56
|
+
|
|
57
|
+
`config.theme` yields the default theme. That is Neutral, unless you
|
|
58
|
+
[choose another default](#choosing-the-default-theme). The block can set any property, and
|
|
59
|
+
the properties you leave alone keep their Neutral values:
|
|
6
60
|
|
|
7
61
|
```ruby
|
|
62
|
+
# config/initializers/iron_admin.rb
|
|
8
63
|
IronAdmin.configure do |config|
|
|
9
64
|
config.theme do |t|
|
|
10
|
-
t.btn_primary = "bg-
|
|
11
|
-
t.
|
|
12
|
-
t.
|
|
65
|
+
t.btn_primary = "bg-emerald-700 text-white hover:bg-emerald-600 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-emerald-600"
|
|
66
|
+
t.link = "text-emerald-700 hover:text-emerald-600"
|
|
67
|
+
t.focus_ring = "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-emerald-600"
|
|
68
|
+
t.input_focus = "focus:border-emerald-600 focus:ring-3 focus:ring-emerald-600/15"
|
|
13
69
|
end
|
|
14
70
|
end
|
|
15
71
|
```
|
|
16
72
|
|
|
17
|
-
|
|
73
|
+
`config.theme` also returns the theme, so `config.theme.link = "text-emerald-700"` works too.
|
|
74
|
+
|
|
75
|
+
An assignment replaces the whole value: the theme does not merge your classes with Neutral's.
|
|
76
|
+
When you change a property that has hover or focus states, write those classes as well.
|
|
77
|
+
|
|
78
|
+
### Change whole groups
|
|
79
|
+
|
|
80
|
+
Properties work together. If you give the sidebar a dark background, change its text colors
|
|
81
|
+
too, or Neutral's dark text stays on your dark background:
|
|
18
82
|
|
|
19
83
|
```ruby
|
|
20
84
|
config.theme do |t|
|
|
21
|
-
t.
|
|
22
|
-
t.
|
|
23
|
-
t.
|
|
24
|
-
t.
|
|
85
|
+
t.sidebar_bg = "bg-zinc-900"
|
|
86
|
+
t.sidebar_border = ""
|
|
87
|
+
t.sidebar_title = "text-white"
|
|
88
|
+
t.sidebar_link = "text-zinc-400"
|
|
89
|
+
t.sidebar_link_hover = "hover:bg-zinc-800 hover:text-white"
|
|
90
|
+
t.sidebar_link_active = "bg-zinc-800 text-white"
|
|
91
|
+
t.sidebar_group_label = "text-zinc-400"
|
|
92
|
+
end
|
|
93
|
+
```
|
|
25
94
|
|
|
26
|
-
|
|
27
|
-
t.link_muted = "text-slate-500 hover:text-slate-700"
|
|
95
|
+
### The current page in the sidebar
|
|
28
96
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
97
|
+
The sidebar link for the current page gets `aria-current="page"` and the `sidebar_link_active`
|
|
98
|
+
classes **instead of** `sidebar_link` and `sidebar_link_hover`, so give it a text color as well
|
|
99
|
+
as a background. The link is `relative`, so `before:` utilities can draw a marker. Neutral
|
|
100
|
+
draws a white pill with a thin ring and a 2px indigo bar on its left edge.
|
|
32
101
|
|
|
33
|
-
|
|
34
|
-
|
|
102
|
+
- The **Dashboard** link is current on the dashboard only.
|
|
103
|
+
- A **resource** link is current on every page of that resource: index, show, new and edit
|
|
104
|
+
(including the form shown again after a failed save), imports and action forms.
|
|
105
|
+
- A **tool** link is current on the tool's page and its action forms.
|
|
106
|
+
- A custom **menu item** (for example from a plugin) is current when the request path is the
|
|
107
|
+
item's path. The query string, the fragment and a trailing slash are ignored. For an item
|
|
108
|
+
with an absolute URL, the scheme and host must match too.
|
|
35
109
|
|
|
36
|
-
|
|
110
|
+
`sidebar_link_hover` must use `hover:` variants (for example `hover:bg-zinc-800`). Without
|
|
111
|
+
them, every link looks like the current one.
|
|
37
112
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
113
|
+
### Theme helpers in views
|
|
114
|
+
|
|
115
|
+
Templates of the engine, and views you override in `app/views/iron_admin/`, can call
|
|
116
|
+
`IronAdmin::ThemeHelper`. Its `t` returns the theme of the current request, and its `cp_`
|
|
117
|
+
helpers return ready-made class strings:
|
|
118
|
+
|
|
119
|
+
```ruby
|
|
120
|
+
t.link # => "text-indigo-600 hover:text-indigo-700"
|
|
121
|
+
cp_btn_primary # => "inline-flex h-9 shrink-0 items-center … bg-zinc-900 text-white hover:bg-zinc-700 …"
|
|
122
|
+
cp_input_class # => "block w-full h-9 px-3 text-sm … border-zinc-500/80 hover:border-zinc-500 …"
|
|
123
|
+
cp_input_class(error: true) # input_error replaces input_border and input_focus
|
|
124
|
+
cp_card # => "bg-white border border-zinc-200 rounded-lg shadow-xs"
|
|
125
|
+
cp_sidebar_link # => "text-zinc-600 hover:bg-zinc-200/60 hover:text-zinc-900"
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
The button and input helpers (`cp_btn_primary`, `cp_btn_secondary`, `cp_btn_danger`,
|
|
129
|
+
`cp_btn_ghost`, `cp_input_class`, `cp_select_class`, `cp_textarea_class`, `cp_checkbox_class`,
|
|
130
|
+
`cp_radio_class`, `cp_file_input_class`) return complete controls built by
|
|
131
|
+
`IronAdmin::Form::ControlClasses`: buttons, inputs and selects are 36px high, checkboxes and
|
|
132
|
+
radio buttons 16px.
|
|
133
|
+
|
|
134
|
+
## Theme properties
|
|
135
|
+
|
|
136
|
+
A theme has 96 properties. Most hold Tailwind classes. The table lists each one with its
|
|
137
|
+
Neutral value and what it controls.
|
|
138
|
+
|
|
139
|
+
**What a property may hold.** A CSS property is set either by a template or by a theme
|
|
140
|
+
property, never both, because Tailwind v4 does not guarantee which of two conflicting utilities
|
|
141
|
+
wins. Templates own the layout, spacing, sizes and font sizes. Theme properties own colors,
|
|
142
|
+
backgrounds, border colors, border width (`border_width`), radius (`border_radius`,
|
|
143
|
+
`control_radius`, `checkbox_radius`), shadows, font families, text transform and letter
|
|
144
|
+
spacing. A few properties are complete recipes that also set a size, weight or padding:
|
|
145
|
+
`page_title`, `card_title`, `table_header_text`, `table_cell_padding`, `metric_label` and
|
|
146
|
+
`metric_value`. So:
|
|
147
|
+
|
|
148
|
+
- don't add padding, heights or font sizes to a color property such as `card_bg`. Two padding
|
|
149
|
+
classes on one element have no reliable winner;
|
|
150
|
+
- don't use Tailwind's `dark:` variant. It follows the visitor's operating system, not the
|
|
151
|
+
theme. Write a [dark theme](#registering-more-themes) with dark colors instead.
|
|
152
|
+
|
|
153
|
+
### Buttons and links
|
|
154
|
+
|
|
155
|
+
| Property | Neutral value | Controls |
|
|
156
|
+
|----------|---------------|----------|
|
|
157
|
+
| `btn_primary` | `bg-zinc-900 text-white hover:bg-zinc-700 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-500` | Primary buttons, such as form submit buttons and the filter panel's Apply: colors, hover and keyboard focus outline. Primary buttons don't get `focus_ring`, so keep `focus-visible:` classes in this value |
|
|
158
|
+
| `btn_secondary` | `bg-white text-zinc-900 border border-zinc-200 hover:bg-zinc-50 hover:border-zinc-300` | Secondary buttons, such as member and bulk actions and the Filters button: colors, border (width included) and hover |
|
|
159
|
+
| `btn_danger` | `bg-red-600 text-white hover:bg-red-700` | Destructive buttons, such as Delete |
|
|
160
|
+
| `btn_ghost` | `bg-transparent text-zinc-700 hover:bg-zinc-100 hover:text-zinc-900` | Ghost and icon buttons: the menu and close buttons, the theme switcher, modal close buttons. They get no `control_shadow` |
|
|
161
|
+
| `link` | `text-indigo-600 hover:text-indigo-700` | Links in tables and text, such as an index row's record link and "View all" |
|
|
162
|
+
| `link_muted` | `text-zinc-500 hover:text-zinc-900` | Secondary links, such as breadcrumbs and the filter panel's Clear link |
|
|
163
|
+
|
|
164
|
+
### Forms and controls
|
|
165
|
+
|
|
166
|
+
| Property | Neutral value | Controls |
|
|
167
|
+
|----------|---------------|----------|
|
|
168
|
+
| `focus_ring` | `focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-500` | Keyboard focus outline of every interactive element except text inputs (which use `input_focus`) and primary buttons: secondary, danger and ghost buttons, sidebar links, scope tabs, pagination, dropdown and switcher items, list rows. Use `focus-visible:` variants |
|
|
169
|
+
| `input_border` | `border-zinc-500/80 hover:border-zinc-500` | Border color, with hover, of inputs, selects, textareas, the file input and the navbar search. An empty input shows nothing but this outline, so it keeps 3:1 contrast against `card_bg` (WCAG 1.4.11): zinc-500 at 80% is 3.3:1 on white, zinc-200 to zinc-400 are below 3:1 |
|
|
170
|
+
| `input_focus` | `focus:border-indigo-500 focus:ring-3 focus:ring-indigo-500/15` | Focus state of those controls: border color and ring |
|
|
171
|
+
| `input_error` | `border-red-500 focus:border-red-600 focus:ring-3 focus:ring-red-500/20` | Used **instead of** `input_border` and `input_focus` on a control whose value failed validation, so include the focus ring. Its border keeps 3:1 too: red-500 is 3.8:1 on white, red-400 2.9:1 |
|
|
172
|
+
| `placeholder_text` | `placeholder:text-zinc-500` | Placeholder color, with the `placeholder:` variant |
|
|
173
|
+
| `checkbox_checked` | `checked:border-indigo-600 checked:bg-indigo-600 focus:ring-3 focus:ring-indigo-500/15` | Checked checkboxes and radio buttons: border and background color, and their focus ring. The check mark and the dot are always white, in light and dark themes, so pick a checked background with at least 3:1 contrast against white (not zinc-50, 100 or 200 in a dark theme) |
|
|
174
|
+
| `checkbox_border` | `border-zinc-500` | Border color of unchecked checkboxes and radio buttons. It is all that shows an unchecked control, so it keeps 3:1 contrast against `card_bg` (WCAG 1.4.11): zinc-500 is 4.8:1 on white, zinc-300 and zinc-400 are below 3:1. They don't use `input_border`, whose hover color would cover the checked border |
|
|
175
|
+
| `checkbox_radius` | `rounded-sm` | Radius of checkboxes. Radio buttons are always round |
|
|
176
|
+
| `control_radius` | `rounded-md` | Radius of buttons, inputs, selects, dropdown and switcher items, sidebar links, pagination links, icon tiles and tooltips |
|
|
177
|
+
| `control_shadow` | `shadow-xs` | Shadow of inputs, selects, textareas, checkboxes, radio buttons and every button except ghost ones. Empty = none |
|
|
178
|
+
| `disabled_text` | `text-zinc-300` | Unavailable pagination links (Previous on the first page, Next on the last) |
|
|
179
|
+
| `rich_text_editor` | `border rounded-md border-zinc-500/80 hover:border-zinc-500 bg-white text-zinc-900 shadow-xs focus:border-indigo-500 focus:ring-3 focus:ring-indigo-500/15` | The rich text editor box (Action Text's `<trix-editor>`): border width and color, radius, background, text color, shadow and focus state, written as for an input. Neutral outlines it like its inputs. Empty = the look of Trix's own stylesheet (see [Rich text](#rich-text)) |
|
|
180
|
+
| `rich_text_toolbar` | `[&_.trix-button-group]:border-zinc-200! [&_.trix-button-group]:rounded-md! [&_.trix-button-group]:overflow-hidden! [&_.trix-button]:border-zinc-200! [&_.trix-button]:border-b-0! [&_.trix-button.trix-active]:bg-zinc-100! [&_.trix-dialog]:border! [&_.trix-dialog]:border-zinc-200! [&_.trix-dialog]:rounded-lg! [&_.trix-dialog]:shadow-lg! [&_.trix-input--dialog]:border-zinc-500/80! [&_.trix-input--dialog]:rounded-md!` | Classes of the box around the rich text toolbar and editor, which style the toolbar's buttons, groups and link dialog with descendant variants and the important modifier, such as `[&_.trix-button-group]:border-zinc-700!`. Empty = Trix's look (see [Rich text](#rich-text)) |
|
|
181
|
+
|
|
182
|
+
### Scope tabs and counts
|
|
183
|
+
|
|
184
|
+
| Property | Neutral value | Controls |
|
|
185
|
+
|----------|---------------|----------|
|
|
186
|
+
| `scope_active` | `border-zinc-900 text-zinc-900` | The current scope tab: underline color and text color |
|
|
187
|
+
| `scope_inactive` | `border-transparent text-zinc-500 hover:text-zinc-900 hover:border-zinc-300` | The other scope tabs, with their hover |
|
|
188
|
+
| `badge_count` | `bg-zinc-100 text-zinc-700` | Count bubbles, such as the number of active filters on the Filters button |
|
|
189
|
+
|
|
190
|
+
### Sidebar
|
|
191
|
+
|
|
192
|
+
| Property | Neutral value | Controls |
|
|
193
|
+
|----------|---------------|----------|
|
|
194
|
+
| `sidebar_bg` | `bg-zinc-50` | Sidebar background, also as the mobile drawer |
|
|
195
|
+
| `sidebar_border` | `lg:border-r border-zinc-200` | The edge between the sidebar and the page: side, width and color. With `lg:`, the mobile drawer has no border |
|
|
196
|
+
| `sidebar_title` | `text-zinc-900` | Text color of the sidebar, which the brand (`config.title`) uses |
|
|
197
|
+
| `sidebar_link` | `text-zinc-600` | Text color of the sidebar links |
|
|
198
|
+
| `sidebar_link_hover` | `hover:bg-zinc-200/60 hover:text-zinc-900` | Hover of the sidebar links (use `hover:` variants) |
|
|
199
|
+
| `sidebar_link_active` | `bg-white text-zinc-900 shadow-xs ring-1 ring-zinc-200 before:absolute before:left-0 before:inset-y-2 before:w-0.5 before:rounded-full before:bg-indigo-500` | The link of the current page, **instead of** `sidebar_link` and `sidebar_link_hover` (see [above](#the-current-page-in-the-sidebar)) |
|
|
200
|
+
| `sidebar_group_label` | `text-zinc-500` | Color of the group labels. Their case comes from `label_transform` |
|
|
201
|
+
|
|
202
|
+
### Navbar
|
|
203
|
+
|
|
204
|
+
| Property | Neutral value | Controls |
|
|
205
|
+
|----------|---------------|----------|
|
|
206
|
+
| `navbar_bg` | `bg-white` | Navbar background |
|
|
207
|
+
| `navbar_border` | `border-zinc-200` | Color of the navbar's bottom border |
|
|
208
|
+
| `navbar_border_width` | `border-b` | Side and width of that border, such as `border-b-3` for a heavy rule |
|
|
209
|
+
| `navbar_search_bg` | `bg-zinc-50` | Background of the navbar search box |
|
|
210
|
+
| `navbar_search_focus_bg` | `focus:bg-white` | Its background while it has the focus |
|
|
211
|
+
| `navbar_text` | `text-zinc-600` | Navbar text, such as the current user's name |
|
|
212
|
+
| `kbd` | `border-zinc-200 bg-white text-zinc-500` | The ⌘K hint in the search box: border, background and text color |
|
|
213
|
+
| `skip_link` | `focus:bg-white focus:text-zinc-900 focus:ring-2 focus:ring-indigo-500` | The "Skip to content" link once it has the focus (use `focus:` variants) |
|
|
214
|
+
|
|
215
|
+
### Tables
|
|
216
|
+
|
|
217
|
+
| Property | Neutral value | Controls |
|
|
218
|
+
|----------|---------------|----------|
|
|
219
|
+
| `table_header_bg` | `bg-zinc-50` | Background of the header row (also of the sticky actions column's header) |
|
|
220
|
+
| `table_header_text` | `text-xs font-medium text-zinc-500` | Header cells: size, weight and color. Their case comes from `label_transform` |
|
|
221
|
+
| `table_cell_padding` | `px-4 py-2.5` | Padding of header and body cells, which sets how dense tables are |
|
|
222
|
+
| `table_frame` | `""` | Extra classes for the panel a table scrolls in, such as a ring. Empty = none |
|
|
223
|
+
| `table_sticky_shadow` | `shadow-[-4px_0_6px_-4px_rgba(0,0,0,0.08)]` | Edge shadow of the sticky actions column of index tables (`config.sticky_actions_column`), cast by a box laid over each sticky cell (browsers do not paint a cell's own shadow in a table with collapsed borders). A hard shadow such as `shadow-[-1px_0_0_#000]` draws a rule. Empty = none |
|
|
224
|
+
| `table_row_hover` | `hover:bg-zinc-50` | Hover of table rows and of the dashboard's quick links and activity feed rows. These rows hold `muted_text`, which keeps AA contrast on it |
|
|
225
|
+
| `table_sticky_row_hover` | `""` | Background of the sticky actions cell while its row is hovered. Each index row is a `group/row`, so use `group-hover/row:` variants in the color of `table_row_hover`, such as `group-hover/row:bg-zinc-50`. Empty = the cell keeps `card_bg` |
|
|
226
|
+
| `table_border` | `divide-zinc-200` | Lines between table rows and between the items of divided lists (dashboard lists, key/value fields). Use `divide-*` classes |
|
|
227
|
+
| `table_head_border` | `""` | The line between a table's header row and its body, for example a black rule over hairline row lines. Use `divide-*` classes. Empty = `table_border` |
|
|
228
|
+
|
|
229
|
+
### Cards and panels
|
|
230
|
+
|
|
231
|
+
| Property | Neutral value | Controls |
|
|
232
|
+
|----------|---------------|----------|
|
|
233
|
+
| `card_bg` | `bg-white` | Background of cards, panels, tables and inputs, and of floating surfaces while `popover_bg` is empty |
|
|
234
|
+
| `card_border` | `border-zinc-200` | Border color of those surfaces, and of the lines inside them (panel headers, the scope tab bar, modal sections) |
|
|
235
|
+
| `card_shadow` | `shadow-xs` | Shadow of cards and panels |
|
|
236
|
+
| `popover_shadow` | `shadow-lg` | Shadow of floating surfaces: dropdown menus, the filter panel, belongs-to autocomplete results, the theme switcher panel and modals. Empty = none |
|
|
237
|
+
| `popover_bg` | `""` | Background of those floating surfaces, such as a raised tone that sets them apart from the cards under them in a dark theme. Empty = `card_bg`, so a theme that changes `card_bg` keeps its popovers on it. Pick an `item_hover` that shows on it |
|
|
238
|
+
| `card_title` | `text-sm font-semibold text-zinc-900` | Titles (h2) of cards, panels, dashboard widgets and modals: size, weight and color |
|
|
239
|
+
|
|
240
|
+
### Typography
|
|
241
|
+
|
|
242
|
+
| Property | Neutral value | Controls |
|
|
243
|
+
|----------|---------------|----------|
|
|
244
|
+
| `font_family` | `font-[family-name:Inter,ui-sans-serif,system-ui,sans-serif]` | Font family of every page (on `<body>`). Empty = the browser's default |
|
|
245
|
+
| `font_stylesheet_url` | `https://fonts.googleapis.com/css2?family=Inter:wght@400..700&display=swap` | Stylesheet that the layout links for the theme's fonts. `nil` = none (see [Fonts](#fonts)) |
|
|
246
|
+
| `heading_font` | `""` | Extra font family classes for page titles, card titles and the sidebar brand. Empty = `font_family` |
|
|
247
|
+
| `heading_weight` | `font-semibold` | Weight of the sidebar brand and of the `cp_heading` helper |
|
|
248
|
+
| `page_title` | `text-xl font-semibold tracking-tight text-zinc-900` | Page titles (h1): size, weight, tracking and color |
|
|
249
|
+
| `label_transform` | `""` | Case and letter spacing of small labels: sidebar group labels, table headers, metric labels and filter labels. Empty = as written. `uppercase tracking-wider` gives the 0.7 look |
|
|
250
|
+
| `field_label_transform` | `""` | Case and letter spacing of field labels: the labels of resource, nested record, import and action forms, and the field names on show pages. Empty = as written. Separate from `label_transform`, so the 0.7 look keeps sentence-case form labels |
|
|
251
|
+
| `body_text` | `text-zinc-900` | Main text color: the page, table cells, inputs, dropdown items |
|
|
252
|
+
| `muted_text` | `text-zinc-500` | Secondary text: hints, timestamps, record ids, empty states, pagination summaries |
|
|
253
|
+
| `label_text` | `text-zinc-700` | Form and filter labels |
|
|
254
|
+
| `error_text` | `text-red-600` | Validation messages, required marks, negative deltas, import rows with errors, and old values in the audit log |
|
|
255
|
+
| `success_text` | `text-emerald-700` | Positive deltas, the icon of a true boolean, and new values in the audit log |
|
|
256
|
+
|
|
257
|
+
### Layout and surfaces
|
|
258
|
+
|
|
259
|
+
| Property | Neutral value | Controls |
|
|
260
|
+
|----------|---------------|----------|
|
|
261
|
+
| `main_bg` | `bg-zinc-50` | Page background (`<body>` and the main area) |
|
|
262
|
+
| `border_radius` | `rounded-lg` | Radius of cards, panels, alerts, dropdowns and modals. Buttons and inputs use `control_radius` |
|
|
263
|
+
| `border_width` | `border` | Width of the outline of cards, panels, popovers, modals, alerts, inputs, checkboxes and pagination links. One-sided dividers (panel headers, footers, table rows, scope tabs) keep their template width; `sidebar_border` and `btn_secondary` carry their own, and `navbar_border_width` sets the navbar's |
|
|
264
|
+
| `color_scheme` | `"light"` | `"light"` or `"dark"`: the CSS color scheme of the page (see [Color scheme](#color-scheme-dark-themes-and-charts)). Not a Tailwind class |
|
|
265
|
+
| `swatch` | `rounded-full bg-white ring-1 ring-inset ring-zinc-500/80` | This theme's 12px swatch in the theme switcher: its shape (Neutral's is a dot), fill and ring |
|
|
266
|
+
| `surface_muted` | `bg-zinc-50` | Secondary backgrounds: readonly and disabled inputs, nested form rows, file previews, the empty state icon, audit change details |
|
|
267
|
+
| `item_hover` | `hover:bg-zinc-100` | Hover of dropdown and switcher items, search result rows and pagination links (rows with `muted_text` use `table_row_hover`) |
|
|
268
|
+
| `item_active` | `bg-zinc-100` | The belongs-to autocomplete option that the arrow keys highlight |
|
|
269
|
+
| `icon_muted` | `text-zinc-400` | Decorative icons, such as the search icon, breadcrumb separators and the empty state icon |
|
|
270
|
+
| `overlay_bg` | `bg-zinc-900/40` | Backdrop behind modals and the mobile sidebar drawer |
|
|
271
|
+
|
|
272
|
+
### Feedback: alerts, badges and other elements
|
|
273
|
+
|
|
274
|
+
| Property | Neutral value | Controls |
|
|
275
|
+
|----------|---------------|----------|
|
|
276
|
+
| `alert_palette` | Hash, see [below](#badges-alerts-and-chips) | Classes (background, border color, text color) of alerts by type: `:success`, `:error`, `:warning`, `:info`. Flash messages, form errors and the audit log's warning use it |
|
|
277
|
+
| `alert_shadow` | `""` | Shadow of those alerts, flash messages, form errors and the audit log's warning. Empty = none |
|
|
278
|
+
| `badge_palette` | Hash, see [below](#badges-alerts-and-chips) | Badge classes by color name: status badges, `:badge` fields, audit actions and activity feed icons |
|
|
279
|
+
| `badge_dot_palette` | Hash, see [below](#badges-alerts-and-chips) | Classes of the dot inside each badge, by color name. An empty Hash (`{}`) draws no dots |
|
|
280
|
+
| `badge_shape` | `rounded-md font-medium` | Radius and weight of badges, chips and count bubbles |
|
|
281
|
+
| `chip` | `bg-zinc-100 text-zinc-700 ring-1 ring-inset ring-zinc-200` | Chips: tags, has-and-belongs-to-many records on show pages, file names, boolean group values and the column names on import pages |
|
|
282
|
+
| `danger_item` | `text-red-600 hover:bg-red-50 hover:text-red-700` | Destructive dropdown items, with their hover |
|
|
283
|
+
| `tooltip` | `bg-zinc-900 text-white` | Tooltip background and text color |
|
|
284
|
+
| `code_block` | `bg-zinc-950 text-zinc-100` | Background and text color of `:code` and `:json` values |
|
|
285
|
+
| `code_font` | `font-mono` | Font family of code-like text: `:code` values, the inputs of `:code`, `:json`, `:key_value`, `:markdown` and `:color` fields, and the audit log's change details |
|
|
286
|
+
| `progress_track` | `bg-zinc-200` | Track of progress bars (`:progress` fields and dashboard progress widgets) |
|
|
287
|
+
| `pagination_active` | `bg-zinc-900 text-white border-zinc-900` | The current page in the pagination |
|
|
288
|
+
|
|
289
|
+
### Dashboard
|
|
290
|
+
|
|
291
|
+
| Property | Neutral value | Controls |
|
|
292
|
+
|----------|---------------|----------|
|
|
293
|
+
| `metric_label` | `text-xs font-medium text-zinc-500` | Label of metric, stat and progress cards: size, weight and color. Its case comes from `label_transform` |
|
|
294
|
+
| `metric_value` | `text-2xl font-semibold tracking-tight tabular-nums text-zinc-900` | The figure of those cards: size, weight, tracking and color |
|
|
295
|
+
| `metric_icon` | `bg-zinc-100 text-zinc-500` | The tile behind a card's icon: background and icon color |
|
|
43
296
|
|
|
44
|
-
|
|
45
|
-
t.navbar_border = "border-slate-200"
|
|
46
|
-
t.navbar_search_bg = "bg-slate-50"
|
|
297
|
+
### Charts
|
|
47
298
|
|
|
48
|
-
|
|
49
|
-
t.table_row_hover = "hover:bg-slate-50"
|
|
50
|
-
t.table_border = "divide-slate-200"
|
|
299
|
+
These hold CSS colors and Chart.js values, not Tailwind classes, because Chart.js draws on a canvas.
|
|
51
300
|
|
|
52
|
-
|
|
53
|
-
|
|
301
|
+
| Property | Neutral value | Controls |
|
|
302
|
+
|----------|---------------|----------|
|
|
303
|
+
| `chart_colors` | `#6366f1`, `#0d9488`, `#b446c3`, `#d07d34`, `#2584c0`, `#d43b51` (indigo, teal and muted fuchsia, amber, sky and rose) | Slice colors of the dashboard charts, in order (an Array). Bar charts fill every bar with the first one. Each Neutral color has 3:1 contrast or more on the white cards, which WCAG 1.4.11 asks of graphical objects, and Neutral's order keeps each color apart from the next, and the last from the first, for normal vision and the common color vision deficiencies |
|
|
304
|
+
| `chart_border_color` | `rgb(99, 102, 241)` | Line color of line, area and radar charts, and the fill of progress bars without a color of their own |
|
|
305
|
+
| `chart_grid_color` | `rgba(228, 228, 231, 1)` | Grid lines and axis lines |
|
|
306
|
+
| `chart_text_color` | `rgb(113, 113, 122)` | Tick labels, radar point labels and the legend |
|
|
307
|
+
| `chart_point_style` | `circle` | Shape of the legend markers, a Chart.js point style: `circle`, `rect`, `rectRounded`, `triangle` and so on |
|
|
308
|
+
| `chart_slice_border_color` | `#ffffff` | Outline of the slices of pie, doughnut and polar area charts (a CSS color). Neutral's is the white of its cards, so a gap sets each slice apart from the next; a theme with other cards sets their color. `nil` = each slice in its own color |
|
|
309
|
+
| `chart_border_width` | `nil` | Width in pixels (an Integer) of slice and bar outlines and of lines. Bars are outlined in `chart_border_color`. `nil` = the Chart.js defaults (no bar outline) |
|
|
54
310
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
311
|
+
A theme also has a `name` (a Symbol, the value its cookie stores) and a `label` (the text in
|
|
312
|
+
the switcher), set when the theme is registered. `dark?` and `scheme_class` read `color_scheme`.
|
|
313
|
+
|
|
314
|
+
## Registering more themes
|
|
315
|
+
|
|
316
|
+
`config.register_theme(name, label: name.to_s.titleize)` builds a new theme with the Neutral
|
|
317
|
+
values, yields it, and stores it under `name`:
|
|
318
|
+
|
|
319
|
+
- every theme starts from the **pristine** Neutral values. It doesn't matter whether you call
|
|
320
|
+
`register_theme` before or after `config.theme`; the changes `config.theme` makes to the
|
|
321
|
+
default theme never carry over;
|
|
322
|
+
- the label defaults to the titleized name (`:high_contrast` is "High Contrast");
|
|
323
|
+
- a Symbol, a String and any other case are the same name (`:Harbor` and `"harbor"`);
|
|
324
|
+
- registering a name the app already owns replaces that theme, and registering `:neutral`
|
|
325
|
+
replaces the built-in theme. A name a plugin owns raises `IronAdmin::PluginError` instead
|
|
326
|
+
(see [Themes from plugins](#themes-from-plugins));
|
|
327
|
+
- a blank name raises `ArgumentError`;
|
|
328
|
+
- the method returns the theme. The theme is stored only after the block returns.
|
|
329
|
+
|
|
330
|
+
Once two or more themes are registered, the navbar shows the
|
|
331
|
+
[theme switcher](#the-theme-switcher-and-its-cookie).
|
|
332
|
+
|
|
333
|
+
### A complete dark theme
|
|
334
|
+
|
|
335
|
+
This theme sets every property that holds a color. The ones it leaves alone (fonts, radii,
|
|
336
|
+
`border_width`, `table_cell_padding`, `label_transform`, `badge_shape` and so on) keep their
|
|
337
|
+
Neutral values.
|
|
338
|
+
|
|
339
|
+
```ruby
|
|
340
|
+
# config/initializers/iron_admin.rb
|
|
341
|
+
IronAdmin.configure do |config|
|
|
342
|
+
config.register_theme(:midnight, label: "Midnight") do |t|
|
|
343
|
+
t.color_scheme = "dark"
|
|
344
|
+
t.swatch = "rounded-full bg-zinc-900 ring-1 ring-inset ring-zinc-600"
|
|
345
|
+
|
|
346
|
+
# Page, sidebar and navbar
|
|
347
|
+
t.main_bg = "bg-zinc-950"
|
|
348
|
+
t.body_text = "text-zinc-100"
|
|
349
|
+
t.muted_text = "text-zinc-400"
|
|
350
|
+
t.label_text = "text-zinc-300"
|
|
351
|
+
t.page_title = "text-xl font-semibold tracking-tight text-zinc-50"
|
|
352
|
+
t.sidebar_bg = "bg-zinc-950"
|
|
353
|
+
t.sidebar_border = "lg:border-r border-zinc-800"
|
|
354
|
+
t.sidebar_title = "text-zinc-50"
|
|
355
|
+
t.sidebar_link = "text-zinc-400"
|
|
356
|
+
t.sidebar_link_hover = "hover:bg-zinc-800/60 hover:text-zinc-50"
|
|
357
|
+
t.sidebar_link_active = "bg-zinc-800 text-zinc-50 before:absolute before:left-0 before:inset-y-2 before:w-0.5 before:rounded-full before:bg-indigo-400"
|
|
358
|
+
t.sidebar_group_label = "text-zinc-400"
|
|
359
|
+
t.navbar_bg = "bg-zinc-950"
|
|
360
|
+
t.navbar_border = "border-zinc-800"
|
|
361
|
+
t.navbar_search_bg = "bg-zinc-900"
|
|
362
|
+
t.navbar_search_focus_bg = "focus:bg-zinc-900"
|
|
363
|
+
t.navbar_text = "text-zinc-400"
|
|
364
|
+
t.kbd = "border-zinc-700 bg-zinc-800 text-zinc-400"
|
|
365
|
+
t.skip_link = "focus:bg-zinc-900 focus:text-zinc-50 focus:ring-2 focus:ring-indigo-400"
|
|
366
|
+
t.overlay_bg = "bg-black/60"
|
|
367
|
+
|
|
368
|
+
# Buttons, links and focus
|
|
369
|
+
t.btn_primary = "bg-zinc-50 text-zinc-900 hover:bg-zinc-200 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-400"
|
|
370
|
+
t.btn_secondary = "bg-zinc-900 text-zinc-100 border border-zinc-700 hover:bg-zinc-800 hover:border-zinc-600"
|
|
371
|
+
t.btn_danger = "bg-red-600 text-white hover:bg-red-700"
|
|
372
|
+
t.btn_ghost = "bg-transparent text-zinc-300 hover:bg-zinc-800 hover:text-zinc-50"
|
|
373
|
+
t.link = "text-indigo-400 hover:text-indigo-300"
|
|
374
|
+
t.link_muted = "text-zinc-400 hover:text-zinc-50"
|
|
375
|
+
t.focus_ring = "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-400"
|
|
376
|
+
|
|
377
|
+
# Inputs
|
|
378
|
+
t.input_border = "border-zinc-500 hover:border-zinc-400" # 3.7:1 on the zinc-900 cards
|
|
379
|
+
t.input_focus = "focus:border-indigo-400 focus:ring-3 focus:ring-indigo-400/25"
|
|
380
|
+
t.input_error = "border-red-500 focus:border-red-400 focus:ring-3 focus:ring-red-400/25"
|
|
381
|
+
t.placeholder_text = "placeholder:text-zinc-400"
|
|
382
|
+
t.checkbox_checked = "checked:border-indigo-500 checked:bg-indigo-500 focus:ring-3 focus:ring-indigo-400/25"
|
|
383
|
+
t.checkbox_border = "border-zinc-500"
|
|
384
|
+
t.control_shadow = ""
|
|
385
|
+
t.disabled_text = "text-zinc-600"
|
|
386
|
+
|
|
387
|
+
# Scope tabs and counts
|
|
388
|
+
t.scope_active = "border-zinc-50 text-zinc-50"
|
|
389
|
+
t.scope_inactive = "border-transparent text-zinc-400 hover:text-zinc-50 hover:border-zinc-600"
|
|
390
|
+
t.badge_count = "bg-zinc-800 text-zinc-300"
|
|
391
|
+
|
|
392
|
+
# Cards, tables and surfaces
|
|
393
|
+
t.card_bg = "bg-zinc-900"
|
|
394
|
+
t.card_border = "border-zinc-800"
|
|
395
|
+
t.card_shadow = ""
|
|
396
|
+
t.popover_shadow = "shadow-xl shadow-black/40"
|
|
397
|
+
t.card_title = "text-sm font-semibold text-zinc-50"
|
|
398
|
+
t.table_header_bg = "bg-zinc-950"
|
|
399
|
+
t.table_header_text = "text-xs font-medium text-zinc-400"
|
|
400
|
+
t.table_row_hover = "hover:bg-zinc-800/50"
|
|
401
|
+
t.table_border = "divide-zinc-800"
|
|
402
|
+
t.table_sticky_shadow = "shadow-[-4px_0_6px_-4px_rgba(0,0,0,0.6)]"
|
|
403
|
+
t.surface_muted = "bg-zinc-950"
|
|
404
|
+
t.item_hover = "hover:bg-zinc-800"
|
|
405
|
+
t.item_active = "bg-zinc-800"
|
|
406
|
+
t.icon_muted = "text-zinc-500"
|
|
407
|
+
|
|
408
|
+
# Text in states
|
|
409
|
+
t.error_text = "text-red-400"
|
|
410
|
+
t.success_text = "text-emerald-400"
|
|
411
|
+
|
|
412
|
+
# Alerts, badges, chips and other elements
|
|
413
|
+
t.alert_palette = {
|
|
414
|
+
success: "bg-emerald-950/60 border-emerald-900 text-emerald-200",
|
|
415
|
+
error: "bg-red-950/60 border-red-900 text-red-200",
|
|
416
|
+
warning: "bg-amber-950/60 border-amber-900 text-amber-200",
|
|
417
|
+
info: "bg-blue-950/60 border-blue-900 text-blue-200",
|
|
418
|
+
}
|
|
419
|
+
t.badge_palette = {
|
|
420
|
+
green: "bg-emerald-400/10 text-emerald-300 ring-1 ring-inset ring-emerald-400/20",
|
|
421
|
+
red: "bg-red-400/10 text-red-300 ring-1 ring-inset ring-red-400/20",
|
|
422
|
+
yellow: "bg-amber-400/10 text-amber-300 ring-1 ring-inset ring-amber-400/20",
|
|
423
|
+
blue: "bg-blue-400/10 text-blue-300 ring-1 ring-inset ring-blue-400/30",
|
|
424
|
+
indigo: "bg-indigo-400/10 text-indigo-300 ring-1 ring-inset ring-indigo-400/30",
|
|
425
|
+
purple: "bg-purple-400/10 text-purple-300 ring-1 ring-inset ring-purple-400/30",
|
|
426
|
+
pink: "bg-pink-400/10 text-pink-300 ring-1 ring-inset ring-pink-400/20",
|
|
427
|
+
orange: "bg-orange-400/10 text-orange-300 ring-1 ring-inset ring-orange-400/20",
|
|
428
|
+
teal: "bg-teal-400/10 text-teal-300 ring-1 ring-inset ring-teal-400/20",
|
|
429
|
+
gray: "bg-zinc-400/10 text-zinc-300 ring-1 ring-inset ring-zinc-400/20",
|
|
430
|
+
}
|
|
431
|
+
t.badge_dot_palette = {
|
|
432
|
+
green: "bg-emerald-400", red: "bg-red-400", yellow: "bg-amber-400", blue: "bg-blue-400",
|
|
433
|
+
indigo: "bg-indigo-400", purple: "bg-purple-400", pink: "bg-pink-400", orange: "bg-orange-400",
|
|
434
|
+
teal: "bg-teal-400", gray: "bg-zinc-500",
|
|
435
|
+
}
|
|
436
|
+
t.chip = "bg-zinc-800 text-zinc-300 ring-1 ring-inset ring-zinc-700"
|
|
437
|
+
t.danger_item = "text-red-400 hover:bg-red-500/10 hover:text-red-300"
|
|
438
|
+
t.tooltip = "bg-zinc-100 text-zinc-900"
|
|
439
|
+
t.code_block = "bg-black text-zinc-100"
|
|
440
|
+
t.progress_track = "bg-zinc-800"
|
|
441
|
+
t.pagination_active = "bg-zinc-50 text-zinc-900 border-zinc-50"
|
|
442
|
+
|
|
443
|
+
# Dashboard and charts
|
|
444
|
+
t.metric_label = "text-xs font-medium text-zinc-400"
|
|
445
|
+
t.metric_value = "text-2xl font-semibold tracking-tight tabular-nums text-zinc-50"
|
|
446
|
+
t.metric_icon = "bg-zinc-800 text-zinc-400"
|
|
447
|
+
t.chart_colors = %w[
|
|
448
|
+
rgba(129,140,248,0.85) rgba(56,189,248,0.85) rgba(52,211,153,0.85)
|
|
449
|
+
rgba(251,191,36,0.85) rgba(251,113,133,0.85) rgba(167,139,250,0.85)
|
|
450
|
+
]
|
|
451
|
+
t.chart_border_color = "rgb(129, 140, 248)"
|
|
452
|
+
t.chart_grid_color = "rgba(63, 63, 70, 1)"
|
|
453
|
+
t.chart_text_color = "rgb(161, 161, 170)"
|
|
454
|
+
# The gap between pie and doughnut slices, in the color of the cards (zinc-900)
|
|
455
|
+
t.chart_slice_border_color = "rgb(24, 24, 27)"
|
|
456
|
+
end
|
|
58
457
|
end
|
|
59
458
|
```
|
|
60
459
|
|
|
61
|
-
|
|
460
|
+
`color_scheme = "dark"` makes the browser draw scrollbars, date pickers and other native
|
|
461
|
+
controls in dark colors; see [Color scheme](#color-scheme-dark-themes-and-charts).
|
|
62
462
|
|
|
63
|
-
|
|
463
|
+
## Themes from plugins
|
|
64
464
|
|
|
65
|
-
|
|
465
|
+
A theme can ship as its own gem. Name the gem `iron_admin-theme-<name>`. A compound name keeps
|
|
466
|
+
an underscore inside that segment: `iron_admin-theme-high_contrast` loads
|
|
467
|
+
`iron_admin/theme/high_contrast`. The namespace `IronAdmin::Theme` is reserved for these gems.
|
|
468
|
+
The guide to writing a theme gem comes later. `admin.theme` belongs to the experimental plugin
|
|
469
|
+
API, which may change before 1.0. See the [plugin system design](../plugin-system-design.md).
|
|
66
470
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
- **Scopes/Tabs**: `scope_active`, `scope_inactive`
|
|
71
|
-
- **Badge**: `badge_count`
|
|
72
|
-
- **Sidebar**: `sidebar_bg`, `sidebar_title`, `sidebar_link`, `sidebar_link_hover`, `sidebar_group_label`
|
|
73
|
-
- **Navbar**: `navbar_bg`, `navbar_border`, `navbar_search_bg`, `navbar_search_focus_bg`
|
|
74
|
-
- **Table**: `table_header_bg`, `table_row_hover`, `table_border`
|
|
75
|
-
- **Cards**: `card_bg`, `card_border`, `card_shadow`
|
|
76
|
-
- **Typography**: `font_family`, `heading_weight`, `body_text`, `muted_text`, `label_text`
|
|
77
|
-
- **Layout**: `border_radius`
|
|
471
|
+
A theme gem that ships CSS defines a `Rails::Engine` with `engine_name "iron_admin_theme_<name>"`
|
|
472
|
+
and ships `app/assets/tailwind/iron_admin_theme_<name>/engine.css`. `bin/rails tailwindcss:build`
|
|
473
|
+
writes `app/assets/builds/tailwind/iron_admin_theme_<name>.css` from that file.
|
|
78
474
|
|
|
79
|
-
|
|
475
|
+
Installing one:
|
|
80
476
|
|
|
81
|
-
|
|
477
|
+
1. Add the gem (`gem "iron_admin-theme-high_contrast"`).
|
|
478
|
+
2. Call `IronAdmin.register_plugin` with the plugin class
|
|
479
|
+
(`IronAdmin.register_plugin(IronAdmin::Theme::HighContrast)`).
|
|
480
|
+
3. When the gem ships that `engine.css`, add
|
|
481
|
+
`@import "../builds/tailwind/iron_admin_theme_<name>";` to the app's Tailwind entry
|
|
482
|
+
(`app/assets/tailwind/application.css`), beside the engine's import. An import with no
|
|
483
|
+
bridge file makes `tailwindcss:build` fail, and `assets:precompile` with it.
|
|
484
|
+
4. Run `bin/rails tailwindcss:build`.
|
|
485
|
+
|
|
486
|
+
Requiring the gem already runs its Ruby. Explicit activation is not a sandbox: trust a theme
|
|
487
|
+
gem the way you trust any other gem you install.
|
|
488
|
+
|
|
489
|
+
The plugin registers the theme with `admin.theme` in its `setup` block. That plugin owns the
|
|
490
|
+
name. `IronAdmin.register_plugin` activates the plugin at once, inside your initializer, so
|
|
491
|
+
whichever registration of the name runs second raises `IronAdmin::PluginError` at boot. The
|
|
492
|
+
message names the theme and both owners. Rename one theme, or remove one registration.
|
|
493
|
+
|
|
494
|
+
Activating the plugin again does not rebuild the theme. Adjust a value on the theme object
|
|
495
|
+
after `register_plugin`. Before that call the theme is not registered, so `find_theme` is `nil`:
|
|
82
496
|
|
|
83
497
|
```ruby
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
cp_card # => "bg-white"
|
|
87
|
-
cp_link # => "text-indigo-600 hover:text-indigo-900"
|
|
498
|
+
IronAdmin.register_plugin(IronAdmin::Theme::HighContrast)
|
|
499
|
+
IronAdmin.configuration.find_theme(:high_contrast).btn_primary = "..."
|
|
88
500
|
```
|
|
89
501
|
|
|
90
|
-
|
|
502
|
+
Reloads in development keep that object, so the change stays. A change made in an initializer
|
|
503
|
+
is applied again on every boot. The plugin's own values only change after a restart.
|
|
504
|
+
|
|
505
|
+
## Choosing the default theme
|
|
506
|
+
|
|
507
|
+
`config.default_theme` names the theme a request gets when the resolver names no registered
|
|
508
|
+
theme. It is `:neutral` unless you change it:
|
|
91
509
|
|
|
92
510
|
```ruby
|
|
93
511
|
IronAdmin.configure do |config|
|
|
94
|
-
config.
|
|
512
|
+
config.register_theme(:midnight, label: "Midnight") { |t| ... }
|
|
513
|
+
config.default_theme = :midnight
|
|
95
514
|
end
|
|
96
515
|
```
|
|
97
516
|
|
|
98
|
-
|
|
517
|
+
- `config.theme` yields and returns the theme that `default_theme` names **at the moment you
|
|
518
|
+
call it**. Set `default_theme` after registering that theme. Before the theme exists,
|
|
519
|
+
`config.theme` still configures Neutral.
|
|
520
|
+
- If `default_theme` names a theme that is not registered, Neutral is used.
|
|
521
|
+
- `config.themes` returns the registered themes as an ordered Hash (`{ name => theme }`),
|
|
522
|
+
the default theme first. The switcher lists them in that order.
|
|
523
|
+
- A blank name raises `ArgumentError`.
|
|
524
|
+
|
|
525
|
+
To change the look without offering a choice, customize the default theme with `config.theme`
|
|
526
|
+
and register nothing: with one theme, the navbar shows no switcher.
|
|
527
|
+
|
|
528
|
+
## Picking a theme per request
|
|
529
|
+
|
|
530
|
+
Before every admin request, and before authentication (so error pages and login redirects
|
|
531
|
+
already use it), `IronAdmin::ApplicationController` calls the resolver and stores the theme it
|
|
532
|
+
names for the request. By default the resolver reads the `iron_admin_theme` cookie that the
|
|
533
|
+
switcher sets.
|
|
534
|
+
|
|
535
|
+
`config.theme_resolver` takes a block that receives the request (an
|
|
536
|
+
`ActionDispatch::Request`) and returns a theme name (a String, a Symbol or `nil`):
|
|
537
|
+
|
|
538
|
+
- a name that is not registered, a blank name and `nil` give the default theme;
|
|
539
|
+
- if the block raises, IronAdmin logs a warning (`[IronAdmin] theme_resolver raised …`) and
|
|
540
|
+
uses the default theme, so a failing resolver never breaks a page;
|
|
541
|
+
- the block runs on every admin request, so keep it cheap;
|
|
542
|
+
- the block gets no controller and no current user, because it runs before authentication.
|
|
543
|
+
Read what you need from the request: `request.cookies`, `request.cookie_jar`,
|
|
544
|
+
`request.session`, `request.env["warden"]`, `request.host`, `request.query_parameters`.
|
|
545
|
+
|
|
546
|
+
`config.theme_resolver` without a block returns the current resolver. The default one is
|
|
547
|
+
`IronAdmin::Configuration::DEFAULT_THEME_RESOLVER`.
|
|
548
|
+
|
|
549
|
+
### A theme saved per user
|
|
550
|
+
|
|
551
|
+
Say your users have an `admin_theme` string column. With Devise (Warden), the resolver can
|
|
552
|
+
read the signed-in user:
|
|
99
553
|
|
|
100
554
|
```ruby
|
|
101
|
-
|
|
555
|
+
config.theme_resolver do |request|
|
|
556
|
+
# The switcher's cookie wins, so switching keeps working; the user's saved theme
|
|
557
|
+
# applies in a browser that has no cookie yet.
|
|
558
|
+
request.cookies[IronAdmin::Configuration::THEME_COOKIE].presence ||
|
|
559
|
+
request.env["warden"]&.user&.admin_theme
|
|
560
|
+
end
|
|
102
561
|
```
|
|
562
|
+
|
|
563
|
+
With a Devise scope other than the default one, pass it: `request.env["warden"]&.user(:admin)`.
|
|
564
|
+
Without Devise, look the user up from the session, for example
|
|
565
|
+
`User.find_by(id: request.session[:user_id])&.admin_theme`.
|
|
566
|
+
|
|
567
|
+
The switcher only sets the cookie; it doesn't save anything to your users. If the resolver
|
|
568
|
+
ignores the cookie, the switcher seems to do nothing. To save the choice to the user, render
|
|
569
|
+
your own switcher (see [below](#replacing-or-hiding-the-switcher)) that posts to your own
|
|
570
|
+
controller.
|
|
571
|
+
|
|
572
|
+
### A theme from a query parameter
|
|
573
|
+
|
|
574
|
+
This resolver lets a link such as `/admin/users?theme=midnight` pick the theme, and saves it
|
|
575
|
+
in the cookie through `request.cookie_jar`, as the switcher does, so the next pages keep it:
|
|
576
|
+
|
|
577
|
+
```ruby
|
|
578
|
+
config.theme_resolver do |request|
|
|
579
|
+
picked = IronAdmin.configuration.find_theme(request.query_parameters["theme"])
|
|
580
|
+
if picked
|
|
581
|
+
request.cookie_jar[IronAdmin::Configuration::THEME_COOKIE] = {
|
|
582
|
+
value: picked.name.to_s, expires: 1.year, httponly: true, same_site: :lax, secure: request.ssl?,
|
|
583
|
+
}
|
|
584
|
+
picked.name
|
|
585
|
+
else
|
|
586
|
+
request.cookies[IronAdmin::Configuration::THEME_COOKIE]
|
|
587
|
+
end
|
|
588
|
+
end
|
|
589
|
+
```
|
|
590
|
+
|
|
591
|
+
`find_theme` returns `nil` for anything that is not a registered name, so only real theme
|
|
592
|
+
names reach the cookie. Rails writes the cookies set on `request.cookie_jar` to the response.
|
|
593
|
+
Because a GET request now changes the cookie, any link, including one on another site, can
|
|
594
|
+
switch a visitor's theme. That's harmless for a look, but don't decide anything sensitive this
|
|
595
|
+
way.
|
|
596
|
+
|
|
597
|
+
## The theme switcher and its cookie
|
|
598
|
+
|
|
599
|
+
When two or more themes are registered, the navbar shows a swatch button (its accessible name
|
|
600
|
+
is "Theme: <label>"). It opens a menu with one button per theme: the theme's swatch and label,
|
|
601
|
+
a check mark and `aria-pressed="true"` on the current one.
|
|
602
|
+
|
|
603
|
+
- **Keyboard:** Tab reaches the button, Enter or Space opens it, Tab moves through the themes,
|
|
604
|
+
and Escape closes the menu and returns the focus to the button. A click outside closes it
|
|
605
|
+
too. The `cp-disclosure` Stimulus controller handles Escape and outside clicks.
|
|
606
|
+
- **Request:** each theme button submits a form, `POST /admin/theme` (`iron_admin.theme_path`)
|
|
607
|
+
with `theme` (the name) and `return_to` (the current path). A page that answers a POST, such
|
|
608
|
+
as an import preview or a form shown again with errors, may have no GET route, so there
|
|
609
|
+
`return_to` is the path of the page the browser came from when that is on this site, and
|
|
610
|
+
is left out otherwise (the switch then leads to the admin root). The form has the CSRF
|
|
611
|
+
token, and the endpoint is protected against forgery and authenticated like every admin
|
|
612
|
+
page. It has `data-turbo="false"`: the browser loads the next page in full, so the `<html>`
|
|
613
|
+
class, the fonts and the color scheme change with it.
|
|
614
|
+
- **Response:** for a registered name, the endpoint stores it in the cookie. Any other value
|
|
615
|
+
leaves the cookie as it is and sets the flash alert `iron_admin.theme_switcher.unknown`
|
|
616
|
+
("That theme is not available."). It then redirects with `303 See Other` to `return_to` when
|
|
617
|
+
that is a path on this site (it starts with a single `/`, has no backslash, space or control
|
|
618
|
+
character, and has no scheme or host), and to the admin root otherwise.
|
|
619
|
+
- **Cookie:** `iron_admin_theme` (`IronAdmin::Configuration::THEME_COOKIE`). It holds the
|
|
620
|
+
theme's name in plain text and lasts one year, with `HttpOnly`, `SameSite=Lax`, and `Secure`
|
|
621
|
+
on HTTPS requests. Editing it can only pick another registered theme, because the resolver
|
|
622
|
+
ignores names that are not registered.
|
|
623
|
+
- **Translations:** `iron_admin.theme_switcher.button_label` ("Theme: %{theme}"),
|
|
624
|
+
`iron_admin.theme_switcher.menu_label` ("Themes") and `iron_admin.theme_switcher.unknown`.
|
|
625
|
+
|
|
626
|
+
The endpoint stores only the themes registered in configuration. A custom resolver can accept
|
|
627
|
+
other inputs, but the endpoint never does.
|
|
628
|
+
|
|
629
|
+
### Replacing or hiding the switcher
|
|
630
|
+
|
|
631
|
+
The switcher fills the `theme_switcher` component slot (see
|
|
632
|
+
[Components](components.md#overriding-components)). The built-in navbar renders it only when
|
|
633
|
+
two or more themes are registered, with `themes:` (an Array of themes, default first),
|
|
634
|
+
`current_theme:` and `current_user:`.
|
|
635
|
+
|
|
636
|
+
To keep several themes but hide the switcher, for example when the resolver picks the theme
|
|
637
|
+
per tenant, use a component that renders nothing:
|
|
638
|
+
|
|
639
|
+
```ruby
|
|
640
|
+
# app/components/no_theme_switcher_component.rb
|
|
641
|
+
class NoThemeSwitcherComponent < ViewComponent::Base
|
|
642
|
+
def render?
|
|
643
|
+
false
|
|
644
|
+
end
|
|
645
|
+
|
|
646
|
+
# ViewComponent needs a template or a call method, even for a component that never renders.
|
|
647
|
+
def call; end
|
|
648
|
+
end
|
|
649
|
+
|
|
650
|
+
# config/initializers/iron_admin.rb
|
|
651
|
+
config.components.theme_switcher = "NoThemeSwitcherComponent"
|
|
652
|
+
```
|
|
653
|
+
|
|
654
|
+
A switcher of your own can post to `helpers.iron_admin.theme_path` with `theme` and
|
|
655
|
+
`return_to`, as the built-in one does, or to a controller of yours that also saves the choice.
|
|
656
|
+
A custom navbar (`config.components.navbar`) can render the slot with
|
|
657
|
+
`helpers.iron_admin_component(:theme_switcher, themes: IronAdmin.configuration.themes.values,
|
|
658
|
+
current_theme: IronAdmin.current_theme, current_user: @current_user)`.
|
|
659
|
+
|
|
660
|
+
## Using the theme in your own components
|
|
661
|
+
|
|
662
|
+
`IronAdmin.current_theme` returns the theme of the current request. Outside a request, for
|
|
663
|
+
example in a component spec, a mailer or a background job, it returns the default theme. Read
|
|
664
|
+
it in every component, view or helper you add to the admin panel:
|
|
665
|
+
|
|
666
|
+
```ruby
|
|
667
|
+
# app/components/admin_notice_component.rb
|
|
668
|
+
class AdminNoticeComponent < ViewComponent::Base
|
|
669
|
+
def initialize(message:)
|
|
670
|
+
@message = message
|
|
671
|
+
end
|
|
672
|
+
|
|
673
|
+
def call
|
|
674
|
+
tag.div(@message, class: "p-4 text-sm #{theme.card_bg} #{theme.border_width} #{theme.card_border} " \
|
|
675
|
+
"#{theme.border_radius} #{theme.card_shadow} #{theme.body_text}")
|
|
676
|
+
end
|
|
677
|
+
|
|
678
|
+
private
|
|
679
|
+
|
|
680
|
+
def theme
|
|
681
|
+
IronAdmin.current_theme
|
|
682
|
+
end
|
|
683
|
+
end
|
|
684
|
+
```
|
|
685
|
+
|
|
686
|
+
Don't read `IronAdmin.configuration.theme` in components. It always returns the default
|
|
687
|
+
theme, so a component that uses it keeps the default look while the rest of the page shows
|
|
688
|
+
another theme.
|
|
689
|
+
|
|
690
|
+
The engine's own recipes are available too, so your controls can match the built-in ones:
|
|
691
|
+
`IronAdmin::Form::ControlClasses.button(theme, :secondary)` (`:primary`, `:secondary`,
|
|
692
|
+
`:danger` or `:ghost`), `.input(theme)`, `.select(theme)`, `.textarea(theme)` and
|
|
693
|
+
`.checkbox(theme)`. Each returns the classes of a complete control: 36px high, or 16px for a
|
|
694
|
+
checkbox.
|
|
695
|
+
|
|
696
|
+
## Fonts
|
|
697
|
+
|
|
698
|
+
Four properties set the type:
|
|
699
|
+
|
|
700
|
+
- `font_family`: the font family class of every page, on `<body>`;
|
|
701
|
+
- `heading_font`: extra font family classes for page titles, card titles and the sidebar
|
|
702
|
+
brand. Leave it empty to use `font_family`;
|
|
703
|
+
- `code_font`: the font family of code-like text (code blocks, code, JSON and markdown
|
|
704
|
+
inputs, audit change details). Neutral uses Tailwind's `font-mono` stack;
|
|
705
|
+
- `font_stylesheet_url`: a stylesheet the layout links in `<head>` to load the fonts.
|
|
706
|
+
|
|
707
|
+
When `font_stylesheet_url` is present, the layout links it with `<link rel="stylesheet">`. When
|
|
708
|
+
it is on `fonts.googleapis.com`, the layout first adds `<link rel="preconnect">` tags for
|
|
709
|
+
`fonts.googleapis.com` and `fonts.gstatic.com`, so the browser opens those connections early.
|
|
710
|
+
Charts draw their text in the font of the card around them, and redraw once a web font has
|
|
711
|
+
loaded.
|
|
712
|
+
|
|
713
|
+
Neutral loads Inter from Google Fonts with `display=swap`. The browser shows text in a fallback
|
|
714
|
+
font right away and swaps in Inter once it arrives, so text is never invisible while the font
|
|
715
|
+
loads.
|
|
716
|
+
|
|
717
|
+
**Privacy.** With a Google Fonts URL, every page view makes the visitor's browser request
|
|
718
|
+
`fonts.googleapis.com` and `fonts.gstatic.com`, which sends Google the visitor's IP address and
|
|
719
|
+
user agent. In the EU, some courts and data protection authorities treat this as a transfer of
|
|
720
|
+
personal data that needs consent. If that applies to you, turn the request off or host the
|
|
721
|
+
font yourself.
|
|
722
|
+
|
|
723
|
+
**Content Security Policy.** If your app sends a CSP header, allow both hosts, or the browser
|
|
724
|
+
blocks the font and Inter never loads:
|
|
725
|
+
|
|
726
|
+
```ruby
|
|
727
|
+
# config/initializers/content_security_policy.rb
|
|
728
|
+
Rails.application.configure do
|
|
729
|
+
config.content_security_policy do |policy|
|
|
730
|
+
policy.style_src :self, "https://fonts.googleapis.com"
|
|
731
|
+
policy.font_src :self, "https://fonts.gstatic.com"
|
|
732
|
+
# ... the rest of your policy
|
|
733
|
+
end
|
|
734
|
+
end
|
|
735
|
+
```
|
|
736
|
+
|
|
737
|
+
**Turning the Google Fonts request off.** Set `font_stylesheet_url` to `nil`. Every
|
|
738
|
+
registered theme starts from Neutral and links Inter too, so do it for each theme. After the
|
|
739
|
+
last `register_theme`, one loop covers them all:
|
|
740
|
+
|
|
741
|
+
```ruby
|
|
742
|
+
IronAdmin.configure do |config|
|
|
743
|
+
config.register_theme(:midnight) { |t| ... }
|
|
744
|
+
|
|
745
|
+
config.themes.each_value { |theme| theme.font_stylesheet_url = nil }
|
|
746
|
+
end
|
|
747
|
+
```
|
|
748
|
+
|
|
749
|
+
Without the stylesheet, pages use Inter where it is installed on the visitor's computer, and
|
|
750
|
+
`ui-sans-serif` / `system-ui` (the operating system's font) elsewhere. For the system font
|
|
751
|
+
everywhere, also set `t.font_family = "font-sans"`, Tailwind's system stack.
|
|
752
|
+
|
|
753
|
+
**Hosting Inter yourself.** Put the font files and a stylesheet with their `@font-face` rules
|
|
754
|
+
in your app (for example `public/fonts/inter.css`), then point the theme at it:
|
|
755
|
+
`t.font_stylesheet_url = "/fonts/inter.css"`. The layout adds no preconnect tags for a URL
|
|
756
|
+
that is not on Google Fonts.
|
|
757
|
+
|
|
758
|
+
**Another font.** Use Tailwind's `font-[family-name:…]` arbitrary value and the font's
|
|
759
|
+
stylesheet:
|
|
760
|
+
|
|
761
|
+
```ruby
|
|
762
|
+
config.theme do |t|
|
|
763
|
+
t.font_family = "font-[family-name:Geist,ui-sans-serif,system-ui,sans-serif]"
|
|
764
|
+
t.font_stylesheet_url = "https://fonts.googleapis.com/css2?family=Geist:wght@400..700&display=swap"
|
|
765
|
+
t.heading_font = "font-serif" # titles in the system serif
|
|
766
|
+
end
|
|
767
|
+
```
|
|
768
|
+
|
|
769
|
+
## Color scheme, dark themes and charts
|
|
770
|
+
|
|
771
|
+
`color_scheme` is `"light"` or `"dark"`. It is not a Tailwind class. The layout turns it into:
|
|
772
|
+
|
|
773
|
+
- a `scheme-light` or `scheme-dark` class on `<html>`, which sets the CSS `color-scheme`, so
|
|
774
|
+
the browser draws scrollbars, date and time pickers, select menus and autofill in light or
|
|
775
|
+
dark colors;
|
|
776
|
+
- a `<meta name="color-scheme" content="light">` (or `"dark"`) tag;
|
|
777
|
+
- a lighter chevron in selects under `scheme-dark` (drawn by the engine's stylesheet). The
|
|
778
|
+
check mark and the radio dot stay white under `scheme-dark`.
|
|
779
|
+
|
|
780
|
+
`color_scheme` doesn't recolor anything else: a dark theme sets dark classes in its properties,
|
|
781
|
+
as the [Midnight example](#a-complete-dark-theme) does. Charts don't read `color_scheme`
|
|
782
|
+
either. Chart.js draws on a canvas, so the chart properties hold CSS colors (hex, `rgb()` or
|
|
783
|
+
`rgba()`) and a dark theme sets all five:
|
|
784
|
+
|
|
785
|
+
- `chart_colors`: the slices of pie, doughnut and polar area charts, in order. A bar chart's
|
|
786
|
+
bars are one series, so it fills them all with the first color;
|
|
787
|
+
- `chart_border_color`: the line of line, area and radar charts, whose fill is the same color
|
|
788
|
+
at 10% opacity. It also fills progress bars that have no color of their own;
|
|
789
|
+
- `chart_grid_color`: grid and axis lines;
|
|
790
|
+
- `chart_text_color`: tick labels, radar point labels and the legend;
|
|
791
|
+
- `chart_slice_border_color`: the outline of every slice. Neutral's is white, the color of its
|
|
792
|
+
cards, which draws a gap between neighboring slices; a dark theme sets its own card color
|
|
793
|
+
(or another outline, such as black), or white gaps show on its dark cards.
|
|
794
|
+
|
|
795
|
+
Two more chart properties shape the marks: `chart_point_style` (the legend markers) and
|
|
796
|
+
`chart_border_width` (the outline width of slices and bars, and the width of lines).
|
|
797
|
+
|
|
798
|
+
A chart's own colors win over the theme: `chart :revenue, type: :bar, colors: ["#0ea5e9"]` in
|
|
799
|
+
a dashboard (or `colors:` on `ChartComponent`) replaces `chart_colors`, and its first color
|
|
800
|
+
replaces `chart_border_color`. A bar chart given its own colors fills its bars with them one by
|
|
801
|
+
one. A dashboard `progress` widget's `color:` is a CSS color, and a
|
|
802
|
+
`:progress` field's `color:` option is a Tailwind class such as `bg-emerald-600`. Both replace
|
|
803
|
+
`chart_border_color` for that bar.
|
|
804
|
+
|
|
805
|
+
## Badges, alerts and chips
|
|
806
|
+
|
|
807
|
+
Badges take their classes from three properties:
|
|
808
|
+
|
|
809
|
+
- `badge_palette`: a Hash from color name to classes. Neutral has `:green`, `:red`, `:yellow`,
|
|
810
|
+
`:blue`, `:indigo`, `:purple`, `:pink`, `:orange`, `:teal` and `:gray`; an unknown color
|
|
811
|
+
uses `:gray`;
|
|
812
|
+
- `badge_dot_palette`: a Hash from the same names to the classes of a 6px dot before the text.
|
|
813
|
+
An empty Hash (`{}`) draws badges without dots;
|
|
814
|
+
- `badge_shape`: the radius and weight of every badge.
|
|
815
|
+
|
|
816
|
+
| Color | Neutral `badge_palette` | Neutral `badge_dot_palette` |
|
|
817
|
+
|-------|-------------------------|-----------------------------|
|
|
818
|
+
| `:green` | `bg-emerald-50 text-emerald-700 ring-1 ring-inset ring-emerald-600/20` | `bg-emerald-500` |
|
|
819
|
+
| `:red` | `bg-red-50 text-red-700 ring-1 ring-inset ring-red-600/10` | `bg-red-500` |
|
|
820
|
+
| `:yellow` | `bg-amber-50 text-amber-800 ring-1 ring-inset ring-amber-600/20` | `bg-amber-500` |
|
|
821
|
+
| `:blue` | `bg-blue-50 text-blue-700 ring-1 ring-inset ring-blue-700/10` | `bg-blue-500` |
|
|
822
|
+
| `:indigo` | `bg-indigo-50 text-indigo-700 ring-1 ring-inset ring-indigo-700/10` | `bg-indigo-500` |
|
|
823
|
+
| `:purple` | `bg-purple-50 text-purple-700 ring-1 ring-inset ring-purple-700/10` | `bg-purple-500` |
|
|
824
|
+
| `:pink` | `bg-pink-50 text-pink-700 ring-1 ring-inset ring-pink-700/10` | `bg-pink-500` |
|
|
825
|
+
| `:orange` | `bg-orange-50 text-orange-800 ring-1 ring-inset ring-orange-600/20` | `bg-orange-500` |
|
|
826
|
+
| `:teal` | `bg-teal-50 text-teal-700 ring-1 ring-inset ring-teal-600/20` | `bg-teal-500` |
|
|
827
|
+
| `:gray` | `bg-zinc-50 text-zinc-600 ring-1 ring-inset ring-zinc-500/10` | `bg-zinc-400` |
|
|
828
|
+
|
|
829
|
+
The palettes are plain Hashes, and each theme has its own copy, so you can add a color to one
|
|
830
|
+
theme:
|
|
831
|
+
|
|
832
|
+
```ruby
|
|
833
|
+
config.theme do |t|
|
|
834
|
+
t.badge_palette[:cyan] = "bg-cyan-50 text-cyan-700 ring-1 ring-inset ring-cyan-600/20"
|
|
835
|
+
t.badge_dot_palette[:cyan] = "bg-cyan-500"
|
|
836
|
+
end
|
|
837
|
+
```
|
|
838
|
+
|
|
839
|
+
**`config.badge_colors`.** This Hash decides which color a value gets: it maps status values
|
|
840
|
+
such as `"active"` to color names such as `"green"` (see
|
|
841
|
+
[Badge Colors](fields.md#badge-colors) for the defaults). A field's own `colors:` option wins
|
|
842
|
+
over it. An entry keyed by a color name Symbol with classes as its value
|
|
843
|
+
(`config.badge_colors[:cyan] = "bg-cyan-100 text-cyan-800"`) sets the classes of that color in
|
|
844
|
+
**every** theme, and those badges have no dot. That keeps the look of apps that set such
|
|
845
|
+
classes before 0.8. For a color that changes with the theme, set the theme's `badge_palette`
|
|
846
|
+
instead. Add entries with `[]=` or `merge!`: assigning a new Hash to `config.badge_colors`
|
|
847
|
+
replaces the default status mapping.
|
|
848
|
+
|
|
849
|
+
**Alerts.** `alert_palette` holds the background, border color and text color of each alert
|
|
850
|
+
type. Flash messages, the form's base errors and the audit log's warning use it. An unknown
|
|
851
|
+
type uses the `:info` entry:
|
|
852
|
+
|
|
853
|
+
| Type | Neutral `alert_palette` |
|
|
854
|
+
|------|-------------------------|
|
|
855
|
+
| `:success` | `bg-emerald-50 border-emerald-200 text-emerald-800` |
|
|
856
|
+
| `:error` | `bg-red-50 border-red-200 text-red-800` |
|
|
857
|
+
| `:warning` | `bg-amber-50 border-amber-200 text-amber-800` |
|
|
858
|
+
| `:info` | `bg-blue-50 border-blue-200 text-blue-800` |
|
|
859
|
+
|
|
860
|
+
**Chips.** Tags, has-and-belongs-to-many records on show pages, file names, boolean group
|
|
861
|
+
values and the column names on import pages use `chip` with `badge_shape`. The activity feed tints its icons from `badge_palette`
|
|
862
|
+
(an item's `icon_color` is one of its color names).
|
|
863
|
+
|
|
864
|
+
## Rich text
|
|
865
|
+
|
|
866
|
+
`:rich_text` fields use Action Text's Trix editor, and the layout links Trix's stylesheet
|
|
867
|
+
(`trix.css`). That stylesheet is not in a cascade layer, so its rules win over every Tailwind
|
|
868
|
+
utility, whatever their order. Two properties restyle it, and Neutral sets both: its editor is
|
|
869
|
+
outlined like its inputs, and its toolbar groups take its borders and radii. Set them to `""`
|
|
870
|
+
for Trix's own look.
|
|
871
|
+
|
|
872
|
+
- `rich_text_editor` holds the classes of the editor box, written as for an input, for
|
|
873
|
+
example `border border-zinc-700 rounded-md bg-zinc-900 text-zinc-100 focus:border-violet-500
|
|
874
|
+
focus:ring-3 focus:ring-violet-500/30`. Include a border width class: once the property is
|
|
875
|
+
set, the engine's stylesheet hands Trix's border and radius over to these classes.
|
|
876
|
+
- `rich_text_toolbar` holds classes of the box around the toolbar and the editor. Trix builds
|
|
877
|
+
the toolbar in JavaScript, so style its parts through descendant variants, and end each class
|
|
878
|
+
with Tailwind's important modifier `!`, which lets it win over Trix's stylesheet:
|
|
879
|
+
|
|
880
|
+
```ruby
|
|
881
|
+
t.rich_text_toolbar = "[&_.trix-button-group]:border-zinc-700! [&_.trix-button]:border-zinc-700! " \
|
|
882
|
+
"[&_.trix-button.trix-active]:bg-violet-500/20! [&_.trix-dialog]:bg-zinc-800! " \
|
|
883
|
+
"[&_.trix-input--dialog]:bg-zinc-900! [&_.trix-input--dialog]:border-zinc-600!"
|
|
884
|
+
```
|
|
885
|
+
|
|
886
|
+
The parts are `.trix-button-group` (a group of buttons, with a border and radius),
|
|
887
|
+
`.trix-button` (a button; its left border separates it from the previous one),
|
|
888
|
+
`.trix-button.trix-active` (a pressed button), `.trix-dialog` (the link dialog) and
|
|
889
|
+
`.trix-input--dialog` (its URL field). Parts the theme leaves alone keep Trix's look.
|
|
890
|
+
|
|
891
|
+
The toolbar icons are black images. Under `color_scheme = "dark"` the engine's stylesheet
|
|
892
|
+
inverts them, so they show on a dark background.
|
|
893
|
+
|
|
894
|
+
Whatever the theme, the field's template and the engine's stylesheet own the rest: the editor's
|
|
895
|
+
text is `text-sm`, like the other inputs; the editor takes its accessible name from the field's
|
|
896
|
+
label (`aria-labelledby`, since a `<label for>` cannot name a `<trix-editor>`); and the box
|
|
897
|
+
around the toolbar carries a `cp-rich-text-field` mark, which makes the toolbar's button groups
|
|
898
|
+
wrap onto more rows on a narrow screen instead of scrolling out of reach.
|
|
899
|
+
|
|
900
|
+
## Tailwind: literal classes and source scanning
|
|
901
|
+
|
|
902
|
+
IronAdmin ships no compiled CSS. Your app's Tailwind v4 build (tailwindcss-rails) generates
|
|
903
|
+
every class it finds in the files it scans. The engine's own templates and the Neutral values in
|
|
904
|
+
`lib/` are scanned through the `iron_admin` bridge file (see
|
|
905
|
+
[Installation](../getting-started/installation.md)). **The classes in your themes live in your
|
|
906
|
+
app, so your build must scan the file that defines them.**
|
|
907
|
+
|
|
908
|
+
Tailwind detects sources automatically from the directory the build runs in, and skips files
|
|
909
|
+
that `.gitignore` lists. `bin/rails tailwindcss:build` and `bin/dev` run from the app's root, so
|
|
910
|
+
a theme in `config/initializers/iron_admin.rb` is usually found without any setup. Name the file
|
|
911
|
+
explicitly when your CSS turns automatic detection off (`@import "tailwindcss" source(none);`),
|
|
912
|
+
when the file is ignored by Git, or just to be safe:
|
|
913
|
+
|
|
914
|
+
```css
|
|
915
|
+
/* app/assets/tailwind/application.css */
|
|
916
|
+
@import "tailwindcss";
|
|
917
|
+
@import "../builds/tailwind/iron_admin";
|
|
918
|
+
@source "../../../config/initializers/iron_admin.rb";
|
|
919
|
+
```
|
|
920
|
+
|
|
921
|
+
Paths in `@source` are relative to the CSS file. After you change a theme, rebuild the CSS
|
|
922
|
+
(`bin/rails tailwindcss:build`), or keep `bin/rails tailwindcss:watch` running. If you commit
|
|
923
|
+
`app/assets/builds/tailwind.css`, commit the rebuilt file too.
|
|
924
|
+
|
|
925
|
+
**Write every class as a complete literal.** Tailwind reads your source files as text: it never
|
|
926
|
+
runs Ruby. A class built by interpolation, such as `"bg-#{color}-600"`, never appears in the
|
|
927
|
+
text, so Tailwind generates no CSS for it and the element is unstyled. Write each class in full.
|
|
928
|
+
A Hash from names to full class strings is fine, and so is a long value split into several
|
|
929
|
+
string literals at a space between classes. Don't split one class, and in particular an
|
|
930
|
+
arbitrary value such as `shadow-[0_1px_2px_rgba(0,0,0,0.05)]`, across two string literals or
|
|
931
|
+
lines.
|
|
932
|
+
|
|
933
|
+
**Tables and tab rows that scroll sideways fade at the edge.** The engine stylesheet's
|
|
934
|
+
`cp-scroll-fade` class masks a frame whose content is wider than it: the frame fades out toward
|
|
935
|
+
each edge it can still scroll to, driven by a CSS scroll timeline, so a frame that fits, or a
|
|
936
|
+
browser without scroll timelines, shows no fade. The mask works on any theme's colors and lifts
|
|
937
|
+
while the frame or a control in it has the keyboard focus. Put the border of a scrolling table
|
|
938
|
+
on a box around the masked one, as `Resources::Styles.table_panel` and
|
|
939
|
+
`Resources::Styles::SCROLL_FRAME` do, or the fade takes the border with it.
|
|
940
|
+
|
|
941
|
+
**Use Tailwind v4 utilities.** Utilities that v4 removed, such as `bg-opacity-50` (use
|
|
942
|
+
`bg-black/50`) and `flex-grow` (use `grow`), generate nothing, and some names changed size:
|
|
943
|
+
v4's `shadow-xs` is v3's `shadow-sm`, and v4's `shadow-sm` is v3's `shadow`. Variants such as `hover:`, `focus:`, `focus-visible:`, `before:`, `lg:` and
|
|
944
|
+
`placeholder:` work in every property.
|
|
945
|
+
|
|
946
|
+
## For contributors: the theme guards
|
|
947
|
+
|
|
948
|
+
Every color the panel draws belongs to the theme, so a registered theme can restyle all of it.
|
|
949
|
+
Several specs keep it that way:
|
|
950
|
+
|
|
951
|
+
- `spec/iron_admin/theme_hardcoded_colors_spec.rb` scans every `app/**/*.{haml,erb,rb,js}` file.
|
|
952
|
+
It fails on any Tailwind color utility (`bg`, `text`, `border`, `divide`, `ring`, `outline`,
|
|
953
|
+
`placeholder`, `fill`, `stroke`, `from`, `via`, `to`, `shadow`, `decoration`, `accent`,
|
|
954
|
+
`caret`, with any variants) that uses a palette color, `white` or `black`, or an arbitrary
|
|
955
|
+
color value such as `bg-[#fafafa]`. It also fails on inline `style` declarations, SVG
|
|
956
|
+
attributes and JavaScript style assignments that hard-code a color. `text-current`,
|
|
957
|
+
`bg-transparent`, `border-transparent`, `fill-current`, `stroke-current` and `inherit` are
|
|
958
|
+
allowed, and so are styles built from theme values or record data. Each failure names the
|
|
959
|
+
file, the line and the class. Take the color from a theme property instead. Colors belong in
|
|
960
|
+
the Neutral values (`lib/iron_admin/configuration/theme/neutral_defaults.rb`), which the guard
|
|
961
|
+
doesn't scan.
|
|
962
|
+
- `spec/iron_admin/engine_theme_reads_spec.rb` fails when `app/` or `lib/` reads
|
|
963
|
+
`IronAdmin.configuration.theme`. Read `IronAdmin.current_theme` (or `t` in views).
|
|
964
|
+
- `spec/iron_admin/engine_tailwind_classes_spec.rb` fails on utilities Tailwind v4 removed, on
|
|
965
|
+
an important modifier placed before the variants, on fractional values in the HAML class
|
|
966
|
+
shorthand (`.gap-1.5` renders the classes `gap-1` and `5`; write
|
|
967
|
+
`class: "gap-1.5"`), and on arbitrary values split across string literals.
|
|
968
|
+
- `spec/lib/iron_admin/configuration/theme_spec.rb` checks every Neutral value and fails when a
|
|
969
|
+
property is not set in `Theme#initialize`, so copies and registered themes always carry it.
|
|
970
|
+
|
|
971
|
+
To add a property: add an `attr_accessor` with YARD to its group in `theme.rb`, set its Neutral
|
|
972
|
+
value in the matching `init_*_defaults` method of `theme/neutral_defaults.rb`, add it to the
|
|
973
|
+
Neutral catalog in `theme_spec.rb`, add a row to the tables in this guide, and add a CHANGELOG
|
|
974
|
+
entry.
|