Skip to main content

Quickstart

Build an admin page for an existing model after installing cm-admin. It takes three steps: write a concern, include it in the model and register the model.

app/models/concerns/cm_admin/blog_category.rb
module CmAdmin
module BlogCategory
extend ActiveSupport::Concern

included do
cm_admin do
actions only: %i[index show new create edit update destroy]

cm_index do
filter %i[name], :search, placeholder: "Search"
column :name
column :color_name
end

cm_show page_title: :name do
tab :profile, "" do
cm_section "Details" do
field :name
field :color_name
field :created_at, field_type: :date, format: "%d %b, %Y"
end
end
end

cm_new do
cm_section "Details" do
form_field :name
form_field :color_id, input_type: :single_select, helper_method: :select_options_for_color
end
end

cm_edit do
cm_section "Details" do
form_field :name
form_field :color_id, input_type: :single_select, helper_method: :select_options_for_color
form_field :slug
end
end
end
end
end
end

1. Write the admin concern​

cm-admin config lives in a concern under app/models/concerns/cm_admin/, named after the model. The cm_admin block declares which actions the model supports and what each page shows:

  • cm_index β€” the listing page: filter adds filters, column adds table columns. See Index page.
  • cm_show β€” the detail page: tab groups content, cm_section adds a titled section, field renders an attribute. See Show page.
  • cm_new / cm_edit β€” the forms: form_field renders an input. See New page and Edit page.

2. Include it in the model​

app/models/blog_category.rb
class BlogCategory < ApplicationRecord
include CmAdmin::BlogCategory
end

3. Register the model​

Add the model class to config.included_models in config/initializers/cm_admin.rb:

config/initializers/cm_admin.rb
CmAdmin.configure do |config|
config.included_models = [BlogCategory, ...]
end

Restart the server and open http://localhost:3000/admin β€” the model appears in the sidebar with index, show and form pages working out of the box.

A complete example​

A real admin page usually combines filters, badges, custom actions and richer forms. Here's a complete concern β€” a blog post with a publish workflow, adapted from a production app:

app/models/concerns/cm_admin/blog_post.rb
module CmAdmin
module BlogPost
extend ActiveSupport::Concern

STATUS_TAG_COLOR = { draft: "cm-badge-blue", published: "cm-badge-green", archived: "cm-badge-gray" }.freeze

included do
cm_admin do
actions only: %i[index show new create edit update destroy]
icon_name "fa-solid fa-newspaper"
sort column: "published_at", display_name: "Publish Date", default_direction: "desc", default: true

cm_index do
page_title "Blog Posts"

# filters: search, selects and a custom scope
filter %i[title description], :search, placeholder: "Search"
filter :status # enum columns get a multi-select with their values automatically
filter :blog_category_id, :single_select, helper_method: :select_options_for_blog_category
filter :is_featured, :single_select, collection: [["Yes", true], ["No", false]], filter_with: :featured

# a row-level action that opens a form modal
custom_action name: "publish", path: ":id/publish", route_type: "member", verb: :patch,
display_type: :form_modal, icon_name: "fa fa-check",
display_if: ->(post) { post.draft? },
modal_configuration: { title: "Publish Post", confirmation_text: "Publish" } do
form do
alert_box body: "Publishing makes the post visible on the live website.", type: :info
cm_section "" do
form_field :published_at, input_type: :date, label: "Publish Date", is_required: true
end
end
on_submit do
post = ::BlogPost.find(params[:id])
post.publish(published_at: params[:blog_post][:published_at])
post
end
end

column :title
column :blog_category_name, header: "Category"
column :status, field_type: :badge, badge_class: STATUS_TAG_COLOR
column :published_at, field_type: :date, format: "%d %b %Y", header: "Publish Date"
end

cm_show page_title: :title do
tab :profile, "" do
cm_section "Blog post details" do
field :title
field :description
field :status, field_type: :badge, badge_class: STATUS_TAG_COLOR
field :featured_image, field_type: :image
field :blog_category_name, label: "Category"
field :published_at, field_type: :date, format: "%d %b, %Y",
display_if: ->(post) { post.published_at.present? }
field :content, field_type: :rich_text
end
cm_section "Log details" do
field :created_at, field_type: :date, format: "%d %b, %Y"
field :updated_at, field_type: :date, format: "%d %b, %Y"
end
end
end

cm_new page_title: "Add Blog Post" do
cm_section "Details" do
form_field :title
form_field :description, input_type: :text
form_field :content, input_type: :rich_text
form_field :featured_image, input_type: :single_file_upload
form_field :is_featured, input_type: :switch, label: "Featured?"
form_field :blog_category_id, input_type: :single_select,
helper_method: :select_options_for_blog_category, can_create_new_entity: true
end
end

cm_edit page_title: "Edit Blog Post" do
cm_section "Details" do
form_field :title
form_field :description, input_type: :text
form_field :featured_image, input_type: :single_file_upload
form_field :is_featured, input_type: :switch, label: "Featured?"
form_field :blog_category_id, input_type: :single_select,
helper_method: :select_options_for_blog_category, can_create_new_entity: true
form_field :published_at, input_type: :date, label: "Publish Date",
html_attrs: { data: { max_date: "today" } }
form_field :content, input_type: :rich_text
end
end
end
end
end
end

The helper_method referenced above returns [label, value] pairs from an admin helper (enum columns like status don't need one β€” their values are inferred from the model's enum):

app/helpers/cm_admin/blog_posts_helper.rb
def select_options_for_blog_category(_record = nil, _field_name = nil)
BlogCategory.all.map { |c| [c.name, c.id] }
end

Recipes​

Show a dropdown for an association​

Use input_type: :single_select with a helper_method that returns [label, value] pairs, defined in an admin helper (app/helpers/cm_admin/). Add can_create_new_entity: true to let admins create the associated record inline.

See Select options.

Add a status badge column​

column :status, field_type: :badge, badge_class: { draft: "cm-badge-yellow", published: "cm-badge-green" }

See Status badges.

Filter by a field​

filter %i[status], :single_select # helper_method is optional for enum columns
filter %i[created_at], :date

See Filters.

Next steps​