administrate 0.19.0 → 1.0.0

data/docs/customizing_dashboards.md

@@ -82,7 +82,8 @@ 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) })`
+Example #1: `.with_options(scope: -> { MyModel.includes(:rel).limit(5) })`
+Example #2: `.with_options(scope: -> (field) { field.resource.my_models.includes(:rel).limit(5) })`
 
 `:include_blank` - Specifies if the select element to be rendered should include
 blank option. Default is `true`.
@@ -105,14 +106,20 @@ For example:
 with this, you will be able to search through the column `name` from the
 association `belongs_to :country`, from your model.
 
-`:primary_key` (deprecated) - Specifies the association's primary_key.
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
 
-`:foreign_key` (deprecated) - Specifies the name of the foreign key directly.
+`:sorting_column` - Specifies the column of the associated model to be used for sorting in the table views and dropdown menu.  
+If `sorting_column` is omitted and `order` is specified, the value of `order` will be used.  
+If neither is specified, sorting will be done using the foreign key.  
 
-`:class_name` (deprecated) - Specifies the name of the associated class.
+`:class_name` - Specifies the name of the associated class.
 
 **Field::HasMany**
 
+`: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`.
 
@@ -120,11 +127,15 @@ set this to `0` or `false`. Default is `5`.
 
 `:direction` - What direction the sort should be in, `:asc` (default) or `:desc`.
 
-`:primary_key` (deprecated) - Specifies object's primary_key.
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
 
-`:foreign_key` (deprecated) - Specifies the name of the foreign key directly.
+`:sorting_column` - Specifies the column of the associated model to be used for sorting in the dropdown menu.  
+If `sorting_column` is omitted and `sort_by` is specified, the value of `sort_by` will be used.  
+If neither is specified, sorting will be done using the foreign key.  
+For `HasMany` associations, sorting is based on the count, so this option is not referenced in the table views.  
 
-`:class_name` (deprecated) - Specifies the name of the associated class.
+`:class_name` - Specifies the name of the associated class.
 
 **Field::HasOne**
 
@@ -141,16 +152,23 @@ Default is `false`.
 For example:
 
 ```ruby
-  cities: Field::HasMany.with_options(
+  city: Field::HasOne.with_options(
     searchable: true,
     searchable_fields: ['name'],
   )
 ```
 
 with this, you will be able to search through the column `name` from the
-association `has_many :cities`, from your model.
+association `has_one :city`, from your model.
+
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
 
-`:class_name` (deprecated) - Specifies the name of the associated class.
+`:sorting_column` - Specifies the column of the associated model to be used for sorting in the table views and dropdown menu.  
+If `sorting_column` is omitted and `order` is specified, the value of `order` will be used.  
+If neither is specified, sorting will be done using the foreign key.  
+
+`:class_name` - Specifies the name of the associated class.
 
 **Field::Number**
 
@@ -158,6 +176,13 @@ association `has_many :cities`, from your model.
 Note that currently number fields are searched like text, which may yield
 more results than expected. Default is `false`.
 
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
 `:decimals` - Set the number of decimals to display. Defaults to `0`.
 
 `:prefix` - Prefixes the number with a string. Defaults to `""`.
@@ -168,8 +193,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:
 
@@ -207,8 +231,18 @@ Default is `[]`.
 `:order` - What to sort the association by in the form select.
 Default is `nil`.
 
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
 **Field::DateTime**
 
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
 `:format` - Specify what format, using `strftime` you would like `DateTime`
 objects to display as.
 
@@ -217,6 +251,13 @@ in.
 
 **Field::Date**
 
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
 `:format` - Specify what format, using `strftime` you would like `Date`
 objects to display as.
 
@@ -246,6 +287,13 @@ If no collection is provided and no enum can be detected, the list of options wi
 `:searchable` - Specify if the attribute should be considered when searching.
 Default is `true`.
 
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
 `: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**
@@ -253,6 +301,13 @@ Default is `true`.
 `:searchable` - Specify if the attribute should be considered when searching.
 Default is `true`.
 
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
 `:truncate` - Set the number of characters to display in the index view.
 Defaults to `50`.
 
@@ -261,14 +316,31 @@ Defaults to `50`.
 `:searchable` - Specify if the attribute should be considered when searching.
 Default is `false`.
 
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
 `:truncate` - Set the number of characters to display in the index view.
 Defaults to `50`.
 
+`:input_options` - Options to customize the text area in form view.
+Example: `.with_options(input_options: { rows: 20 })`
+
 **Field::Url**
 
 `:searchable` - Specify if the attribute should be considered when searching.
 Default is `true`.
 
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`:sorting_column` - Specifies the column to be used for sorting in the table view.  
+By default, the column itself is used, but when used as a virtual column,  
+a custom sorting column can be specified.  
+
 `:truncate` - Set the number of characters to display in the index view.
 Defaults to `50`.
 
@@ -280,6 +352,9 @@ Defaults is `{}`.
 `:searchable` - Specify if the attribute should be considered when searching.
 Default is `false`.
 
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `false`.  
+
 `:truncate` - Set the number of characters to display in the views.
 Defaults to `50`.
 
@@ -383,3 +458,184 @@ 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.
+
+## Virtual Attributes
+
+For all field types, you can use the `getter` option to change where the data is retrieved from or to set the data directly.
+
+By using this, you can define an attribute in `ATTRIBUTE_TYPES` that doesn’t exist in the model, and use it for various purposes.
+
+### Attribute Aliases
+
+You can create an alias for an attribute. For example:
+
+```ruby
+  ATTRIBUTE_TYPES = {
+    shipped_at: Field::DateTime,
+    shipped_on: Field::Date.with_options(
+      getter: :shipped_at
+    )
+  }
+  COLLECTION_ATTRIBUTES = [
+    :shipped_on
+  }
+  SHOW_PAGE_ATTRIBUTES = [
+    :shipped_at
+  }
+```
+
+In this example, a virtual attribute `shipped_on` based on the value of `shipped_at` is defined as a `Date` type and used for display on the index page (this can help save table cell space).
+
+### Decorated Attributes
+
+You can also use this to decorate data. For example:
+
+```ruby
+  ATTRIBUTE_TYPES = {
+    price: Field::Number,
+    price_including_tax: Field::Number.with_options(
+      getter: -> (field) {
+        field.resource.price * 1.1 if field.resource.price.present?
+      }
+    )
+  }
+```
+
+### Composite Attributes
+
+You can dynamically create a virtual attribute by combining multiple attributes for display. For example:
+
+```ruby
+  ATTRIBUTE_TYPES = {
+    first_name: Field::String,
+    last_name: Field::String,
+    full_name: Field::String.with_options(
+      getter: -> (field) {
+        [
+          field.resource.first_name,
+          field.resource.last_name
+        ].compact_blank.join(' ')
+      }
+    )
+  }
+```
+
+## Virtual Fields
+
+Custom fields can also be defined using virtual fields.
+
+```ruby
+  ATTRIBUTE_TYPES = {
+    id: Field::Number,
+    receipt: Field::ReceiptLink
+  }
+```
+
+```ruby
+module Administrate
+  module Field
+    class ReceiptLink < Base
+      def data
+        resource.id
+      end
+
+      def filename
+        "receipt-#{data}.pdf"
+      end
+
+      def url
+        "/files/receipts/#{filename}"
+      end
+    end
+  end
+end
+```
+
+```erb
+<%= link_to field.filename, field.url %>
+```
+
+### Custom Actions via Virtual Field
+
+By creating custom fields that are not dependent on specific attributes, you can insert custom views into any screen.
+For example, you can add custom buttons like this:
+
+```ruby
+  ATTRIBUTE_TYPES = {
+    id: Field::Number,
+    custom_index_actions: Field::CustomActionButtons,
+    custom_show_actions: Field::CustomActionButtons,
+  }
+```
+
+```ruby
+module Administrate
+  module Field
+    class CustomActionButtons < Base
+      def data
+        resource.id
+      end
+    end
+  end
+end
+```
+
+```erb
+<%# app/views/fields/custom_action_buttons/_index.html.erb %>
+<% if field.data.present? %>
+  <%= button_to "some action 1", [:some_action_1, namespace, field.resource] %>
+  <%= button_to "some action 2", [:some_action_2, namespace, field.resource] %>
+  <%= button_to "some action 3", [:some_action_3, namespace, field.resource] %>
+<% end %>
+```

data/docs/customizing_page_views.md

@@ -10,7 +10,7 @@ In general, you can override any of the views under Administrate's
 [/app/views][1].
 For example, say that you want to customize the template used for flash
 messages. You can provide your own as
-`/app/views/administrate/application/_flashes.html.erb`, and it will replace
+`app/views/admin/application/_flashes.html.erb`, and it will replace
 Administrate's own.
 
 Figuring out which views are available and where can be repetitive. You can
@@ -94,3 +94,50 @@ rails generate administrate:views:layout
  # It only generates the sidebar partial
  # -> app/views/admin/application/_navigation.html.erb
 ```
+
+## Customizing for a specific layout
+
+You can use several hook points to add elements to specific layouts or specific pages:
+
+* header_middle
+* header_last
+* before_main
+* main
+* after_main
+
+For example, you can add a button in the middle of the header as follows:
+
+```eruby
+<%# app/views/admin/customers/_index_header.html.erb %>
+
+<% content_for(:header_middle) do %>
+  <div>
+    You are logged in as <em><%= pundit_user.name %></em>.
+    <%= link_to("Become the Admin", become_admin_customer_path("admin")) unless pundit_user.admin? %>
+  </div>
+<% end %>
+
+<%= render template: 'administrate/application/_index_header', locals: local_assigns %>
+```
+
+## Adding custom CSS and JS
+
+You can add custom CSS and JS to Administrate. Put the files in the
+appropriate folders (typically under `assets`) and point Administrate to them
+using the following API, preferably in an initializer. For example, if your
+files are called `admin.css` and `admin.js`:
+
+```
+/// config/initializers/administrate.rb
+Administrate::Engine.add_stylesheet("admin")
+Administrate::Engine.add_javascript("admin")
+```
+
+Then make sure to list them in your manifest file (Rails will helpfully remind
+you of this step if you miss it):
+
+```
+/// app/assets/config/manifest.js
+//= link admin.css
+//= link admin.js
+```

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 6.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/scoping_has_many_relations.md

@@ -18,10 +18,10 @@ Since ActiveRecord infers the class name from the first argument, the new `has_m
 
 ## 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.
+Your new scoped relation can be used in the dashboard just like the original `HasMany`.
 
 ```ruby
 ATTRIBUTE_TYPES = {
   orders: Field::HasMany,
-  processed_orders: Field::HasMany.with_options(class_name: 'Order')
+  processed_orders: Field::HasMany
 ```

data/docs/guides/switching_templates_with_view_variants.md

@@ -0,0 +1,45 @@
+---
+title: Switching templates with view variants
+---
+
+You can switch to different templates using Rails' support for [view
+variants][], which can be used to override the template used inside the
+controller.
+
+By setting the `request.variant` option to any value (in this case, `:admin`)
+at any point in any controller, you can add a new variant to Rails' template
+lookup tree (in this case, `.html+admin.erb`).
+
+For example, to add a button to become the admin to view certain functionality:
+
+```ruby
+class CustomersController < Admin::ApplicationController
+  before_action :with_variant, only: %i[index]
+
+  private
+
+  def with_variant
+    if @current_user.admin?
+      request.variant = :admin
+    end
+  end
+end
+```
+
+```erb
+<!-- app/views/admin/customers/_index_header.html.erb -->
+<p class="identity__banner">
+  You are logged in as <em><%= pundit_user.name %></em>.
+  <%= link_to("Become the Admin", become_admin_customer_path("admin"),
+        class: "identity__become-action")%>
+</p>
+```
+
+```erb
+<!-- app/views/admin/customers/_index_header.html+admin.erb -->
+<p class="identity__banner identity__banner--admin">
+  You are logged in as <em><%= pundit_user.name %></em>.
+</p>
+```
+
+[view variants]: https://guides.rubyonrails.org/layouts_and_rendering.html#the-variants-option

data/docs/guides.md

@@ -5,3 +5,4 @@ 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)
+- [Switching templates with view variants](./guides/switching_templates_with_view_variants.md)

data/docs/migrating-to-v1.md

@@ -0,0 +1,34 @@
+---
+title: Migrating to v1
+---
+
+In the release of v1.0.0, we [began bundling assets in the gem itself][2397].
+In the future, this should mean that any changes made to assets (coming
+from you or from Administrate updates) should not have an effect on you.
+However, this is quite a big change and so you might find some problems.
+
+As with most upgrades, if you're upgrading between versions with changes to the
+templates, and if you've customised them, you may need to apply recent changes.
+You can see those which changed in the [CHANGELOG][].
+
+This applies to both modified files in `app/views/admin` and `app/views/fields`
+if you have your own Field classes defined. A good way is to use the same 
+command to generate the view as for the earlier version:
+`rails generate administrate:views:ACTION MyModel`
+noting the changes and re-applying the modifications
+
+[2397]: https://github.com/thoughtbot/administrate/pull/2397
+[CHANGELOG]: https://github.com/thoughtbot/administrate/blob/main/CHANGELOG.md
+
+## Reported issues
+
+### Removal of the `sprockets-rails` transitive dependency
+
+[Issue][2514]
+
+Previously, Administrate depended on [`sprockets-rails`][], if you have a
+dependency which requires this, you may now need to add a direct dependency on
+your application.
+
+[2514]: https://github.com/thoughtbot/administrate/issues/2514
+[`sprockets-rails`]: https://rubygems.org/gems/sprockets-rails

data/lib/administrate/base_dashboard.rb

@@ -7,6 +7,7 @@ require "administrate/field/has_many"
 require "administrate/field/has_one"
 require "administrate/field/number"
 require "administrate/field/polymorphic"
+require "administrate/field/rich_text"
 require "administrate/field/select"
 require "administrate/field/string"
 require "administrate/field/text"
@@ -69,11 +70,17 @@ module Administrate
     end
 
     def permitted_attributes(action = nil)
-      form_attributes(action).map do |attr|
+      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,
+          action: action
         )
       end.uniq
     end
@@ -83,7 +90,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
@@ -100,14 +111,13 @@ module Administrate
       attribute_includes(collection_attributes)
     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)
+      attributes = if show_page_attributes.is_a?(Hash)
+        show_page_attributes.values.flatten
+      else
+        show_page_attributes
+      end
+      attribute_associated attributes
     end
 
     private

data/lib/administrate/engine.rb

@@ -1,8 +1,4 @@
-require "jquery-rails"
 require "kaminari"
-require "sassc-rails"
-require "selectize-rails"
-require "sprockets/railtie"
 
 require "administrate/namespace/resource"
 require "administrate/not_authorized_error"
@@ -13,7 +9,6 @@ require "administrate/order"
 require "administrate/resource_resolver"
 require "administrate/search"
 require "administrate/namespace"
-require "administrate/namespace/resource"
 
 module Administrate
   class Engine < ::Rails::Engine
@@ -25,10 +20,16 @@ module Administrate
     initializer "administrate.assets.precompile" do |app|
       app.config.assets.precompile += [
         "administrate/application.js",
-        "administrate/application.css",
+        "administrate/application.css"
       ]
     end
 
+    initializer "administrate.action_text" do
+      ActiveSupport.on_load :action_text_rich_text do
+        require "administrate/field/rich_text"
+      end
+    end
+
     def self.add_javascript(script)
       @@javascripts << script
     end