administrate 0.9.0 → 0.14.0

data/docs/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

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.
@@ -10,7 +12,7 @@ require "administrate/dashboard/base"
 
 class CustomerDashboard < Administrate::Dashboard::Base
   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,7 @@ specify, including:
 - `Field::Select`
 - `Field::String`
 - `Field::Text`
+- `Field::Password`
 
 ## Customizing Fields
 
@@ -80,6 +84,30 @@ than one column. e.g.: `"name, email DESC"`.
 `: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_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.
+
 **Field::HasMany**
 
 `:limit` - Set the number of resources to display in the show view. Default is
@@ -93,8 +121,38 @@ Defaults to `:#{attribute}_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_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.
+
 **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 `""`.
@@ -135,9 +193,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`.
@@ -158,6 +222,17 @@ 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,
@@ -180,11 +255,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
 
@@ -196,18 +271,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.
 
@@ -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/getting_started.md

@@ -1,4 +1,6 @@
-# Getting Started
+---
+title: Getting Started
+---
 
 Administrate is released as a Ruby gem, and can be installed on Rails
 applications version 4.2 or greater.
@@ -37,11 +39,11 @@ Rails.application.routes.draw 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.
@@ -73,10 +75,19 @@ namespace :admin do
 end
 ```
 
+## 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
 
-If you've installed Administrate and generated dashboards and _then_ 
-subsequently added attributes to your models you'll need to manually add 
+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:
@@ -89,7 +100,7 @@ Example:
     the_new_attribute: Field::String,
     # ...
   }.freeze
-  
+
   SHOW_PAGE_ATTRIBUTES = [
     # ...
     :the_new_attribute,
@@ -101,7 +112,7 @@ Example:
     :the_new_attribute,
     # ...
   ].freeze
-  
+
   COLLECTION_ATTRIBUTES = [
     # ...
     :the_new_attribute, # if you want it on the index, also.
@@ -109,49 +120,9 @@ Example:
   ].freeze
 ```
 
-It's recommended that you make this change at the same time as you add the 
+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.
-
-## 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 the 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
-```
+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/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
+```