Rear will automatically detect and handle all columns defined by your model and allow you to fine-tune them.

Column Types

Following types will be handled automatically:

- :string
- :text
- :date
- :time
- :datetime
- :boolean

Following types should be set manually:

- :rte - rich text editor, aka WYSIWYG editor
- :radio
- :checkbox
- :select
- :password

To define a column of specific type, use column method with column name as first argument and type as second:

class Foo < ActiveRecord::Base
  # ...
end

Rear.register Foo do
  column :content, :ckeditor
end

Manually setting columns makes sense only when you need to use a custom type or/and add some extra opts, like HTML attributes or a fine-tuning block.

[ contents ↑ ]

Columns Label

By default Rear will use capitalized column name as label for pane and editor pages.

To have a custom label, use :label option or label method inside block:

  column :date, label: 'Select date please'
  # or
  column :date do
    label 'Select date please'
  end

[ contents ↑ ]

Radio/Checkbox/Select Columns

These types of columns requires a block to work properly.

Options can be provided via options method.

It accepts a Hash or Array.

When stored keys and displayed values are the same, use an Array:

column :color, :select do
  options 'Red', 'Green', 'Blue'
end

When stored keys are different from displayed values, use a Hash:

column :color, :radio do
  options 'r' => 'Red', 'g' => 'Green', 'b' => 'Blue'
end

Radio and single Select columns will send a String to your ORM.

Checkbox and multiple Select columns will send an Array.

If your ORM does not handle arrays automatically, you'll have to use a Rear hook to convert sent Array into a String:

column :color, :checkbox do
  options 'r' => 'Red', 'g' => 'Green', 'b' => 'Blue'
end

on_save do
  params[:color] = params[:color].join(',')
end

Now if say "Red" and "Green" options checked, an "r,g" String will be sent to ORM.

However, now no options will be automatically checked on editor page.

That's because Rear loads "r,g" String from db and does not know how to correctly convert it into array.

We have to pass a block to options method that will have access to item object and should return an array:

column :color, :checkbox do
  options 'r' => 'Red', 'g' => 'Green', 'b' => 'Blue' do
    item.color.split(',')
  end
end

on_save do
  params[:color] = params[:color].join(',')
end

This way we dumping data via a hook and loading it via a block.

[ contents ↑ ]

Rich Text Editors

When you are dealing with columns containing source code you need a specialized editor.

For now, Rear is offering support for CKEditor and Ace editors.

Before using editors you'll have to install and load corresponding gems.

See el-ckeditor and el-ace for details.

Editing HTML using CKEditor:

class MyModel < ActiveRecord::Base
  # ...
end

Rear.register MyModel do
  column :content, :ckeditor
end

CKEditor File Browser

If you need a file browser to pick up images/movies from, set path to files via ckeditor method:

column :content, :ckeditor do
  ckeditor path: '../public/images'
end

When setting image's URL, Rear will remove :path from image's physical path, so if :path was set to /foo/bar, /foo/bar/baz/image.jpg will become /baz/image.jpg in browser.

If your web server is looking for images in /anything/baz/image.jpg, use :prefix option to prepend /anything to image's URL:

column :content, :ckeditor do
  ckeditor path: '../public/images', prefix: '/anything'
end

CKEditor Localization

It is possible to localize CKEditor via lang option:

column :content, :ckeditor do
  ckeditor lang: :de
end

Ace Editor

To make use of Ace editor, set column type to :ace:

Rear.register ModelName do
  column :content, :ace
end

Snippets

If you have a list of snippets you need to insert into edited content, pass them into editor via snippets method.

Both CKEditor and Ace editors will detect passed snippets and enable a dialog allowing you to insert them.

Snippets ca be passed as multiple arguments, as a single array argument or as a proc that returns an array:

column :content, :ckeditor do # or :ace
  snippets '{{ "top-menu" }}', '{{ "left-menu" }}'
  # or
  snippets ['{{ "top-menu" }}', '{{ "left-menu" }}']
  # or
  snippets do
    ['{{ "top-menu" }}', '{{ "left-menu" }}']
  end
end

[ contents ↑ ]

Readonly/Disabled Columns

Sometimes you need some column to be displayed on editor in readonly/disabled mode.

This can be achieved by using options or block:

Using options:

column :visits, readonly: true
# or
column :visits, disabled: true

Using block with readonly! and disabled! methods:

column :visits do
  readonly!
end
# or
column :visits do
  disabled!
end

In both cases readonly/disabled attributes will be added to HTML tag.

Worth to note that readonly status is effective only on existing items.

When creating new items all columns will be editable.

Disabled columns instead will always be disabled, regardless item is new or existing.

If you need to totally exclude some column from editor, set editor option to false:

column :visits, editor: false
# or
column :visits do
  editor false
end

If you need it also excluded from pane pages, set pane option to false:

column :visits, editor: false, pane: false
# or
column :visits do
  editor false
  pane   false
end

[ contents ↑ ]

Ignored columns

When you need to disable some columns use ignored_columns helper.

When passing a list of column names, Rear wont render given columns on pane nor on editor.

Ignore :created_at and :updated_at columns both on pane and editor:

ignored_columns :created_at, :updated_at

To define a list of columns ignored only on pane/editor, use a Hash of options.

Ignore :created_at and :updated_at columns on pane but render on editor:

ignored_columns pane: [:created_at, :updated_at]

[ contents ↑ ]

Organizing Columns by Rows

By default a separate row will be used for each column.

To render N columns on same row, use :row option or row method inside block:

column :meta_title,       row: :Meta
column :meta_discription, row: :Meta
column :meta_keywords,    row: :Meta

# or

row :Meta do
  column :meta_title   
  column :meta_discription
  column :meta_keywords
end

# or use a nameless row

row do
  column :active
  column :published
  column :archived
end

[ contents ↑ ]

Organizing Columns by Tabs

By default all columns will be contained in one tab.

If you need a separate tab for several columns, use tab method with a block:

tab :Meta do
  column :meta_title   
  column :meta_discription
  column :meta_keywords
end

It is also possible to pass tab as option:

column :meta_title,       tab: :Meta
column :meta_discription, tab: :Meta
column :meta_keywords,    tab: :Meta

[ contents ↑ ]

HTML Attributes

When you need to provide extra attributes to column's HTML tag, pass them as options or use html_attrs method inside block:

column :short_text, style: "height: 400px;"

# or

column :short_text do
  html_attrs style: "height: 400px;"
end

When passing attrs as options or via html_attrs method, they will be used on both pane and editor pages.

Use pane_attrs to set attrs used only on pane pages and editor_attrs to set attrs used only on editor pages respectively.

Please Note that on pane pages attrs will be added to the div element containing column value. On editor pages instead, attrs will be added to the input element, being it text, textarea, select, radio etc.

[ contents ↑ ]

Loading Data

By default the column value will be displayed as extracted from db.

If you need to pre-process data before displaying it, use value method with a block.

column :created_at do
  value { item.created_at.strftime('%d %m, %Y') }
end

value method will set loader for both pane and editor pages.

To set loader for either of them use pane_value or editor_value methods:

column :created_at do
  pane_value { item.created_at.strftime('%d %m, %Y') }
end

value wont work on :radio/:checkbox/:select columns, which uses a block passed to options method to load data.

[ contents ↑ ]

Inline Templates

Sometimes you need some column to look different.

This is easily achievable by using template method:

column :preview do
  template { a_tag(:Preview, href: item.url, target: :_blank) }
end

This will display a link rather than a text field.

To apply template only to pane or editor, use pane_template or editor_template instead.

[ contents ↑ ]

Hiding Columns

There are two pages where Rear will display columns - Pane pages and Editor pages.

Pane pages, aka summary pages, will display all available items, with a paginator and filters.

Editor pages, aka CRUD pages, will allow to Create, Edit, Delete a specific item.

By default any column will be displayed on any page.

To hide it on some page, set :pane / :editor option to false:

column :content, pane: false   # long text, do not display on pane pages
column :visits,  editor: false # stat can not be edited

Also a block can be used to setup columns.

In this case pane / editor methods are used with first argument set to false:

column :content do
  pane false
end
column :visits do
  editor false
end

[ contents ↑ ]

Resetting Columns

In case you are not satisfied with columns automatically added by Rear, reset them and start over with your own.

Columns can be reseted by using reset_columns! method:

reset_columns!

[ contents ↑ ]