Skip to main content

Dashboards

cm_dashboard adds a dashboard page to a model, built from rows of metric cards, charts and tables. Each widget gets its data from a helper method that receives permission-scoped records and the applied filters.

Quick example​

cm_admin do
cm_dashboard :user_dashboard, display_name: "User Dashboard" do
filter :cm_role_id, :single_select, helper_method: :select_options_for_cm_role

row do
cm_section "" do
metric_card :total_users_metric, title: "Total Users"
end
cm_section "" do
chart :users_by_role_chart_data, title: "Users by Role", chart_type: :pie_chart
end
end
end
end
app/helpers/cm_admin/dashboard_helper.rb
module CmAdmin
module DashboardHelper
def total_users_metric(scoped_ar_object, _scoped_filters = {})
scoped_ar_object.count
end

def users_by_role_chart_data(scoped_ar_object, _scoped_filters = {})
scoped_ar_object.joins(:cm_role).group("cm_roles.name").count
end
end
end

The dashboard is served at /admin/<models>/<name> (here /admin/users/user_dashboard). Enable its permission for each role in Roles β†’ Permissions.

Options​

cm_dashboard(name, display_name: nil, icon_name: nil, page_title: nil, page_description: nil, partial: nil)
NameTypeDefaultDescription
nameSymbolrequiredUnique action name of the dashboard. Define several with different names.
display_nameStringnilLabel of the dashboard link.
icon_nameStringnilIcon of the dashboard link.
page_titleStringdisplay_name, or "<Models> Dashboard"Page title.
page_descriptionStringnilText below the title.
partialStringnilRender this partial instead.

Inside the block, use filter, sort, row and cm_section, and these widgets inside sections:

WidgetSignatureOptions
metric_cardmetric_card(helper_method, options = {})title, description, col_size (default 6), display_if, html_attrs, partial
chartchart(helper_method, options = {})title, description, chart_type (default :line_chart; also :pie_chart, :bar_chart, :stacked_bar_chart, :scatter_chart), x_label, y_label, legends, col_size (default 12), chart_attrs, display_if, html_attrs
tabletable(source_method, options = {}) { ... }title, description, associated_model_name, per_page (default 20), eager_load_associations, display_if. Declare column and sort inside the block.

Helper methods live in CmAdmin::DashboardHelper and receive (scoped_ar_object, scoped_filters).

Writing dashboard helpers​

Helper signature​

Create custom dashboard helper methods in /app/helpers/cm_admin/dashboard_helper.rb:

module CmAdmin
module DashboardHelper
# Dashboard helper methods receive (scoped_ar_object, scoped_filters)
# scoped_ar_object is already permission-scoped based on user permissions

def total_users_metric(scoped_ar_object, scoped_filters = {})
base_query = scoped_ar_object # Already permission-scoped

# Apply dashboard filters
if scoped_filters[:single_select].present?
scoped_filters[:single_select].each do |key, value|
next if value.blank?
base_query = base_query.where(key => value)
end
end

if scoped_filters[:search].present?
search_term = scoped_filters[:search]
base_query = base_query.where("email ILIKE ? OR first_name ILIKE ?",
"%#{search_term}%", "%#{search_term}%")
end

base_query.count
end

def users_by_role_chart_data(scoped_ar_object, scoped_filters = {})
base_query = scoped_ar_object

# Apply filters similar to above
# ... filter logic ...

base_query.joins(:cm_role).group('cm_roles.name').count
end
end
end

Permission Scoping​

Dashboard helpers automatically receive permission-scoped data:

  1. Dashboard-specific permissions: Uses scope_name from permissions with matching action_name and ar_model_name
  2. Policy scope fallback: Falls back to CmAdmin::{Model}PolicyIndexScope if no dashboard-specific scope
  3. Filter integration: Dashboard filters are automatically scoped and passed to helper methods

Filters, permissions and errors​

Filter Integration​

Dashboard filters are automatically passed to helper methods:

def filtered_users_metric(scoped_ar_object, scoped_filters = {})
base_query = scoped_ar_object

# Single select filters
if scoped_filters[:single_select]&.dig(:cm_role_id).present?
base_query = base_query.where(cm_role_id: scoped_filters[:single_select][:cm_role_id])
end

# Date filters
if scoped_filters[:date]&.dig(:created_at).present?
date_range = scoped_filters[:date][:created_at]
base_query = base_query.where(created_at: date_range)
end

# Search filters
if scoped_filters[:search].present?
search_term = scoped_filters[:search]
base_query = base_query.where("email ILIKE ?", "%#{search_term}%")
end

base_query.count
end

Permission-Based Scoping​

Dashboard helpers automatically respect user permissions:

# This helper will only see data the user has permission to access
def department_users_metric(scoped_ar_object, scoped_filters = {})
# scoped_ar_object is already filtered based on:
# 1. Dashboard-specific permission scope (if configured)
# 2. Model policy scope (fallback)

scoped_ar_object.where(department: 'Engineering').count
end

Error Handling​

Dashboard helpers include built-in error handling:

def safe_metric_calculation(scoped_ar_object, scoped_filters = {})
begin
# Your calculation logic
scoped_ar_object.complex_calculation
rescue StandardError => e
Rails.logger.error "Dashboard metric error: #{e.message}"
0 # Return safe default value
end
end

Recipes​

Dashboard with filters, metrics and charts​

# app/models/concerns/cm_admin/student.rb

module CmAdmin
module Student
extend ActiveSupport::Concern
included do
cm_admin do
actions only: []
icon_name 'fa fa-graduation-cap'

cm_dashboard :dashboard_student_type,
display_name: 'Dashboard',
page_title: 'Dashboard',
page_description: 'Student Dashboard' do
# Permissions / access control to be wired into your system:
# - Full Access
# - User Office Only
# - Assignee Only

# Filters - These will be automatically passed to dashboard helpers
filter :office_id,
:multi_select,
helper_method: :select_options_for_office,
placeholder: 'Office',
display_name: 'Office',
active_by_default: true

filter :assigned_to_id,
:multi_select,
helper_method: :select_options_for_lead_assignees,
placeholder: 'Assignee',
display_name: 'Assignee',
active_by_default: true

filter :application_coordinator_id,
:multi_select,
helper_method: :select_options_for_application_coordinators,
placeholder: 'Application Coordinator',
display_name: 'Application Coordinator',
active_by_default: true,
filter_with: :with_application_coordinator_ids

# Row 1 – 3 metric cards (Total Leads | Total Prospects | Total Applications)
row do
cm_section '' do
metric_card :total_leads_metric,
title: 'Total Leads'
end

cm_section '' do
metric_card :total_prospects_metric,
title: 'Total Prospects'
end

cm_section '' do
metric_card :total_applications_metric,
title: 'Total Applications'
end
end

# Charts – Layout: 2 columns, Pie Chart for all
# Row 2 – Leads by Status | Prospects by Status
row do
cm_section '' do
chart :leads_by_status_chart_data,
title: 'Leads by Status',
chart_type: :pie_chart
end
end

row do
cm_section '' do
chart :prospects_by_status_chart_data,
title: 'Prospects by Status',
chart_type: :pie_chart
end
end

# Row 3 – Applications by Status (single column)
row do
cm_section '' do
chart :applications_by_status_chart_data,
title: 'Applications by Status',
chart_type: :pie_chart
end
end
end

cm_index do
page_title 'Students'

# These same filters will be used for dashboard filtering
filter %i[first_name last_name email], :search, placeholder: 'Search'
filter :office_id, :multi_select, helper_method: :select_options_for_office
filter :assigned_to_id, :multi_select, helper_method: :select_options_for_lead_assignees

sort column: "created_at", default: true, default_direction: "desc"

column :full_name
column :email
column :office_name, header: 'Office'
column :status
column :created_at, field_type: :date, format: '%d %b, %Y'
end
end
end
end
end

Helpers for that dashboard​

Create the dashboard helper methods in /app/helpers/cm_admin/dashboard_helper.rb:

module CmAdmin
module DashboardHelper
# Metric card methods - receive permission-scoped data and filters
def total_leads_metric(scoped_ar_object, scoped_filters = {})
base_query = scoped_ar_object.where(status: 'lead')
apply_dashboard_filters(base_query, scoped_filters).count
end

def total_prospects_metric(scoped_ar_object, scoped_filters = {})
base_query = scoped_ar_object.where(status: 'prospect')
apply_dashboard_filters(base_query, scoped_filters).count
end

def total_applications_metric(scoped_ar_object, scoped_filters = {})
base_query = scoped_ar_object.where(status: 'application')
apply_dashboard_filters(base_query, scoped_filters).count
end

# Chart data methods
def leads_by_status_chart_data(scoped_ar_object, scoped_filters = {})
base_query = scoped_ar_object.where(status: 'lead')
filtered_query = apply_dashboard_filters(base_query, scoped_filters)
filtered_query.group(:sub_status).count
end

def prospects_by_status_chart_data(scoped_ar_object, scoped_filters = {})
base_query = scoped_ar_object.where(status: 'prospect')
filtered_query = apply_dashboard_filters(base_query, scoped_filters)
filtered_query.group(:sub_status).count
end

def applications_by_status_chart_data(scoped_ar_object, scoped_filters = {})
base_query = scoped_ar_object.where(status: 'application')
filtered_query = apply_dashboard_filters(base_query, scoped_filters)
filtered_query.group(:application_status).count
end

private

# Helper method to apply dashboard filters consistently
def apply_dashboard_filters(base_query, scoped_filters)
return base_query if scoped_filters.blank?

# Apply multi-select filters
if scoped_filters[:multi_select].present?
scoped_filters[:multi_select].each do |key, values|
next if values.blank?

case key.to_s
when 'office_id'
base_query = base_query.where(office_id: values)
when 'assigned_to_id'
base_query = base_query.where(assigned_to_id: values)
when 'application_coordinator_id'
base_query = base_query.where(application_coordinator_id: values)
end
end
end

# Apply search filters
if scoped_filters[:search].present?
search_term = scoped_filters[:search]
base_query = base_query.where(
"first_name ILIKE ? OR last_name ILIKE ? OR email ILIKE ?",
"%#{search_term}%", "%#{search_term}%", "%#{search_term}%"
)
end

# Apply date filters
if scoped_filters[:date].present?
scoped_filters[:date].each do |key, date_range|
next if date_range.blank?
base_query = base_query.where(key => date_range)
end
end

base_query
end
end
end

Table widget​

row do
cm_section "Tables" do
table "Recent Activity", associated_model_name: "User" do
column :full_name
column :email
end
end
end

Best Practices​

  1. Use descriptive method names: total_active_users_metric instead of user_count
  2. Handle empty data gracefully: Return appropriate defaults for empty datasets
  3. Apply filters consistently: Use the same filter logic across related widgets
  4. Optimize queries: Use includes, joins, and select to optimize database queries
  5. Cache expensive calculations: Use Rails caching for complex metrics
  6. Test with different permission levels: Ensure widgets work for all user types

Security Considerations​

  • Dashboard helpers automatically receive permission-scoped data
  • Filters are validated against dashboard configuration
  • All database queries respect user access controls
  • Error messages don't expose sensitive information