Show Fields
field displays one value inside a cm_section of a show page.
Quick exampleβ
cm_section "Details" do
field :title
field :created_at, field_type: :date, format: "%d %b, %Y"
field :status, field_type: :badge, badge_class: { approved: "cm-badge-green", draft: "cm-badge-yellow", rejected: "cm-badge-red" }
end
Optionsβ
field(field_name, attributes = {})
| Name | Type | Description |
|---|---|---|
field_name | Symbol | The name of the field (usually a model attribute or method). |
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. Default: :string. |
label | String | Custom label for the field. Defaults to titleized field name. |
label_method | Symbol | Method to call on the association for displaying the label. |
format | String | Format string for date/time fields (e.g., '%d %b, %Y'). |
precision | Integer | Decimal precision for numeric fields. Default: 2. |
width | Integer | Width for image fields. Default: 50 for images. |
height | Integer | Height for image fields. Default: 50 for images. |
helper_method | Symbol | Custom helper method defined in custom_helper.rb. Receives record and field_name as arguments. |
preview | Boolean | Enable preview for the field. |
link_text | String, Symbol | Text for link, if Symbol is used, it will be method called from custom_helper.rb. |
prefix | String | Prefix to prepend to the field value. |
suffix | String | Suffix to append to the field value. |
badge_class | Hash | Badge classes for :badge fields. Values must be cm-badge-* classes. Example: { approved: 'cm-badge-green', draft: 'cm-badge-yellow' }. Default: {}. |
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 | Lambda that takes the current object and returns boolean to conditionally display the field. Default: ->(_arg) { true }. |
association_name | Symbol | Name of the association for association fields. |
association_type | Symbol | Type of association (:belongs_to, :has_one, :polymorphic). |
col_size | Integer | Column size in grid layout. |
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β
Image fieldβ
field :avatar, field_type: :image, height: 80, width: 80
Badge, enum and boolean valuesβ
field :status, field_type: :badge, badge_class: { approved: "cm-badge-green", draft: "cm-badge-yellow" },
badge_helper_texts: { rejected: "Check the rejection reason" }
field :duration_type, field_type: :enum # titleizes the stored enum value
field :is_featured, field_type: :boolean
Money and numbersβ
field :salary, field_type: :money
field :price, field_type: :money_with_symbol
field :rating, field_type: :decimal, precision: 1
Linksβ
field_type: :link renders the field's value (a URL) as an external link. link_text sets the anchor text β a String, or a Symbol naming a helper that returns it:
field :website_url, field_type: :link, link_text: "Visit site"
field :download_url, field_type: :link, link_text: :download_link_text
field :contract, field_type: :attachment # preview/download of an ActiveStorage file
Drawerβ
field :notes, field_type: :drawer # truncated text + a "View" button that opens a side drawer
Rich text and colorβ
field :content, field_type: :rich_text
field :theme_color, field_type: :color_picker
Datetimesβ
field :starts_at, field_type: :datetime, timezone: "Asia/Kolkata"
field :starts_at, field_type: :datetime, timezone: ->(record) { record.user.timezone }
field :updated_at, field_type: :datetime, display_as_local_time: false, format: "%d %b, %Y %H:%M"
Email and phone fields (adds a copy-to-clipboard button)β
field :email, field_type: :link_to_email
field :phone, field_type: :link_to_phone
Field with prefix and suffixβ
field :price, prefix: '$', suffix: 'USD'
Field rendered by a helperβ
field_type: :custom sends the field to a helper in custom_helper.rb that returns HTML:
field :preview, field_type: :custom, helper_method: :blog_post_preview_link, label: "Preview"
app/helpers/cm_admin/custom_helper.rb
def blog_post_preview_link(record, _field_name)
link_to "Preview", "/blog/#{record.slug}", target: "_blank", data: { turbo_frame: "_top" }
end
Conditional field displayβ
field :admin_notes, display_if: ->(record) { record.admin_visible? }
Field with Associationβ
Belongs to association (works for :belongs_to and :has_one)β
field :title, field_type: :association, association_name: :parent, association_type: :belongs_to,
label: 'Parent Task'
Polymorphic associationβ
field [{ post: 'title', user: 'full_name' }], field_type: :association, association_name: :commentable,
association_type: :polymorphic, label: 'Commented on'
Relatedβ
- Columns and Form fields
- Nested form fields: list a
has_manyassociation on the show page - Status badges