-
Notifications
You must be signed in to change notification settings - Fork 329
API: List
Always show create is an option that will always show the create form while on the list view. If the create action is disabled this option has no affect. It also has no affect on nested views. This option does not display the Create new action link, or the cancel/close option on the create view because the create section is always showing.
Examples:
config.list.always_show_create = trueThe always show search option always show the search form while on the list view. This option has no effect if the search and field_search action is excluded. It will in turn display the corresponding search view, regular search or field search. This option does not display the search action link, and removes the close option from the search container because the search is always showing.
It can be set to :search or :field_search, so that kind of search is always displayed when both searches, search and field_search, are enabled.
Examples:
config.list.always_show_search = trueconfig.actions.swap :search, :field_search
config.actions << :search
config.list.always_show_search = :searchDefines what string to use to join records from plural associations. Defaults to ", ".
When enabled, first page is loaded in first request, then all pages are loaded and displayed by ajax automatically.
Enable it to automatically select only columns included in list. It uses [API: Column]#select_columns for every included column, so virtual columns or columns with field overrides must set select_columns to work. Defaults to false.
It’s called to preload the counts of collection association columns which has empty `includes`, `associated_number` is enabled, and don’t use counter cache. It sets `@counts` instance variable with a hash, indexed by column name, with the result of grouped count query, so counts for an association is got with one SQL query for all records. See Preload Column Counts for an explanation on how it works and how to change the column to count, e.g. adding some conditions to count some records only.
Enable ETag calculation (when conditional_get_support is enabled), it requires to load records for page, when is disabled query can be avoided when page is cached in browser.
It returns a hash with attributes for the <td> tag of a column. It can be overrided, with the same name, or prefixed with the model name as column overrides, defining a per-model helper, e.g. user_column_attributes for User model. The :class key will be overrided with the result of column_class helper, so it must be used to define other html attributes than class.
def user_column_attributes(column, record)
if column == :role && record.role
{title: record.role.description}
else
{}
end
endIt returns the default classes for <td> tag of a column. It can be overrided to add more classes for a record and a column:
def column_class(column, column_value, record)
classes = super
if [:acc_balance, :balance].include? column.name
if record.send(column.name) >= 0
classes << 'debit '
else
classes << 'credit '
end
end
classes
endThe set of columns used for the List action. By default, all but :id, foreign keys, updated/created_on/at columns are inherited from config.columns. You can mandate which columns to inherit from config.columns, and also tell active scaffold which order to display the columns in:
config.list.columns = [:id, :name, :user_id, :created_on]If you want to change the attribute of a column, like the label, you must do in config.columns, which keeps column configuration, config.list.columns only store what columns display and the order.
config.columns[:created_on].label = "How old"Columns with plural associations will be render as a link to nested view.
Columns with singular associations will be render as a link to create when there is no associated record and create is authorized. When the column has an associated record will be linked to the edit view if record is authorized for update, or show view if it’s authorized for read and not for update. If the action is excluded in the association’s controller, column is not linked to that action too. You can control what actions are tried with API: Column#actions_for_association_links.
If a link is set to a column using API: Column#set_link, automatic linking will be ignored for it. You can supress automatic linking for a column using API: Column#clear_link.
If you want to add custom conditions to the find query used by List, then define this method. It may return conditions in string or array syntax. And as an instance method on the controller, it has access to params and session and all the standard good stuff.
Example:
def conditions_for_collection
['user_type IN (?)', ['admin', 'sysop']]
endIf you want to add custom conditions in some columns from associations, you can use conditions_for_collection and you must enable join with the association. You can set includes in the association column (although it’s enabled by default) if it’s included in list columns, or you can add the assocation to active_scaffold_includes, active_scaffold_outer_joins, or override joins_for_collection for a INNER JOIN.
In rails 4, if you use a string condition and you use includes, don’t forget to add the association to active_scaffold_references.
def conditions_for_collection
if params[:admin]
# user has_and_belongs_to_many user_types
self.active_scaffold_includes << :user_types
self.active_scaffold_references << :user_types
['user_types.name IN (?)', ['admin', 'sysop']]
end
enddef conditions_for_collection
if params[:admin]
# we don't need user_types columns, only join to use in where clause
self.active_scaffold_outer_joins << :user_types
['user_types.name IN (?)', ['admin', 'sysop']]
end
endOverrides default includes used for count sql query. Use to speed up query to count records when you need many includes to list records.
If you want to add custom options, e.g. grouping or sorting to the find(:all) used by List, then define this method. It may return hash with symbol keys, such as :reorder, :group, :having, etc. And as an instance method on the controller, it has access to params and session and all the standard good stuff.
Example:
def custom_finder_options
{:reorder => "some_field = #{some_magic_value} DESC, another_field ASC NULLS LAST"}
endDefines what appears when a field is empty. This can be important for columns with links – without some empty field text the link would have no clickable area. Defaults to a single hyphen.
You can set the message displayed when you do a search. Default value is :filtered. You can set a different message symbol to get translated with I18n, or set a text with won’t be translated. Also, you can change text in your locale file.
Active scaffold supports html, js, json, yaml, and xml formats by default. If you need to add another mime type for the list action you can do it here. The format is then added to the default formats.
Examples:
config.list.formats << :pdf
# or
config.list.formats = [:pdf]ActiveScaffold doesn’t display parent column in nested scaffolds. Enable this property so parent column will be displayed when you open a nested scaffold.
You can override this method to add some joins to the list query. It must return an array of symbols, hashes of symbols (which must be associations and you will get a inner join) or join strings, the same arguments accepted by joins method from ActiveRecord.
def joins_for_collection
[:user_types, 'LEFT JOIN customers ON customers.sales_rep_id = users.id']
endThe label of the list. Appears in the table heading.
It can be overrided to change the attributes used in <tr> tag, or add more attributes. It defaults to add id attribute, data-refresh attribute, and class attribute with value “record #{tr_class}”.
Example:
# the Helper for the LedgerController
module LedgerHelper
def list_row_attributes(tr_class, tr_id, data_refresh)
super.merge(...)
end
endSince version “3.2.1”, this helper is defined per-model using the format “_list_row_class”, for example “user_list_row_class”
If you need to customize the CSS class of a <tr> or a <td> tag based on some attribute of the record, then you should define a method in your helper file named list_row_class. This method should return a CSS class. You can then use the custom CSS class, combined with the built-in classes of the columns, to add styles as desired.
Example:
# the Helper for the LedgerController
module LedgerHelper
def list_row_class(record)
record.transaction < 0 ? 'negative' : 'positive'
end
endIn your main.css (or other)
.active-scaffold tr.negative td.amount-column {
background-color: red;
}Display messages above of columns header instead of below of it
config.list.messages_above_header = trueYou can set the message displayed when no items can be found. Default value is :no_entries. You can set a different message symbol to get translated with I18n, or set a text with won’t be translated. Also, you can change text in your locale file.
How many page links around current page to show. Default is 2, so a list with 10 pages showing page 5 will show:
Previous 1 .. 3 4 5 6 7 .. 10 Next
It was named page_links_window until 3.2.5, when was renamed to page_links_inner_window
How many page links around first and last page to show. Default is 0, so a list with 10 pages showing page 5 will show:
Previous 1 .. 3 4 5 6 7 .. 10 Next
What kind of pagination to use:
-
true: The usual pagination -
:infinite: Treat the source as having an infinite number of pages (i.e. don’t count the records; useful for large tables) -
false: Disable pagination
How many records to show on each page. Default is 15.
Include list header when list is refreshed by JS (using refresh_list partial)
You can modify the link displayed to reset a search. It’s a readonly property, but you can change link properties as explained in API: Action Link
If you don’t want ActiveScaffold displays a link to reset search, you can remove disabling this property.
The default sorting for the page. When a user clicks on a column, they override this sorting. On the third click for a column, they reset the sorting back to this value. You can define the sorting either by a shortcut data structure like { :title => :desc } or [{ :title => :desc}, {:subtitle => :asc}], or you can use the methods in the examples below.
The sorting names here refer to columns in config.columns, and when ActiveScaffold tries to actually perform the sorting it will check the column configuration to see whether to use method sorting or sql sorting.
columns that depend on method sorting must load and sort the entire table, and will not scale for large data sets. Try to sort on columns that use sort_by :sql.
Examples:
# default sorting: descending on the title column
config.list.sorting = { :title => :desc }
# default sorting: descending on title, then ascending on subtitle
config.list.sorting = [{ :title => :desc}, {:subtitle => :asc}]
# same thing, but without as much punctuation
config.list.sorting = { :title => :desc }
config.list.sorting.add :subtitle, :ascIf you need more complicated sorting, try to use custom_finder_options controller method, e.g:
protected
def custom_finder_options
{:reorder => "some_field = #{some_magic_value} DESC, another_field ASC NULLS LAST"}
endSet a tag name to get table cells content wrapped in that tag. It allows you for more css styling, for example a background color which doesn’t fill all cell. It won’t wrap inplace editable columns or columns with link, it’s not needed to style them.
config.list.sorting = :spanWould you like to format a number as currency? Or, would you like to format a date a different way? Would you like to combine two fields from your model in one column? If you answer yes to any of these, you will want to read Column Overrides (List).
If you want to use named scopes to limit the resultset of find(:all) used by List, then override this method. It may return a scoped model. Defeault is active_scaffold_config.model. And as an instance method on the controller, it has access to params and session and all the standard good stuff.
Examples:
def beginning_of_chain
super.vegetarian.older_than(20)
end