Bulk Actions
bulk_action adds an action to the toolbar that appears when users select rows on an index page. It runs once per selected record or once for the whole selection.
Quick exampleβ
cm_index do
bulk_action name: "approve", display_name: "Approve", icon_name: "fa-regular fa-circle-check",
display_type: :modal, execution_mode: :individual,
modal_configuration: { title: "Approve Posts", description: "Approve the selected posts?", confirmation_text: "Approve" } do |id|
::Post.find(id).approved!
end
end
Optionsβ
bulk_action(name: nil, display_name: nil, display_if: ->(_) { true }, redirection_url: nil, icon_name: nil, verb: nil, display_type: nil, modal_configuration: {}, route_type: nil, partial: nil, icon_style: nil, execution_mode: :individual, success_message: ->(_arg) { nil }, error_message: ->(_arg) { nil }, alert_type: :banner, &block)
| Name | Type | Default | Description |
|---|---|---|---|
name | String | required | Action name, used in the route. |
display_name | String | name, humanized | Button label. |
execution_mode | Symbol | :individual | :individual calls the block once per selected id; :bulk calls it once with the array of ids. |
display_type | Symbol | nil | :button, :modal, :form_modal or :page. |
modal_configuration | Hash | {} | title, description and confirmation_text of the modal. |
display_if | Proc | ->(_) { true } | Lambda returning whether to show the action. |
verb | Symbol | nil | HTTP verb: :get, :post, :put, :patch or :delete. :form_modal always posts. |
icon_name | String | nil | Font Awesome icon class. |
icon_style | String | nil | Inline icon style. |
redirection_url | String | referrer | Where to go afterwards. |
route_type | String | nil | member or collection. |
partial | String | nil | Partial rendered by the action. |
success_message | Proc | ->(_arg) { nil } | Receives the successful records; returns { header:, body:, icon: }. |
error_message | Proc | ->(_arg) { nil } | Receives the failed records; returns { header:, body:, icon: }. |
alert_type | Symbol | :banner | Success alert style: :banner or :flash. |
execution_mode decides what the block receives: :individual calls it once per selected id; :bulk calls it once with the array of ids.
Raise an error in the block to mark a record (or the whole :bulk run) as failed. In :individual mode a failure stops only that row β the rest still run. Failed rows stay selected and are listed in the error alert with their message; validation errors from save! / update! are shown in full.
Recipesβ
Run the block once per selected recordβ
With execution_mode: :individual (the default), the block is called once for each selected row and receives that row's id. Use it when each record needs its own logic or transaction β one failing row doesn't stop the others:
bulk_action name: "approve", display_name: "Approve", execution_mode: :individual,
icon_name: "fa-regular fa-circle-check", display_type: :modal,
modal_configuration: { title: "Approve Posts", description: "Approve the selected posts?",
confirmation_text: "Approve" } do |id|
post = ::Post.find(id)
raise "Drafts only" unless post.draft?
post.approved!
end
Selecting 5 posts calls the block 5 times. If post #3 isn't a draft, only it is marked failed β the other 4 are still approved, and #3 stays selected with its error in the alert.
Update all selected records in one queryβ
bulk_action name: "archive", display_name: "Archive", display_type: :button, execution_mode: :bulk do |ids|
::Post.where(id: ids).update_all(status: :archived)
end
Ask for input firstβ
With display_type: :form_modal, declare the form in a form block and handle it in on_submit:
bulk_action name: "bulk_status_update", display_name: "Status", icon_name: "fa-light fa-arrow-progress",
display_type: :form_modal, execution_mode: :bulk,
modal_configuration: { title: "Select Status", confirmation_text: "Submit" } do
form do
cm_section "" do
alert_box body: "The selected status will be applied to all chosen tasks.", type: :warning
form_field :status, input_type: :single_select, is_required: true,
helper_method: :select_options_for_task_user_status
end
end
on_submit do |ids|
::Task.where(id: ids).update!(status: params.dig(:task, :status))
end
end
Delete the selected recordsβ
bulk_action name: "bulk_delete", display_name: "Delete", verb: :delete,
icon_name: "fa-regular fa-trash", display_type: :modal,
execution_mode: :bulk,
modal_configuration: { title: "Delete Posts", description: "Are you sure?", confirmation_text: "Delete" } do |ids|
::Post.where(id: ids).destroy_all
end
Redirect after the actionβ
redirection_url overrides the default (back to the index page):
bulk_action name: "publish", display_name: "Publish", display_type: :button,
execution_mode: :bulk, redirection_url: "/cm_admin/posts" do |ids|
::Post.where(id: ids).update_all(status: :published)
end
Custom success messageβ
bulk_action name: "approve", execution_mode: :individual,
success_message: ->(records) { { header: "Approved", body: "#{records.size} posts approved." } } do |id|
::Post.find(id).approved!
end
Custom error messageβ
error_message receives the failed records and returns { header:, body:, icon: }. A custom body replaces the default list of failed rows and their messages, so include the reason in your text if you want it shown:
bulk_action name: "approve", execution_mode: :individual,
error_message: ->(records) {
{ header: "Approval failed",
body: "#{records.size} post(s) could not be approved β check the selected rows for the reason.",
icon: "fa fa-circle-xmark" }
} do |id|
post = ::Post.find(id)
raise "Already published" if post.published?
post.approved!
end