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.
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:filteradds filters,columnadds table columns. See Index page.cm_showβ the detail page:tabgroups content,cm_sectionadds a titled section,fieldrenders an attribute. See Show page.cm_new/cm_editβ the forms:form_fieldrenders an input. See New page and Edit page.
2. Include it in the modelβ
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:
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:
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):
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β
- Views β every page type and its DSL
- Filters & Search
- Custom actions
- Roles & Permissions