Skip to main content

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 = {})
NameTypeDescription
field_nameSymbolThe name of the field (usually a model attribute or method).
field_typeSymbolThe 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.
labelStringCustom label for the field. Defaults to titleized field name.
label_methodSymbolMethod to call on the association for displaying the label.
formatStringFormat string for date/time fields (e.g., '%d %b, %Y').
precisionIntegerDecimal precision for numeric fields. Default: 2.
widthIntegerWidth for image fields. Default: 50 for images.
heightIntegerHeight for image fields. Default: 50 for images.
helper_methodSymbolCustom helper method defined in custom_helper.rb. Receives record and field_name as arguments.
previewBooleanEnable preview for the field.
link_textString, SymbolText for link, if Symbol is used, it will be method called from custom_helper.rb.
prefixStringPrefix to prepend to the field value.
suffixStringSuffix to append to the field value.
badge_classHashBadge classes for :badge fields. Values must be cm-badge-* classes. Example: { approved: 'cm-badge-green', draft: 'cm-badge-yellow' }. Default: {}.
badge_helper_textsHashHelper texts for badge fields, shown as a tooltip icon next to the badge. Example: { approved: 'Reviewed by admin', rejected: 'Check rejection reason' }. Default: {}.
display_ifProcLambda that takes the current object and returns boolean to conditionally display the field. Default: ->(_arg) { true }.
association_nameSymbolName of the association for association fields.
association_typeSymbolType of association (:belongs_to, :has_one, :polymorphic).
col_sizeIntegerColumn size in grid layout.
display_as_local_timeBooleanWhether 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.
timezoneString, Symbol, ProcTimezone 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

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'