Skip to content

API: Core

Jump to bottom Edit New page
Reid Cooper edited this page Jun 2, 2017 · 63 revisions

actions global local

The components of ActiveScaffold (e.g. Create, Update, Delete, Show) are called actions. This setting lets you define which ones are active. Only actions present in this list will be configurable. Only actions present in this list will be mixed into your controllers.

Examples:

config.actions = [:create, :update, :show]
config.actions.exclude :create
config.actions.add :delete
config.actions.swap :search, :live_search

action_links global local

If you want to tie ActiveScaffold to a custom action, or to some other page or controller or site or whatever, you can create your own action link. This setting is just for your custom action link: the action links used by various action components are editable within the configuration for that action component (e.g. config.create.link). See API: Action Link for details on the per-link options.

Examples:

# Add an action link (with options)
config.action_links.add 'get_pdf', :label => 'Download PDF'

# You can look up and modify action links by searching by the :action attribute
config.action_links['get_pdf'].label = 'Save PDF'

# Quick-add (doesn't accept options)
config.action_links << 'print_pdf'

# NOTE: if you want to edit a "native" link, you can find it on the proper config object
config.show.link.label = 'Display Record'

cache_action_link_urls global local v3.3+

ActiveScaffold caches action link urls since v3.3. If you use nested resources routes to get pretty routes without query string, you will need to disable caching, or you will get longer urls because parameters will be added to query string anyway.

Examples:

# config/routes.rb
resources :customers do
  as_nested_resources :invoices
end

# app/controllers/application_controller.rb
ActiveScaffold.set_defaults do |config|
  config.cache_action_link_urls = false
end

# or only in invoices controller
# app/controllers/invoices_controller.rb
active_scaffold do |conf|
  conf.cache_action_link_urls = false
end

cache_association_options global local v3.3.1+

ActiveScaffold caches cache_association_options since v3.3.1. It is useful for has_many associations rendered as subform. Association name, class owner of the association, associated class (for polymorphic associations), and conditions returned by options_for_association_conditions must be equal to reuse cached result. If association_options_find gets a block (due to some overrided methods), or default class is overrided (e.g. overriding method to use a scope), cache is skipped. Anyway, if cache is causing problems to you, it can be disabled with this option.

Example:

# app/controllers/application_controller.rb
ActiveScaffold.set_defaults do |config|
  config.cache_association_options = false
end

# or only in invoices controller
# app/controllers/invoices_controller.rb
active_scaffold do |conf|
  conf.cache_association_options = false
end

columns local

The columns setting is a collection of metadata about attributes of your model. Columns in here may be simple attributes, virtual fields (fields with just an accessor on the model), or associations. See API: Column for details on per-column configuration.

If you want to remove a particular column from use in a particular action, then use the appropriate config.#{action}.columns collection (e.g. config.list.columns).

Examples:

# Add a column (virtual, probably)
config.columns.add :first_and_last_name
config.columns << :name_spelled_backwards

# Edit a column (options described below)
config.columns[:first_and_last_name].label = 'Full Name'

# Remove a column from Create, Update, List, etc. (version 1.1+)
config.columns.exclude :sekret_field

Note that if excluding and re-adding columns, the order/weight of columns may seem disregarded if class caching is enabled (if config.cache_classes=true in development.rb, test.rb, and/or production.rb). If this is the case, you should first reset columns to their initial state via:

active_scaffold_config.list.columns = active_scaffold_config.columns._inheritable

This solution of resetting columns prior to additions and exclusions is preferred since it supports class caching being enabled or disabled. For more information, please read issue 732 and this post.

conditional_get_support global local v3.4+

Enable setting Etag and LastModified on responses and using fresh_when/stale? to respond with 304 and avoid rendering views. Etag is calculated only for get requests and based on record or @records. To change records used to calculate etag, override @objects_for_etag in your controller.

config.list.columns, config.create.columns, config.update.columns inherit from config.columns

By default, config.columns contains all of the columns for your model, including primary key, foreign key identifiers, created/updated_on/at, etc. These other fields

config.list.columns, config.create.columns, and config.update.columns inherit their columns from config.columns. However, some columns are excluded by default: foreign key identifiers such as `user_id`, the `id` column, and the `created/updated_at/on` fields.

After v3.4.33 config.update.columns are inherited from config.create.columns, if not defined.

Real, Association, and Virtual Columns

The minimum requirement for an ActiveScaffold column is an accessor on the model. If the accessor is named the same as a database attribute, then it’s a “real” column. If the accessor is named the same as an association, then it’s an “association” column (these accessors are a special type of virtual column created and managed by ActiveRecord, e.g. @user.user_group). Otherwise it’s a “virtual” column.

In general, ActiveScaffold’s default column set will include one column for every database attribute and one column for every association. If you want to use virtual columns (which can be very handy), you’ll need to add them in yourself.

Examples:

class User < ActiveRecord::Base
  # defining an association will also create an association column with the same name
  has_and_belongs_to_many :roles

  # create an accessor that can be used as a virtual column
  def first_and_last_name
    "#{self.first_name} #{self.last_name}"
  end
end

class UserController < ApplicationController
  active_scaffold :users do |config|
    # In the List view, we'll combine two fields into one by hiding two "real" fields and adding one "virtual" field.
    config.list.columns.exclude :first_name, :last_name
    config.list.columns << :first_and_last_name

    # If you want to customize the metadata on the virtual field, you need to add it to the main columns object.
    config.columns << :first_and_last_name
    config.columns[:first_and_last_name].label = 'Full Name'
  end
end

dhtml_history global v1.1

The DHTML History is javascript designed to save the state of the page in the URL, so that if someone refreshes or bookmarks the page, the page can return to the way it was. If this is causing problems for you, or you just don’t like the overhead, you can disable the dhtml history altogether.

class ApplicationController < ActionController::Base
  ActiveScaffold.set_defaults do |config|
    # disables dhtml history globally
    config.dhtml_history = false
  end
end

formats

Active scaffold supports html, js, json and xml formats by default. If you need to add another mime type for your controller you can do it here. The format is then added to the default formats.

Examples:

# Add a column (virtual, probably)
config.formats << :pdf
or
config.formats = [:pdf]

frontend global local

ActiveScaffold is skinnable by creating and using different frontends. These frontends can package up completely different javascript, stylesheets, images, language files, and partials. They are a powerful way of potentially changing the entire UI for ActiveScaffold to blend with your design. Any partial called for by the ActiveScaffold code that is not provided by a frontend will fallback to using the partial from the default frontend.

When more frontends are shipped with ActiveScaffold, or when you have written your own, you can decide which frontend to use either globally or on a per-controller basis.

Examples:

config.frontend = :shiny_new_frontend

Note: Not working in current version. Only up to 2.3.8.

highlight_messages global local v3.2.12

Set this option to highlight some words of the flash messages. It will use highlight rails helper, so you can set phrases as keys (a string or array of strings to highlight) and format strings as values. Look at highlight rails API for more info about this method.

config.highlight_messages = {'created' => '<em>\\1</em>'}

ignore_columns global

If your database schema has special fields that should just be ignored by ActiveScaffold, you can define a global blacklist here. This is meant to be used on the ApplicationController. If you want to exclude columns in some specific scaffold, use the config.#{action}.columns.exclude method.

Examples:

config.ignore_columns = [:created_at, :updated_at, :lock_version]
config.ignore_columns.add :is_deleted

label local

This is a string giving a base name for the entire scaffold. This base name will be extended appropriately by actions, unless those actions have explicitely defined their own labels. For example, if might set config.label = 'Customers', and then the Create action would have a label like “Create Customer”. This label makes the most sense as a plural noun describing the records in the collection.

Examples:

config.label = 'Customers'

sti_children local v2.3

Set it in a controller for a superclass model of a hierarchy. Set an array with names of subclasses. The inheritance column will use form_ui select, and the subclasses will be used as options for the select. If you set another form_ui for the column it won’t be overridden.

config.sti_children = [:subclass1, :subclass2]

sti_create_links global local v2.3

It’s only used when sti_children is used. Enabling it, create link will be changed with multiple create links for each subclass from sti_children. Also type column will be hidden in create and update forms.

store_user_settings global local v3.3.1

Enable saving user settings in session (per_page, limit, page, sort, search params). It’s enabled by default becuase it was the previous behaviour.

When it’s disabled search params will be send in every sorting and pagination request, and sort params will be send in every pagination request, instead of getting them from session. Also, closing and opening search form won’t display previous search params.

timestamped_messages global local v3.2.12

Prefix flash messages with current timestamp. You can set true and :short format will be used, or set the format to display, either a string format or a I18n format key.

theme global local

For each frontend there may by a set of available themes: different look and feels for the same underlying UI (frontend). Themes are entirely CSS based.

Examples:

config.theme = :default
config.theme = :blue # AjaxScaffold look with a blue header

active_scaffold_controller_for override method

This class method accepts an ActiveRecord::Base klass and returns an ActionController::base klass (a constant, not a string). We use the method to link controllers together (like for API: Nested), and to find configuration of associated models (like for API: Subform). The default behavior is to try and search for a singular or plural version of #{model}Controller within the namespace of the current controller. If this doesn’t work for you, maybe because you have your own convention or because you have one controller that doesn’t match up, you can override active_scaffold_controller_for to define your own search pattern.

Example:

class Admin::Scaffold::ScaffoldTableController < Admin::Scaffold::BaseController
  protected

  def self.active_scaffold_controller_for(klass)
    return FooController if klass == Bar
    super
  end
end
Add a custom footer
Add a custom sidebar
Clone this wiki locally