administrate 0.13.0 → 0.17.0

data/docs/customizing_dashboards.md

@@ -8,9 +8,9 @@ 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::Number,
     name: Field::String,
@@ -65,6 +65,7 @@ specify, including:
 - `Field::Select`
 - `Field::String`
 - `Field::Text`
+- `Field::Url`
 - `Field::Password`
 
 ## Customizing Fields
@@ -79,21 +80,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:
@@ -101,13 +97,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
@@ -117,22 +119,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:
@@ -140,13 +138,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.
@@ -159,6 +159,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
@@ -166,15 +173,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**
@@ -200,11 +217,15 @@ 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.
@@ -221,6 +242,14 @@ 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.
@@ -300,3 +329,32 @@ 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

@@ -2,12 +2,24 @@
 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].
+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

@@ -3,16 +3,16 @@ 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
@@ -37,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
@@ -56,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
@@ -65,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

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/lib/administrate/base_dashboard.rb

@@ -18,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
@@ -38,13 +50,24 @@ module Administrate
       attribute_types.keys
     end
 
-    def form_attributes
-      self.class::FORM_ATTRIBUTES
+    def form_attributes(action = nil)
+      specific_form_attributes_for(action) || self.class::FORM_ATTRIBUTES
+    end
+
+    def specific_form_attributes_for(action)
+      return unless action
+
+      cname = "FORM_ATTRIBUTES_#{action.upcase}"
+
+      self.class.const_get(cname) if self.class.const_defined?(cname)
     end
 
     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
 
@@ -56,6 +79,12 @@ module Administrate
       self.class::COLLECTION_ATTRIBUTES
     end
 
+    def search_attributes
+      attribute_types.keys.select do |attribute|
+        attribute_types[attribute].searchable?
+      end
+    end
+
     def display_resource(resource)
       "#{resource.class} ##{resource.id}"
     end
@@ -74,18 +103,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,6 +12,10 @@ module Administrate
         field_type.dasherize
       end
 
+      def self.associative?
+        self < Associative
+      end
+
       def self.searchable?
         false
       end
@@ -44,6 +48,32 @@ module Administrate
         "/fields/#{self.class.field_type}/#{page}"
       end
 
+      def required?
+        return false unless resource.class.respond_to?(:validators_on)
+
+        resource.class.validators_on(attribute).any? do |v|
+          next false unless v.class == ActiveRecord::Validations::PresenceValidator
+
+          options = v.options
+          next false if options.include?(:if)
+          next false if options.include?(:unless)
+
+          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

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

data/lib/administrate/field/deferred.rb

@@ -21,17 +21,36 @@ module Administrate
           options == other.options
       end
 
+      def associative?
+        deferred_class.associative?
+      end
+
       def searchable?
         options.fetch(:searchable, deferred_class.searchable?)
       end
 
       def searchable_field
+        ActiveSupport::Deprecation.warn(
+          "searchable_field is deprecated, use searchable_fields instead",
+        )
         options.fetch(:searchable_field)
       end
 
-      def permitted_attribute(attr, _options = nil)
-        options.fetch(:foreign_key,
-          deferred_class.permitted_attribute(attr, options))
+      def searchable_fields
+        if options.key?(:searchable_field)
+          [searchable_field]
+        else
+          options.fetch(:searchable_fields)
+        end
+      end
+
+      def permitted_attribute(attr, opts = {})
+        if options.key?(:foreign_key)
+          Administrate.warn_of_deprecated_option(:foreign_key)
+          options.fetch(:foreign_key)
+        else
+          deferred_class.permitted_attribute(attr, options.merge(opts))
+        end
       end
 
       delegate :html_class, to: :deferred_class