mini-max-mod 0.0.1

data/administrate-1.0.0/docs/customizing_dashboards.md

@@ -0,0 +1,641 @@
+---
+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:
+
+```ruby
+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 column used to order the records. It will apply both in
+the table views and in the dropdown menu on the record forms.
+You can set multiple columns as well with direction. E.g.: `"name, email DESC"`.
+
+`:scope` - Specifies a custom scope inside a callable. Useful for preloading.
+Example #1: `.with_options(scope: -> { MyModel.includes(:rel).limit(5) })`
+Example #2: `.with_options(scope: -> (field) { field.resource.my_models.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:
+
+```ruby
+  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.
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column of the associated model to be used for sorting in the table views and dropdown menu.  
+If `sorting_column` is omitted and `order` is specified, the value of `order` will be used.  
+If neither is specified, sorting will be done using the foreign key.  
+
+`:class_name` - Specifies the name of the associated class.
+
+**Field::HasMany**
+
+`:collection_attributes` - Set the columns to display in the show view.
+Default is COLLECTION_ATTRIBUTES in dashboard.
+
+`:limit` - The number of resources (paginated) to display in the show view. To disable pagination,
+set this to `0` or `false`. 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`.
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column of the associated model to be used for sorting in the dropdown menu.  
+If `sorting_column` is omitted and `sort_by` is specified, the value of `sort_by` will be used.  
+If neither is specified, sorting will be done using the foreign key.  
+For `HasMany` associations, sorting is based on the count, so this option is not referenced in the table views.  
+
+`:class_name` - Specifies the name of the associated class.
+
+**Field::HasOne**
+
+`:order` - Specifies the column used to order the records. It will apply both in
+the table views and in the dropdown menu on the record forms.
+You can set multiple columns as well with direction. E.g.: `"name, email DESC"`.
+
+`: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:
+
+```ruby
+  city: Field::HasOne.with_options(
+    searchable: true,
+    searchable_fields: ['name'],
+  )
+```
+
+with this, you will be able to search through the column `name` from the
+association `has_one :city`, from your model.
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column of the associated model to be used for sorting in the table views and dropdown menu.  
+If `sorting_column` is omitted and `order` is specified, the value of `order` will be used.  
+If neither is specified, sorting will be done using the foreign key.  
+
+`:class_name` - 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`.
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
+`: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. All helpers from `ActiveSupport::NumberHelper` are supported.
+
+For example, you might use the following to display U.S. currency:
+
+```ruby
+  unit_price: Field::Number.with_options(
+    prefix: "$",
+    decimals: 2,
+  )
+
+  # "$5.99"
+```
+
+Or, to display a distance in kilometers, using a space as the delimiter:
+
+```ruby
+  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`.
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+**Field::DateTime**
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
+`: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**
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
+`:format` - Specify what format, using `strftime` you would like `Date`
+objects to display as.
+
+**Field::Select**
+
+`:collection` - The options available to select. The format is the same as for Rails's own [`options_for_select`](https://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-options_for_select).
+
+If the given value responds to `call`, this will be called and the result used instead. The call will receive an instance of the field as argument. For example:
+
+```ruby
+  confirmation: Field::Select.with_options(
+    collection: ->(field) {
+      person = field.resource
+      {
+        "no, #{person.name}" => "opt0",
+        "yes, #{person.name}" => "opt1",
+        "absolutely, #{person.name}" => "opt2",
+      }
+    },
+  )
+```
+
+Administrate will detect if the attribute is an `ActiveRecord::Enum` and extract the available options. Note that if a `collection` is provided it will take precedence.
+
+If no collection is provided and no enum can be detected, the list of options will be empty.
+
+`:searchable` - Specify if the attribute should be considered when searching.
+Default is `true`.
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
+`:include_blank` - Similar to [the option of the same name accepted by Rails helpers](https://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html). If provided, a "blank" option will be added first to the list of options, with the value of `include_blank` as label.
+
+**Field::String**
+
+`:searchable` - Specify if the attribute should be considered when searching.
+Default is `true`.
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
+`: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`.
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
+`:truncate` - Set the number of characters to display in the index view.
+Defaults to `50`.
+
+`:input_options` - Options to customize the text area in form view.
+Example: `.with_options(input_options: { rows: 20 })`
+
+**Field::Url**
+
+`:searchable` - Specify if the attribute should be considered when searching.
+Default is `true`.
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
+`:truncate` - Set the number of characters to display in the index view.
+Defaults to `50`.
+
+`:html_options` - Specify anchor tag attributes (e.g., `target="_blank"`).
+Defaults is `{}`.
+
+**Field::Password**
+
+`:searchable` - Specify if the attribute should be considered when searching.
+Default is `false`.
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+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:
+
+```yaml
+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*:
+
+```ruby
+def display_resource(user)
+  user.name
+end
+```
+
+[define your own]: /adding_custom_field_types
+
+To change the dashboard name in sidebar menu, sub-header and search string use default ActiveRecord i18n translations for models:
+
+```yaml
+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:
+
+```ruby
+COLLECTION_FILTERS = {
+  inactive: ->(resources) { resources.where("login_at < ?", 1.week.ago) }
+}
+```
+
+…to a dashboard, we can query the resources of that dashboard with:
+
+```ruby
+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).
+
+```ruby
+COLLECTION_FILTERS = {
+  inactive: ->(resources) { resources.inactive }
+}
+```
+
+You can also define a filter with parameters:
+
+```ruby
+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:
+
+```ruby
+FORM_ATTRIBUTES_NEW = [
+  :name,
+  :email
+]
+FORM_ATTRIBUTES_EDIT = [
+  :name,
+  :email,
+  :orders
+]
+```
+
+Or for custom action with constant name `"FORM_ATTRIBUTES_#{action.upcase}"`
+
+### Form Fields' Hints
+
+You can show a brief text element below an input field by setting the
+corresponding translation key using the path:
+
+`administrate.field_hints.#{model_name}.#{field_name}`
+
+For example, with a Customer dashboard with an email field you can add a
+string value that will be used as text hint:
+
+```yml
+en:
+  administrate:
+    field_hints:
+      customer:
+        email: field_hint
+```
+
+## Grouped Attributes
+
+You may have models with a large number of fields and therefore you might want to group them in a meaningul way:
+
+```ruby
+class UserDashboard < Administrate::BaseDashboard
+  SHOW_PAGE_ATTRIBUTES = {
+    "" => [:username],
+    "Personal Information" => [:first_name, :last_name, :email],
+    "Address" => [:address_line_one, :address_line_two, :address_city, :address_state, :address_country]
+  }
+
+  FORM_ATTRIBUTES = {
+    "" => [:username, :password, :password_confirmation],
+    "personal_information" => [:first_name, :last_name, :email],
+    "address" => [:address_line_one, :address_line_two, :address_city, :address_state, :address_country]
+  }
+end
+```
+
+You can optionally translate your group labels:
+
+```yaml
+en:
+  helpers:
+    label:
+      user:
+        address: Address
+        personal_information: Personal Information
+```
+
+If not defined (see `SHOW_PAGE_ATTRIBUTES` above), Administrate will default to the given strings.
+
+## Virtual Attributes
+
+For all field types, you can use the `getter` option to change where the data is retrieved from or to set the data directly.
+
+By using this, you can define an attribute in `ATTRIBUTE_TYPES` that doesn’t exist in the model, and use it for various purposes.
+
+### Attribute Aliases
+
+You can create an alias for an attribute. For example:
+
+```ruby
+  ATTRIBUTE_TYPES = {
+    shipped_at: Field::DateTime,
+    shipped_on: Field::Date.with_options(
+      getter: :shipped_at
+    )
+  }
+  COLLECTION_ATTRIBUTES = [
+    :shipped_on
+  }
+  SHOW_PAGE_ATTRIBUTES = [
+    :shipped_at
+  }
+```
+
+In this example, a virtual attribute `shipped_on` based on the value of `shipped_at` is defined as a `Date` type and used for display on the index page (this can help save table cell space).
+
+### Decorated Attributes
+
+You can also use this to decorate data. For example:
+
+```ruby
+  ATTRIBUTE_TYPES = {
+    price: Field::Number,
+    price_including_tax: Field::Number.with_options(
+      getter: -> (field) {
+        field.resource.price * 1.1 if field.resource.price.present?
+      }
+    )
+  }
+```
+
+### Composite Attributes
+
+You can dynamically create a virtual attribute by combining multiple attributes for display. For example:
+
+```ruby
+  ATTRIBUTE_TYPES = {
+    first_name: Field::String,
+    last_name: Field::String,
+    full_name: Field::String.with_options(
+      getter: -> (field) {
+        [
+          field.resource.first_name,
+          field.resource.last_name
+        ].compact_blank.join(' ')
+      }
+    )
+  }
+```
+
+## Virtual Fields
+
+Custom fields can also be defined using virtual fields.
+
+```ruby
+  ATTRIBUTE_TYPES = {
+    id: Field::Number,
+    receipt: Field::ReceiptLink
+  }
+```
+
+```ruby
+module Administrate
+  module Field
+    class ReceiptLink < Base
+      def data
+        resource.id
+      end
+
+      def filename
+        "receipt-#{data}.pdf"
+      end
+
+      def url
+        "/files/receipts/#{filename}"
+      end
+    end
+  end
+end
+```
+
+```erb
+<%= link_to field.filename, field.url %>
+```
+
+### Custom Actions via Virtual Field
+
+By creating custom fields that are not dependent on specific attributes, you can insert custom views into any screen.
+For example, you can add custom buttons like this:
+
+```ruby
+  ATTRIBUTE_TYPES = {
+    id: Field::Number,
+    custom_index_actions: Field::CustomActionButtons,
+    custom_show_actions: Field::CustomActionButtons,
+  }
+```
+
+```ruby
+module Administrate
+  module Field
+    class CustomActionButtons < Base
+      def data
+        resource.id
+      end
+    end
+  end
+end
+```
+
+```erb
+<%# app/views/fields/custom_action_buttons/_index.html.erb %>
+<% if field.data.present? %>
+  <%= button_to "some action 1", [:some_action_1, namespace, field.resource] %>
+  <%= button_to "some action 2", [:some_action_2, namespace, field.resource] %>
+  <%= button_to "some action 3", [:some_action_3, namespace, field.resource] %>
+<% end %>
+```