Columns
column adds a column to an index page or an association tab. all_db_columns adds one for every database column.
Quick exampleβ
cm_index do
column :title
column :status, field_type: :badge, badge_class: { draft: "cm-badge-yellow", published: "cm-badge-green" }
column :author_name, header: "Author"
column :created_at, field_type: :date, format: "%d %b, %Y"
end
Optionsβ
column(field_name, options = {})
| Name | Type | Description |
|---|---|---|
field_name | String | The name of the field. |
field_type | Symbol | The type of field. Can be :association, :attachment, :badge, :boolean, :color_picker, :custom, :date, :datetime, :decimal, :drawer, :enum, :image, :integer, :link, :link_to_email, :link_to_phone, :money, :money_with_symbol, :rich_text, :string, or :text. |
header | String | The header of the field. |
format | String | The format of the field for date fields. |
prefix | String | Prefix to display before the field value. |
suffix | String | Suffix to display after the field value. |
exportable | Boolean | Whether the column is exportable. Default is true. |
round | Integer | Number of decimal places to round numeric values to. |
height | Integer | The height of the field for image fields. |
width | Integer | The width of the field for image fields. |
cm_css_class | String | CSS class to apply to the column. |
link | Boolean | Whether to render the field as a link. |
url | String | Custom URL for the link field. |
link_text | String | Custom text to display for the link. |
custom_method | Symbol | Custom method to call on the record for the field value. |
helper_method | Symbol | The helper method for the field. Should be defined in custom_helper.rb and will take two arguments: record and field_name. |
export_method | Symbol | The export method for the field. Should be defined in the model and will take no arguments. |
managable | Boolean | Whether the column is managable (can be shown/hidden by the user). Default is true. |
lockable | Boolean | Whether the column is lockable (always visible). Default is false. |
viewable | Boolean | Whether the column is visible when the table first loads. When false, the column is hidden by default but still listed under Hidden in the Manage Columns panel, so users can enable it; the choice persists with their column preferences. Default is true. |
drawer_partial | String | Partial path for drawer field type. |
badge_class | Hash | Badge classes for the field. Values must be cm-badge-* classes (see Status Tags). Example: { approved: 'cm-badge-green', draft: 'cm-badge-yellow', rejected: 'cm-badge-red' }. |
badge_helper_texts | Hash | Helper texts for badge fields, shown as a tooltip icon next to the badge. Example: { approved: 'Reviewed by admin', rejected: 'Check rejection reason' }. Default: {}. |
display_if | Proc | A lambda that takes the current object and returns true or false. |
association_name | Symbol | Name of the association for field_type: :association. |
association_type | Symbol | Type of the association (:belongs_to, :has_one, :has_many). |
add_to_filter | Boolean | Whether to add this column to filters. Default is true. |
card_image | Boolean | Whether this column is the card image for card/kanban view. Default is false. |
card_title | Boolean | Whether this column is the card title for card/kanban view. When no column is marked as the title, the first column is used as the title. Default is false. |
card_footer | Boolean | Whether this column is the card footer for card/kanban view. Default is false. |
no_wrap | Boolean | Whether to wrap the content of the field or not. Default is false. |
display_as_local_time | Boolean | Whether to display datetime fields in the user's local time using the local_time helper. When false, the datetime is formatted server-side using strftime. Default: true. |
timezone | String, Symbol, Proc | Timezone to use when displaying :datetime fields. A String is used as a timezone name (e.g. 'Asia/Kolkata'), a Symbol calls a helper method from custom_helper.rb with (record, field_name), and a Proc receives the record and returns the timezone string. Overrides display_as_local_time. |
Recipesβ
Badges and enumsβ
column :status, field_type: :badge, badge_class: { draft: "cm-badge-blue", published: "cm-badge-green" },
badge_helper_texts: { draft: "Not visible yet", published: "Live on the site" }
column :duration_type, field_type: :enum # titleizes the stored enum value
Images, attachments and drawersβ
column :cover, field_type: :image, height: 40, width: 60
column :document, field_type: :attachment
column :notes, field_type: :drawer # truncated text + a "View" button that opens a drawer
Linksβ
column :website_url, field_type: :link, link_text: "Visit site"
column :download_url, field_type: :link, link_text: :download_link_text # Symbol calls a helper
Money, numbers and booleansβ
column :salary, field_type: :money
column :price, field_type: :money_with_symbol
column :rating, field_type: :decimal, round: 1
column :is_featured, field_type: :boolean
Hide a column until the user enables itβ
column :internal_notes, viewable: false
The column is listed under Hidden in the Manage Columns panel, and the user's choice is saved with their column preferences.
Keep a column always visibleβ
column :id, lockable: true
Call a method on the recordβ
column :applicant, custom_method: :user_full_name
Render a value with a helperβ
column :amount, field_type: :custom, helper_method: :format_currency
app/helpers/cm_admin/custom_helper.rb
def format_currency(record, field_name)
number_to_currency(record.send(field_name))
end
Show datetimes in a fixed timezoneβ
column :starts_at, field_type: :datetime, timezone: "Asia/Kolkata"
column :starts_at, field_type: :datetime, timezone: ->(record) { record.user.timezone }
Control export and filteringβ
column :internal_token, exportable: false
column :full_address, export_method: :exportable_address # method on the model used in CSVs
column :computed_total, add_to_filter: false # skip the auto-generated filter
Style a column's cellsβ
column :long_title, no_wrap: true
column :status, cm_css_class: "status-cell"
Card and kanban viewsβ
Mark the columns that fill the card slots when view_type is :card or the kanban board is on:
column :cover, field_type: :image, card_image: true
column :title, card_title: true
column :created_at, field_type: :date, card_footer: true
Add every database columnβ
all_db_columns(exclude: ["id"]) # all_db_columns(options = {})