administrate 0.10.0 → 0.15.0

data/docs/adding_controllers_without_related_model.md

@@ -0,0 +1,54 @@
+---
+title: Adding Controllers without a related Model
+---
+
+# Adding Controllers without a related Model
+
+Sometimes you may want to add a custom controller that has no resource
+related to it (for example for a statistics page).
+
+To do that, you must define an `index` route, as only controllers with index
+routes are displayed in the sidebar and then add a custom dashboard:
+
+```erb
+# app/views/admin/stats/index.html.erb 
+
+<div style="padding: 20px">
+  <h1>Stats</h1>
+  <br>
+  <p><b>Total Customers:</b> <%= @stats[:customer_count] %></h1>
+  <br>
+  <p><b>Total Orders:</b> <%= @stats[:order_count] %></h1>
+</div>
+```
+
+```ruby
+# app/dashboards/stat_dashboard.rb
+require "administrate/custom_dashboard"
+
+class StatDashboard < Administrate::CustomDashboard
+  resource "Stats" # used by administrate in the views
+end
+```
+
+```ruby
+# app/controllers/admin/stats_controller.rb
+module Admin
+  class StatsController < Admin::ApplicationController
+    def index
+      @stats = {
+        customer_count: Customer.count,
+        order_count: Order.count,
+      }
+    end
+  end
+end
+```
+
+```ruby
+# config/routes.rb
+namespace :admin do
+  # ...
+  resources :stats, only: [:index]
+end
+```

data/docs/adding_custom_field_types.md

@@ -1,4 +1,6 @@
-# Adding Custom Field Types
+---
+title: Adding Custom Field Types
+---
 
 If your application deals with a nonstandard data type,
 you can create an `Administrate::Field` object to help display

data/docs/authentication.md

@@ -1,4 +1,6 @@
-# Authenticating admin users
+---
+title: Authenticating admin users
+---
 
 Authentication is left for you to implement after you install Administrate into
 your app. It's expected that you can plugin your existing authentication

data/docs/authorization.md

@@ -1,4 +1,6 @@
-# Authorization
+---
+title: Authorization
+---
 
 The default configuration of Administrate is "authenticate-only" - once a
 user is authenticated, that user has access to every action of every object.
@@ -37,7 +39,7 @@ class PostPolicy < ApplicationPolicy
     def resolve
       scope.all
     end
-    
+
     def resolve_admin
       scope.where(owner: user)
     end
@@ -62,7 +64,7 @@ def authorize_resource(resource)
   raise "Erg!" unless show_action?(params[:action], resource)
 end
 
-# Hide links to actions if the user is not allowed to do them      
+# Hide links to actions if the user is not allowed to do them
 def show_action?(action, resource)
   current_user.can? action, resource
 end

data/docs/customizing_attribute_partials.md

@@ -1,4 +1,6 @@
-# Customizing attribute partials
+---
+title: Customizing attribute partials
+---
 
 Occasionally you might want to change how specific types of attributes appear
 across all dashboards. You can customize the following built in field types:
@@ -6,11 +8,12 @@ across all dashboards. You can customize the following built in field types:
 - `belongs_to`
 - `boolean`
 - `date_time`
+- `date`
 - `email`
 - `has_many`
 - `has_one`
 - `number`
-- `polymporphic`
+- `polymorphic`
 - `select`
 - `string`
 - `text`

data/docs/customizing_controller_actions.md

@@ -1,4 +1,6 @@
-# Customizing controller actions
+---
+title: Customizing controller actions
+---
 
 When you install Administrate into your app,
 we generate empty controllers for each of your resources.
@@ -28,9 +30,10 @@ class Admin::FoosController < Admin::ApplicationController
   # def find_resource(param)
   #   Foo.find_by!(slug: param)
   # end
-  #
+
   # Override this if you have certain roles that require a subset
   # this will be used to set the records shown on the `index` action.
+  #
   # def scoped_resource
   #  if current_user.super_admin?
   #    resource_class
@@ -40,3 +43,30 @@ class Admin::FoosController < Admin::ApplicationController
   # end
 end
 ```
+
+## Customizing Actions
+
+To enable or disable certain actions you could override `valid_action?` method in your dashboard controller like this:
+
+```ruby
+# disable 'edit' and 'destroy' links
+def valid_action?(name, resource = resource_class)
+  %w[edit destroy].exclude?(name.to_s) && super
+end
+```
+
+Action is one of `new`, `edit`, `show`, `destroy`.
+
+## Customizing Default Sorting
+
+To set the default sorting on the index action you could override `default_sorting_attribute` or `default_sorting_direction` in your dashboard controller like this:
+
+```ruby
+def default_sorting_attribute
+  :age
+end
+
+def default_sorting_direction
+  :desc
+end
+```

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.
@@ -54,6 +56,7 @@ specify, including:
 - `Field::BelongsTo`
 - `Field::Boolean`
 - `Field::DateTime`
+- `Field::Date`
 - `Field::Email`
 - `Field::HasMany`
 - `Field::HasOne`
@@ -76,35 +79,36 @@ which are specified through the `.with_options` class method:
 `: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`.
+`: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_field` - Specify which column to use on the search, only applies
+`searchable_fields` - Specify which columns to use on the search, only applies
 if `searchable` is `true`
 
 For example:
 
 ```ruby
-  country: Field::BelongsTo(
+  country: Field::BelongsTo.with_options(
     searchable: true,
-    seachable_field: 'name',
+    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
@@ -114,36 +118,34 @@ association `belongs_to :country`, from your model.
 
 `:direction` - What direction the sort should be in, `:asc` (default) or `:desc`.
 
-`:primary_key` - Specifies object's primary_key. Defaults to `:id`.
+`:primary_key` (deprecated) - Specifies object's primary_key.
 
-`:foreign_key` - Specifies the name of the foreign key directly. Defaults to `:#{attribute}_id`
+`:foreign_key` (deprecated) - Specifies the name of the foreign key directly.
 
-`:class_name` - Specifies the name of the associated class.
-Defaults to `:#{attribute}.to_s.singularize.camelcase`.
+`:class_name` (deprecated) - Specifies the name of the associated class.
 
 **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_fields` - Specify which columns to use on the search, only applies if
 `searchable` is `true`
 
 For example:
 
 ```ruby
-  cities: Field::HasMany(
+  cities: Field::HasMany.with_options(
     searchable: true,
-    seachable_field: 'name',
+    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.
@@ -156,6 +158,13 @@ more results than expected. Default is `false`.
 
 `: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
@@ -163,15 +172,25 @@ 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**
@@ -190,9 +209,15 @@ 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`.
@@ -246,11 +271,11 @@ 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
 
@@ -262,18 +287,33 @@ en:
     models:
       customer:
         one: Happy Customer
-        others: Happy Customers
+        other: Happy Customers
 ```
 
-## Customizing Actions
+## Collection Filters
 
-To enable or disable certain actions you could override `valid_action?` method in your dashboard controller like this:
+Resources can be filtered with pre-set filters. For example if we added:
 
 ```ruby
-# disable 'edit' and 'destroy' links
-def valid_action?(name, resource = resource_class)
-  %w[edit destroy].exclude?(name.to_s) && super
-end
+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:
 ```
 
-Action is one of `new`, `edit`, `show`, `destroy`.
+…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 }
+}
+```

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.
 

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].
+At the time of writing, these appear to be the most popular ones:
+
+1. [ActiveStorage support](https://github.com/Dreamersoul/administrate-field-active_storage)
+2. [Password field](https://github.com/valiot/administrate-field-password)
+3. [Enum field](https://github.com/Valiot/administrate-field-enum)
+4. [Nested has-many forms](https://github.com/nickcharlton/administrate-field-nested_has_many)
+5. [Belongs-to with Ajax search](https://github.com/fishbrain/administrate-field-belongs_to_search)
+
+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