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)
| Name | Type | Default | Description |
|---|---|---|---|
display_name | String | nil | Display name of the page. |
page_title | String | Model name, pluralized | Page title. |
page_description | String | nil | Text below the title. See Page header. |
partial | String | nil | Render this partial instead of the default page. |
view_type | Symbol | :table | :table, :card or :kanban. |
Inside the block you can use:
| Method | Description |
|---|---|
column / all_db_columns | Columns of the listing. See Columns. |
filter | Filters. See Filters. |
sort | Sort options. See Sorting. |
kanban_view | Group a :kanban view by a column. See below. |
scope_list | Model scopes always applied to this listing. See below. |
eager_load_associations | Preload associations to avoid N+1 queries. See below. |
custom_action, bulk_action | Actions on the listing. See Actions. |
View typesβ
| View type | Use it for |
|---|---|
:table | Default table layout with pagination. |
:card | Media-rich models. Mark columns with card_title, card_image and card_footer. |
:kanban | A 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.
ArLazyPreload.config.auto_preload = true
Relatedβ
- Show page
- Saved views: let users save filters, sort and columns
- Importer: CSV import from the listing