Skip to main content

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)
NameTypeDefaultDescription
nameStringrequiredAction name, used in the route.
display_nameStringname, humanizedButton label.
execution_modeSymbol:individual:individual calls the block once per selected id; :bulk calls it once with the array of ids.
display_typeSymbolnil:button, :modal, :form_modal or :page.
modal_configurationHash{}title, description and confirmation_text of the modal.
display_ifProc->(_) { true }Lambda returning whether to show the action.
verbSymbolnilHTTP verb: :get, :post, :put, :patch or :delete. :form_modal always posts.
icon_nameStringnilFont Awesome icon class.
icon_styleStringnilInline icon style.
redirection_urlStringreferrerWhere to go afterwards.
route_typeStringnilmember or collection.
partialStringnilPartial rendered by the action.
success_messageProc->(_arg) { nil }Receives the successful records; returns { header:, body:, icon: }.
error_messageProc->(_arg) { nil }Receives the failed records; returns { header:, body:, icon: }.
alert_typeSymbol:bannerSuccess 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