Skip to main content

CmAdmin Configuration

All cm-admin global settings live in the initializer file (config/initializers/zcm_admin.rb by default) and are exposed through the CmAdmin.configure block. The leading z in the filename ensures the initializer is loaded last in the Rails boot sequence, so any models it references are already defined.

# config/initializers/zcm_admin.rb
CmAdmin.configure do |config|
  config.layout = 'admin'
  config.included_models = [User, Post]
  config.project_name = 'My App'
  # ...see sections below for every option
end

Quick Reference​

OptionTypeDefaultDescription
layoutString'admin'Name of the Rails layout used to render cm-admin pages.
included_modelsArray<Class>[]Models registered with cm-admin (the ones that appear in the sidebar and routes).
cm_admin_modelsArray<CmAdmin::Model>[]Resolved CmAdmin::Model wrappers. Populated automatically — do not set manually.
project_nameString''Display name shown in the browser title and header.
sidebarArray[]Custom sidebar navigation entries. When empty, the sidebar is auto-generated from included_models.
auth_methodSymbol:otpAuthentication strategy. Valid values: :otp, :password.
display_role_on_sidebarBooleantrueWhether to show the current user's role on the sidebar.
display_date_formatString'M d, Y'Flatpickr/JS date format used when rendering date fields.
display_datetime_formatString'M d, Y, H:i K'Flatpickr/JS datetime format used when rendering datetime fields.
global_search_modelsArray<Class>[]Models searchable from the global search bar.
enable_trackingBooleanfalseEnables Google Tag Manager / tracking snippets in the layout.
enable_email_loggingBooleanfalseLogs every CmAdmin.send_email delivery to the cm_email_logs table.
email_template_settingsHash{ show_copyright: true, footer_content: nil }Default email template options (copyright footer, custom footer content).
mcp_enabledBooleanfalseMounts the built-in MCP server endpoint at <mount_path>/mcp.
mcp_system_promptString|nilnilCustom system prompt sent to MCP AI clients during the initialize handshake.
layout_css_filesArray<String>[]Extra host-app SCSS files compiled into the cm-admin CSS bundle.

Layout & Branding​

layout​

Name of the Rails layout used to render cm-admin pages. Defaults to 'admin'.

config.layout = 'admin'

project_name​

Shown in the browser title and the cm-admin header. Commonly wired to your Rails project settings:

config.project_name = Rails.configuration.x.project_settings.name

When provided, replaces the auto-generated sidebar with custom navigation entries. When left empty (default), cm-admin builds the sidebar from included_models, filtered by the current user's policies.

config.sidebar = [
  { label: 'Dashboard', path: '/dashboard', icon: 'fa-solid fa-gauge' },
  { label: 'Users', path: '/cm_admin/users', icon: 'fa-solid fa-users' }
]

display_role_on_sidebar​

When true (default), the current user's role name is displayed on the sidebar. Set to false to hide it.

config.display_role_on_sidebar = false

Models​

included_models​

The list of ActiveRecord models that cm-admin should register. Each model must have a corresponding CmAdmin::<Model> concern with a cm_admin DSL block. Only models listed here appear in the sidebar, routes, and MCP tool discovery.

config.included_models = [User, Post, CmRole, ApiToken]

Generator-based features (scheduler, support tickets, etc.) will prompt you to add their models here.

cm_admin_models​

This is a runtime-populated collection of CmAdmin::Model wrappers built from included_models. Do not set this manually — it is managed by cm-admin during boot.

global_search_models​

Models that should be searchable from the global search bar in the header. The first three are surfaced as quick links in the search dropdown.

config.global_search_models = [User, Post]

Authentication​

auth_method​

Controls which login flow cm-admin renders. Valid values are :otp (default) and :password. Setting an invalid value raises ArgumentError.

config.auth_method = :password
  • :otp — email-based OTP login. The user enters their email and receives a one-time code.
  • :password — email + password login.

The chosen method also toggles password-related UI (e.g. "forgot password" links are only shown for :password).

Date & Time Formatting​

display_date_format and display_datetime_format​

These are Flatpickr formatting strings passed to the JS date/datetime pickers used across index and form views.

config.display_date_format = 'M d, Y'              # e.g. "Aug 6, 2026"
config.display_datetime_format = 'M d, Y, H:i K'   # e.g. "Aug 6, 2026, 14:30 PM"

These only affect the picker UI. Use the format: option on individual column/field declarations to override how stored values are rendered.

Email​

enable_email_logging​

When true, every email sent via CmAdmin.send_email is recorded in the cm_email_logs table with delivery status, recipients, failure reasons, and record association. Disabled by default.

config.enable_email_logging = true

To set up the required table:

rails g cm_admin:add_email_logs
rails db:migrate

See CmAdminEmail for the full email sending API.

email_template_settings​

Default options applied to every email template unless overridden per-call:

config.email_template_settings = {
  show_copyright: true,       # render the © footer
  footer_content: 'Acme Inc.' # custom HTML/text shown above the copyright
}

Both keys can be overridden on individual CmAdmin.send_email calls via the email_template_settings: argument.

Tracking​

enable_tracking​

When true, cm-admin injects Google Tag Manager snippets into the layout head and body. Use this only in environments where GTM is configured.

config.enable_tracking = true

MCP Server​

cm-admin ships with a built-in Model Context Protocol server that exposes your admin-registered models to AI clients. See McpServer for the full setup guide.

mcp_enabled​

When true, the MCP Rack endpoint is mounted at <cm_admin_engine_mount_path>/mcp and models with mcp_actions in their DSL block become available as list/show tools. Defaults to false.

config.mcp_enabled = true

mcp_system_prompt​

A custom system prompt sent to the AI client during the MCP initialize handshake. This is the right place to inject domain-specific knowledge, business semantics, and known limitations the AI should respect.

config.mcp_system_prompt = <<~PROMPT
  You are reading records from the Acme Platform via MCP tools.

  Data model notes:
  - `assignee` is the current owner of a work item, not the original creator.
  - `internal_feedback_rating` is unused; QA ratings live inside each work
    item's history and cannot be bulk-aggregated through MCP tools.

  Best practices:
  - Use aggregate tools for counts/sums/averages instead of listing all rows.
  - Use `fetch_options` to resolve select filter values before filtering.
PROMPT

When left nil (default), the server falls back to a generic one-line instruction. Keep the prompt focused on semantic guidance — avoid pasting the full schema, which the AI can already discover through list_models and tool schemas.

CSS Bundling​

layout_css_files​

Extra SCSS files from the host app (app/assets/stylesheets/) that should be compiled into the cm-admin CSS bundle. Each entry is a filename relative to app/assets/stylesheets/.

config.layout_css_files = ['application.scss', 'theme_overrides.scss']

This is used by the cm-admin CSS bundler (CmAdminCssBundler) when building the Tailwind/Sass output. Each file is compiled to app/assets/builds/<name>.css.