administrate 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6711a800e61649dffc4e96f9ddfaf3af21d364a1cfc659959dc5496357af262
-  data.tar.gz: 3dc0046165d843a60359343d756b584cb7d5a8a505c5ba4c2858749b4aceba28
+  metadata.gz: eebcadb06ece9944279b1119e950922a388078a5c9ab5b95d6d8863c1e03994d
+  data.tar.gz: 96a697e2e10228a5f2772b1602985107f7ed428ca63d77c7d6e964a614659b9d
 SHA512:
-  metadata.gz: 88099b1defc211784c017a82dc2a4f90d91599f664a768acb652dd5a9ac3358b00180bc1f7da7b072e26cb1412b967fb7c244096005ee782fb1719340a832f3b
-  data.tar.gz: 2d01b4c1131ed1a7c2d9f70756c5d9b0b442abf846425c486ae0d9b5ee6d65c9d3e0e3f45b1d9864749c6901cc29cc90f3261c229ba8ba96e26ee552f92e9d88
+  metadata.gz: da130cb7cdcfd15321a653a59cfb499411f85324c19216097a6f4a76407268cc6691647e2ccdf86c367bd6c2e1491342324de89e22c9152eddbea8e6ba32b819
+  data.tar.gz: 8813f237457fa4e37abf8d5c350e4fb4f8f536583a6919764bc5c2abb0bc3b3fc436431b41e731722045179c45dcfef0d4c45d8c5534e7d26ee52d151252665f

data/app/assets/javascripts/administrate/components/select.js

@@ -0,0 +1,3 @@
+$(function() {
+  $('.field-unit--select select').selectize({});
+});

data/app/assets/stylesheets/administrate/components/_field-unit.scss

@@ -2,6 +2,7 @@
   @include administrate-clearfix;
   align-items: center;
   display: flex;
+  flex-wrap: wrap;
   margin-bottom: $base-spacing;
   position: relative;
   width: 100%;
@@ -25,6 +26,12 @@
   }
 }
 
+.field-unit__hint {
+  font-size: 90%;
+  margin-left: calc(15% + 2rem);
+  width: 100%;
+}
+
 .field-unit--nested {
   border: $base-border;
   margin-left: 7.5%;

data/app/controllers/administrate/application_controller.rb

@@ -40,10 +40,11 @@ module Administrate
     end
 
     def create
-      resource = resource_class.new(resource_params)
+      resource = new_resource(resource_params)
       authorize_resource(resource)
 
       if resource.save
+        yield(resource) if block_given?
         redirect_to(
           after_resource_created_path(resource),
           notice: translate_with_resource("create.success"),
@@ -201,7 +202,7 @@ module Administrate
 
     def resource_params
       params.require(resource_class.model_name.param_key).
-        permit(dashboard.permitted_attributes).
+        permit(dashboard.permitted_attributes(action_name)).
         transform_values { |v| read_param_value(v) }
     end
 
@@ -214,6 +215,8 @@ module Administrate
         end
       elsif data.is_a?(ActionController::Parameters)
         data.transform_values { |v| read_param_value(v) }
+      elsif data.is_a?(String) && data.blank?
+        nil
       else
         data
       end
@@ -265,8 +268,8 @@ module Administrate
     end
     helper_method :show_action?
 
-    def new_resource
-      resource_class.new
+    def new_resource(params = {})
+      resource_class.new(params)
     end
     helper_method :new_resource
 

data/app/controllers/concerns/administrate/punditize.rb

@@ -2,37 +2,59 @@ module Administrate
   module Punditize
     if Object.const_defined?("Pundit")
       extend ActiveSupport::Concern
-      include Pundit::Authorization
 
-      included do
-        private
+      if Pundit.const_defined?(:Authorization)
+        include Pundit::Authorization
+      else
+        include Pundit
+      end
 
-        def scoped_resource
-          policy_scope_admin super
-        end
+      private
 
-        def authorize_resource(resource)
-          authorize resource
-        end
+      def policy_namespace
+        []
+      end
 
-        def authorized_action?(resource, action)
-          Pundit.policy!(pundit_user, resource).send("#{action}?".to_sym)
-        end
+      def scoped_resource
+        namespaced_scope = policy_namespace + [super]
+        policy_scope!(pundit_user, namespaced_scope)
       end
 
-      private
+      def authorize_resource(resource)
+        namespaced_resource = policy_namespace + [resource]
+        authorize namespaced_resource
+      end
 
-      # Like the policy_scope method in stock Pundit, but allows the 'resolve'
-      # to be overridden by 'resolve_admin' for a different index scope in Admin
-      # controllers.
-      def policy_scope_admin(scope)
-        ps = Pundit::PolicyFinder.new(scope).scope!.new(pundit_user, scope)
-        if ps.respond_to? :resolve_admin
-          ps.resolve_admin
+      def authorized_action?(resource, action)
+        namespaced_resource = policy_namespace + [resource]
+        policy = Pundit.policy!(pundit_user, namespaced_resource)
+        policy.send("#{action}?".to_sym)
+      end
+
+      def policy_scope!(user, scope)
+        policy_scope_class = Pundit::PolicyFinder.new(scope).scope!
+
+        begin
+          policy_scope = policy_scope_class.new(user, pundit_model(scope))
+        rescue ArgumentError
+          raise(Pundit::InvalidConstructorError,
+                "Invalid #<#{policy_scope_class}> constructor is called")
+        end
+
+        if policy_scope.respond_to? :resolve_admin
+          Administrate.deprecator.warn(
+            "Pundit policy scope `resolve_admin` method is deprecated. " +
+            "Please use a namespaced pundit policy instead.",
+          )
+          policy_scope.resolve_admin
         else
-          ps.resolve
+          policy_scope.resolve
         end
       end
+
+      def pundit_model(record)
+        record.is_a?(Array) ? record.last : record
+      end
     end
   end
 end

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

@@ -27,15 +27,14 @@ to display a collection of resources in an HTML table.
         cell-label--<%= collection_presenter.ordered_html_class(attr_name) %>
         cell-label--<%= "#{collection_presenter.resource_name}_#{attr_name}" %>"
         scope="col"
-        role="columnheader"
         aria-sort="<%= sort_order(collection_presenter.ordered_html_class(attr_name)) %>">
         <%= link_to(sanitized_order_params(page, collection_field_name).merge(
           collection_presenter.order_params_for(attr_name, key: collection_field_name)
         )) do %>
         <%= t(
           "helpers.label.#{collection_presenter.resource_name}.#{attr_name}",
-          default: resource_class.human_attribute_name(attr_name),
-        ).titleize %>
+          default: resource_class.human_attribute_name(attr_name).titleize,
+        ) %>
             <% if collection_presenter.ordered_by?(attr_name) %>
               <span class="cell-label__sort-indicator cell-label__sort-indicator--<%= collection_presenter.ordered_html_class(attr_name) %>">
                 <svg aria-hidden="true">

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

@@ -33,10 +33,25 @@ and renders all form fields for a resource's editable attributes.
     </div>
   <% end %>
 
-  <% page.attributes(controller.action_name).each do |attribute| -%>
-    <div class="field-unit field-unit--<%= attribute.html_class %> field-unit--<%= requireness(attribute) %>">
-      <%= render_field attribute, f: f %>
-    </div>
+  <% page.attributes(controller.action_name).each do |title, attributes| -%>
+    <fieldset class="<%= "field-unit--nested" if title.present? %>">
+      <% if title.present? %>
+        <legend><%= t "helpers.label.#{f.object_name}.#{title}", default: title %></legend>
+      <% end %>
+
+      <% attributes.each do |attribute| %>
+        <div class="field-unit field-unit--<%= attribute.html_class %> field-unit--<%= requireness(attribute) %>">
+          <%= render_field attribute, f: f %>
+
+          <% hint_key = "administrate.field_hints.#{page.resource_name}.#{attribute.name}" %>
+          <% if I18n.exists?(hint_key) -%>
+            <div class="field-unit__hint">
+              <%= I18n.t(hint_key) %>
+            </div>
+          <% end -%>
+        </div>
+      <% end %>
+    </fieldset>
   <% end -%>
 
   <div class="form-actions">

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

@@ -2,7 +2,7 @@
   <%= display_resource_name(page.resource_name) %>
 <% end %>
 
-<header class="main-content__header" role="banner">
+<header class="main-content__header">
   <h1 class="main-content__page-title" id="page-title">
     <%= content_for(:title) %>
   </h1>

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

@@ -7,7 +7,7 @@ for all resources in the admin dashboard,
 as defined by the routes in the `admin/` namespace
 %>
 
-<nav class="navigation" role="navigation">
+<nav class="navigation">
   <%= link_to(t("administrate.navigation.back_to_app"), root_url, class: "button button--alt button--nav") if defined?(root_url) %>
 
   <% Administrate::Namespace.new(namespace).resources_with_index_route.each do |resource| %>

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

@@ -1 +1 @@
-<%= paginate resources, param_name: '_page' %>
+<%= paginate resources, param_name: local_assigns.fetch(:param_name, "_page") %>

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

@@ -17,7 +17,7 @@ It displays a header, and renders the `_form` partial to do the heavy lifting.
 
 <% content_for(:title) { t("administrate.actions.edit_resource", name: page.page_title) } %>
 
-<header class="main-content__header" role="banner">
+<header class="main-content__header">
   <h1 class="main-content__page-title">
     <%= content_for(:title) %>
   </h1>

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

@@ -22,7 +22,7 @@ to do the heavy lifting.
   ) %>
 <% end %>
 
-<header class="main-content__header" role="banner">
+<header class="main-content__header">
   <h1 class="main-content__page-title">
     <%= content_for(:title) %>
   </h1>

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

@@ -18,7 +18,7 @@ as well as a link to its edit page.
 
 <% content_for(:title) { t("administrate.actions.show_resource", name: page.page_title) } %>
 
-<header class="main-content__header" role="banner">
+<header class="main-content__header">
   <h1 class="main-content__page-title">
     <%= content_for(:title) %>
   </h1>
@@ -42,16 +42,24 @@ as well as a link to its edit page.
 
 <section class="main-content__body">
   <dl>
-    <% page.attributes.each do |attribute| %>
-      <dt class="attribute-label" id="<%= attribute.name %>">
-      <%= t(
-        "helpers.label.#{resource_name}.#{attribute.name}",
-        default: page.resource.class.human_attribute_name(attribute.name),
-      ) %>
-      </dt>
-
-      <dd class="attribute-data attribute-data--<%=attribute.html_class%>"
-          ><%= render_field attribute, page: page %></dd>
+    <% page.attributes.each do |title, attributes| %>
+      <fieldset class="<%= "field-unit--nested" if title.present? %>">
+        <% if title.present? %>
+          <legend><%= t "helpers.label.#{page.resource_name}.#{title}", default: title %></legend>
+        <% end %>
+
+        <% attributes.each do |attribute| %>
+          <dt class="attribute-label" id="<%= attribute.name %>">
+          <%= t(
+            "helpers.label.#{resource_name}.#{attribute.name}",
+            default: page.resource.class.human_attribute_name(attribute.name),
+          ) %>
+          </dt>
+
+          <dd class="attribute-data attribute-data--<%=attribute.html_class%>"
+              ><%= render_field attribute, page: page %></dd>
+        <% end %>
+      </fieldset>
     <% end %>
   </dl>
 </section>

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

@@ -28,9 +28,10 @@ from the associated resource class's dashboard.
     page: page,
     resources: field.resources(page_number, order),
     table_title: field.name,
+    resource_class: field.associated_class,
   ) %>
   <% if field.more_than_limit? %>
-    <%= paginate field.resources(page_number), param_name: "#{field.name}[page]" %>
+    <%= render("pagination", resources: field.resources(page_number), param_name: "#{field.name}[page]") %>
   <% end %>
 
 <% else %>

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

@@ -19,10 +19,20 @@ The form will be rendered as nested_from to parent relationship.
 <%= f.fields_for field.attribute, field.data || field.nested_form.resource.class.new do |has_one_f| %>
   <fieldset class="field-unit--nested">
     <legend><%= t "helpers.label.#{f.object_name}.#{field.name}", default: field.name.titleize %></legend>
-    <% field.nested_form.attributes.each do |attribute| -%>
-      <div class="field-unit field-unit--<%= attribute.html_class %>">
-        <%= render_field attribute, f: has_one_f %>
-      </div>
+    <% field.nested_form.attributes.each do |title, attributes| -%>
+
+      <fieldset class="<%= "field-unit--nested" if title.present? %>">
+        <% if title.present? %>
+          <legend><%= t "helpers.label.#{f.object_name}.#{title}", default: title %></legend>
+        <% end %>
+
+        <% attributes.each do |attribute| %>
+          <div class="field-unit field-unit--<%= attribute.html_class %>">
+            <%= render_field attribute, f: has_one_f %>
+          </div>
+        <% end %>
+      </fieldset>
+
     <% end -%>
   </fieldset>
 <% end %>

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

@@ -24,18 +24,24 @@ All show page attributes of has_one relationship would be rendered
         [namespace, field.data],
       ) %>
     </legend>
-    <% field.nested_show.attributes.each do |attribute| -%>
-      <div>
-      <dt class="attribute-label">
-        <%= t(
-          "helpers.label.#{field.associated_class_name.underscore}.#{attribute.name}",
-          default: attribute.name.titleize,
-        ) %>
-      </dt>
-      <dd class="attribute-data attribute-data--<%= attribute.html_class %>">
-        <%= render_field attribute, { page: page } %>
-      </dd>
-      </div>
+    <% field.nested_show.attributes.each do |title, attributes| -%>
+      <fieldset class="<%= "field-unit--nested" if title.present? %>">
+        <% if title.present? %>
+          <legend><%= t "helpers.label.#{namespace}.#{title}", default: title %></legend>
+        <% end %>
+
+        <% attributes.each do |attribute| %>
+          <dt class="attribute-label">
+            <%= t(
+              "helpers.label.#{field.associated_class_name.underscore}.#{attribute.name}",
+              default: attribute.name.titleize,
+            ) %>
+          </dt>
+          <dd class="attribute-data attribute-data--<%= attribute.html_class %>">
+            <%= render_field attribute, { page: page } %>
+          </dd>
+        <% end %>
+      </fieldset>
     <% end -%>
   </fieldset>
 <% end %>

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/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.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/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

data/docs/customizing_controller_actions.md

@@ -93,3 +93,17 @@ To set custom redirects after the actions `create`, `update` and `destroy` you c
       [namespace, requested_resource.some_other_resource]
     end
 ```
+
+## Creating Records
+
+You can perform actions after creation by passing a `block` to `super` in the
+`create` method. The block will only be called if the resource is successfully
+created.
+
+```ruby
+def create
+  super do |resource|
+    # do something with the newly created resource
+  end
+end
+```

data/docs/customizing_dashboards.md

@@ -113,8 +113,11 @@ association `belongs_to :country`, from your model.
 
 **Field::HasMany**
 
-`:limit` - Set the number of resources to display in the show view. Default is
-`5`.
+`:collection_attributes` - Set the columns to display in the show view. 
+Default is COLLECTION_ATTRIBUTES in dashboard.
+
+`: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.
 
@@ -128,6 +131,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`.
 
@@ -164,8 +171,7 @@ more results than expected. Default is `false`.
 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.
+example below. All helpers from `ActiveSupport::NumberHelper` are supported.
 
 For example, you might use the following to display U.S. currency:
 
@@ -218,25 +224,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).
 
-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:
+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
-  currency = Field::Select.with_options(
-    collection: [ ['usd', 'Dollar'], ['eur', 'Euro'], ['yen', 'Yen'] ]
+  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**
 
@@ -373,3 +385,54 @@ FORM_ATTRIBUTES_EDIT = [
 ```
 
 Or for custom action with constant name `"FORM_ATTRIBUTES_#{action.upcase}"`
+
+### Form Fields' Hints
+
+You can show a brief text element below an input field by setting the
+corresponding translation key using the path:
+
+`administrate.field_hints.#{model_name}.#{field_name}`
+
+For example, with a Customer dashboard with an email field you can add a
+string value that will be used as text hint:
+
+```yml
+en:
+  administrate:
+    field_hints:
+      customer:
+        email: field_hint
+```
+
+## Grouped Attributes
+
+You may have models with a large number of fields and therefore you might want to group them in a meaningul way:
+
+```ruby
+class UserDashboard < Administrate::BaseDashboard
+  SHOW_PAGE_ATTRIBUTES = {
+    "" => [:username],
+    "Personal Information" => [:first_name, :last_name, :email],
+    "Address" => [:address_line_one, :address_line_two, :address_city, :address_state, :address_country]
+  }
+
+  FORM_ATTRIBUTES = {
+    "" => [:username, :password, :password_confirmation],
+    "personal_information" => [:first_name, :last_name, :email],
+    "address" => [:address_line_one, :address_line_two, :address_city, :address_state, :address_country]
+  }
+end
+```
+
+You can optionally translate your group labels:
+
+```yaml
+en:
+  helpers:
+    label:
+      user:
+        address: Address
+        personal_information: Personal Information
+```
+
+If not defined (see `SHOW_PAGE_ATTRIBUTES` above), Administrate will default to the given strings.

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.7 and up.
+applications version 6.0 or greater. We support Ruby 3.0 and up.
 
 First, add the following to your Gemfile:
 

data/docs/guides/customising_search.md

@@ -135,7 +135,7 @@ records.
 
 ## A working example
 
-The [Administrate demo app](/admin)
+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