Custom Actions
custom_action adds your own action to a model: a button, a confirmation modal, a form, a page, a link or a JSON endpoint. Its block runs your Ruby code against a record or the collection. Typical use cases:
- State transitions β approve, archive, publish, or soft-delete a record.
- Quick edits β update a subset of fields through a modal or dedicated page.
- Exports / bulk fetches β trigger a collection-level operation.
- External links β send the user to another URL related to the record.
Quick exampleβ
cm_show page_title: :title do
custom_action name: "approve", display_name: "Approve", route_type: "member", verb: "patch",
path: ":id/approve", display_type: :modal, display_if: lambda(&:draft?),
icon_name: "fa-regular fa-circle-check",
modal_configuration: { title: "Approve Post", description: "Are you sure?", confirmation_text: "Approve" } do
post = ::Post.find(params[:id])
post.approved!
post
end
end
Optionsβ
custom_action(name: nil, page_title: nil, page_description: nil, display_name: nil, verb: nil, layout: nil, layout_type: nil, partial: nil, path: nil, display_type: nil, redirect_to: nil, modal_configuration: {}, url_params: {}, display_if: ->(_) { true }, route_type: nil, icon_name: "fa fa-th-large", icon_style: nil, group_name: nil, success_message: ->(_) {}, error_message: ->(_, _) {}, alert_type: :flash, show_on_index: true, &block)
| Option | Type | Description |
|---|---|---|
name | String | Unique identifier for the action. Used to build the route and controller method. |
display_name | String | Human-friendly label shown on the button/link. Falls back to name.titleize. |
verb | String | HTTP verb: get, post, put, patch, or delete. |
path | String | URL path. Use :id for member routes (e.g. ':id/approve'). |
route_type | String | member (operates on a single record) or collection (operates on many). |
display_type | Symbol | How the action is rendered. See Display types. |
display_if | Proc | Lambda receiving the record; return true to show the action. |
icon_name | String | Font Awesome icon class, e.g. 'fa-regular fa-circle-check'. |
icon_style | String | Inline icon style, e.g. '--fa-primary-color: #ff6b6b;'. |
modal_configuration | Hash | Modal title, description, and confirmation_text for modal display types. |
page_title | String | Title shown for :page / :form_page display types. |
page_description | String | Description shown for :page / :form_page display types. |
group_name | String | Groups actions together in the dropdown (see Group Action). |
show_on_index | Boolean | Whether the action appears in the index row dropdown. Defaults to true. |
redirect_to | Proc | Lambda returning a URL to redirect to (used by :link). |
success_message | Proc | Lambda receiving the record; returns an alert Hash { header:, body:, icon: }. |
error_message | Proc | Lambda receiving the record and its errors; returns an alert Hash { header:, body:, icon: }. |
alert_type | Symbol | Success alert style: :flash (default) or :banner. |
layout_type | String | cm_association_index or cm_association_show for pages that list associated records. |
layout | String | Layout used by :page actions. Defaults to cm_admin. |
partial | String | Partial rendered by :page actions. |
url_params | Hash | Extra URL parameters added to the action link. |
How it worksβ
custom_action name: 'action_name', route_type: 'member', verb: 'patch',
path: ':id/action_name', display_type: :button do
record = ::YourModel.find(params[:id])
# perform the operation
record
end
The block can read params and must return the affected record (or collection). The return value is used to render the response and to evaluate success_message / error_message. Returning a Hash or an Array renders it as JSON β that is how display_type: :route endpoints work.
Declare the action inside cm_index for collection actions and inside cm_show for member actions. After adding one, enable its permission for each role in Roles β Permissions.
Display typesβ
The display_type option controls how the action is presented:
:buttonβ A button that submits directly and runs the block. Best for one-click state changes.:modalβ Shows a confirmation modal before submitting. Configure copy viamodal_configuration.:form_modalβ Opens a modal containing a form. Requires aformblock and anon_submitblock.:pageβ Renders a dedicated page. Usepage_title/page_description.:form_pageβ A full-page form. Requires aformblock and anon_submitblock.:linkβ Renders a link to an external/related URL viaredirect_to.:icon_onlyβ Renders only the icon with no label.:routeβ No UI: exposes the block as an endpoint, for example to serve select options.
Recipesβ
Button actionβ
Runs immediately when clicked. Here display_if hides the action unless the record is a draft.
custom_action name: 'activate', display_name: 'Activate', route_type: 'member', verb: 'post',
icon_name: 'fa-regular fa-power-off', path: ':id/activate',
display_type: :button, display_if: ->(df) { !df.is_active? } do
demo_form = ::DemoForm.find(params[:id])
demo_form.update!(is_active: true)
demo_form
end
Modal actionβ
Prompts the user to confirm before running the block.
custom_action name: 'approve', display_name: 'Approve', route_type: 'member', verb: 'patch',
icon_name: 'fa-regular fa-circle-check', path: ':id/approve',
display_type: :modal, display_if: lambda(&:draft?),
modal_configuration: { title: 'Approve Demo Form',
description: 'Are you sure you want to approve this demo form?',
confirmation_text: 'Approve' } do
demo_form = ::DemoForm.find(params[:id])
demo_form.approved!
demo_form
end
Form modal actionβ
Collects input through a form rendered in a modal. Requires both a form block (defining the fields) and an on_submit block (handling the update).
custom_action name: 'assign_user', display_name: 'Assign User', verb: 'post', route_type: 'member',
icon_name: 'fa-regular fa-user', display_type: :form_modal,
path: ':id/assign_user',
modal_configuration: { title: 'Select User', confirmation_text: 'Assign' } do
form do
cm_section '' do
alert_box body: 'This will assign a new user to the demo form.', type: :info
form_field :user_id, input_type: :radio_button_group, helper_method: :select_options_for_user, label: 'User'
end
end
on_submit do
@demo_form = ::DemoForm.find(params[:id])
@demo_form.update!(user_id: params.dig(:demo_form, :user_id))
@demo_form
end
end
Note: For
:form_modaland:form_page, theformblock is mandatory. Submitted params are nested under the model name, e.g.params[:demo_form][:user_id].
Form page actionβ
Renders a dedicated page containing the form instead of a modal. Declare the fields in a form block and handle the submit in on_submit. The action itself is a GET route that renders the page; submitting hits an auto-generated <name>_update action with the given verb and path.
custom_action name: 'quick_edit', display_name: 'Quick Edit',
page_title: 'Quick Edit Form', page_description: 'Update the demo form details',
route_type: 'member', verb: 'post',
icon_name: 'fa-regular fa-pen-to-square', path: ':id/quick_edit',
display_type: :form_page do
form do
cm_section '' do
form_field :name, input_type: :string, label: 'Form Name'
form_field :status, input_type: :single_select,
helper_method: :select_options_for_demo_form_status, label: 'Status'
form_field :description, input_type: :text, label: 'Description'
end
end
on_submit do
@demo_form = ::DemoForm.find(params[:id])
@demo_form.update!(name: params.dig(:demo_form, :name),
status: params.dig(:demo_form, :status),
description: params.dig(:demo_form, :description))
@demo_form
end
end
Collection actionβ
Use route_type: 'collection' for actions that operate on the whole collection rather than a single record. These paths do not include :id.
custom_action name: 'export_all', display_name: 'Export All', route_type: 'collection', verb: 'get',
icon_name: 'fa-regular fa-download', path: 'export_all',
display_type: :button do
::DemoForm.all
end
Styled actionβ
Customize the icon appearance with icon_style.
custom_action name: 'styled_action', display_name: 'Styled Action', route_type: 'member', verb: 'post',
icon_name: 'fa-regular fa-palette',
icon_style: '--fa-primary-color: #ff6b6b; --fa-secondary-color: #4ecdc4;',
path: ':id/styled_action', display_type: :button do
demo_form = ::DemoForm.find(params[:id])
demo_form
end
Custom success and error messagesβ
success_message and error_message are lambdas that return an alert Hash with :header, :body, and :icon keys. success_message receives the record; error_message receives the record and its errors. Any key you omit falls back to a sensible default.
custom_action name: 'approve', display_name: 'Approve', route_type: 'member', verb: 'patch',
icon_name: 'fa-regular fa-circle-check', path: ':id/approve',
display_type: :button,
success_message: lambda { |demo_form|
{ header: 'Approved', body: "#{demo_form.name} was approved.", icon: 'fa fa-check-circle' }
},
error_message: lambda { |_demo_form, errors|
{ header: 'Approval failed', body: errors.full_messages.to_sentence, icon: 'fa fa-circle-xmark' }
} do
demo_form = ::DemoForm.find(params[:id])
demo_form.approved!
demo_form
end
Relatedβ
- Group Action β group multiple custom actions under a common heading.
- Bulk Action β run an action across multiple selected records.
- Adding Alert β configure success and error alerts.