-
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.
It allows to set any setting which is assigned with a setter (most of them) with a hash. For example:
conf.columns[:roles].attributes = {
label: 'Select your roles',
form_ui: [:select, label_method: :name_with_desc],
options: {collapsible: true}
}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 = :averageClears out any existing link, and prevents ActiveScaffold from automatically adding a nesting link.
config.columns[:owned_by].clear_linkDefines 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.
The default value for a DB column, not virtual or association, can be changed in the ActiveScaffold config, overriding the default value defined in the DB. If no value is set, it will return the default value defined in the DB. This default value is used on the create form, new rows added to subforms, but not used for field search, as it doesn’t make sense.
Also, when saving a form with empty value for the column, the DB default will be used, ignoring the default setting in the column. When default_value is not used, and DB has a default and column can’t be null, ActiveScaffold won’t allow to save empty string, it will set the default value. For example, a model with a column action and default value New:
`action` VARCHAR(255) NOT NULL DEFAULT 'New'If the form submits an empty value for it, such as {"record" => {"action" => ""}}, ActiveScaffold will save 'New'. If you want to default to 'New' in the create form, or new rows in a subform, but allow user to save empty string, just don’t set default in the DB, and set default_value in the ActiveScaffold config.
`action` VARCHAR(255) NOT NULL DEFAULT ''conf.columns[:action].default_value = 'New'Returns true if the default value has been set in the ActiveScaffold config. If the column has a default value set in the DB, and no default value is set in the ActiveScaffold config, then it will return false although the column has default value.
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.
There are different form_ui types which may be used for a column. Depending on the column type, it may default to nil, rendering text field, or may default to one of these types. Each type support different options, which may be set in column.options, or can be provided next to the form_ui type since v3.7, in one assignment, and these options will be used instead of column’s options, isolating the options for the form_ui from other column’s options not related to the form_ui, which may pollute the html tag.
config.columns[:roles].form_ui = :select, {label_method: :human_label, draggable_lists: true}These options can be read with form_ui_options method if needed: config.columns[:roles].form_ui_options
Association columns render the whole subform by default, that lets you actually create/update associated records.
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"
endEnable 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
endEnable 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:
-
:columnsto update some columns, defined withupdate_columnsattribute. If some column has update_columns, they will be updated too, avoiding circular dependencies. -
:rowto update the row. It must be used if action_links can change after updating the column, for example due to permission checks. -
:tableto 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
endThe 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.
Label can be set to a proc or lambda to support defining dynamic label in the controller for the form only, although label can be overrided with helpers, different helpers for different situations, see Per Request Configuration for the different available helpers and examples.
config.columns[:password].label = Proc.new { |record, column, scope| record.requires_api_key? ? 'API Key' : 'Password' }When using a proc, the label will use the default value instead of proc when the record is not available, e.g. for horizontal subforms and list header.
There are different list_ui types which may be used for a column. Form_ui is used if list_ui is not specified and it exists such list_ui. Each type support different options, which may be set in column.options, or can be provided next to the list_ui type since v3.7, in one assignment, and these options will be used instead of column’s options, isolating the options for the list_ui from other column’s options not related to the list_ui, which may pollute the html tag.
Since v3.7, the options for the list_ui can be provided next to the list_ui type, in one assignment, and these options will be used instead of column’s options, isolating the options for the list_ui from other column’s options not related to the list_ui, which may pollute the html tag.
config.columns[:description].list_ui = :text, {truncate: 30}These options can be read with list_ui_options method if needed: config.columns[:description].list_ui_options
If no list_ui is defined, and form_ui is defined with options, list_ui_options will return the form_ui_options too, but if list_ui is defined without options, list_ui_options will never return form_ui_options.
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.localizeto format them. - number columns, it can be
:i18n_number(set by default),:currency,:percentageor:size.:i18n_numberwill usenumber_with_delimiter, other options will usenumber_to_currency,number_to_percentageornumber_to_human_size. Options for these helpers can be set inoptions[:i18n_options].
options[:collapsible] can be set to true to allow collapsing the column in Create/Update form, column is never collapsed initially.
options[:tabbed_by] can be set in columns, used when the column is in any subgroup of form action (create or update), and the subgroup is using tabbed_by, so it’s only useful for collection associations.
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, and association_table.primary_key for association 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.
When using field_search, the items in search_sql array can be a hash too, to use a subquery for the condition, with the following structure:
-
subquerykey, required, with an array:- the first element in the array must be the model or ActiveRecord relation used for the subquery. If the relation doesn’t select one column for the subquery, the primary key will be used.
- the next elements are column names or SQL code, like normal items in
search_sql, used for the conditions in the subquery
-
fieldkey, optional, the column name to match with the subquery result -
conditionskey, optional, an array with extra conditions, like the parameters forwheremethod from ActiveRecord.
For example, for a polymorphic association, in a Resume model:
conf.columns[:resume_holder].search_sql = [
{subquery: [User, 'first_name', 'last_name']},
{subquery: [Candidate, 'first_name', 'last_name']}
]Then it would generate a condition when searching for ‘John’ like this:
resume_holder_id IN (SELECT id FROM users WHERE first_name LIKE '%John%' OR last_name LIKE '%John%') AND resume_holder_type = 'User' OR
resume_holder_id IN (SELECT id FROM candidates WHERE first_name LIKE '%John%' OR last_name LIKE '%John%') AND resume_holder_type = 'Candidate'In that example, field key is not needed as the foreign key for the column is used, and conditions key is not needed because it’s generated automatically to match the foreign type of the association. However, if using a virtual column, field will be needed, and conditions may be needed too, depending on the case:
conf.columns[:parent].search_sql = [
{subquery: [User, 'first_name', 'last_name'], field: :resume_holder_id, conditions: ['resume_holder_type = ?', 'User']},
{subquery: [Candidate, 'first_name', 'last_name'], field: :resume_holder_id, conditions: ['resume_holder_type = ?', 'Candidate']}
]In the subquery key, scopes or where can be used, e.g. User.where(disabled: false), or select(:column) to use it instead of :id.
There are different search_ui types which may be used for a column. Form_ui is used if search_ui is not specified and it exists such search_ui, otherwise the form_ui helper will be used, but using `search[field]` instead of `record[field]` in the name attribute. Each type support different options, which may be set in column.options, or can be provided next to the search_ui type since v3.7, in one assignment, and these options will be used instead of column’s options, isolating the options for the search_ui from other column’s options not related to the search_ui, which may pollute the html tag.
If no search_ui is defined, and form_ui is defined with options, search_ui_options will return the form_ui_options too, but if search_ui is defined without options, search_ui_options will never return form_ui_options.
config.columns[:roles].search_ui = :select, {label_method: :human_label}These options can be read with search_ui_options method if needed: config.columns[:roles].search_ui_options
For association columns, if search_ui and form_ui is not set, it defaults to :select, which works with the default search_sql, then it renders a select box to search for a specific object. Also, :multi_select or :record_select (if recordselect gem is available) may work with the default search_sql, :multi_select renders a collection of checkboxes to search for some specific objects. Other search_ui can be used 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 = trueThere are different show_ui types which may be used for a column. List_ui is used if show_ui is not specified and it exists such show_ui, then will check if a show UI exists for the column’s type, otherwise will use the same method used in list. Each show UI support different options, which may be set in column.options, or can be provided next to the show_ui type since v3.7, in one assignment, and these options will be used instead of column’s options, isolating the options for the show_ui from other column’s options not related to the search_ui, which may pollute the html tag.
config.columns[:description].show_ui = :text, {html_options: {class: 'description'}, wrapper_tag: :div}These options can be read with show_ui_options method if needed: config.columns[:description].show_ui_options
If no show_ui is defined, and list_ui is defined with options, show_ui_options will return the list_ui_options too, but if show_ui is defined without options, show_ui_options will never return list_ui_options.
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.