-
Notifications
You must be signed in to change notification settings - Fork 330
API: Column
A list of actions enabled for singular association columns. Removing an action from the list disables showing links to that action in lists. Possible values are :new, :edit, :show and :list. 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]
Whether to enable add_existing for this column when is used as a subform
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.
A boolean for whether shows the number of associated records when all associated records aren’t shown. Defaults to true.
For association columns, lets you specify the reverse association name in case ActiveScaffold is unable to guess itself. For more information see the API: Nested.
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 = :average
Clears out any existing link, and prevents ActiveScaffold from automatically adding a nesting link.
config.columns[:owned_by].clear_link
Defines whether the column initializes in a collapsed state. Currently collapsing is only supported for association columns on the Create/Update forms.
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. You can set a proc, which will get 2 arguments, column_value and record, but proc only will be used in List.
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.
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:
:boolean
renders a select box with true
and false
options (default for boolean type columns which can be null since v2.4+, previously default for all boolean type columns)
:calendar_date_select
(this requires the calendar date select plugin, again plugin specifics can be passed via the Column#options hash, when plugin is installed is used for date and datetime columns by default)
:checkbox
renders a checkbox (default for boolean type columns which can’t be null since v2.4+)
:chosen
renders a select using chosen library. Accepts the same options as :select form_ui, except :draggable_lists. You need to add chosen to Gemfile, assets will be added by ActiveScaffold.
:country
(accepts :priority
in the Column#options hash)
:date_picker
(this requires the jquery datepicker, again datepicker specific options can be passed via the Column#options hash, when jquery-ui-rails is installed is used for date and datetime columns by default). To format input use locale: date.formats.default
datetime_picker
same as date_picker, but with time controls. Format input with locale time.formats.picker
:paperclip
(this requires the paperclip gem; when gem is installed, it is used for paperclip columns by default)
:password
:record_select
for associations only, renders a text box to search.
: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 associations:
- :label_method with method name (as symbol) to use instead of :to_label
- 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:
config.columns[:name].options = {:include_blank => 'some text'}
- the :optgroup in options hash will be used to build a grouped options
- For plural associations:
- :draggable_lists to show two lists, one with available options and the other with selected options; users select them with drag and drop instead of checkboxes.
config.columns[:name].options = {:draggable_lists => true}
- :draggable_lists to show two lists, one with available options and the other with selected options; users select them with drag and drop instead of checkboxes.
- For other columns:
- a hash with:
- options hash or nested array under options key
config.columns[:name].options = {:options => [['some text', 'some value'], ['another text', 'another value']]}
- options array under options key, array elements will be used as values and texts, symbols will be translated to use as texts:
config.columns[:name].options = {:options => [:some_value, :another value]}
#translation en: activerecord: attributes: model_name: some_value: "Some translated value" another_value: "Another translated value"
<option value="some_value">Some translated value</option> <option value="another_value">Another translated value</option>
- html options hash under html_options key
config.columns[:name].options = {:html_options => {:onchange => 'some javascript code'}}
- options for the select rails method
config.columns[:name].options = {:include_blank => 'some text'}
- options hash or nested array under options key
- a hash with:
:radio
You can define options the same way as :select
:text_editor
(this requires the tinymce-rails gem for rails >= 3.1 or tiny_mce for rails < 3.1)
- The default TinyMCE configuration can be modified via the
:tinymce
Column#options hash. Any configuration options that can be passed via the JavascripttinyMCE.init({ ... })
may be passed as options
active_scaffold :product do |conf| conf.columns[:description_html].form_ui = :text_editor conf.columns[:description_html].options = { :tinymce => { :theme => '<theme_name>', :editor_css => '/product_editor.css' } } end
:textarea
(accepts :cols
and :rows
in the Column#options hash)
:usa_state
(accepts :priority
in the Column#options hash)
Since 3.3.0 version, there are available some of the HTML5 form controls:
:email
renders text input field, in which modern browsers will accept only well-formed email addresses (old browsers will treat it as simple text input).
:url
renders text input field, in which modern browsers will accept only well-formed URLs.
:telephone
renders text input field, in which modern browsers will accept only well-formed phone numbers.
:number
in modern browsers will be rendered as spinbox control, that allows only numbers. If there is numericality validators in model for that column, the max
, min
and step
attributes will be set automatically, according to them (They can be overriden or manually set in the Column#options hash). In old browsers will be treated as usual text input.
:slider
is same as :number
, but will be rendered as a slider control.
Some examples and screenshots available on appropriate pull request page .
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
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 some form_ui, such as :record_select or :chosen.
active_scaffold :users do | config |
config.columns[:title].inplace_edit = true # uses JS to show string field, or copy from UI from list header, same UI for each row, no AJAX request
config.columns[:title].inplace_edit = :ajax # uses JS request to render UI in the server
end
Enable updating columns, row or table after updating the column with in_place_editor. Default is nil, which will update only the column,
Possible values are:
-
:columns
to update some columns, defined withupdate_columns
attribute. If some column has update_columns, they will be updated too, avoiding circular dependencies. -
:row
to update the row. It must be used if action_links can change after updating the column, for example due to permission checks. -
:table
to update the table.
active_scaffold :users do | config |
config.columns[:status].inplace_edit_update = :row # refreshes the whole row
config.columns[:favorite].inplace_edit_update = :table # refreshes the whole table
config.columns[:approve_reason].inplace_edit_update = :columns # refreshes the columns defined in next line
config.columns[:approve_reason].update_columns = [:approved_at] # refreshes the columns defined in next line
end
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.
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)
Html options for text input fields, and options for some form interfaces (see Column#form_ui and Column#list_ui methods).
options[:format] can be set for:
- date and time columns, and it will be used as the format argument of I18n.localize to format them.
- number columns, it can be i18n_number (set by default), currency, percentage or size. i18n_number will use number_with_delimiter, other options will use number_to_currency, number_to_percentage or number_to_human_size. Options for these helpers can be set in options[:i18n_options].
Specifies a placeholder for HTML input
tag in create/update actions. Could replace or be used together with description.
If you don’t set a text, it will use the key activerecord.placeholder.model_name.column_name
to search a placeholder translation. Examples available on appropriate pull request page .
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. If it’s true, the required
attribute on HTML input
tag will be set and modern browsers won’t allow user to send form unless this column is filled.
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. Since 3.2.13 you can set an array with multiple left sides, and conditions will be OR’ed.
# 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"
# good since 3.2.13. this will get turned into "WHERE first_name = ? OR last_name = ?"
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 .
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
, :multi_select
or :record_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
.
:select
Since v2.4+, accepts :html_options => {:multiple => true}
in the Column#options and renders a list box to search with multiple options
:record_select
Since v2.4+, accepts :multiple => true
in the Column#options and allows to search with multiple options
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
:datetime
, :date
, :time
: to search by date and time range
:range
(:integer
, :decimal
, :float
, :string
): for range comparisons, used by default for numeric and string type columns. Allows to search for strings with contains some text or begins or ends with some text too, enabled for :string type columns v2.4+, to enable that comparators for other columns, such as associations, set options[:string_comparators]
; allows to search for null and non-null colums for columns which can be null, this behaviour can be changed setting options[:null_comparators]
: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)
WARNING Before v3.2.20 this method was named select_columns, added on 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_associated_columns = [:name]
What columns load from main table when [API: List]#auto_select_columns is enabled. By default is the own column for real columns and foreign key for belongs_to associations. Must be an array or nil.
# Turn off column selection
config.columns[:association_column].select_columns = nil
# Select two columns
config.columns[:association_column].select_columns = ['name, surname']
Send all the form instead of single value when this column changes.
You can set options[:send_form_selector]
to filter which fields are sent.
Also, you can set to :row
and it will send only the row of the associated record instead of whole form, when column is in a subform.
Sets the action link for this column. Currently used only in List. See API: Action Link 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 .
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
A boolean for whether this column is sortable or not. Defaults to false for virtual columns.
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 multiple DB columns, more efficient than SQL expression becuase it can use indexes
# _(only since 3.2)_
columns[:name].sort_by :sql => ['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.
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.
In newer versions replaced with update_columns
The column to be updated in a form when this column changes.
The columns to be updated in a form when this column changes. If some column has update_columns, they will be updated too, avoiding circular dependencies.
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.