Class: IronAdmin::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/iron_admin/configuration.rb,
lib/iron_admin/configuration/theme.rb,
lib/iron_admin/configuration/components.rb

Overview

Global configuration for the IronAdmin admin panel.

Configure IronAdmin in an initializer using the configure method. All configuration options are optional and have sensible defaults.

Examples:

Basic configuration

# config/initializers/iron_admin.rb
IronAdmin.configure do |config|
  config.title = "My Admin"
  config.per_page = 50

  config.authenticate do |controller|
    controller.redirect_to "/login" unless controller.current_user&.admin?
  end

  config.current_user do |controller|
    controller.current_user
  end
end

Multi-tenant configuration

IronAdmin.configure do |config|
  config.tenant_scope do |scope|
    scope.where(organization_id: Current.organization.id)
  end
end

Audit logging configuration

IronAdmin.configure do |config|
  config.audit_enabled = true
  config.audit_storage = :database  # or :memory
end

Theme configuration

IronAdmin.configure do |config|
  config.theme do |t|
    t.primary_color = "#4F46E5"
    t.sidebar_bg = "#1F2937"
  end
end

See Also:

Defined Under Namespace

Classes: Components, Theme

Constant Summary collapse

BADGE_COLOR_CLASSES =

Maps color names to Tailwind CSS classes for badges.

Returns:

  • (Hash{Symbol => String}) 
{
  green: "bg-green-100 text-green-800",
  red: "bg-red-100 text-red-800",
  yellow: "bg-yellow-100 text-yellow-800",
  blue: "bg-blue-100 text-blue-800",
  indigo: "bg-indigo-100 text-indigo-800",
  purple: "bg-purple-100 text-purple-800",
  pink: "bg-pink-100 text-pink-800",
  orange: "bg-orange-100 text-orange-800",
  teal: "bg-teal-100 text-teal-800",
  gray: "bg-gray-100 text-gray-800",
}.freeze
DEFAULT_BADGE_COLORS =

Default mappings from common status values to badge colors. These are applied automatically to enum and status fields.

Returns:

  • (Hash{String, Boolean => String}) 
{
  # Common status values
  "active" => "green",
  "inactive" => "gray",
  "enabled" => "green",
  "disabled" => "gray",
  "pending" => "yellow",
  "processing" => "blue",
  "in_progress" => "blue",
  "completed" => "green",
  "done" => "green",
  "success" => "green",
  "failed" => "red",
  "error" => "red",
  "cancelled" => "red",
  "canceled" => "red",
  "rejected" => "red",
  "declined" => "red",
  "approved" => "green",
  "accepted" => "green",
  "published" => "green",
  "unpublished" => "gray",
  "draft" => "gray",
  "archived" => "gray",
  "expired" => "red",
  "suspended" => "red",
  "blocked" => "red",
  # Boolean representations
  true => "green",
  false => "red",
  "true" => "green",
  "false" => "red",
  "yes" => "green",
  "no" => "red",
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Creates a new Configuration with default values.



177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/iron_admin/configuration.rb', line 177

def initialize
  @title = "Admin"
  @per_page = 25
  @default_sort = :created_at
  @default_sort_direction = :desc
  @search_engine = :default
  @badge_colors = DEFAULT_BADGE_COLORS.dup
  @theme_config = Theme.new
  @components = Components.new
  @audit_enabled = false
  @audit_storage = :memory
  @sticky_actions_column = true
  @http_base_url = nil
  @http_headers = {}
  @live_updates = :disabled
  @live_poll_interval = 3.seconds
  @live_throttle = 0.5.seconds
end

Instance Attribute Details

#audit_enabled ⇒ Boolean

Returns Whether audit logging is enabled (default: false).

Returns:

  • (Boolean) —

    Whether audit logging is enabled (default: false)



76
77
78
 
# File 'lib/iron_admin/configuration.rb', line 76

def audit_enabled
  @audit_enabled
end

#audit_storage ⇒ Symbol

Returns Audit storage backend, :memory or :database (default: :memory).

Returns:

  • (Symbol) —

    Audit storage backend, :memory or :database (default: :memory)



79
80
81
 
# File 'lib/iron_admin/configuration.rb', line 79

def audit_storage
  @audit_storage
end

#authenticate_block ⇒ Proc? (readonly)

Returns Authentication block.

Returns:

  • (Proc, nil) —

    Authentication block

See Also:



101
102
103
 
# File 'lib/iron_admin/configuration.rb', line 101

def authenticate_block
  @authenticate_block
end

#badge_colors ⇒ Hash{String => String}

Returns Mapping of status values to badge colors.

Returns:

  • (Hash{String => String}) —

    Mapping of status values to badge colors

See Also:



73
74
75
 
# File 'lib/iron_admin/configuration.rb', line 73

def badge_colors
  @badge_colors
end

#components ⇒ IronAdmin::Configuration::Components (readonly)

Returns Component overrides.

Returns:



116
117
118
 
# File 'lib/iron_admin/configuration.rb', line 116

def components
  @components
end

#current_user_block ⇒ Proc? (readonly)

Returns Current user block.

Returns:

  • (Proc, nil) —

    Current user block

See Also:



105
106
107
 
# File 'lib/iron_admin/configuration.rb', line 105

def current_user_block
  @current_user_block
end

#default_sort ⇒ Symbol

Returns Default sort column (default: :created_at).

Returns:

  • (Symbol) —

    Default sort column (default: :created_at)



63
64
65
 
# File 'lib/iron_admin/configuration.rb', line 63

def default_sort
  @default_sort
end

#default_sort_direction ⇒ Symbol

Returns Default sort direction, :asc or :desc (default: :desc).

Returns:

  • (Symbol) —

    Default sort direction, :asc or :desc (default: :desc)



66
67
68
 
# File 'lib/iron_admin/configuration.rb', line 66

def default_sort_direction
  @default_sort_direction
end

#http_base_url ⇒ String?

Returns Base URL for HTTP adapter (e.g., "https://api.example.com/v1").

Returns:



85
86
87
 
# File 'lib/iron_admin/configuration.rb', line 85

def http_base_url
  @http_base_url
end

#http_headers ⇒ Hash

Returns Default headers for HTTP adapter (e.g., auth tokens).

Returns:

  • (Hash) —

    Default headers for HTTP adapter (e.g., auth tokens)



88
89
90
 
# File 'lib/iron_admin/configuration.rb', line 88

def http_headers
  @http_headers
end

#live_poll_interval ⇒ ActiveSupport::Duration

Returns Client polling interval for live updates.

Returns:

  • (ActiveSupport::Duration) —

    Client polling interval for live updates



94
95
96
 
# File 'lib/iron_admin/configuration.rb', line 94

def live_poll_interval
  @live_poll_interval
end

#live_throttle ⇒ ActiveSupport::Duration

Returns Minimum interval between live broadcasts.

Returns:

  • (ActiveSupport::Duration) —

    Minimum interval between live broadcasts



97
98
99
 
# File 'lib/iron_admin/configuration.rb', line 97

def live_throttle
  @live_throttle
end

#live_updates ⇒ Symbol

Returns Live update strategy (:disabled or :polling).

Returns:

  • (Symbol) —

    Live update strategy (:disabled or :polling)



91
92
93
 
# File 'lib/iron_admin/configuration.rb', line 91

def live_updates
  @live_updates
end

#logo ⇒ String?

Returns Path to a custom logo image.

Returns:

  • (String, nil) —

    Path to a custom logo image



57
58
59
 
# File 'lib/iron_admin/configuration.rb', line 57

def 
  @logo
end

#on_action_block ⇒ Proc? (readonly)

Returns Action callback block.

Returns:

  • (Proc, nil) —

    Action callback block

See Also:



109
110
111
 
# File 'lib/iron_admin/configuration.rb', line 109

def on_action_block
  @on_action_block
end

#per_page ⇒ Integer

Returns Number of records per page (default: 25).

Returns:

  • (Integer) —

    Number of records per page (default: 25)



60
61
62
 
# File 'lib/iron_admin/configuration.rb', line 60

def per_page
  @per_page
end

#search_engine ⇒ Symbol

Returns Search engine to use (default: :default).

Returns:

  • (Symbol) —

    Search engine to use (default: :default)



69
70
71
 
# File 'lib/iron_admin/configuration.rb', line 69

def search_engine
  @search_engine
end

#sticky_actions_column ⇒ Boolean

Returns Whether the actions column stays fixed on horizontal scroll (default: true).

Returns:

  • (Boolean) —

    Whether the actions column stays fixed on horizontal scroll (default: true)



82
83
84
 
# File 'lib/iron_admin/configuration.rb', line 82

def sticky_actions_column
  @sticky_actions_column
end

#tenant_scope_block ⇒ Proc? (readonly)

Returns Tenant scope block.

Returns:

  • (Proc, nil) —

    Tenant scope block

See Also:



120
121
122
 
# File 'lib/iron_admin/configuration.rb', line 120

def tenant_scope_block
  @tenant_scope_block
end

#theme_config ⇒ IronAdmin::Configuration::Theme (readonly)

Returns Theme configuration.

Returns:

See Also:



113
114
115
 
# File 'lib/iron_admin/configuration.rb', line 113

def theme_config
  @theme_config
end

#title ⇒ String

Returns The admin panel title displayed in the header.

Examples:

config.title = "My Company Admin"

Returns:

  • (String) —

    The admin panel title displayed in the header



54
55
56
 
# File 'lib/iron_admin/configuration.rb', line 54

def title
  @title
end

Instance Method Details

#authenticate {|controller| ... } ⇒ void

This method returns an undefined value.

Defines the authentication check for admin access.

The block receives the controller instance and should redirect unauthenticated users or return false to deny access.

Examples:

Redirect unauthenticated users

config.authenticate do |controller|
  controller.redirect_to "/login" unless controller.session[:user_id]
end

Require admin role

config.authenticate do |controller|
  unless controller.current_user&.admin?
    controller.head :forbidden
  end
end

Yields:

  • (controller) —

    Block executed before each admin request

Yield Parameters:

  • controller (ActionController::Base) —

    The current controller



217
218
219
 
# File 'lib/iron_admin/configuration.rb', line 217

def authenticate(&block)
  @authenticate_block = block
end

#current_user {|controller| ... } ⇒ void

This method returns an undefined value.

Defines how to retrieve the current user.

The block receives the controller and should return the current user object. This user is passed to policy conditions and field visibility procs.

Examples:

config.current_user do |controller|
  controller.current_user
end

Using session

config.current_user do |controller|
  User.find_by(id: controller.session[:user_id])
end

Yields:

  • (controller) —

    Block that returns the current user

Yield Parameters:

  • controller (ActionController::Base) —

    The current controller

Yield Returns:

  • (Object) —

    The current user object



241
242
243
 
# File 'lib/iron_admin/configuration.rb', line 241

def current_user(&block)
  @current_user_block = block
end

#on_action {|action, resource, record, user| ... } ⇒ void

This method returns an undefined value.

Defines a callback executed after any CRUD action.

Use this for audit logging, notifications, or other side effects.

Examples:

Audit logging

config.on_action do |action, resource, record, user|
  AuditLog.create!(
    action: action,
    resource: resource.name,
    record_id: record.id,
    user_id: user.id
  )
end

Yields:

  • (action, resource, record, user) —

    Block executed after actions

Yield Parameters:

  • action (Symbol) —

    The action (:create, :update, :delete)

  • resource (Class) —

    The resource class

  • record (ActiveRecord::Base) —

    The affected record

  • user (Object) —

    The current user



266
267
268
 
# File 'lib/iron_admin/configuration.rb', line 266

def on_action(&block)
  @on_action_block = block
end

#tenant_scope {|scope| ... } ⇒ void

Note:

Ensure the tenant context (e.g., Current.organization) is set before IronAdmin requests are processed, typically via a before_action.

This method returns an undefined value.

Defines a tenant scope for multi-tenant applications.

The block receives an ActiveRecord::Relation and should return a scoped relation that only includes records for the current tenant. This scope is applied to all resource queries.

Examples:

Organization-based tenancy

config.tenant_scope do |scope|
  scope.where(organization_id: Current.organization.id)
end

Account-based tenancy

config.tenant_scope do |scope|
  scope.where(account_id: Current..id)
end

Yields:

  • (scope) —

    Block that scopes queries to current tenant

Yield Parameters:

  • scope (ActiveRecord::Relation) —

    The base query scope

Yield Returns:

  • (ActiveRecord::Relation) —

    The tenant-scoped query



313
314
315
 
# File 'lib/iron_admin/configuration.rb', line 313

def tenant_scope(&block)
  @tenant_scope_block = block
end

#theme {|theme| ... } ⇒ IronAdmin::Configuration::Theme

Configures the admin panel theme.

Examples:

config.theme do |t|
  t.primary_color = "#4F46E5"
  t.sidebar_bg = "#1F2937"
  t.font_family = "Inter, sans-serif"
end

Yields:

  • (theme) —

    Block to configure theme options

Yield Parameters:

Returns:

See Also:



284
285
286
287
 
# File 'lib/iron_admin/configuration.rb', line 284

def theme
  yield @theme_config if block_given?
  @theme_config
end