administrate 0.17.0 → 0.20.0

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

@@ -2,7 +2,8 @@
 title: Hiding Dashboards from the Sidebar
 ---
 
-Resources can be removed form the sidebar by removing their index action from the routes. For example:
+Resources can be removed from the sidebar by removing their `index` action
+from the routes. For example:
 
 ```ruby
 # config/routes.rb
@@ -16,4 +17,5 @@ Rails.application.routes.draw do
 end
 ```
 
-In this case, only Orders and Products will appear in the sidebar, while Line Items can still appear as an association.
+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

@@ -2,4 +2,6 @@
 title: Guides
 ---
 
-* [Hiding Dashboards from the Sidebar](./guides/hiding_dashboards_from_sidebar)
+- [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/lib/administrate/base_dashboard.rb

@@ -51,6 +51,12 @@ module Administrate
     end
 
     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
 
@@ -62,11 +68,18 @@ module Administrate
       self.class.const_get(cname) if self.class.const_defined?(cname)
     end
 
-    def permitted_attributes
-      form_attributes.map do |attr|
+    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
@@ -76,7 +89,11 @@ 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
@@ -94,9 +111,20 @@ 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)
@@ -104,6 +132,14 @@ module Administrate
     end
 
     def attribute_includes(attributes)
+      attributes.map do |key|
+        field = attribute_type_for(key)
+
+        key if field.eager_load?
+      end.compact
+    end
+
+    def attribute_associated(attributes)
       attributes.map do |key|
         field = attribute_type_for(key)
 

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"

data/lib/administrate/field/associative.rb

@@ -7,12 +7,16 @@ module Administrate
         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)
-        reflection(resource_class, attr).class_name
+        associated_class(resource_class, attr).name
       end
 
       def self.reflection(resource_class, attr)
@@ -31,12 +35,6 @@ module Administrate
         end
       end
 
-      private
-
-      def associated_dashboard
-        "#{associated_class_name}Dashboard".constantize.new
-      end
-
       def associated_class_name
         if option_given?(:class_name)
           deprecated_option(:class_name)
@@ -48,11 +46,23 @@ module Administrate
         end
       end
 
+      private
+
+      def associated_dashboard
+        "#{associated_class_name}Dashboard".constantize.new
+      end
+
       def primary_key
+        # Deprecated, renamed `association_primary_key`
+        Administrate.warn_of_deprecated_method(self.class, :primary_key)
+        association_primary_key
+      end
+
+      def association_primary_key
         if option_given?(:primary_key)
           deprecated_option(:primary_key)
         else
-          :id
+          self.class.association_primary_key_for(resource.class, attribute)
         end
       end
 

data/lib/administrate/field/base.rb

@@ -16,6 +16,10 @@ module Administrate
         self < Associative
       end
 
+      def self.eager_load?
+        false
+      end
+
       def self.searchable?
         false
       end

data/lib/administrate/field/belongs_to.rb

@@ -13,18 +13,25 @@ module Administrate
         end
       end
 
+      def self.eager_load?
+        true
+      end
+
       def permitted_attribute
         foreign_key
       end
 
       def associated_resource_options
         candidate_resources.map do |resource|
-          [display_candidate_resource(resource), resource.send(primary_key)]
+          [
+            display_candidate_resource(resource),
+            resource.send(association_primary_key),
+          ]
         end
       end
 
       def selected_option
-        data && data.send(primary_key)
+        data&.send(association_primary_key)
       end
 
       def include_blank_option

data/lib/administrate/field/deferred.rb

@@ -25,12 +25,16 @@ module Administrate
         deferred_class.associative?
       end
 
+      def eager_load?
+        deferred_class.eager_load?
+      end
+
       def searchable?
         options.fetch(:searchable, deferred_class.searchable?)
       end
 
       def searchable_field
-        ActiveSupport::Deprecation.warn(
+        Administrate.deprecator.warn(
           "searchable_field is deprecated, use searchable_fields instead",
         )
         options.fetch(:searchable_field)

data/lib/administrate/field/has_many.rb

@@ -22,7 +22,11 @@ module Administrate
       end
 
       def associated_collection(order = self.order)
-        Administrate::Page::Collection.new(associated_dashboard, order: order)
+        Administrate::Page::Collection.new(
+          associated_dashboard,
+          order: order,
+          collection_attributes: options[:collection_attributes],
+        )
       end
 
       def attribute_key
@@ -30,21 +34,28 @@ module Administrate
       end
 
       def associated_resource_options
-        candidate_resources.map do |resource|
-          [display_candidate_resource(resource), resource.send(primary_key)]
+        candidate_resources.map do |associated_resource|
+          [
+            display_candidate_resource(associated_resource),
+            associated_resource.send(association_primary_key),
+          ]
         end
       end
 
       def selected_options
         return if data.empty?
 
-        data.map { |object| object.send(primary_key) }
+        data.map { |object| object.send(association_primary_key) }
       end
 
       def limit
         options.fetch(:limit, DEFAULT_LIMIT)
       end
 
+      def paginate?
+        limit.respond_to?(:positive?) ? limit.positive? : limit.present?
+      end
+
       def permitted_attribute
         self.class.permitted_attribute(
           attribute,
@@ -53,12 +64,15 @@ module Administrate
       end
 
       def resources(page = 1, order = self.order)
-        resources = order.apply(data).page(page).per(limit)
+        resources = order.apply(data)
+        if paginate?
+          resources = resources.page(page).per(limit)
+        end
         includes.any? ? resources.includes(*includes) : resources
       end
 
       def more_than_limit?
-        data.count(:all) > limit
+        paginate? && data.count(:all) > limit
       end
 
       def data

data/lib/administrate/field/has_one.rb

@@ -26,6 +26,10 @@ module Administrate
         { "#{attr}_attributes": related_dashboard_attributes }
       end
 
+      def self.eager_load?
+        true
+      end
+
       def nested_form
         @nested_form ||= Administrate::Page::Form.new(
           resolver.dashboard_class.new,

data/lib/administrate/field/number.rb

@@ -38,14 +38,8 @@ module Administrate
         formatter = options[:format][:formatter]
         formatter_options = options[:format][:formatter_options].to_h
 
-        case formatter
-        when :number_to_delimited
-          ActiveSupport::NumberHelper.number_to_delimited(
-            result, **formatter_options
-          )
-        else
-          result
-        end
+        ActiveSupport::NumberHelper.
+          try(formatter, result, **formatter_options) || result
       end
     end
   end

data/lib/administrate/field/polymorphic.rb

@@ -30,7 +30,8 @@ module Administrate
       end
 
       def classes
-        options.fetch(:classes, [])
+        klasses = options.fetch(:classes, [])
+        klasses.respond_to?(:call) ? klasses.call : klasses
       end
 
       private

data/lib/administrate/field/select.rb

@@ -8,22 +8,32 @@ module Administrate
       end
 
       def selectable_options
-        collection
+        values =
+          if options.key?(:collection)
+            options.fetch(:collection)
+          elsif active_record_enum?
+            active_record_enum_values
+          else
+            []
+          end
+
+        if values.respond_to? :call
+          values = values.arity.positive? ? values.call(self) : values.call
+        end
+
+        values
       end
 
       def include_blank_option
         options.fetch(:include_blank, false)
       end
 
-      private
-
-      def collection
-        values = options.fetch(:collection, [])
-        if values.respond_to? :call
-          return values.arity.positive? ? values.call(self) : values.call
-        end
+      def active_record_enum?
+        resource.class.defined_enums.key?(attribute.to_s)
+      end
 
-        @collection ||= values
+      def active_record_enum_values
+        resource.class.defined_enums[attribute.to_s].map(&:first)
       end
     end
   end

data/lib/administrate/field/url.rb

@@ -11,6 +11,10 @@ module Administrate
         data.to_s[0...truncation_length]
       end
 
+      def html_options
+        @options[:html_options] || {}
+      end
+
       private
 
       def truncation_length

data/lib/administrate/not_authorized_error.rb

@@ -0,0 +1,20 @@
+module Administrate
+  class NotAuthorizedError < StandardError
+    def initialize(action:, resource:)
+      @action = action
+      @resource = resource
+
+      case resource
+      when String, Symbol
+        super("Not allowed to perform #{action.inspect} on #{resource.inspect}")
+      when Module
+        super("Not allowed to perform #{action.inspect} on #{resource.name}")
+      else
+        super(
+          "Not allowed to perform #{action.inspect} on the given " +
+            resource.class.name
+        )
+      end
+    end
+  end
+end