administrate 0.17.0 → 0.19.0

data/app/views/fields/has_one/_index.html.erb

@@ -16,7 +16,8 @@ By default, the relationship is rendered as a link to the associated object.
 %>
 
 <% if field.linkable? %>
-  <%= link_to(
+  <%= link_to_if(
+    accessible_action?(field.data, :show),
     field.display_associated_resource,
     [namespace, field.data],
   ) %>

data/app/views/fields/has_one/_show.html.erb

@@ -18,7 +18,8 @@ All show page attributes of has_one relationship would be rendered
 <% if field.linkable? %>
   <fieldset class="attribute--nested">
     <legend>
-      <%= link_to(
+      <%= link_to_if(
+        accessible_action?(field.data, :show),
         field.display_associated_resource,
         [namespace, field.data],
       ) %>
@@ -27,7 +28,7 @@ All show page attributes of has_one relationship would be rendered
       <div>
       <dt class="attribute-label">
         <%= t(
-          "helpers.label.#{resource_name}.#{attribute.name}",
+          "helpers.label.#{field.associated_class_name.underscore}.#{attribute.name}",
           default: attribute.name.titleize,
         ) %>
       </dt>

data/app/views/fields/polymorphic/_index.html.erb

@@ -17,7 +17,8 @@ By default, the relationship is rendered as a link to the associated object.
 %>
 
 <% if field.data %>
-  <%= link_to(
+  <%= link_to_if(
+    accessible_action?(field.data, :show),
     field.display_associated_resource,
     [namespace, field.data]
   ) %>

data/app/views/fields/polymorphic/_show.html.erb

@@ -17,7 +17,7 @@ By default, the relationship is rendered as a link to the associated object.
 %>
 
 <% if field.data %>
-  <% if valid_action?(:show, field.data.class) %>
+  <% if accessible_action?(field.data, :show) %>
     <%= link_to(
       field.display_associated_resource,
       [namespace, field.data],

data/app/views/fields/select/_form.html.erb

@@ -19,27 +19,14 @@ to be displayed on a resource's edit form page.
   <%= f.label field.attribute %>
 </div>
 <div class="field-unit__field">
-  <% if field.selectable_options.first&.is_a?(Array) %>
-    <%= f.select(
+  <%=
+    f.select(
       field.attribute,
-      options_from_collection_for_select(
+      options_for_select(
         field.selectable_options,
-        :last,
-        :first,
         field.data,
       ),
       include_blank: field.include_blank_option
-    ) %>
-  <% else %>
-    <%= f.select(
-      field.attribute,
-      options_from_collection_for_select(
-        field.selectable_options,
-        :to_s,
-        :to_s,
-        field.data,
-      ),
-      include_blank: field.include_blank_option
-    ) %>
-  <% end %>
+    )
+  %>
 </div>

data/app/views/fields/time/_form.html.erb

@@ -2,7 +2,6 @@
 # Time Form Partial
 
 This partial renders an input element for time attributes.
-By default, the input is a text field that is augmented with [DateTimePicker].
 
 ## Local variables:
 
@@ -12,12 +11,12 @@ By default, the input is a text field that is augmented with [DateTimePicker].
   An instance of [Administrate::Field::Time][1].
   A wrapper around the tmie attributes pulled from the model.
 
-[DateTimePicker]: https://github.com/Eonasdan/bootstrap-datetimepicker
+[1]: http://www.rubydoc.info/gems/administrate/Administrate/Field/Time
 %>
 
 <div class="field-unit__label">
   <%= f.label field.attribute %>
 </div>
 <div class="field-unit__field">
-  <%= f.text_field field.attribute, data: { type: 'time' }, value: field.data&.strftime("%H:%M:%S") %>
+  <%= f.time_field field.attribute, step: 1 %>
 </div>

data/app/views/fields/url/_index.html.erb

@@ -15,6 +15,6 @@ By default, the value is rendered as an `a` element.
 [1]: http://www.rubydoc.info/gems/administrate/Administrate/Field/Url
 %>
 
-<%= content_tag :a, href: field.data do %>
+<%= content_tag :a, href: field.data, **field.html_options do %>
   <%= field.data %>
 <% end %>

data/app/views/fields/url/_show.html.erb

@@ -15,6 +15,6 @@ By default, the value is rendered as an `a` element.
 [1]: http://www.rubydoc.info/gems/administrate/Administrate/Field/Url
 %>
 
-<%= content_tag :a, href: field.data do %>
+<%= content_tag :a, href: field.data, **field.html_options do %>
   <%= field.data %>
 <% end %>

data/app/views/layouts/administrate/application.html.erb

@@ -31,7 +31,7 @@ By default, it renders:
   <div class="app-container">
     <%= render "navigation" -%>
 
-    <main class="main-content" role="main">
+    <main class="main-content">
       <%= render "flashes" -%>
       <%= yield %>
     </main>

data/config/locales/administrate.de.yml

@@ -21,8 +21,8 @@ de:
         more: "%{count} von %{total_count}"
         none: Keine
     form:
-      error: error
-      errors: "%{pluralized_errors} haben das Speichern dieses %{resource_name} verhindert:"
+      error: Fehler
+      errors: "%{resource_name} konnte nicht gespeichert werden, es gab %{pluralized_errors}."
     navigation:
       back_to_app: Zurück zur App
     search:

data/config/locales/administrate.ja.yml

@@ -5,9 +5,9 @@ ja:
       confirm: 本当によろしいですか？
       destroy: 削除
       edit: 編集
-      edit_resource: 編集 %{name}
-      show_resource: 参照 %{name}
-      new_resource: 新規 %{name}
+      edit_resource: "%{name}を編集"
+      show_resource: "%{name}を参照"
+      new_resource: "%{name}を作成"
       back: 戻る
     controller:
       create:
@@ -22,9 +22,9 @@ ja:
         none: データがありません
     form:
       error: エラー
-      errors: "%{pluralized_errors}のため%{resource_name}を保存できません。"
+      errors: "%{pluralized_errors}のため%{resource_name}を保存できませんでした。"
     navigation:
       back_to_app: アプリに戻る
     search:
       clear: 検索をクリアする
-      label: サーチ %{resource}
+      label: "%{resource}を検索"

data/config/locales/administrate.sl.yml

@@ -0,0 +1,30 @@
+---
+sl:
+  administrate:
+    actions:
+      confirm: Ali ste preričani?
+      destroy: Izbriši
+      edit: Uredi
+      edit_resource: Uredi %{name}
+      show_resource: Prikaži %{name}
+      new_resource: Dodaj %{name}
+      back: Nazaj
+    controller:
+      create:
+        success: "%{resource} je dodan."
+      destroy:
+        success: "%{resource} je izbrisan."
+      update:
+        success: "%{resource} je posodobljen."
+    fields:
+      has_many:
+        more: Prikazanih %{count} od %{total_count}
+        none: Nobene
+    form:
+      error: napaka
+      errors: "%{resource_name} ni mogoče shraniti zaradi:"
+    navigation:
+      back_to_app: Nazaj v aplikacijo
+    search:
+      clear: Počisti iskanje
+      label: Išči %{resource}

data/docs/adding_controllers_without_related_model.md

@@ -14,9 +14,9 @@ routes are displayed in the sidebar and then add a custom dashboard:
 <div style="padding: 20px">
   <h1>Stats</h1>
   <br>
-  <p><b>Total Customers:</b> <%= @stats[:customer_count] %></h1>
+  <p><b>Total Customers:</b> <%= @stats[:customer_count] %></p>
   <br>
-  <p><b>Total Orders:</b> <%= @stats[:order_count] %></h1>
+  <p><b>Total Orders:</b> <%= @stats[:order_count] %></p>
 </div>
 ```
 

data/docs/authorization.md

@@ -28,20 +28,30 @@ technically have access to see in the main app. For example, a user may
 have all public records in their scope, but you want to only show *their*
 records in the admin interface to reduce confusion.
 
-In this case, you can add an additional `resolve_admin` to your policy's
-scope and Administrate will use this instead of the `resolve` method.
+In this case, you can add additional pundit `policy_namespace` in your controller
+and Administrate will use the namespaced pundit policy instead.
 
 For example:
 
 ```ruby
-class PostPolicy < ApplicationPolicy
-  class Scope < Scope
-    def resolve
-      scope.all
+# app/controllers/admin/posts_controller.rb
+module Admin
+  class PostsController < ApplicationController
+    include Administrate::Punditize
+
+    def policy_namespace
+      [:admin]
     end
+  end
+end
 
-    def resolve_admin
-      scope.where(owner: user)
+# app/policies/admin/post_policy.rb
+module Admin
+  class PostPolicy < ApplicationPolicy
+    class Scope < Scope
+      def resolve
+        scope.where(owner: user)
+      end
     end
   end
 end
@@ -49,23 +59,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) })`
@@ -112,8 +113,8 @@ association `belongs_to :country`, from your model.
 
 **Field::HasMany**
 
-`:limit` - Set the number of resources to display in the show view. Default is
-`5`.
+`:limit` - The number of resources (paginated) to display in the show view. To disable pagination,
+set this to `0` or `false`. Default is `5`.
 
 `:sort_by` - What to sort the association by in the show view.
 
@@ -127,6 +128,10 @@ association `belongs_to :country`, from your model.
 
 **Field::HasOne**
 
+`: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"`.
+
 `:searchable` - Specify if the attribute should be considered when searching.
 Default is `false`.
 
@@ -217,14 +222,31 @@ objects to display as.
 
 **Field::Select**
 
-`:collection` - Specify the options shown on the select field. It accept either
-an array or an object responding to `:call`. Defaults to `[]`.
+`:collection` - The options available to select. The format is the same as for Rails's own [`options_for_select`](https://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-options_for_select).
+
+If the given value responds to `call`, this will be called and the result used instead. The call will receive an instance of the field as argument. For example:
+
+```ruby
+  confirmation: Field::Select.with_options(
+    collection: ->(field) {
+      person = field.resource
+      {
+        "no, #{person.name}" => "opt0",
+        "yes, #{person.name}" => "opt1",
+        "absolutely, #{person.name}" => "opt2",
+      }
+    },
+  )
+```
+
+Administrate will detect if the attribute is an `ActiveRecord::Enum` and extract the available options. Note that if a `collection` is provided it will take precedence.
+
+If no collection is provided and no enum can be detected, the list of options will be empty.
 
 `: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`.
+`:include_blank` - Similar to [the option of the same name accepted by Rails helpers](https://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html). If provided, a "blank" option will be added first to the list of options, with the value of `include_blank` as label.
 
 **Field::String**
 
@@ -250,6 +272,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 6.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](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)