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
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)
| Name | Type | Default | Description |
|---|---|---|---|
name | Symbol | required | Unique action name of the dashboard. Define several with different names. |
display_name | String | nil | Label of the dashboard link. |
icon_name | String | nil | Icon of the dashboard link. |
page_title | String | display_name, or "<Models> Dashboard" | Page title. |
page_description | String | nil | Text below the title. |
partial | String | nil | Render this partial instead. |
Inside the block, use filter, sort, row and cm_section, and these widgets inside sections:
| Widget | Signature | Options |
|---|---|---|
metric_card | metric_card(helper_method, options = {}) | title, description, col_size (default 6), display_if, html_attrs, partial |
chart | chart(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 |
table | table(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:
- Dashboard-specific permissions: Uses
scope_namefrom permissions with matchingaction_nameandar_model_name - Policy scope fallback: Falls back to
CmAdmin::{Model}PolicyIndexScopeif no dashboard-specific scope - 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β
- Use descriptive method names:
total_active_users_metricinstead ofuser_count - Handle empty data gracefully: Return appropriate defaults for empty datasets
- Apply filters consistently: Use the same filter logic across related widgets
- Optimize queries: Use includes, joins, and select to optimize database queries
- Cache expensive calculations: Use Rails caching for complex metrics
- 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