API: List

always_show_create 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 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

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:

# correct way
config.list.columns = [:id, :name, :user_id, :created_on]

# incorrect!  Can you tell why?
config.columns = [:name, :user_id, :created_on]
config.list.columns = [:id, :name, :user_id, :created_on] 
# Hint: config.columns must contain all of the columns config.list.columns wants to inherit.

If you want to change the attribute of a column, like the label:

# correct way:
config.columns[:created_on].label = "How old"

# incorrect!  not like this!
config.list.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.

If a link is set to a column using API: Column, automatic linking will be ignored for it. You can supress automatic linking for a column using API: Column.

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.

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.

formats

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]

label local

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

list_row_class helper method, v1.1+

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
end

# in your main.css (or other)
.active-scaffold tr.negative td.amount-column {
  background-color: red;
}

per_page global local

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

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.

Warning: 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

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.