customizing_dashboards.md

title
Customizing Dashboards

In order to customize which attributes get displayed for each resource, edit the dashboard file generated by the installation generator.

By default, the file will look something like this:

require "administrate/dashboard/base"

class CustomerDashboard < Administrate::Dashboard::Base
  ATTRIBUTE_TYPES = {
    id: Field::Number,
    name: Field::String,
    email: Field::String,
    created_at: Field::DateTime,
    updated_at: Field::DateTime,
    orders: Field::HasMany,
  }

  COLLECTION_ATTRIBUTES = [
    :id,
    :name,
    :email,
    :created_at,
    :updated_at,
    :orders,
  ]

  SHOW_PAGE_ATTRIBUTES = [
    :id,
    :name,
    :email,
    :created_at,
    :updated_at,
    :orders,
  ]

  FORM_ATTRIBUTES = [
    :name,
    :email,
    :orders,
  ]
end

To change which attributes appear on each of the index, show, and edit pages, add or remove attributes to each constant array.

Finally, the ATTRIBUTE_TYPES method defines how each attribute is displayed throughout the dashboard. There are a number of Field classes that you can specify, including:

• Field::BelongsTo
• Field::Boolean
• Field::DateTime
• Field::Date
• Field::Email
• Field::HasMany
• Field::HasOne
• Field::Number
• Field::Polymorphic
• Field::Select
• Field::String
• Field::Text
• Field::Password

Customizing Fields

Setting Options

Each of the Field types take a different set of options, which are specified through the .with_options class method:

Field::BelongsTo

:order - Specifies the order of the dropdown menu, can be ordered by more than one column. e.g.: "name, email DESC".

:primary_key - Specifies object's primary_key. Defaults to :id.

:foreign_key - Specifies the name of the foreign key directly. Defaults to :#{attribute}_id.

:scope - Specifies a custom scope inside a callable. Useful for preloading. Example: .with_options(scope: -> { MyModel.includes(:rel).limit(5) })

:class_name - Specifies the name of the associated class. Defaults to :#{attribute}.to_s.singularize.camelcase.

:searchable - Specify if the attribute should be considered when searching. Default is false.

searchable_field - Specify which column to use on the search, only applies if searchable is true

For example:

  country: Field::BelongsTo.with_options(
    searchable: true,
    searchable_field: 'name',
  )

with this, you will be able to search through the column name from the association belongs_to :country, from your model.

Field::HasMany

:limit - Set the number of resources to display in the show view. Default is 5.

:sort_by - What to sort the association by in the show view.

:direction - What direction the sort should be in, :asc (default) or :desc.

:primary_key - Specifies object's primary_key. Defaults to :id.

:foreign_key - Specifies the name of the foreign key directly. Defaults to :#{attribute}_id

:class_name - Specifies the name of the associated class. Defaults to :#{attribute}.to_s.singularize.camelcase.

Field::HasOne

:class_name - Specifies the name of the associated class. Defaults to :#{attribute}.to_s.singularize.camelcase.

:searchable - Specify if the attribute should be considered when searching. Default is false.

searchable_field - Specify which column to use on the search, only applies if searchable is true

For example:

  cities: Field::HasMany.with_options(
    searchable: true,
    searchable_field: 'name',
  )

with this, you will be able to search through the column name from the association has_many :cities, from your model.

Field::Number

:searchable - Specify if the attribute should be considered when searching. Note that currently number fields are searched like text, which may yield more results than expected. Default is false.

:decimals - Set the number of decimals to display. Defaults to 0.

:prefix - Prefixes the number with a string. Defaults to "".

:suffix - Suffixes the number with a string. Defaults to "".

For example, you might use the following to display U.S. currency:

  unit_price: Field::Number.with_options(
    prefix: "$",
    decimals: 2,
  )

Or, to display a distance in kilometers:

  unit_price: Field::Number.with_options(
    suffix: " km",
    decimals: 2,
  )

Field::Polymorphic

:classes - Specify a list of classes whose objects will be used to populate select boxes for editing this polymorphic field. Default is [].

:order - What to sort the association by in the form select. Default is nil.

Field::DateTime

:format - Specify what format, using strftime you would like DateTime objects to display as.

:timezone - Specify which timezone Date and DateTime objects are based in.

Field::Date

:format - Specify what format, using strftime you would like Date objects to display as.

Field::Select

:collection - Specify the array or range to select from. Defaults to [].

:searchable - Specify if the attribute should be considered when searching. Default is true.

Field::String

:searchable - Specify if the attribute should be considered when searching. Default is true.

:truncate - Set the number of characters to display in the index view. Defaults to 50.

Field::Text

:searchable - Specify if the attribute should be considered when searching. Default is false.

:truncate - Set the number of characters to display in the index view. Defaults to 50.

Field::Password

:searchable - Specify if the attribute should be considered when searching. Default is false.

:truncate - Set the number of characters to display in the views. Defaults to 50.

:character - Set the replace character. Defaults to •.

Defining Labels

To change the user-facing label for an attribute, define a custom I18n translation:

en:
  helpers:
    label:
      customer:
        name: Full Name

To change the labels used for resources in dashboard collections. Assume you have a users dashboard and you want to change "User #1" to "Testy McTesterson", the user's name.

Add this method to the dashboard for Users. Use whatever attribute or method you like. Example for user:

def display_resource(user)
  user.name
end

To change the dashboard name in sidebar menu, sub-header and search string use default ActiveRecord i18n translations for models:

en:
  activerecord:
    models:
      customer:
        one: Happy Customer
        other: Happy Customers

Collection Filters

Resources can be filtered with pre-set filters. For example if we added:

COLLECTION_FILTERS = {
  inactive: ->(resources) { resources.where("login_at < ?", 1.week.ago) }
}

…to a dashboard, we can query the resources of that dashboard with:

bob inactive:

…to find users named "bob" who hasn't logged in the last week.

If you already had the inactive scope you could define the filter like so to take advantage of existing ActiveRecord scopes (and other class methods on the resource class).

COLLECTION_FILTERS = {
  inactive: ->(resources) { resources.inactive }
}