Skip to main content

Index Page

cm_index configures the paginated listing of a model. It wraps every column, filter and sort option shown on that page.

Quick example​

cm_index do
page_title "Posts"
filter %i[title], :search, placeholder: "Search"
sort column: "created_at", display_name: "Created At", default: true, default_direction: "desc"

column :title
column :status, field_type: :badge, badge_class: { draft: "cm-badge-yellow", published: "cm-badge-green" }
column :created_at, field_type: :date, format: "%d %b, %Y"
column :updated_at, field_type: :date, format: "%d %b, %Y", header: "Last Updated At"
end

Options​

cm_index(display_name: nil, page_title: nil, page_description: nil, partial: nil, view_type: :table)
NameTypeDefaultDescription
display_nameStringnilDisplay name of the page.
page_titleStringModel name, pluralizedPage title.
page_descriptionStringnilText below the title. See Page header.
partialStringnilRender this partial instead of the default page.
view_typeSymbol:table:table, :card or :kanban.

Inside the block you can use:

MethodDescription
column / all_db_columnsColumns of the listing. See Columns.
filterFilters. See Filters.
sortSort options. See Sorting.
kanban_viewGroup a :kanban view by a column. See below.
scope_listModel scopes always applied to this listing. See below.
eager_load_associationsPreload associations to avoid N+1 queries. See below.
custom_action, bulk_actionActions on the listing. See Actions.

View types​

View typeUse it for
:tableDefault table layout with pagination.
:cardMedia-rich models. Mark columns with card_title, card_image and card_footer.
:kanbanA board grouped by a status-like column. Needs kanban_view.

Recipes​

Kanban board​

cm_index view_type: :kanban do
kanban_view "status" # kanban_view(column_name, exclude: [], only: [])
column :name, card_title: true
column :status, field_type: :badge, badge_class: STATUS_TAG_COLOR
end

The column must be an enum: each enum key becomes a board column. Pass enum keys (as strings) to only: to keep just those columns, or to exclude: to drop some (only: wins when both are set).

Card view​

cm_index view_type: :card do
column :cover, field_type: :image, card_image: true
column :title, card_title: true
column :status, field_type: :badge, badge_class: STATUS_TAG_COLOR
column :created_at, field_type: :date, card_footer: true
end

When no column sets card_title, the first column is used.

Always apply model scopes​

scope_list chains the given model scopes onto this listing (and its record counts). To scope every action of a model, use default_scopes in the cm_admin block instead.

cm_index do
scope_list %i[active not_archived]
end

Avoid N+1 queries​

cm_index do
eager_load_associations %i[author category]
column :author_name
end

cm-admin registers these through ar_lazy_preload instead of includes: each association is loaded for every returned record in one query the first time it is accessed. To skip declaring them at all, enable auto-preload in the host app. Every accessed association is then preloaded for the whole relation, at the cost of sometimes preloading an association only one record needs.

config/initializers/ar_lazy_preload.rb
ArLazyPreload.config.auto_preload = true