iron_admin 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +129 -1
  3. data/README.md +48 -1
  4. data/UPGRADING.md +495 -8
  5. data/app/assets/tailwind/iron_admin/engine.css +79 -4
  6. data/app/components/iron_admin/dashboards/activity_feed_component/item_component.html.haml +6 -9
  7. data/app/components/iron_admin/dashboards/activity_feed_component.html.haml +6 -5
  8. data/app/components/iron_admin/dashboards/activity_feed_component.rb +21 -24
  9. data/app/components/iron_admin/dashboards/chart_component.html.haml +3 -5
  10. data/app/components/iron_admin/dashboards/chart_component.rb +86 -24
  11. data/app/components/iron_admin/dashboards/concerns/themed_card.rb +39 -0
  12. data/app/components/iron_admin/dashboards/metric_card_component.html.haml +8 -7
  13. data/app/components/iron_admin/dashboards/metric_card_component.rb +2 -0
  14. data/app/components/iron_admin/dashboards/progress_component.html.haml +11 -7
  15. data/app/components/iron_admin/dashboards/progress_component.rb +11 -6
  16. data/app/components/iron_admin/dashboards/quick_links_component/link_component.html.haml +8 -9
  17. data/app/components/iron_admin/dashboards/quick_links_component.html.haml +6 -5
  18. data/app/components/iron_admin/dashboards/quick_links_component.rb +4 -12
  19. data/app/components/iron_admin/dashboards/recent_table_component.html.haml +15 -10
  20. data/app/components/iron_admin/dashboards/recent_table_component.rb +49 -0
  21. data/app/components/iron_admin/dashboards/stats_grid_component/stat_component.html.haml +13 -14
  22. data/app/components/iron_admin/dashboards/stats_grid_component.html.haml +1 -0
  23. data/app/components/iron_admin/dashboards/stats_grid_component.rb +9 -11
  24. data/app/components/iron_admin/filters/bar_component.html.haml +8 -6
  25. data/app/components/iron_admin/filters/bar_component.rb +56 -9
  26. data/app/components/iron_admin/filters/control_styles.rb +82 -0
  27. data/app/components/iron_admin/filters/date_range_component.html.haml +9 -4
  28. data/app/components/iron_admin/filters/date_range_component.rb +10 -6
  29. data/app/components/iron_admin/filters/search_component.html.haml +4 -4
  30. data/app/components/iron_admin/filters/search_component.rb +3 -5
  31. data/app/components/iron_admin/filters/select_filter_component.html.haml +1 -1
  32. data/app/components/iron_admin/filters/select_filter_component.rb +5 -16
  33. data/app/components/iron_admin/form/belongs_to_autocomplete_component.html.haml +9 -5
  34. data/app/components/iron_admin/form/belongs_to_autocomplete_component.rb +10 -8
  35. data/app/components/iron_admin/form/belongs_to_component.html.haml +2 -2
  36. data/app/components/iron_admin/form/belongs_to_component.rb +4 -18
  37. data/app/components/iron_admin/form/checkbox_component.rb +2 -3
  38. data/app/components/iron_admin/form/concerns/form_input_behavior.rb +1 -1
  39. data/app/components/iron_admin/form/control_classes.rb +108 -0
  40. data/app/components/iron_admin/form/date_picker_component.rb +3 -7
  41. data/app/components/iron_admin/form/field_wrapper_component.html.haml +3 -3
  42. data/app/components/iron_admin/form/field_wrapper_component.rb +3 -3
  43. data/app/components/iron_admin/form/nested_form_component.html.haml +4 -5
  44. data/app/components/iron_admin/form/nested_form_component.rb +12 -2
  45. data/app/components/iron_admin/form/select_component.html.haml +1 -1
  46. data/app/components/iron_admin/form/select_component.rb +2 -16
  47. data/app/components/iron_admin/form/text_input_component.rb +1 -5
  48. data/app/components/iron_admin/form/textarea_component.rb +1 -5
  49. data/app/components/iron_admin/layout/flash_component.html.haml +1 -1
  50. data/app/components/iron_admin/layout/flash_component.rb +4 -3
  51. data/app/components/iron_admin/layout/navbar_component.html.haml +15 -9
  52. data/app/components/iron_admin/layout/navbar_component.rb +29 -1
  53. data/app/components/iron_admin/layout/shell_component.html.haml +4 -4
  54. data/app/components/iron_admin/layout/shell_component.rb +16 -3
  55. data/app/components/iron_admin/layout/sidebar_component.html.haml +21 -25
  56. data/app/components/iron_admin/layout/sidebar_component.rb +76 -1
  57. data/app/components/iron_admin/layout/theme_switcher_component.html.haml +15 -0
  58. data/app/components/iron_admin/layout/theme_switcher_component.rb +74 -0
  59. data/app/components/iron_admin/resources/actions_component.html.haml +15 -8
  60. data/app/components/iron_admin/resources/actions_component.rb +34 -2
  61. data/app/components/iron_admin/resources/breadcrumb_component.html.haml +3 -3
  62. data/app/components/iron_admin/resources/breadcrumb_component.rb +8 -7
  63. data/app/components/iron_admin/resources/bulk_actions_component.html.haml +9 -8
  64. data/app/components/iron_admin/resources/bulk_actions_component.rb +47 -4
  65. data/app/components/iron_admin/resources/data_table_component.html.haml +15 -15
  66. data/app/components/iron_admin/resources/data_table_component.rb +34 -3
  67. data/app/components/iron_admin/resources/related_list_component.html.haml +7 -7
  68. data/app/components/iron_admin/resources/related_list_component.rb +26 -2
  69. data/app/components/iron_admin/resources/show_field_component.html.haml +3 -3
  70. data/app/components/iron_admin/resources/show_field_component.rb +10 -4
  71. data/app/components/iron_admin/resources/styles.rb +136 -0
  72. data/app/components/iron_admin/ui/alert_component.html.haml +2 -2
  73. data/app/components/iron_admin/ui/alert_component.rb +27 -31
  74. data/app/components/iron_admin/ui/badge_component.rb +40 -20
  75. data/app/components/iron_admin/ui/button_component.rb +37 -11
  76. data/app/components/iron_admin/ui/card_component.rb +3 -3
  77. data/app/components/iron_admin/ui/dropdown_component.html.haml +1 -1
  78. data/app/components/iron_admin/ui/dropdown_component.rb +34 -13
  79. data/app/components/iron_admin/ui/empty_state_component.html.haml +4 -5
  80. data/app/components/iron_admin/ui/empty_state_component.rb +2 -2
  81. data/app/components/iron_admin/ui/modal_component.html.haml +5 -5
  82. data/app/components/iron_admin/ui/modal_component.rb +6 -4
  83. data/app/components/iron_admin/ui/pagination_component.html.haml +14 -14
  84. data/app/components/iron_admin/ui/pagination_component.rb +26 -9
  85. data/app/components/iron_admin/ui/scopes_component.html.haml +2 -2
  86. data/app/components/iron_admin/ui/scopes_component.rb +44 -11
  87. data/app/components/iron_admin/ui/tooltip_component.rb +11 -4
  88. data/app/controllers/iron_admin/application_controller.rb +58 -4
  89. data/app/controllers/iron_admin/audit_controller.rb +30 -6
  90. data/app/controllers/iron_admin/concerns/action_executable.rb +37 -0
  91. data/app/controllers/iron_admin/concerns/assignable_references.rb +149 -0
  92. data/app/controllers/iron_admin/concerns/authorizable.rb +11 -0
  93. data/app/controllers/iron_admin/concerns/blank_password_filterable.rb +21 -0
  94. data/app/controllers/iron_admin/concerns/event_emittable.rb +47 -7
  95. data/app/controllers/iron_admin/concerns/filterable.rb +34 -9
  96. data/app/controllers/iron_admin/concerns/nested_permittable.rb +5 -3
  97. data/app/controllers/iron_admin/concerns/nested_tenant_check.rb +159 -0
  98. data/app/controllers/iron_admin/concerns/polymorphic_references.rb +131 -0
  99. data/app/controllers/iron_admin/concerns/scopeable.rb +54 -7
  100. data/app/controllers/iron_admin/concerns/searchable.rb +3 -3
  101. data/app/controllers/iron_admin/concerns/tenant_assignable.rb +118 -0
  102. data/app/controllers/iron_admin/concerns/tenant_containment.rb +146 -0
  103. data/app/controllers/iron_admin/exports_controller.rb +2 -2
  104. data/app/controllers/iron_admin/imports_controller.rb +1 -1
  105. data/app/controllers/iron_admin/resources_controller.rb +48 -41
  106. data/app/controllers/iron_admin/search_controller.rb +1 -2
  107. data/app/controllers/iron_admin/themes_controller.rb +50 -0
  108. data/app/controllers/iron_admin/tools_controller.rb +58 -5
  109. data/app/helpers/iron_admin/action_form_helper.rb +19 -0
  110. data/app/helpers/iron_admin/application_helper.rb +93 -16
  111. data/app/helpers/iron_admin/assignable_records_helper.rb +32 -0
  112. data/app/helpers/iron_admin/component_overrides_helper.rb +9 -4
  113. data/app/helpers/iron_admin/field_display_helper.rb +88 -43
  114. data/app/helpers/iron_admin/related_records_helper.rb +51 -0
  115. data/app/helpers/iron_admin/theme_helper.rb +56 -46
  116. data/app/javascript/iron_admin/controllers/cp_bulk_select_controller.js +12 -0
  117. data/app/javascript/iron_admin/controllers/cp_chart_controller.js +4 -0
  118. data/app/javascript/iron_admin/controllers/cp_disclosure_controller.js +19 -0
  119. data/app/javascript/iron_admin/controllers/cp_search_shortcut_controller.js +39 -0
  120. data/app/javascript/iron_admin/index.js +4 -0
  121. data/app/views/iron_admin/audit/index.html.haml +78 -81
  122. data/app/views/iron_admin/dashboard/index.html.haml +10 -9
  123. data/app/views/iron_admin/form/_action_field.html.haml +50 -0
  124. data/app/views/iron_admin/form/_nested_row.html.haml +18 -13
  125. data/app/views/iron_admin/imports/new.html.haml +14 -13
  126. data/app/views/iron_admin/imports/preview.html.haml +24 -21
  127. data/app/views/iron_admin/resources/_form.html.haml +70 -68
  128. data/app/views/iron_admin/resources/action_form.html.haml +16 -59
  129. data/app/views/iron_admin/resources/bulk_action_form.html.haml +20 -58
  130. data/app/views/iron_admin/resources/edit.html.haml +3 -3
  131. data/app/views/iron_admin/resources/index.html.haml +87 -74
  132. data/app/views/iron_admin/resources/new.html.haml +2 -2
  133. data/app/views/iron_admin/resources/show.html.haml +53 -41
  134. data/app/views/iron_admin/search/index.html.haml +17 -9
  135. data/app/views/iron_admin/shared/_pagination.html.haml +13 -10
  136. data/app/views/iron_admin/shared/error.html.haml +16 -12
  137. data/app/views/iron_admin/tools/action_form.html.haml +9 -55
  138. data/app/views/iron_admin/tools/show.html.haml +4 -5
  139. data/app/views/layouts/iron_admin/_document_head.html.haml +24 -0
  140. data/app/views/layouts/iron_admin/application.html.haml +4 -17
  141. data/app/views/layouts/iron_admin/minimal.html.haml +7 -0
  142. data/config/importmap.rb +2 -0
  143. data/config/locales/en.yml +23 -0
  144. data/config/routes.rb +1 -0
  145. data/docs/FAQ.md +87 -37
  146. data/docs/README.md +8 -2
  147. data/docs/components/README.md +6 -2
  148. data/docs/components/dashboard-components.md +24 -35
  149. data/docs/components/filter-components.md +44 -92
  150. data/docs/components/form-components.md +16 -32
  151. data/docs/components/resource-components.md +46 -27
  152. data/docs/components/ui-components.md +44 -26
  153. data/docs/getting-started/installation.md +5 -1
  154. data/docs/getting-started/quick-start.md +36 -23
  155. data/docs/guides/authentication.md +182 -42
  156. data/docs/guides/components.md +97 -15
  157. data/docs/guides/custom-adapters.md +24 -4
  158. data/docs/guides/dashboard.md +68 -44
  159. data/docs/guides/export.md +24 -8
  160. data/docs/guides/extending.md +206 -51
  161. data/docs/guides/fields.md +229 -70
  162. data/docs/guides/imports.md +33 -18
  163. data/docs/guides/resources.md +333 -111
  164. data/docs/guides/theming.md +930 -58
  165. data/docs/guides/troubleshooting.md +7 -3
  166. data/docs/plugin-system-design.md +8 -7
  167. data/docs/reference/configuration.md +51 -16
  168. data/docs/reference/routes.md +1 -0
  169. data/docs/reference/theme-properties.md +101 -38
  170. data/lib/generators/iron_admin/install/templates/initializer.rb.tt +7 -2
  171. data/lib/generators/iron_admin/install_audit/templates/create_iron_admin_audit_entries.rb.tt +2 -0
  172. data/lib/iron_admin/action_field.rb +11 -0
  173. data/lib/iron_admin/adapters/active_record.rb +95 -0
  174. data/lib/iron_admin/adapters/base.rb +107 -0
  175. data/lib/iron_admin/adapters/http/query.rb +21 -0
  176. data/lib/iron_admin/adapters/http.rb +84 -4
  177. data/lib/iron_admin/adapters/mongoid.rb +96 -2
  178. data/lib/iron_admin/audit_log.rb +64 -6
  179. data/lib/iron_admin/authentication_warning.rb +31 -0
  180. data/lib/iron_admin/concerns/filter_definable.rb +15 -1
  181. data/lib/iron_admin/concerns/nestable.rb +25 -0
  182. data/lib/iron_admin/concerns/scope_countable.rb +56 -0
  183. data/lib/iron_admin/concerns/soft_deletable.rb +28 -9
  184. data/lib/iron_admin/configuration/components.rb +14 -3
  185. data/lib/iron_admin/configuration/theme/neutral_defaults.rb +179 -0
  186. data/lib/iron_admin/configuration/theme.rb +292 -87
  187. data/lib/iron_admin/configuration.rb +340 -45
  188. data/lib/iron_admin/dashboard.rb +22 -38
  189. data/lib/iron_admin/engine.rb +16 -2
  190. data/lib/iron_admin/errors.rb +3 -0
  191. data/lib/iron_admin/field.rb +78 -17
  192. data/lib/iron_admin/field_inferrer.rb +61 -3
  193. data/lib/iron_admin/field_override_warning.rb +67 -0
  194. data/lib/iron_admin/import/import_preview.rb +56 -7
  195. data/lib/iron_admin/import/importer.rb +91 -14
  196. data/lib/iron_admin/import/tenant_precheck.rb +67 -0
  197. data/lib/iron_admin/plugin/registration.rb +64 -0
  198. data/lib/iron_admin/plugin_registry.rb +3 -2
  199. data/lib/iron_admin/policy.rb +22 -12
  200. data/lib/iron_admin/policy_coverage_warning.rb +46 -0
  201. data/lib/iron_admin/request_context.rb +18 -0
  202. data/lib/iron_admin/resource.rb +218 -77
  203. data/lib/iron_admin/resource_registry.rb +86 -13
  204. data/lib/iron_admin/scope_counts.rb +73 -0
  205. data/lib/iron_admin/tenant_scope.rb +30 -0
  206. data/lib/iron_admin/tool.rb +61 -12
  207. data/lib/iron_admin/tool_context.rb +10 -6
  208. data/lib/iron_admin/version.rb +1 -1
  209. data/lib/iron_admin.rb +29 -2
  210. metadata +37 -7
@@ -16,11 +16,12 @@ module IronAdmin
16
16
  # config.per_page = 50
17
17
  #
18
18
  # config.authenticate do |controller|
19
- # controller.redirect_to "/login" unless controller.current_user&.admin?
19
+ # user = User.find_by(id: controller.session[:user_id])
20
+ # controller.redirect_to "/login" unless user&.admin?
20
21
  # end
21
22
  #
22
23
  # config.current_user do |controller|
23
- # controller.current_user
24
+ # User.find_by(id: controller.session[:user_id])
24
25
  # end
25
26
  # end
26
27
  #
@@ -35,14 +36,18 @@ module IronAdmin
35
36
  # IronAdmin.configure do |config|
36
37
  # config.audit_enabled = true
37
38
  # config.audit_storage = :database # or :memory
39
+ # config.audit_user_labels do |identifiers|
40
+ # User.where(id: identifiers).pluck(:id, :email).to_h
41
+ # end
38
42
  # end
39
43
  #
40
44
  # @example Theme configuration
41
45
  # IronAdmin.configure do |config|
42
46
  # config.theme do |t|
43
- # t.primary_color = "#4F46E5"
44
- # t.sidebar_bg = "#1F2937"
47
+ # t.font_stylesheet_url = nil
48
+ # t.label_transform = "uppercase tracking-wider"
45
49
  # end
50
+ # config.register_theme(:midnight, label: "Midnight") { |t| t.color_scheme = "dark" }
46
51
  # end
47
52
  #
48
53
  # @see IronAdmin.configure
@@ -56,6 +61,12 @@ module IronAdmin
56
61
  # @return [String, nil] Path to a custom logo image
57
62
  attr_accessor :logo
58
63
 
64
+ # @return [String, nil] Icon the admin layout links with +<link rel="icon">+: a path, a URL or
65
+ # an asset name, resolved like {#logo} (default: nil, no icon link, so browsers request /favicon.ico)
66
+ # @example
67
+ # config.favicon = "/icon.svg"
68
+ attr_accessor :favicon
69
+
59
70
  # @return [Integer] Number of records per page (default: 25)
60
71
  attr_accessor :per_page
61
72
 
@@ -65,7 +76,8 @@ module IronAdmin
65
76
  # @return [Symbol] Default sort direction, :asc or :desc (default: :desc)
66
77
  attr_accessor :default_sort_direction
67
78
 
68
- # @return [Symbol] Search engine to use (default: :default)
79
+ # Unused. The value is stored and returned, and nothing in IronAdmin reads it (default: :default).
80
+ # @return [Symbol]
69
81
  attr_accessor :search_engine
70
82
 
71
83
  # @return [Hash{String => String}] Mapping of status values to badge colors
@@ -96,6 +108,52 @@ module IronAdmin
96
108
  # @return [ActiveSupport::Duration] Minimum interval between live broadcasts
97
109
  attr_accessor :live_throttle
98
110
 
111
+ # When +true+, tools dispatch only actions declared with +tool_action+.
112
+ # The legacy fallback that runs a tool's own public methods is off, and
113
+ # undeclared names return 404. Declared actions are unchanged.
114
+ #
115
+ # @return [Boolean] whether undeclared tool actions are rejected (default: false)
116
+ # @see IronAdmin::Tool
117
+ attr_accessor :strict_tool_actions
118
+
119
+ # Values accepted by {#default_policy=}.
120
+ DEFAULT_POLICIES = %i[allow deny].freeze
121
+
122
+ # What a resource without a +policy+ block allows: +:allow+ (the
123
+ # default) lets every user the authenticate block admits run every CRUD,
124
+ # custom and bulk action; +:deny+ denies them all. Tools without a
125
+ # +tool_access+ condition follow the same setting. A resource's own
126
+ # policy, and a tool's own condition, always apply.
127
+ #
128
+ # @return [Symbol] +:allow+ or +:deny+ (default: +:allow+)
129
+ # @see IronAdmin::Resource.policy
130
+ attr_reader :default_policy
131
+
132
+ # @param value [Symbol, String] +:allow+ or +:deny+
133
+ # @raise [ArgumentError] for any other value
134
+ # @return [void]
135
+ def default_policy=(value)
136
+ policy = value.respond_to?(:to_sym) ? value.to_sym : value
137
+ raise ArgumentError, "default_policy must be :allow or :deny, got #{value.inspect}" unless DEFAULT_POLICIES.include?(policy)
138
+
139
+ @default_policy = policy
140
+ end
141
+
142
+ # @return [Boolean] whether {#default_policy} is +:allow+
143
+ def default_allow?
144
+ default_policy == :allow
145
+ end
146
+
147
+ # When +true+, each scope tab on a resource index shows how many records
148
+ # that tab would list: the tenant scope, the current filters, that tab's
149
+ # scope and the current search. The selected scope and the page are not
150
+ # part of the count. Each counted scope runs one query. Off by default.
151
+ # A resource overrides this with +scope_counts+.
152
+ #
153
+ # @return [Boolean] whether scope tabs show record counts (default: false)
154
+ # @see IronAdmin::Concerns::ScopeCountable::ScopeCountDsl
155
+ attr_accessor :scope_counts
156
+
99
157
  # @return [Proc, nil] Authentication block
100
158
  # @see #authenticate
101
159
  attr_reader :authenticate_block
@@ -108,9 +166,18 @@ module IronAdmin
108
166
  # @see #on_action
109
167
  attr_reader :on_action_block
110
168
 
111
- # @return [IronAdmin::Configuration::Theme] Theme configuration
112
- # @see #theme
113
- attr_reader :theme_config
169
+ # @return [Proc, nil] Block that labels the users of the audit log page
170
+ # @see #audit_user_labels
171
+ attr_reader :audit_user_labels_block
172
+
173
+ # @return [Proc, nil] Block that returns the current tenant's audit key
174
+ # @see #audit_tenant
175
+ attr_reader :audit_tenant_block
176
+
177
+ # @return [Symbol] Name of the theme used when the request resolves no registered theme
178
+ # (default: :neutral)
179
+ # @see #theme_resolver
180
+ attr_reader :default_theme
114
181
 
115
182
  # @return [IronAdmin::Configuration::Components] Component overrides
116
183
  attr_reader :components
@@ -119,6 +186,18 @@ module IronAdmin
119
186
  # @see #tenant_scope
120
187
  attr_reader :tenant_scope_block
121
188
 
189
+ # Name of the built-in theme, registered by every Configuration.
190
+ # @return [Symbol]
191
+ NEUTRAL_THEME = :neutral
192
+
193
+ # Cookie that stores the theme picked in the theme switcher.
194
+ # @return [String]
195
+ THEME_COOKIE = "iron_admin_theme"
196
+
197
+ # Resolver used until {#theme_resolver} is given a block: the theme cookie.
198
+ # @return [Proc]
199
+ DEFAULT_THEME_RESOLVER = ->(request) { request.cookies[THEME_COOKIE] }
200
+
122
201
  # Maps color names to Tailwind CSS classes for badges.
123
202
  # @return [Hash{Symbol => String}]
124
203
  BADGE_COLOR_CLASSES = {
@@ -176,12 +255,18 @@ module IronAdmin
176
255
  # Creates a new Configuration with default values.
177
256
  def initialize
178
257
  @title = "Admin"
258
+ @favicon = nil
179
259
  @per_page = 25
180
260
  @default_sort = :created_at
181
261
  @default_sort_direction = :desc
182
262
  @search_engine = :default
183
263
  @badge_colors = DEFAULT_BADGE_COLORS.dup
184
- @theme_config = Theme.new
264
+ @themes = { NEUTRAL_THEME => Theme.new(name: NEUTRAL_THEME) }
265
+ # Name => owner. +:app+ is the application (Neutral and {#register_theme}); a String is a
266
+ # plugin's +plugin_name+, a logical identity, not proof that two implementations match.
267
+ @theme_owners = { NEUTRAL_THEME => :app }
268
+ @default_theme = NEUTRAL_THEME
269
+ @theme_resolver = DEFAULT_THEME_RESOLVER
185
270
  @components = Components.new
186
271
  @audit_enabled = false
187
272
  @audit_storage = :memory
@@ -191,26 +276,46 @@ module IronAdmin
191
276
  @live_updates = :disabled
192
277
  @live_poll_interval = 3.seconds
193
278
  @live_throttle = 0.5.seconds
279
+ @strict_tool_actions = false
280
+ @scope_counts = false
281
+ @default_policy = :allow
194
282
  end
195
283
 
196
284
  # Defines the authentication check for admin access.
197
285
  #
198
- # The block receives the controller instance and should redirect
199
- # unauthenticated users or return false to deny access.
286
+ # The block receives the controller and runs before each admin request.
287
+ # Redirect or render inside the block to customize the response. Make
288
+ # +false+ the block's last value to deny access with 403: HTML gets the
289
+ # error page without the admin shell, and other formats a bare 403.
290
+ # +nil+ or any other value allows the request. A block that has already
291
+ # redirected or rendered keeps that response, whatever its value is.
292
+ # Stop early with +next false+. Do not use +return+ inside the block:
293
+ # from an initializer it raises +LocalJumpError+.
294
+ #
295
+ # The controller inherits from ActionController::Base, not from the host
296
+ # application's ApplicationController, so helpers defined only there are
297
+ # missing. Read cookies with +controller.request.cookie_jar+;
298
+ # +controller.cookies+ is private.
200
299
  #
201
300
  # @yield [controller] Block executed before each admin request
202
301
  # @yieldparam controller [ActionController::Base] The current controller
302
+ # @yieldreturn [false, nil, Object] +false+ denies with 403; anything else allows the request
203
303
  #
204
304
  # @example Redirect unauthenticated users
205
305
  # config.authenticate do |controller|
206
306
  # controller.redirect_to "/login" unless controller.session[:user_id]
207
307
  # end
208
308
  #
209
- # @example Require admin role
309
+ # @example Deny with 403 unless the user is an admin
210
310
  # config.authenticate do |controller|
211
- # unless controller.current_user&.admin?
212
- # controller.head :forbidden
213
- # end
311
+ # # || false: a missing user makes &.admin? nil, and nil allows the request.
312
+ # User.find_by(id: controller.session[:user_id])&.admin? || false
313
+ # end
314
+ #
315
+ # @example Choose the response yourself
316
+ # config.authenticate do |controller|
317
+ # user = User.find_by(id: controller.session[:user_id])
318
+ # controller.head :forbidden unless user&.admin?
214
319
  # end
215
320
  #
216
321
  # @return [void]
@@ -229,12 +334,12 @@ module IronAdmin
229
334
  #
230
335
  # @example
231
336
  # config.current_user do |controller|
232
- # controller.current_user
337
+ # User.find_by(id: controller.session[:user_id])
233
338
  # end
234
339
  #
235
- # @example Using session
340
+ # @example With Devise
236
341
  # config.current_user do |controller|
237
- # User.find_by(id: controller.session[:user_id])
342
+ # controller.current_user
238
343
  # end
239
344
  #
240
345
  # @return [void]
@@ -242,23 +347,79 @@ module IronAdmin
242
347
  @current_user_block = block
243
348
  end
244
349
 
245
- # Defines a callback executed after any CRUD action.
350
+ # Labels the users of the audit log page. Called once per page with the
351
+ # id (as a String) of every user on it, so one query loads them all. With
352
+ # database storage the page only has that id; with memory storage the
353
+ # label replaces the user's email or name. Users it does not label
354
+ # (deleted ones), and all users when it raises, keep the default: the id
355
+ # with database storage, the email or name with memory storage.
356
+ #
357
+ # @yield [identifiers] Block that returns the label of each user
358
+ # @yieldparam identifiers [Array<String>] Distinct, non-blank user identifiers
359
+ # @yieldreturn [Hash{String, Integer => String}] Label by user identifier
360
+ #
361
+ # @example Label users by email
362
+ # config.audit_user_labels do |identifiers|
363
+ # User.where(id: identifiers).pluck(:id, :email).to_h
364
+ # end
365
+ #
366
+ # @example Label users with a display method
367
+ # config.audit_user_labels do |identifiers|
368
+ # AdminUser.where(id: identifiers).to_h { |user| [user.id, user.display_name] }
369
+ # end
370
+ #
371
+ # @return [void]
372
+ # @see IronAdmin::AuditLog.user_labels
373
+ def audit_user_labels(&block)
374
+ @audit_user_labels_block = block
375
+ end
376
+
377
+ # Keeps the audit log per tenant. The block runs in the controller, with
378
+ # the controller as its argument, and returns the current tenant's key.
379
+ # Each logged change stores it (as a String) in +tenant_key+, and the
380
+ # audit page lists only the entries whose key is the current one: none
381
+ # when the block returns nil, and never the entries logged without a key.
382
+ # With database storage the table needs a +tenant_key+ column (see
383
+ # UPGRADING.md); without it the audit page raises.
384
+ #
385
+ # @yieldparam controller [ActionController::Base] the admin controller
386
+ # @yieldreturn [Object, nil] the current tenant's key
387
+ # @example
388
+ # config.audit_tenant { |_controller| Current.organization&.id }
389
+ # @return [void]
390
+ def audit_tenant(&block)
391
+ @audit_tenant_block = block
392
+ end
393
+
394
+ # Registers a block called with one event after a resource change.
395
+ #
396
+ # Create, update and destroy call it after a successful save. A custom
397
+ # action, a bulk action and an import call it after the resource transaction
398
+ # commits, or immediately when there is no transaction. The import's action
399
+ # is +:create+ or +:update+.
246
400
  #
247
- # Use this for audit logging, notifications, or other side effects.
401
+ # The event has these readers:
402
+ # * +user+ — +iron_admin_current_user+
403
+ # * +action+ — +:create+, +:update+ or +:destroy+ for CRUD. For a custom
404
+ # action, +event.action+ is the String URL segment (+params[:action_name]+).
405
+ # For a bulk action, it is the Symbol passed to +bulk_action+. Compare with
406
+ # +event.action.to_s+. An import is +:create+ or +:update+
407
+ # * +resource+ — the resource class name as a String, not the class
408
+ # * +record_id+ — +record.id.to_s+
409
+ # * +changes+ — a Hash of the saved changes. Password fields and the host's
410
+ # +filter_parameters+ are replaced with +"[FILTERED]"+
411
+ # * +ip_address+ — +request.remote_ip+
248
412
  #
249
- # @yield [action, resource, record, user] Block executed after actions
250
- # @yieldparam action [Symbol] The action (:create, :update, :delete)
251
- # @yieldparam resource [Class] The resource class
252
- # @yieldparam record [ActiveRecord::Base] The affected record
253
- # @yieldparam user [Object] The current user
413
+ # @yield [event] Block called with the event
414
+ # @yieldparam event [OpenStruct] The event described above
254
415
  #
255
- # @example Audit logging
256
- # config.on_action do |action, resource, record, user|
257
- # AuditLog.create!(
258
- # action: action,
259
- # resource: resource.name,
260
- # record_id: record.id,
261
- # user_id: user.id
416
+ # @example Record the event
417
+ # config.on_action do |event|
418
+ # AuditTrail.create!(
419
+ # action: event.action,
420
+ # resource: event.resource,
421
+ # record_id: event.record_id,
422
+ # user_id: event.user&.id
262
423
  # )
263
424
  # end
264
425
  #
@@ -267,23 +428,115 @@ module IronAdmin
267
428
  @on_action_block = block
268
429
  end
269
430
 
270
- # Configures the admin panel theme.
431
+ # Configures the default theme: the one {#default_theme} names, else Neutral.
271
432
  #
272
- # @yield [theme] Block to configure theme options
273
- # @yieldparam theme [IronAdmin::Configuration::Theme] The theme config
274
- # @return [IronAdmin::Configuration::Theme] The theme configuration
433
+ # @yieldparam theme [IronAdmin::Configuration::Theme] The default theme
434
+ # @return [IronAdmin::Configuration::Theme] The default theme
275
435
  #
276
436
  # @example
277
- # config.theme do |t|
278
- # t.primary_color = "#4F46E5"
279
- # t.sidebar_bg = "#1F2937"
280
- # t.font_family = "Inter, sans-serif"
281
- # end
282
- #
283
- # @see IronAdmin::Configuration::Theme
437
+ # config.theme { |t| t.btn_primary = "bg-blue-600 text-white" }
284
438
  def theme
285
- yield @theme_config if block_given?
286
- @theme_config
439
+ default = find_theme(default_theme) || @themes.fetch(NEUTRAL_THEME)
440
+ yield default if block_given?
441
+ default
442
+ end
443
+
444
+ # @return [IronAdmin::Configuration::Theme] The default theme, as {#theme} returns it
445
+ def theme_config
446
+ theme
447
+ end
448
+
449
+ # Registers a theme that starts from the Neutral values and yields it.
450
+ # Registering a name the app already owns replaces that theme and records
451
+ # the app as its owner. A name a plugin owns raises {PluginError} before
452
+ # anything is replaced. A blank name raises ArgumentError. A Symbol, a
453
+ # String and any other case are the same name. The theme and its owner are
454
+ # stored only after the block returns.
455
+ #
456
+ # @param name [Symbol, String] Cookie value
457
+ # @param label [String] Switcher text
458
+ # @return [IronAdmin::Configuration::Theme]
459
+ # @raise [ArgumentError] The name is blank
460
+ # @raise [IronAdmin::PluginError] A plugin already owns the name
461
+ # @see IronAdmin::Plugin::Registration#theme
462
+ def register_theme(name, label: name.to_s.titleize, &)
463
+ key = theme_name!(name)
464
+ refuse_foreign_theme!(key, :app)
465
+ write_theme(key, label, :app, &)
466
+ end
467
+
468
+ # Registers a theme owned by a plugin. The same +plugin_name+ on a later
469
+ # activation keeps the theme object: the block is not called again, so an
470
+ # adjustment the app made stays until the process restarts.
471
+ #
472
+ # +plugin_name+ is a logical identity, not a proof that two implementations
473
+ # are the same. Another plugin class that declares it is the same owner.
474
+ #
475
+ # @api private
476
+ # @param plugin_name [#to_s] {IronAdmin::Plugin.plugin_name} of the owner
477
+ # @param name [Symbol, String] Cookie value
478
+ # @param label [String] Switcher text
479
+ # @return [IronAdmin::Configuration::Theme]
480
+ # @raise [IronAdmin::PluginError] Another owner already has the name
481
+ # @raise [ArgumentError] The name is blank
482
+ def register_plugin_theme(plugin_name, name, label: name.to_s.titleize, &)
483
+ key = theme_name!(name)
484
+ owner = plugin_name.to_s
485
+ return @themes.fetch(key) if @theme_owners[key] == owner
486
+
487
+ refuse_foreign_theme!(key, owner)
488
+ write_theme(key, label, owner, &)
489
+ end
490
+
491
+ # @return [Hash{Symbol => IronAdmin::Configuration::Theme}] Registered themes by name: the
492
+ # default theme first, then the others in registration order
493
+ def themes
494
+ default = find_theme(default_theme)
495
+ default ? { default.name => default }.merge(@themes) : @themes.dup
496
+ end
497
+
498
+ # @param name [Symbol, String] Name of the theme used when no registered theme resolves
499
+ # @return [void]
500
+ # @raise [ArgumentError] If the name is blank
501
+ def default_theme=(name)
502
+ @default_theme = theme_name!(name)
503
+ end
504
+
505
+ # Sets the block that names each request's theme, which by default is the
506
+ # {THEME_COOKIE} cookie, and returns the resolver.
507
+ #
508
+ # @yieldparam request [ActionDispatch::Request] The current request
509
+ # @yieldreturn [Symbol, String, nil] Name of a registered theme
510
+ # @return [Proc] The resolver
511
+ def theme_resolver(&block)
512
+ @theme_resolver = block if block
513
+ @theme_resolver
514
+ end
515
+
516
+ # @param request [ActionDispatch::Request] The current request
517
+ # @return [IronAdmin::Configuration::Theme] The theme {#theme_resolver} names, else the
518
+ # default theme (also when the resolver raises, which is logged)
519
+ def resolve_theme(request)
520
+ theme_for(theme_resolver.call(request))
521
+ rescue StandardError => e
522
+ log_theme_resolver_error(e)
523
+ theme
524
+ end
525
+
526
+ # @param name [Symbol, String, nil] Name of a theme
527
+ # @return [IronAdmin::Configuration::Theme] The theme registered under the name, else the default theme
528
+ def theme_for(name)
529
+ find_theme(name) || theme
530
+ end
531
+
532
+ # @param name [Symbol, String, nil] Name of a theme. A String that is not valid UTF-8 is ignored
533
+ # @return [IronAdmin::Configuration::Theme, nil] The theme registered under the name, else nil
534
+ def find_theme(name)
535
+ text = name.to_s
536
+ return unless text.valid_encoding?
537
+ return if text.strip.empty?
538
+
539
+ @themes[theme_name!(name)]
287
540
  end
288
541
 
289
542
  # Defines a tenant scope for multi-tenant applications.
@@ -313,5 +566,47 @@ module IronAdmin
313
566
  def tenant_scope(&block)
314
567
  @tenant_scope_block = block
315
568
  end
569
+
570
+ private
571
+
572
+ def theme_name!(name)
573
+ text = name.to_s
574
+ raise ArgumentError, "IronAdmin theme name must not be blank, got #{name.inspect}" if text.strip.empty?
575
+
576
+ text.downcase.to_sym
577
+ end
578
+
579
+ def refuse_foreign_theme!(key, claimant)
580
+ owner = @theme_owners[key]
581
+ return if owner.nil? || owner == claimant
582
+
583
+ raise PluginError, theme_conflict_message(key, claimant, owner)
584
+ end
585
+
586
+ def write_theme(key, label, owner)
587
+ theme = Theme.new(name: key, label: label)
588
+ yield theme if block_given?
589
+ @themes[key] = theme
590
+ @theme_owners[key] = owner
591
+ theme
592
+ end
593
+
594
+ def theme_conflict_message(key, claimant, owner)
595
+ "Cannot register theme #{key.inspect} for #{theme_owner_phrase(claimant)}: " \
596
+ "#{theme_owner_phrase(owner)} already registered it. " \
597
+ "Rename one theme, or remove one registration."
598
+ end
599
+
600
+ def theme_owner_phrase(owner)
601
+ return "the app" if owner == :app
602
+
603
+ "plugin #{owner.inspect}"
604
+ end
605
+
606
+ def log_theme_resolver_error(error)
607
+ return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
608
+
609
+ Rails.logger.warn("[IronAdmin] theme_resolver raised #{error.class}: #{error.message}; using the default theme")
610
+ end
316
611
  end
317
612
  end
@@ -11,35 +11,27 @@ module IronAdmin
11
11
  # it automatically registers itself as the active dashboard.
12
12
  #
13
13
  # @example Basic dashboard
14
- # class AdminDashboard < IronAdmin::Dashboard
15
- # metric :total_users, format: :number do
16
- # User.count
17
- # end
18
- #
19
- # metric :revenue, format: :currency do
20
- # Order.sum(:total)
21
- # end
14
+ # module IronAdmin
15
+ # module Dashboards
16
+ # class AdminDashboard < IronAdmin::Dashboard
17
+ # metric :total_users, format: :number do
18
+ # User.count
19
+ # end
22
20
  #
23
- # chart :signups_by_month, type: :bar do
24
- # User.group_by_month(:created_at).count
25
- # end
21
+ # metric :revenue, format: :currency do
22
+ # Order.sum(:total)
23
+ # end
26
24
  #
27
- # recent :orders, limit: 10
28
- # recent :users, limit: 5
29
- # end
30
- #
31
- # @example Dashboard with custom layout
32
- # class AdminDashboard < IronAdmin::Dashboard
33
- # metric :active_users do
34
- # User.where(active: true).count
35
- # end
25
+ # # The block returns a Hash of label => value. groupdate is not a dependency.
26
+ # # group_by keeps row order, so sort the YYYY-MM keys. Zero-fill empty months if you need all twelve.
27
+ # chart :signups_by_month, type: :bar do
28
+ # signups = User.where(created_at: 11.months.ago.beginning_of_month..).pluck(:created_at)
29
+ # signups.group_by { |created_at| created_at.strftime("%Y-%m") }.transform_values(&:count).sort.to_h
30
+ # end
36
31
  #
37
- # chart :orders_by_day, type: :line do
38
- # Order.group_by_day(:created_at).count
39
- # end
40
- #
41
- # layout do
42
- # # Define custom grid layout
32
+ # recent :orders, limit: 10
33
+ # recent :users, limit: 5
34
+ # end
43
35
  # end
44
36
  # end
45
37
  class Dashboard
@@ -106,7 +98,7 @@ module IronAdmin
106
98
  # @param label [String, nil] Custom display title for the chart.
107
99
  # Defaults to `name.to_s.humanize` when not provided.
108
100
  # @yield Block that computes and returns the chart data
109
- # @yieldreturn [Hash, Array] Data for the chart (format depends on type)
101
+ # @yieldreturn [Hash] Labels (+keys+) and values (+values+). An Array has no +keys+.
110
102
  #
111
103
  # @example Chart with custom label
112
104
  # chart :projects_by_status, type: :bar, label: "Projects by Status" do
@@ -184,18 +176,10 @@ module IronAdmin
184
176
  self.defined_recents = defined_recents + [{ resource_name: resource_name, limit: limit, scope: scope }]
185
177
  end
186
178
 
187
- # Defines a custom layout for the dashboard.
188
- #
189
- # Use this to control the arrangement of metrics, charts, and
190
- # recent record lists on the dashboard page.
191
- #
192
- # @yield Block that defines the layout structure
193
- #
194
- # @example Custom two-column layout
195
- # layout do
196
- # # Layout definition
197
- # end
179
+ # Stores a block. Nothing reads it, so the block has no effect yet.
180
+ # The page renders metrics, then charts, then progress bars, then recent lists.
198
181
  #
182
+ # @yield Block stored on the class and not called
199
183
  # @return [void]
200
184
  def layout(&block)
201
185
  self._layout_block = block
@@ -23,6 +23,10 @@ module IronAdmin
23
23
  class Engine < ::Rails::Engine
24
24
  isolate_namespace IronAdmin
25
25
 
26
+ initializer "iron_admin.deprecator" do |app|
27
+ app.deprecators[:iron_admin] = IronAdmin.deprecator
28
+ end
29
+
26
30
  initializer "iron_admin.assets" do |app|
27
31
  if app.config.respond_to?(:assets) && app.config.assets
28
32
  # Sprockets hosts need this manifest (it link_trees app/javascript/iron_admin)
@@ -38,6 +42,12 @@ module IronAdmin
38
42
  end
39
43
  end
40
44
 
45
+ # Production with no authenticate block answers every request unless a
46
+ # route constraint protects the mount, so say so once at boot.
47
+ config.after_initialize do
48
+ IronAdmin::AuthenticationWarning.call
49
+ end
50
+
41
51
  initializer "iron_admin.importmap", before: "importmap" do |app|
42
52
  app.config.importmap.paths << root.join("config/importmap.rb") if app.config.respond_to?(:importmap)
43
53
  end
@@ -70,10 +80,14 @@ module IronAdmin
70
80
  # taken effect), call `finalize!` to run the model introspection
71
81
  # steps (soft-delete features, etc.) with the correct adapter.
72
82
  IronAdmin::ResourceRegistry.finalize!
83
+ IronAdmin::PolicyCoverageWarning.call
84
+ IronAdmin::FieldOverrideWarning.call
73
85
  end
74
86
  # Re-activate registered plugins so their component overrides and menu
75
- # items survive the per-reload configuration lifecycle. Activation is
76
- # idempotent, so this is safe to run on every `to_prepare`.
87
+ # items survive the per-reload configuration lifecycle. A plugin theme
88
+ # is not rebuilt here: the theme object, including an app's adjustments,
89
+ # stays until the process restarts. Activation is idempotent, so this
90
+ # is safe to run on every `to_prepare`.
77
91
  IronAdmin::PluginRegistry.activate_all!
78
92
  end
79
93
  end
@@ -8,6 +8,9 @@ module IronAdmin
8
8
  # Adapter-agnostic replacement for ActiveRecord::RecordNotFound.
9
9
  class RecordNotFound < Error; end
10
10
 
11
+ # Raised when the host app's setup cannot support a configured feature.
12
+ class ConfigurationError < Error; end
13
+
11
14
  # Raised inside a transaction block to trigger a rollback.
12
15
  # Adapter-agnostic replacement for ActiveRecord::Rollback.
13
16
  class Rollback < Error; end