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/base_dashboard"
class CustomerDashboard < Administrate::BaseDashboard
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::Url
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"
.
:scope
- Specifies a custom scope inside a callable. Useful for preloading.
Example: .with_options(scope: -> { MyModel.includes(:rel).limit(5) })
:include_blank
- Specifies if the select element to be rendered should include
blank option. Default is true
.
:searchable
- Specify if the attribute should be considered when searching.
Default is false
.
searchable_fields
- Specify which columns to use on the search, only applies
if searchable
is true
For example:
country: Field::BelongsTo.with_options(
searchable: true,
searchable_fields: ['name'],
)
with this, you will be able to search through the column name
from the
association belongs_to :country
, from your model.
:primary_key
(deprecated) - Specifies the association's primary_key.
:foreign_key
(deprecated) - Specifies the name of the foreign key directly.
:class_name
(deprecated) - Specifies the name of the associated class.
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
(deprecated) - Specifies object's primary_key.
:foreign_key
(deprecated) - Specifies the name of the foreign key directly.
:class_name
(deprecated) - Specifies the name of the associated class.
Field::HasOne
:searchable
- Specify if the attribute should be considered when searching.
Default is false
.
searchable_fields
- Specify which columns to use on the search, only applies if
searchable
is true
For example:
cities: Field::HasMany.with_options(
searchable: true,
searchable_fields: ['name'],
)
with this, you will be able to search through the column name
from the
association has_many :cities
, from your model.
:class_name
(deprecated) - Specifies the name of the associated class.
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 ""
.
:format
- Specify a hash which defines a formatter. This uses ActiveSupport
and works by by passing a hash that includes the formatter (formatter
) and
the options for the formatter (formatter_options
). Defaults to the locale's
delimiter when formatter_options
does not include a delimiter
. See the
example below. Note that currently only
ActiveSupport::NumberHelper.number_to_delimited
is supported.
For example, you might use the following to display U.S. currency:
unit_price: Field::Number.with_options(
prefix: "$",
decimals: 2,
)
# "$5.99"
Or, to display a distance in kilometers, using a space as the delimiter:
distance: Field::Number.with_options(
suffix: " km",
decimals: 2,
format: {
formatter: :number_to_delimited,
formatter_options: {
delimiter: ' ',
},
},
)
# "2 000.00 km"
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 options shown on the select field. It accept either
an array or an object responding to :call
. Defaults to []
.
:searchable
- Specify if the attribute should be considered when searching.
Default is true
.
:include_blank
- Specifies if the select element to be rendered should include
blank option. Default is false
.
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::Url
: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::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 }
}
You can also define a filter with parameters:
COLLECTION_FILTERS = {
state: ->(resources, attr) { resources.where(state: attr) }
}
You can now search your resource with 'state:open' and your collection filter Proc will be called with with attr = open.
Form Attributes
You can define different attributes for new/create or edit/update actions:
FORM_ATTRIBUTES_NEW = [
:name,
:email
]
FORM_ATTRIBUTES_EDIT = [
:name,
:email,
:orders
]
Or for custom action with constant name "FORM_ATTRIBUTES_#{action.upcase}"