administrate 0.17.0 → 0.18.0

data/docs/authorization.md

@@ -49,23 +49,36 @@ end
 
 ## Authorization without Pundit
 
-If you use a different authorization library, or you want to roll your own,
-you just need to override a few methods in your controllers or
-`Admin::ApplicationController`. For example:
+Pundit is not necessary to implement authorization within Administrate. It is
+simply a common solution that many in the community use, and for this reason
+Administrate provides a plugin to work with it. However you can use a different
+solution or roll out your own.
+
+To integrate a different authorization solution, you will need to
+implement some methods in `Admin::ApplicationController`
+or its subclasses.
+
+These are the methods to override, with examples:
 
 ```ruby
-# Limit the scope of the given resource
+# Used in listings, such as the `index` actions. It
+# restricts the scope of records that a user can access.
+# Returns an ActiveRecord scope.
 def scoped_resource
   super.where(user: current_user)
 end
 
-# Raise an exception if the user is not permitted to access this resource
-def authorize_resource(resource)
-  raise "Erg!" unless show_action?(params[:action], resource)
-end
-
-# Hide links to actions if the user is not allowed to do them
-def show_action?(action, resource)
-  current_user.can? action, resource
+# Return true if the current user can access the given
+# resource, false otherwise.
+def authorized_action?(resource, action)
+  current_user.can?(resource, action)
 end
 ```
+
+Additionally, the method `authorize_resource(resource)`
+should throw an exception if the current user is not
+allowed to access the given resource. Normally
+you wouldn't need to override it, as the default
+implementation uses `authorized_action?` to produce the
+correct behaviour. However you may still want to override it
+if you want to raise a custom error type.

data/docs/customizing_controller_actions.md

@@ -46,17 +46,22 @@ end
 
 ## Customizing Actions
 
-To enable or disable certain actions you could override `valid_action?` method in your dashboard controller like this:
+To disable certain actions globally, you can disable their
+routes in `config/routes.rb`, using the usual Rails
+facilities for this. For example:
 
 ```ruby
-# disable 'edit' and 'destroy' links
-def valid_action?(name, resource = resource_class)
-  %w[edit destroy].exclude?(name.to_s) && super
+Rails.application.routes.draw do
+  # ...
+  namespace :admin do
+    # ...
+
+    # Payments can only be listed or displayed
+    resources :payments, only: [:index, :show]
+  end
 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:

data/docs/customizing_dashboards.md

@@ -77,8 +77,9 @@ which are specified through the `.with_options` class method:
 
 **Field::BelongsTo**
 
-`:order` - Specifies the order of the dropdown menu, can be ordered by more
-than one column. e.g.: `"name, email DESC"`.
+`:order` - Specifies the column used to order the records. It will apply both in
+the table views and in the dropdown menu on the record forms.
+You can set multiple columns as well with direction. E.g.: `"name, email DESC"`.
 
 `:scope` - Specifies a custom scope inside a callable. Useful for preloading.
 Example: `.with_options(scope: -> { MyModel.includes(:rel).limit(5) })`
@@ -220,6 +221,17 @@ objects to display as.
 `:collection` - Specify the options shown on the select field. It accept either
 an array or an object responding to `:call`. Defaults to `[]`.
 
+To customize option labels, pass an array of pairs where the first element is the value submitted with the form and the second element is the label shown to the user.
+
+For example:
+
+```ruby
+  currency = Field::Select.with_options(
+    collection: [ ['usd', 'Dollar'], ['eur', 'Euro'], ['yen', 'Yen'] ]
+  )
+
+```
+
 `:searchable` - Specify if the attribute should be considered when searching.
 Default is `true`.
 
@@ -250,6 +262,9 @@ Default is `true`.
 `:truncate` - Set the number of characters to display in the index view.
 Defaults to `50`.
 
+`:html_options` - Specify anchor tag attributes (e.g., `target="_blank"`).
+Defaults is `{}`.
+
 **Field::Password**
 
 `:searchable` - Specify if the attribute should be considered when searching.

data/docs/getting_started.md

@@ -3,7 +3,7 @@ title: Getting Started
 ---
 
 Administrate is released as a Ruby gem, and can be installed on Rails
-applications version 5.0 or greater. We support Ruby 2.6 and up.
+applications version 5.0 or greater. We support Ruby 2.7 and up.
 
 First, add the following to your Gemfile:
 

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](/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

@@ -94,9 +94,15 @@ 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
+      attribute_associated(show_page_attributes)
+    end
+
     private
 
     def attribute_not_found_message(attr)
@@ -104,6 +110,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

@@ -12,7 +12,7 @@ module Administrate
       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 +31,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,6 +42,12 @@ module Administrate
         end
       end
 
+      private
+
+      def associated_dashboard
+        "#{associated_class_name}Dashboard".constantize.new
+      end
+
       def primary_key
         if option_given?(:primary_key)
           deprecated_option(:primary_key)

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,6 +13,10 @@ module Administrate
         end
       end
 
+      def self.eager_load?
+        true
+      end
+
       def permitted_attribute
         foreign_key
       end

data/lib/administrate/field/deferred.rb

@@ -25,6 +25,10 @@ module Administrate
         deferred_class.associative?
       end
 
+      def eager_load?
+        deferred_class.eager_load?
+      end
+
       def searchable?
         options.fetch(:searchable, deferred_class.searchable?)
       end

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/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,18 @@
+module Administrate
+  class NotAuthorizedError < StandardError
+    def initialize(action:, resource:)
+      @action = action
+      @resource = resource
+
+      case resource
+      when Module, String, Symbol
+        super("Not allowed to perform #{action.inspect} on #{resource.inspect}")
+      else
+        super(
+          "Not allowed to perform #{action.inspect} on the given " +
+            resource.class.name
+        )
+      end
+    end
+  end
+end

data/lib/administrate/order.rb

@@ -1,8 +1,9 @@
 module Administrate
   class Order
-    def initialize(attribute = nil, direction = nil)
+    def initialize(attribute = nil, direction = nil, association_attribute: nil)
       @attribute = attribute
       @direction = sanitize_direction(direction)
+      @association_attribute = association_attribute
     end
 
     def apply(relation)
@@ -12,7 +13,7 @@ module Administrate
       order = "#{relation.table_name}.#{attribute} #{direction}"
 
       return relation.reorder(Arel.sql(order)) if
-        relation.columns_hash.keys.include?(attribute.to_s)
+        column_exist?(relation, attribute)
 
       relation
     end
@@ -32,7 +33,7 @@ module Administrate
 
     private
 
-    attr_reader :attribute
+    attr_reader :attribute, :association_attribute
 
     def sanitize_direction(direction)
       %w[asc desc].include?(direction.to_s) ? direction.to_sym : :asc
@@ -53,7 +54,7 @@ module Administrate
     def order_by_association(relation)
       return order_by_count(relation) if has_many_attribute?(relation)
 
-      return order_by_id(relation) if belongs_to_attribute?(relation)
+      return order_by_attribute(relation) if belongs_to_attribute?(relation)
 
       relation
     end
@@ -68,7 +69,36 @@ module Administrate
     end
 
     def order_by_id(relation)
-      relation.reorder("#{foreign_key(relation)} #{direction}")
+      relation.reorder(Arel.sql(order_by_id_query(relation)))
+    end
+
+    def order_by_attribute(relation)
+      if ordering_by_association_column?(relation)
+        relation.joins(
+          attribute.to_sym,
+        ).reorder(Arel.sql(order_by_attribute_query))
+      else
+        order_by_id(relation)
+      end
+    end
+
+    def ordering_by_association_column?(relation)
+      association_attribute &&
+        column_exist?(
+          reflect_association(relation).klass, association_attribute.to_sym
+        )
+    end
+
+    def column_exist?(table, column_name)
+      table.columns_hash.key?(column_name.to_s)
+    end
+
+    def order_by_id_query(relation)
+      "#{relation.table_name}.#{foreign_key(relation)} #{direction}"
+    end
+
+    def order_by_attribute_query
+      "#{attribute.tableize}.#{association_attribute} #{direction}"
     end
 
     def has_many_attribute?(relation)

data/lib/administrate/page/base.rb

@@ -23,6 +23,10 @@ module Administrate
         dashboard.try(:item_includes) || []
       end
 
+      def item_associations
+        dashboard.try(:item_associations) || []
+      end
+
       private
 
       def attribute_field(dashboard, resource, attribute_name, page)

data/lib/administrate/version.rb

@@ -1,3 +1,3 @@
 module Administrate
-  VERSION = "0.17.0".freeze
+  VERSION = "0.18.0".freeze
 end

data/lib/administrate.rb

@@ -20,4 +20,22 @@ module Administrate
       "if you think otherwise.",
     )
   end
+
+  def self.warn_of_deprecated_method(klass, method)
+    ActiveSupport::Deprecation.warn(
+      "The method #{klass}##{method} is deprecated. " +
+      "If you are seeing this message you are probably " +
+      "using a dashboard that depends explicitly on it. " +
+      "Please make sure you update it to a version that " +
+      "does not use a deprecated API",
+    )
+  end
+
+  def self.warn_of_deprecated_authorization_method(method)
+    ActiveSupport::Deprecation.warn(
+      "The method `#{method}` is deprecated. " +
+      "Please use `accessible_action?` instead, " +
+      "or see the documentation for other options.",
+    )
+  end
 end

data/lib/generators/administrate/dashboard/dashboard_generator.rb

@@ -53,9 +53,22 @@ module Administrate
       end
 
       def attributes
-        klass.reflections.keys +
+        attrs = (
+          klass.reflections.keys +
           klass.columns.map(&:name) -
           redundant_attributes
+        )
+
+        primary_key = attrs.delete(klass.primary_key)
+        created_at = attrs.delete("created_at")
+        updated_at = attrs.delete("updated_at")
+
+        [
+          primary_key,
+          *attrs.sort,
+          created_at,
+          updated_at,
+        ].compact
       end
 
       def form_attributes