Class: IronAdmin::Dashboard

Inherits:
Object
  • Object
show all
Defined in:
lib/iron_admin/dashboard.rb

Overview

Base class for defining the admin dashboard.

The dashboard is the landing page of the admin panel and typically displays key metrics, charts, and recent records. Create a subclass of Dashboard to customize what appears on your admin home page.

Only one Dashboard subclass should exist per application. When defined, it automatically registers itself as the active dashboard.

Examples:

Basic dashboard

class AdminDashboard < IronAdmin::Dashboard
  metric :total_users, format: :number do
    User.count
  end

  metric :revenue, format: :currency do
    Order.sum(:total)
  end

  chart :signups_by_month, type: :bar do
    User.group_by_month(:created_at).count
  end

  recent :orders, limit: 10
  recent :users, limit: 5
end

Dashboard with custom layout

class AdminDashboard < IronAdmin::Dashboard
  metric :active_users do
    User.where(active: true).count
  end

  chart :orders_by_day, type: :line do
    Order.group_by_day(:created_at).count
  end

  layout do
    # Define custom grid layout
  end
end

Class Method Summary collapse

Class Method Details

.chart(name, type: :line, colors: nil, label: nil, live: false) { ... } ⇒ void

This method returns an undefined value.

Defines a chart for the dashboard.

Charts display time-series or categorical data visually. The block should return data in a format suitable for the chart type.

Examples:

Chart with custom label

chart :projects_by_status, type: :bar, label: "Projects by Status" do
  Project.group(:status).count
end

Bar chart with custom colors

chart :orders_by_status, type: :bar, colors: ["#10b981", "#3b82f6", "#ef4444"] do
  Order.group(:status).count
end

Parameters:

  • name (Symbol) —

    The chart identifier

  • type (Symbol) (defaults to: :line) —

    The chart type

    • :line - Line chart for trends over time
    • :bar - Bar chart for comparisons
    • :pie - Pie chart for proportions
    • :doughnut - Doughnut chart for proportions
  • colors (Array<String>, nil) (defaults to: nil) —

    Optional per-chart color palette (CSS color values). Overrides the global theme chart_colors for this chart.

  • label (String, nil) (defaults to: nil) —

    Custom display title for the chart. Defaults to name.to_s.humanize when not provided.

Yields:

  • Block that computes and returns the chart data

Yield Returns:

  • (Hash, Array) —

    Data for the chart (format depends on type)



117
118
119
120
121
 
# File 'lib/iron_admin/dashboard.rb', line 117

def chart(name, type: :line, colors: nil, label: nil, live: false, &block)
  self.defined_charts = defined_charts + [
    { name: name, type: type, colors: colors, label: label, live: live, block: block },
  ]
end

.inherited(subclass) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Automatically registers subclasses as the active dashboard.



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

def inherited(subclass)
  super
  IronAdmin.dashboard_class = subclass
end

.layout { ... } ⇒ void

This method returns an undefined value.

Defines a custom layout for the dashboard.

Use this to control the arrangement of metrics, charts, and recent record lists on the dashboard page.

Examples:

Custom two-column layout

layout do
  # Layout definition
end

Yields:

  • Block that defines the layout structure



159
160
161
 
# File 'lib/iron_admin/dashboard.rb', line 159

def layout(&block)
  self._layout_block = block
end

.metric(name, format: :number, icon: nil, live: false) { ... } ⇒ void

This method returns an undefined value.

Defines a metric card for the dashboard.

Metrics are displayed as cards showing a single value with a label. They're useful for key performance indicators and summary statistics.

Examples:

User count metric with icon

metric :total_users, format: :number, icon: "users" do
  User.count
end

Revenue metric

metric :total_revenue, format: :currency do
  Order.where(status: "completed").sum(:total)
end

Parameters:

  • name (Symbol) —

    The metric identifier (used as the card title)

  • format (Symbol) (defaults to: :number) —

    How to format the value

    • :number - Plain number with thousands separators
    • :currency - Currency format (uses Rails number_to_currency)
    • :percentage - Percentage format
  • icon (String, nil) (defaults to: nil) —

    Optional Heroicon name for visual context (e.g., "users", "currency-dollar")

Yields:

  • Block that computes and returns the metric value

Yield Returns:

  • (Numeric) —

    The metric value



84
85
86
 
# File 'lib/iron_admin/dashboard.rb', line 84

def metric(name, format: :number, icon: nil, live: false, &block)
  self.defined_metrics = defined_metrics + [{ name: name, format: format, icon: icon, live: live, block: block }]
end

.recent(resource_name, limit: 5, scope: nil) ⇒ void

This method returns an undefined value.

Displays a list of recent records from a resource.

Shows a table of the most recent records, with links to view each one. Useful for quick access to newly created or updated items.

Examples:

Recent orders

recent :orders, limit: 10

Recent pending orders

recent :orders, limit: 5, scope: -> { where(status: "pending") }

Recent active users

recent :users, limit: 5, scope: -> { where(active: true) }

Parameters:

  • resource_name (Symbol) —

    The resource name (pluralized, e.g., :orders)

  • limit (Integer) (defaults to: 5) —

    Maximum number of records to show (default: 5)

  • scope (Proc, nil) (defaults to: nil) —

    Optional scope to filter records



142
143
144
 
# File 'lib/iron_admin/dashboard.rb', line 142

def recent(resource_name, limit: 5, scope: nil)
  self.defined_recents = defined_recents + [{ resource_name: resource_name, limit: limit, scope: scope }]
end