administrate 0.12.0 → 0.20.1

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 6.0 or greater. We support Ruby 3.0 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/customising_search.md

@@ -0,0 +1,149 @@
+---
+title: Customising the search
+---
+
+Administrate dashboards provide a search function, but it is quite basic.
+Things like search across complex associations, inside JSON columns, or outside
+the database (eg: an Elasticsearch index) are not possible out of the box.
+
+Fortunately, Administrate is just Rails, so you can use your existing Rails
+knowledge to customize the search feature. Let's look into that.
+
+## In short
+
+Override the `filter_resources` method in your admin controllers in order
+to customize the search.
+
+It has two parameters:
+
+* `resources`: an ActiveRecord relation for the model on whose dashboard the
+               search originated.
+* `search_term:`: a string representing the search query entered by the user.
+
+Return an ActiveRecord relation for the same model as `resources`, matching
+the desired search results.
+
+## In more detail
+
+When you install Administrate in your application, it generates an admin
+controller for each of your ActiveRecord models, as well as a base controller
+that all of these inherit from.
+
+For example, if you have two ActiveRecord models: `Person` and `Address`,
+running `rails generate administrate:install` will get you the following
+files (plus others that are not relevant here):
+
+* `app/controllers/admin/people_controller.rb`
+* `app/controllers/admin/addresses_controller.rb`
+* `app/controllers/admin/application_controller.rb`
+
+By default, searches are handled by the `index` action of the controller that
+the user was visiting when they performed the search. For example, if a user
+is visiting the People dashboard and submits a search, the user is sent to
+the path `/admin/people?search=<search query>`. This is routed to
+`Admin::PeopleController#index`, where the search query can be read as
+`params[:search]`.
+
+By default, these controllers are empty. Administrate's code is implemented
+at `Administrate::ApplicationController`, from which all inherit. This is
+where search is implemented. You can read the code yourself at:
+https://github.com/thoughtbot/administrate/blob/main/app/controllers/administrate/application_controller.rb.
+
+It is in the linked code that you can see what Administrate actually does.
+For example, this is the `index` action at the time of writing these lines:
+
+```ruby
+    def index
+      authorize_resource(resource_class)
+      search_term = params[:search].to_s.strip
+      resources = filter_resources(scoped_resource, search_term: search_term)
+      resources = apply_collection_includes(resources)
+      resources = order.apply(resources)
+      resources = resources.page(params[:_page]).per(records_per_page)
+      page = Administrate::Page::Collection.new(dashboard, order: order)
+
+      render locals: {
+        resources: resources,
+        search_term: search_term,
+        page: page,
+        show_search_bar: show_search_bar?,
+      }
+    end
+```
+
+What the above does is applying a few transforms
+to the variable `resources`, filtering it, applying includes for associations,
+ordering the results, paginating them, and finally handing them over to the
+template in order to be rendered. All this is pretty standard Rails, although
+split into individual steps that can be overriden by developers in order
+to add customizations, and ultimately wrapped in an instance of
+`Administrate::Page::Collection` which will read your dashboard definitions
+and figure out what fields you want displayed.
+
+It is the filtering part where the search is implemented. You will notice the
+`filter_resources` method, which takes a parameter `search_term`. This is what
+this method looks like at the moment:
+
+```ruby
+    def filter_resources(resources, search_term:)
+      Administrate::Search.new(
+        resources,
+        dashboard,
+        search_term,
+      ).run
+    end
+```
+
+The class `Administrate::Search` implements the default search facilities
+within Administrate... but you do not have to worry about it! You can ignore
+it and implement your own search in `filter_resources`. For example, you
+could write your own version in your controller, to override Administrate's
+own. Something like this:
+
+```ruby
+    def filter_resources(resources, search_term:)
+      resources.where(first_name: search_term)
+        .or(People.where(last_name: search_term))
+    end
+```
+
+It can be as complex (or simple) as you want, as long as the return value
+of the method is an ActiveRecord relation.
+
+What if you do not want to search in the DB? For example, say that your records
+are indexed by Elasticsearch or something like that. You can still search
+in your external index and convert the results to an ActiveRecord relation.
+Here's an example:
+
+```ruby
+    def filter_resources(resources, search_term:)
+      # Run the search term through your search facility
+      results = MySuperDuperSearchSystem.search_people(search_term)
+
+      # Collect the ids of the results. This assumes that they will
+      # be the same ones as in the DB.
+      record_ids = results.entries.map(&:id)
+
+      # Use the ids to create an ActiveRecord relation and return it
+      People.where(id: record_ids)
+    end
+```
+
+Note though: the records must still exist in the DB. Administrate does
+require ActiveRecord in order to show tables, and to display, create and edit
+records.
+
+## A working example
+
+The [Administrate demo app](https://administrate-demo.herokuapp.com/admin)
+includes an example of custom search in the "Log Entries" dashboard.
+In this app, each `LogEntry` instance has a polymorphic `belongs_to`
+association to a `:logeable`. Logeables are other models for which logs can be
+created. At the moment these are `Order` and `Customer`.
+
+Administrate's default search is not able to search across polymorphic
+associations, and therefore it is not possible to search logs by the contents
+of their logeables. Fortunately this can be fixed with a custom search. This is
+done by implementing `Admin::LogEntriesController#filter_resources` to override
+the default search. You can see the code at
+https://github.com/thoughtbot/administrate/blob/main/spec/example_app/app/controllers/admin/log_entries_controller.rb

data/docs/guides/hiding_dashboards_from_sidebar.md

@@ -0,0 +1,21 @@
+---
+title: Hiding Dashboards from the Sidebar
+---
+
+Resources can be removed from 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/scoping_has_many_relations.md

@@ -0,0 +1,27 @@
+---
+title: Scoping HasMany Relations
+---
+
+To show a subset of a has_many relationship, create a new [has_many](https://apidock.com/rails/ActiveRecord/Associations/ClassMethods/has_many) relationship in your model (using the `scope` argument) and add it to the model's dashboard.
+
+## Creating a scoped has_many relationship
+
+Models can define subsets of a `has_many` relationship by passing a callable (i.e. proc or lambda) as its second argument.
+
+```ruby
+class Customer < ApplicationRecord
+   has_many :orders
+   has_many :processed_orders, ->{ where(processed: true) }, class_name: "Order"
+```
+
+Since ActiveRecord infers the class name from the first argument, the new `has_many` relation needs to specify the model using the `class_name` option.
+
+## Add new relationship to dashboard
+
+Your new scoped relation can be used in the dashboard just like the original `HasMany`. Notice the new field needs to specifiy the class name as an option like you did in the model.
+
+```ruby
+ATTRIBUTE_TYPES = {
+  orders: Field::HasMany,
+  processed_orders: Field::HasMany.with_options(class_name: 'Order')
+```

data/docs/guides.md

@@ -0,0 +1,7 @@
+---
+title: Guides
+---
+
+- [Hiding Dashboards from the Sidebar](./guides/hiding_dashboards_from_sidebar)
+- [Customising the search](./guides/customising_search)
+- [Scoping HasMany Relations](./guides/scoping_has_many_relations.md)

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
@@ -37,13 +50,37 @@ module Administrate
       attribute_types.keys
     end
 
-    def form_attributes
-      self.class::FORM_ATTRIBUTES
+    def form_attributes(action = nil)
+      action =
+        case action
+        when "update" then "edit"
+        when "create" then "new"
+        else action
+        end
+      specific_form_attributes_for(action) || self.class::FORM_ATTRIBUTES
     end
 
-    def permitted_attributes
-      form_attributes.map do |attr|
-        attribute_types[attr].permitted_attribute(attr)
+    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(action = nil)
+      attributes = form_attributes action
+
+      if attributes.is_a? Hash
+        attributes = attributes.values.flatten
+      end
+
+      attributes.map do |attr|
+        attribute_types[attr].permitted_attribute(
+          attr,
+          resource_class: self.class.model,
+          action: action,
+        )
       end.uniq
     end
 
@@ -52,7 +89,17 @@ module Administrate
     end
 
     def collection_attributes
-      self.class::COLLECTION_ATTRIBUTES
+      if self.class::COLLECTION_ATTRIBUTES.is_a?(Hash)
+        self.class::COLLECTION_ATTRIBUTES.values.flatten
+      else
+        self.class::COLLECTION_ATTRIBUTES
+      end
+    end
+
+    def search_attributes
+      attribute_types.keys.select do |attribute|
+        attribute_types[attribute].searchable?
+      end
     end
 
     def display_resource(resource)
@@ -64,27 +111,39 @@ module Administrate
     end
 
     def item_includes
+      # Deprecated, internal usage has moved to #item_associations
+      Administrate.warn_of_deprecated_method(self.class, :item_includes)
       attribute_includes(show_page_attributes)
     end
 
+    def item_associations
+      attributes = if show_page_attributes.is_a?(Hash)
+                     show_page_attributes.values.flatten
+                   else
+                     show_page_attributes
+                   end
+      attribute_associated attributes
+    end
+
     private
 
     def attribute_not_found_message(attr)
       "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 }
+    def attribute_includes(attributes)
+      attributes.map do |key|
+        field = attribute_type_for(key)
+
+        key if field.eager_load?
+      end.compact
     end
 
-    def attribute_includes(attributes)
+    def attribute_associated(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

@@ -1,11 +1,11 @@
-require "datetime_picker_rails"
 require "jquery-rails"
 require "kaminari"
-require "momentjs-rails"
 require "sassc-rails"
 require "selectize-rails"
 require "sprockets/railtie"
 
+require "administrate/namespace/resource"
+require "administrate/not_authorized_error"
 require "administrate/page/form"
 require "administrate/page/show"
 require "administrate/page/collection"
@@ -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,84 @@ 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.association_primary_key_for(resource_class, attr)
+        reflection(resource_class, attr).association_primary_key
+      end
+
+      def self.associated_class(resource_class, attr)
+        reflection(resource_class, attr).klass
+      end
+
+      def self.associated_class_name(resource_class, attr)
+        associated_class(resource_class, attr).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
+      def associated_class_name
+        if option_given?(:class_name)
+          deprecated_option(:class_name)
+        else
+          self.class.associated_class_name(
+            resource.class,
+            attribute,
+          )
+        end
+      end
+
+      private
 
       def associated_dashboard
         "#{associated_class_name}Dashboard".constantize.new
       end
 
-      def associated_class_name
-        options.fetch(:class_name, attribute.to_s.singularize.camelcase)
+      def primary_key
+        # Deprecated, renamed `association_primary_key`
+        Administrate.warn_of_deprecated_method(self.class, :primary_key)
+        association_primary_key
       end
 
-      def primary_key
-        options.fetch(:primary_key, :id)
+      def association_primary_key
+        if option_given?(:primary_key)
+          deprecated_option(:primary_key)
+        else
+          self.class.association_primary_key_for(resource.class, attribute)
+        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,26 @@ module Administrate
         field_type.dasherize
       end
 
+      def self.associative?
+        self < Associative
+      end
+
+      def self.eager_load?
+        false
+      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 +40,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 +52,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