administrate 0.8.1 → 0.17.0

data/docs/customizing_dashboards.md

@@ -1,4 +1,6 @@
-# Customizing Dashboards
+---
+title: Customizing Dashboards
+---
 
 In order to customize which attributes get displayed for each resource,
 edit the dashboard file generated by the installation generator.
@@ -6,11 +8,11 @@ edit the dashboard file generated by the installation generator.
 By default, the file will look something like this:
 
 ```ruby
-require "administrate/dashboard/base"
+require "administrate/base_dashboard"
 
-class CustomerDashboard < Administrate::Dashboard::Base
+class CustomerDashboard < Administrate::BaseDashboard
   ATTRIBUTE_TYPES = {
-    id: Field::Integer,
+    id: Field::Number,
     name: Field::String,
     email: Field::String,
     created_at: Field::DateTime,
@@ -54,6 +56,7 @@ specify, including:
 - `Field::BelongsTo`
 - `Field::Boolean`
 - `Field::DateTime`
+- `Field::Date`
 - `Field::Email`
 - `Field::HasMany`
 - `Field::HasOne`
@@ -62,6 +65,8 @@ specify, including:
 - `Field::Select`
 - `Field::String`
 - `Field::Text`
+- `Field::Url`
+- `Field::Password`
 
 ## Customizing Fields
 
@@ -70,6 +75,41 @@ specify, including:
 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:
+
+```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.
+
+`: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
@@ -79,14 +119,53 @@ which are specified through the `.with_options` class method:
 
 `: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:
+
+```ruby
+  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:
 
 ```ruby
@@ -94,24 +173,59 @@ For example, you might use the following to display U.S. currency:
     prefix: "$",
     decimals: 2,
   )
+
+  # "$5.99"
 ```
 
-Or, to display a distance in kilometers:
+Or, to display a distance in kilometers, using a space as the delimiter:
 
 ```ruby
-  unit_price: Field::Number.with_options(
+  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 array or range to select from.  Defaults to `[]`.
+`: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.
@@ -128,6 +242,25 @@ 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,
@@ -150,10 +283,78 @@ Add this method to the dashboard for Users.
 Use whatever attribute or method you like.
 Example for *user*:
 
-````ruby
+```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}"`

data/docs/customizing_page_views.md

@@ -1,11 +1,25 @@
-# Customizing page views
+---
+title: Customizing page views
+---
 
-In order to change the appearance of any page,
-you can write custom Rails views.
+You can provide replacements for any of Administrate's templates.
+This way you can change the appearance of any page or element of
+the interface.
+
+In general, you can override any of the views under Administrate's
+[/app/views][1].
+For example, say that you want to customize the template used for flash
+messages. You can provide your own as
+`/app/views/administrate/application/_flashes.html.erb`, and it will replace
+Administrate's own.
+
+Figuring out which views are available and where can be repetitive. You can
+spare yourself some effort by using the built-in view generators.
+
+[1]: https://github.com/thoughtbot/administrate/tree/master/app/views
 
 ## Customizing for all resources
 
-The easiest way to get started is by using the built-in generators.
 In order to change the appearance of views for all resource types,
 call the generators with no arguments.
 
@@ -67,7 +81,7 @@ and will leave the show pages for other resources unchanged.
 ## Customizing layouts
 
 Many developers need to customize the layouts of their admin dashboard.
-It's so easy that pass in the "layout" key word to the view generators.
+It's as easy as passing in the "layout" keyword to the view generators.
 
 ```bash
 rails generate administrate:views:layout
@@ -75,4 +89,8 @@ rails generate administrate:views:layout
  # -> app/views/admin/application/_navigation.html.erb
  # -> app/views/admin/application/_javascript.html.erb
  # -> app/views/admin/application/_flashes.html.erb
+
+ rails generate administrate:views:navigation
+ # It only generates the sidebar partial
+ # -> app/views/admin/application/_navigation.html.erb
 ```

data/docs/extending_administrate.md

@@ -0,0 +1,27 @@
+---
+title: Extending Administrate
+---
+
+Apart from the configuration described in these pages, it is possible to
+extend Administrate's capabilities with the use of plugins. There are a
+number of plugins available, many of which can be found at [RubyGems.org].
+These are some popular examples:
+
+1. [ActiveStorage support](https://github.com/Dreamersoul/administrate-field-active_storage)
+2. [Enum field](https://github.com/Valiot/administrate-field-enum)
+3. [Nested has-many forms](https://github.com/nickcharlton/administrate-field-nested_has_many)
+4. [Belongs-to with Ajax search](https://github.com/fishbrain/administrate-field-belongs_to_search)
+5. [JSONb field plugin for Administrate](https://github.com/codica2/administrate-field-jsonb/)
+
+See many more at https://rubygems.org/gems/administrate/reverse_dependencies.
+
+Please note that these plugins are written by third parties. We do not
+have any control over them, and we cannot give any assurances as to how
+well they perform their advertised functions.
+
+You can write your own plugins too! We don't document this specifically,
+but you can have a look at the existing plugins for some directions.
+In general, Administrate tries to abide by Rails's conventions, so that
+hopefully should help!
+
+[RubyGems.org]: https://rubygems.org

data/docs/getting_started.md

@@ -1,16 +1,18 @@
-# Getting Started
+---
+title: Getting Started
+---
 
 Administrate is released as a Ruby gem, and can be installed on Rails
-applications version 4.2 or greater.
+applications version 5.0 or greater. We support Ruby 2.6 and up.
 
-Add the following to your Gemfile:
+First, add the following to your Gemfile:
 
 ```ruby
 # Gemfile
 gem "administrate"
 ```
 
-Re-bundle, then run the installer:
+Re-bundle with `bundle install`, then run the installer:
 
 ```bash
 $ rails generate administrate:install
@@ -29,6 +31,20 @@ The `Admin::ApplicationController` can be customized to add
 authentication logic, authorization, pagination,
 or other controller-level concerns.
 
+You will also want to add a `root` route to show a dashboard when you go to `/admin`.
+
+```ruby
+Rails.application.routes.draw do
+  namespace :admin do
+    # Add dashboard for your models here
+    resources :customers
+    resources :orders
+
+    root to: "customers#index" # <--- Root route
+  end
+ end
+```
+
 The routes can be customized to show or hide
 different models on the dashboard.
 
@@ -40,6 +56,28 @@ Each `Admin::FooController` can be overwritten to specify custom behavior.
 Once you have Administrate installed,
 visit <http://localhost:3000/admin> to see your new dashboard in action.
 
+### Errors about assets?
+
+If your apps uses Sprockets 4, you'll need to add Administrate's assets to
+your `manifest.js` file. To do this, add these two lines to the file:
+
+```
+//= link administrate/application.css
+//= link administrate/application.js
+```
+
+Otherwise, your app will show you this error:
+
+```
+Asset `administrate/application.css` was not declared to be precompiled in production.
+Declare links to your assets in `app/assets/config/manifest.js`.
+```
+
+For more information on why this is necessary, see Richard Schneeman's article
+["Self Hosted Config: Introducing the Sprockets manifest.js"][]
+
+[schneems]: https://www.schneems.com/2017/11/22/self-hosted-config-introducing-the-sprockets-manifestjs
+
 ## Create Additional Dashboards
 
 In order to create additional dashboards, pass in the resource name to
@@ -49,7 +87,7 @@ the dashboard generator. A dashboard and controller will be created.
 $ rails generate administrate:dashboard Foo
 ```
 
-Add a route for the new dashboard.
+Then add a route for the new dashboard.
 
 ```ruby
 # config/routes.rb
@@ -59,18 +97,54 @@ namespace :admin do
 end
 ```
 
-## Rails API
+## Using a Custom Namespace
+
+Administrate supports using a namespace other than `Admin`, such as
+`Supervisor`. This will also change the route it's using:
+
+```sh
+rails generate administrate:install --namespace=supervisor
+```
+
+## Keep Dashboards Updated as Model Attributes Change
 
-Since Rails 5.0, we've been able to have API only applications. Yet, sometimes
-we still want to have an admin. To get this working, please update this config:
+If you've installed Administrate and generated dashboards and _then_
+subsequently added attributes to your models you'll need to manually add
+these additions (or removals) to your dashboards.
+
+Example:
 
 ```ruby
-# config/application.rb
-config.api_only = false
+# app/dashboards/your_model_dashboard.rb
+
+  ATTRIBUTE_TYPES = {
+    # ...
+    the_new_attribute: Field::String,
+    # ...
+  }.freeze
+
+  SHOW_PAGE_ATTRIBUTES = [
+    # ...
+    :the_new_attribute,
+    # ...
+  ].freeze
+
+  FORM_ATTRIBUTES = [
+    # ...
+    :the_new_attribute,
+    # ...
+  ].freeze
+
+  COLLECTION_ATTRIBUTES = [
+    # ...
+    :the_new_attribute, # if you want it on the index, also.
+    # ...
+  ].freeze
 ```
 
-That means, when your app _boots_, we'll have access to flashes and such. We
-also don't use your `ApplicationController`. Instead, Administrate provides its
-own. Meaning you're free to specify `ActionController::API` as your parent
-controller to make sure no flash, session, or cookie middleware is used by your
-API.
+It's recommended that you make this change at the same time as you add the
+attribute to the model.
+
+The alternative way to handle this is to re-run `rails g administrate:install`
+and carefully pick through the diffs. This latter method is probably more
+cumbersome.

data/docs/guides/hiding_dashboards_from_sidebar.md

@@ -0,0 +1,19 @@
+---
+title: Hiding Dashboards from the Sidebar
+---
+
+Resources can be removed form the sidebar by removing their index action from the routes. For example:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace :admin do
+    resources :line_items, except: :index
+    resources :orders
+    resources :products
+    root to: "customers#index"
+  end
+end
+```
+
+In this case, only Orders and Products will appear in the sidebar, while Line Items can still appear as an association.

data/docs/guides.md

@@ -0,0 +1,5 @@
+---
+title: Guides
+---
+
+* [Hiding Dashboards from the Sidebar](./guides/hiding_dashboards_from_sidebar)

data/docs/rails_api.md

@@ -0,0 +1,45 @@
+---
+title: Rails API
+---
+
+Since Rails 5.0, we've been able to have API only applications. Yet, sometimes
+we still want to have an admin.
+
+To get this working, we recommend updating this config:
+
+```ruby
+# config/application.rb
+config.api_only = false
+```
+
+That means, when your app _boots_, we'll have access to flashes and such. We
+also don't use your `ApplicationController`. Instead, Administrate provides its
+own. Meaning you're free to specify `ActionController::API` as your parent
+controller to make sure no flash, session, or cookie middleware is used by your
+API.
+
+Alternatively, if your application needs to have `config.api_only = true`, we
+recommend you add the following lines to your `config/application.rb`
+
+```ruby
+# Enable Flash, Cookies, MethodOverride for Administrate Gem
+config.middleware.use ActionDispatch::Flash
+config.session_store :cookie_store
+config.middleware.use ActionDispatch::Cookies
+config.middleware.use ActionDispatch::Session::CookieStore, config.session_options
+config.middleware.use ::Rack::MethodOverride
+```
+
+You must also ensure that all the required controller actions are available
+and accessible as routes since generators in API-only applications only
+generate some of the required actions. Here is an example:
+
+```ruby
+# routes.rb
+namespace :admin do
+  resources :name, only: %i(index show new create edit update destroy)
+end
+
+# names_controller.rb
+# Ensure each of those methods are defined
+```