API: List

always_show_create global local

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 = true

always_show_search global local

The always show search option always show the search form while on the list view. This option has no affect if the search action is excluded. It will in turn display the corresponding search view, regular search, field search, or live 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.

Examples:

config.list.always_show_search = true

association_join_text global local v2.4+

Defines what string to use to join records from plural associations. Defaults to ", ".

auto_select_columns global local v3.3

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.

columns local

The 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.

conditions_for_collection controller method

If you want to add custom conditions to the find(:all) 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']]
end

count_includes local

Overrides default includes used for count sql query. Use to speed up query to count records when you need many includes to list records.

custom_finder_options controller method

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 :order (or :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
  {:order => "some_field = #{some_magic_value} DESC, another_field ASC NULLS LAST"}
end

empty_field_text global local

Defines 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.

filtered_message local

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.

formats local

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]

hide_nested_column local

ActiveScaffold doesn’t display parent column in nested scaffolds. Enable this property so parent column will be displayed when you open a nested scaffold.

label local

The label of the list. Appears in the table heading.

list_row_class helper method, v1.1+

Since 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

or a 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
end

In your main.css (or other)

.active-scaffold tr.negative td.amount-column {
  background-color: red;
}

messages_above_header global local

Display messages above of columns header instead of below of it

config.list.messages_above_header = true

nested_auto_open local

Auto open a nested scaffolds when there are few records in the list. You have to set a hash, using the nested link as a key and the maximum records number to be in list so nested scaffold is open.

config.list.nested_auto_open = {:players => 1}

Players scaffold will be open automatically when there is only one record in the list, for example after a search.

no_entries_message local

You 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.

page_links_inner_window global local v2.3+

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

page_links_outer_window global local v3.2.5+

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

pagination global local v2.3+

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 t
• false: Disable pagination

per_page global local

How many records to show on each page. Set to something ridiculously high to effectively disable pagination. Default is 15.

refresh_with_header global local v3.3+

Include list header when list is refreshed by JS (using refresh_list partial)

reset_link global local

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

show_search_reset global local

If you don’t want ActiveScaffold displays a link to reset search, you can remove disabling this property.

sorting local

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, :asc

If you need more complicated sorting, try to use custom_finder_options controller method, e.g:

protected

  def custom_finder_options
    {:order => "some_field = #{some_magic_value} DESC, another_field ASC NULLS LAST"}
  end

wrap_tag global local v3.2.8

Set 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 = :span

Modifying how the data outputs

Would 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 Field Overrides.

beginning_of_chain controller method, v2.3+

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