administrate 0.12.0 → 0.15.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.
@@ -54,6 +56,7 @@ specify, including:
 - `Field::BelongsTo`
 - `Field::Boolean`
 - `Field::DateTime`
+- `Field::Date`
 - `Field::Email`
 - `Field::HasMany`
 - `Field::HasOne`
@@ -76,21 +79,16 @@ 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:
@@ -98,13 +96,19 @@ For example:
 ```ruby
   country: Field::BelongsTo.with_options(
     searchable: true,
-    searchable_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,22 +118,18 @@ 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:
@@ -137,13 +137,15 @@ For example:
 ```ruby
   cities: Field::HasMany.with_options(
     searchable: true,
-    searchable_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`.
@@ -265,19 +290,6 @@ en:
         other: Happy Customers
 ```
 
-## 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`.
-
 ## Collection Filters
 
 Resources can be filtered with pre-set filters. For example if we added:

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

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.4 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
@@ -35,7 +37,7 @@ You will also want to add a `root` route to show a dashboard when you go to `/ad
 Rails.application.routes.draw do
   namespace :admin do
     # Add dashboard for your models here
-    resources :customers,
+    resources :customers
     resources :orders
 
     root to: "customers#index" # <--- Root route
@@ -54,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
@@ -63,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
@@ -84,8 +108,8 @@ 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:
@@ -98,7 +122,7 @@ Example:
     the_new_attribute: Field::String,
     # ...
   }.freeze
-  
+
   SHOW_PAGE_ATTRIBUTES = [
     # ...
     :the_new_attribute,
@@ -110,7 +134,7 @@ Example:
     :the_new_attribute,
     # ...
   ].freeze
-  
+
   COLLECTION_ATTRIBUTES = [
     # ...
     :the_new_attribute, # if you want it on the index, also.
@@ -118,7 +142,7 @@ 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`

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

@@ -1,7 +1,9 @@
-## Rails API
+---
+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. 
+we still want to have an admin.
 
 To get this working, we recommend updating this config:
 
@@ -29,7 +31,7 @@ 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 
+and accessible as routes since generators in API-only applications only
 generate some of the required actions. Here is an example:
 
 ```ruby

data/lib/administrate/base_dashboard.rb

@@ -1,6 +1,7 @@
 require "administrate/field/belongs_to"
 require "administrate/field/boolean"
 require "administrate/field/date_time"
+require "administrate/field/date"
 require "administrate/field/email"
 require "administrate/field/has_many"
 require "administrate/field/has_one"
@@ -17,6 +18,18 @@ module Administrate
   class BaseDashboard
     include Administrate
 
+    DASHBOARD_SUFFIX = "Dashboard".freeze
+
+    class << self
+      def model
+        to_s.chomp(DASHBOARD_SUFFIX).classify.constantize
+      end
+
+      def resource_name(opts)
+        model.model_name.human(opts)
+      end
+    end
+
     def attribute_types
       self.class::ATTRIBUTE_TYPES
     end
@@ -43,7 +56,10 @@ module Administrate
 
     def permitted_attributes
       form_attributes.map do |attr|
-        attribute_types[attr].permitted_attribute(attr)
+        attribute_types[attr].permitted_attribute(
+          attr,
+          resource_class: self.class.model,
+        )
       end.uniq
     end
 
@@ -73,18 +89,11 @@ module Administrate
       "Attribute #{attr} could not be found in #{self.class}::ATTRIBUTE_TYPES"
     end
 
-    def association_classes
-      @association_classes ||=
-        ObjectSpace.each_object(Class).
-          select { |klass| klass < Administrate::Field::Associative }
-    end
-
     def attribute_includes(attributes)
       attributes.map do |key|
-        field = self.class::ATTRIBUTE_TYPES[key]
+        field = attribute_type_for(key)
 
-        next key if association_classes.include?(field)
-        key if association_classes.include?(field.try(:deferred_class))
+        key if field.associative?
       end.compact
     end
   end

data/lib/administrate/custom_dashboard.rb

@@ -0,0 +1,15 @@
+module Administrate
+  class CustomDashboard
+    include Administrate
+
+    class << self
+      def resource_name(_opts)
+        named_resource.pluralize.titleize
+      end
+
+      def resource(resource_name)
+        define_singleton_method(:named_resource) { resource_name }
+      end
+    end
+  end
+end

data/lib/administrate/engine.rb

@@ -22,6 +22,13 @@ module Administrate
     @@javascripts = []
     @@stylesheets = []
 
+    initializer "administrate.assets.precompile" do |app|
+      app.config.assets.precompile += [
+        "administrate/application.js",
+        "administrate/application.css",
+      ]
+    end
+
     def self.add_javascript(script)
       @@javascripts << script
     end

data/lib/administrate/field/associative.rb

@@ -3,30 +3,74 @@ require_relative "base"
 module Administrate
   module Field
     class Associative < Base
+      def self.foreign_key_for(resource_class, attr)
+        reflection(resource_class, attr).foreign_key
+      end
+
+      def self.associated_class(resource_class, attr)
+        reflection(resource_class, attr).klass
+      end
+
+      def self.associated_class_name(resource_class, attr)
+        reflection(resource_class, attr).class_name
+      end
+
+      def self.reflection(resource_class, attr)
+        resource_class.reflect_on_association(attr)
+      end
+
       def display_associated_resource
         associated_dashboard.display_resource(data)
       end
 
       def associated_class
-        associated_class_name.constantize
+        if option_given?(:class_name)
+          associated_class_name.constantize
+        else
+          self.class.associated_class(resource.class, attribute)
+        end
       end
 
-      protected
+      private
 
       def associated_dashboard
         "#{associated_class_name}Dashboard".constantize.new
       end
 
       def associated_class_name
-        options.fetch(:class_name, attribute.to_s.singularize.camelcase)
+        if option_given?(:class_name)
+          deprecated_option(:class_name)
+        else
+          self.class.associated_class_name(
+            resource.class,
+            attribute,
+          )
+        end
       end
 
       def primary_key
-        options.fetch(:primary_key, :id)
+        if option_given?(:primary_key)
+          deprecated_option(:primary_key)
+        else
+          :id
+        end
       end
 
       def foreign_key
-        options.fetch(:foreign_key, :"#{attribute}_id")
+        if option_given?(:foreign_key)
+          deprecated_option(:foreign_key)
+        else
+          self.class.foreign_key_for(resource.class, attribute)
+        end
+      end
+
+      def option_given?(name)
+        options.key?(name)
+      end
+
+      def deprecated_option(name)
+        Administrate.warn_of_deprecated_option(name)
+        options.fetch(name)
       end
     end
   end

data/lib/administrate/field/base.rb

@@ -12,10 +12,22 @@ module Administrate
         field_type.dasherize
       end
 
+      def self.associative?
+        self < Associative
+      end
+
       def self.searchable?
         false
       end
 
+      def self.field_type
+        to_s.split("::").last.underscore
+      end
+
+      def self.permitted_attribute(attr, _options = nil)
+        attr
+      end
+
       def initialize(attribute, data, page, options = {})
         @attribute = attribute
         @data = data
@@ -24,10 +36,6 @@ module Administrate
         @options = options
       end
 
-      def self.permitted_attribute(attr, _options = nil)
-        attr
-      end
-
       def html_class
         self.class.html_class
       end
@@ -40,15 +48,33 @@ module Administrate
         "/fields/#{self.class.field_type}/#{page}"
       end
 
-      attr_reader :attribute, :data, :page, :resource
+      def required?
+        return false unless resource.class.respond_to?(:validators_on)
 
-      protected
+        resource.class.validators_on(attribute).any? do |v|
+          next false unless v.class == ActiveRecord::Validations::PresenceValidator
 
-      attr_reader :options
+          options = v.options
+          next false if options.include?(:if)
+          next false if options.include?(:unless)
 
-      def self.field_type
-        to_s.split("::").last.underscore
+          if on_option = options[:on]
+            if on_option == :create && !resource.persisted?
+              next true
+            end
+
+            if on_option == :update && resource.persisted?
+              next true
+            end
+
+            next false
+          end
+
+          true
+        end
       end
+
+      attr_reader :attribute, :data, :options, :page, :resource
     end
   end
 end

data/lib/administrate/field/belongs_to.rb

@@ -3,8 +3,14 @@ require_relative "associative"
 module Administrate
   module Field
     class BelongsTo < Associative
-      def self.permitted_attribute(attr, _options = nil)
-        :"#{attr}_id"
+      def self.permitted_attribute(attr, options = {})
+        resource_class = options[:resource_class]
+        if resource_class
+          foreign_key_for(resource_class, attr)
+        else
+          Administrate.warn_of_missing_resource_class
+          :"#{attr}_id"
+        end
       end
 
       def permitted_attribute
@@ -12,7 +18,7 @@ module Administrate
       end
 
       def associated_resource_options
-        [nil] + candidate_resources.map do |resource|
+        candidate_resources.map do |resource|
           [display_candidate_resource(resource), resource.send(primary_key)]
         end
       end
@@ -21,6 +27,10 @@ module Administrate
         data && data.send(primary_key)
       end
 
+      def include_blank_option
+        options.fetch(:include_blank, true)
+      end
+
       private
 
       def candidate_resources