API: Column

associated_limit global local v1.2

The number of associated records to show. If there are more associated records, a ellipsis (“…”) will be added and the number of associated records will be shown if associated_number is enabled. Set to nil to show all associated records. Defaults to 3.

associated_number global local v1.2

A boolean for whether shows the number of associated records when all associated records aren’t shown. Defaults to true.

actions_for_association_links global local v2.2

A list of actions enabled for singular association columns, removing an action from it, disable showing links to that action in lists. Defaults to [:new, :edit, :show].

# Disable :new globally
ActiveScaffold::DataStructures::Column.actions_for_association_links.delete :new
# Only shows links to show in user column
config.columns[:user].actions_for_association_links = [:show]

calculate

Defines a calculation on the column. Anything that ActiveRecord::Calculations::ClassMethods#calculate accepts will do. Only works on real columns.

Examples:

config.columns[:price].calculate = :sum
config.columns[:price].calculate = :avg

clear_link v1.1

Clears out any existing link, and prevents ActiveScaffold from automatically adding a nesting link.

collapsed

Defines whether the column initializes in a collapsed state. Currently collapsing is only supported for association columns on the Create/Update forms.

css_class

An extra css class to apply to this column. Currently used in List and Create/Update forms. In lists is added to TD tag, and in forms is added to DL tag, so you can set css for labels and fields.

description

A short description or example text. Currently used in Update/Create.

config.columns[:name].description = "Enter the users first and last name"

If you don’t set a text, it will use the key activerecord.description.model_name.column_name to search a description translation.

form_ui v1.1

If a column has multiple supported form interfaces, you may pick an option here. The options depend on the column type.

Association columns, by default renders the whole subform that lets you actually create/update associated records.

You may pick:

:calendar_date_select (this requires the calendar date select plugin, again plugin specifics can be passed via the Column#options hash )

:checkbox (useful for boolean type columns)

:country (accepts :priority in the Column#options hash)

:password

:select for associations renders a select box (singular associations) or a collection of checkboxes (plural associations), for other columns renders a select box.
Valid options:

• For singular associations:
  • a hash with html options, all keys will be added as tag attributes
  • a hash with options for the select rails method, html options must be added in a hash under html_options key to enable this feature:
    config.columns[:name].options = {:include_blank => 'some text', :html_options => {}}
• For plural associations:
  • draggable_lists to show two lists with available options and selected options to select them with drag and drop instead of checkboxes.
• For other columns:
  • a hash with:
    • options array under options key
    • html options hash under html_options key
    • options for the select rails method
  • a options array for backward compatibility, html options and options for rails method can’t be set in this case

:text_editor (this requires the tiny_mce plugin)

:textarea (accepts :cols and :rows in the Column#options hash)

:usa_state (accepts :priority in the Column#options hash)

includes

An array of associations for eager loading that are relevant for this column. For association columns, defaults to the association itself. This is especially useful with virtual columns. Consider the following example:

# last_transaction_date is a virtual column that references a joined field 

active_scaffold :users do | config |
  config.columns = [:name, :last_transaction_date, :status]  
  config.columns[:last_transaction_date] = "Last transaction date"
  config.columns[:last_transaction_date].includes = [:user_transactions]
  config.columns[:last_transaction_date].sort_by :sql => "user_transactions.created_at"
end

inplace_edit v1.1

Enable in_place_editor for this column (true, :ajax or false). Defaults to false. Validation errors are reported via page.alert.

Since v2.3:

• For columns with form_ui or form override, it will copy the fields from a hidden template in the column header instead of use the default InPlaceEditor.
• If inplace_edit is set to :ajax, an AJAX request will be made to get the field, that option is needed for in place editing with RecordSelect.

label

The displayable name.

config.columns[:created_at].label = "How Old"

If you don’t set the label, it will use the key activerecord.attributes.model_name.column_name to search a label translation.

list_ui v1.1

If a column has a special presentation you may pick an option here. Form_ui is used if list_ui is not specified and it exists such list_ui. You may pick:

:checkbox (useful for boolean type columns)

:text (used automatically in text type columns, accepts :truncate in the Column#options hash to set truncate length, default is 50)

options

Html options for text input fields, and options for some form interfaces (see Column#form_ui and Column#list_ui methods).

set_link

Sets the action link for this column. Currently used only in List. See API: Core for options. This link will automatically get the id of the current row, but if you want to put any other dynamic values in the link you’re better off just using a Field Overrides .

required

A boolean for whether the column is required through already-existing validation. Currently used in Update/Create. Defaults to false, but if validation reflection is available it defaults to true for columns with validates_presence_of.

search_sql

The SQL string used when searching on this column. Defaults to the field name of the column (for real columns). This SQL is the left side of a condition, which means that if you want to do something with multiple fields they have to be in a function.

# good. this will get turned into "WHERE name = ?"
config.columns[:name].search_sql = 'name'

# bad. this will get turned into "WHERE first_name OR last_name = ?", which is invalid syntax
config.columns[:name].search_sql = 'first_name OR last_name = ?'

# good. this will get turned into "WHERE CONCAT(first_name, ' ', last_name) = ?"
config.columns[:name].search_sql = "CONCAT(first_name, ' ', last_name)"
#good.  in PostgreSQL for multiple columns
config.columns[:name].search_sql = "first_name||last_name"

Note: After you define the search_sql you may need to add the column to the API: Search .

search_ui v1.1

If a column has multiple supported form interfaces, you may pick an option here for the field search view. The options depend on the column type. Form_ui is used if search_ui is not specified and it exists such search_ui.

For association columns, you may pick :select or :multi_select. :select renders a select box to search for a specific object. :multi_select renders a collection of checkboxes to search for some specific objects. Search_sql must be set as #{table_name}.id.

For all other columns, you may pick:

:calendar (this requires a calendar plugin, again plugin specifics can be passed via the Column#options hash)

:country (accepts :priority in the Column#options hash)

:numeric (for numeric comparisons)

:datetime :date :time (to search by date and time range)

:text (for simple text field. It’s useful when it has a form_ui but you want a simple text field for search view)

:usa_state (accepts :priority in the Column#options hash)

Association columns can use search ui from above to search in some field (setting search_sql)

select_columns local v2.3

What columns load from association table when eager loading is disabled. It’s only used when includes is nil.

# Turn off eager loading
config.columns[:association_column].includes = nil
# Select only the name
config.columns[:association_column].select_columns = [:name]

show_blank_record global local v2.2

Whether to show a blank record in subform or not. When is disabled, you must click in add new to get a blank row. Defaults to true.

# Turn off blank records in all subforms
ActiveScaffold::DataStructures::Column.show_blank_record = false
# And enable blank record to role column
config.columns[:role].show_blank_record = true

sort

A boolean for whether this column is sortable or not. Defaults to false for virtual columns.

sort_by

Lets you define either the SQL used for sorting (defaults to the field name) or a string for method based sorting.

# To sort by an SQL expression
columns[:name].sort_by :sql => 'concat(first_name, last_name)'

# to sort by a Ruby method (notice this is a method on the model you are scaffolding against):
columns[:name].sort_by :method => 'full_name'

# If your method sorting can return nil, then you may need to typecast:
columns[:name].sort_by :method => 'full_name or String.new'

Association columns default to using method-based sorting.

Warning: method-based sorting is slow and resource-intensive. The entire table must be loaded and sorted, which will not scale for large data sets. Try to use sort_by :sql as much as possible.

ui_type v1.0 only

Deprecated: in version 1.1 this is an alias for form_ui. In version 1.2 it will be removed entirely.

If a column has multiple supported form interfaces, you may pick an option here. Currently used for association columns. The default interface lets you not only (dis)associate records, but also edit the associated records. If you just want a simple interface to (dis)associate records, then set ui_type = :select.

weight v1.2

Add a weight to the column to override alphabetical sorting. Columns are sorted from lowest weight to highest one, and columns with same weight are sorted alphabetically. You must assign weights before use @config.#{action}.columns, whenever you call @config.#{action}.columns, columns are sorted and copied from global config to action.