administrate 0.20.1 → 1.0.0

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

@@ -17,10 +17,11 @@ that displays all possible records to associate with.
 %>
 
 <div class="field-unit__label">
-  <%= f.label field.permitted_attribute %>
+  <%= f.label field.attribute, for: "#{f.object_name}_#{field.permitted_attribute}" %>
 </div>
 <div class="field-unit__field">
   <%= f.select(field.permitted_attribute,
                options_for_select(field.associated_resource_options, field.selected_option),
-               include_blank: field.include_blank_option) %>
+               {include_blank: field.include_blank_option},
+               data: {controller: field.html_controller}) %>
 </div>

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

@@ -16,14 +16,14 @@ and is augmented with [Selectize].
   Contains helper methods for displaying a collection select box.
 
 [1]: http://www.rubydoc.info/gems/administrate/Administrate/Field/HasMany
-[Selectize]: http://brianreavis.github.io/selectize.js
+[Selectize]: https://github.com/selectize/selectize.js
 %>
 
 <div class="field-unit__label">
   <%= f.label field.attribute, for: "#{f.object_name}_#{field.attribute_key}" %>
 </div>
 <div class="field-unit__field">
-  <%= f.select(field.attribute_key, nil, {}, multiple: true) do %>
+  <%= f.select(field.attribute_key, nil, {}, multiple: true, data: {controller: field.html_controller}) do %>
     <%= options_for_select(field.associated_resource_options, field.selected_options) %>
   <% end %>
 </div>

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

@@ -30,6 +30,12 @@ The form will be rendered as nested_from to parent relationship.
           <div class="field-unit field-unit--<%= attribute.html_class %>">
             <%= render_field attribute, f: has_one_f %>
           </div>
+          <% hint_key = "administrate.field_hints.#{field.name}.#{attribute.name}" %>
+          <% if I18n.exists?(hint_key) -%>
+            <div class="field-unit__hint">
+              <%= I18n.t(hint_key) %>
+            </div>
+          <% end -%>
         <% end %>
       </fieldset>
 

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

@@ -22,7 +22,7 @@ This partial renders an input element for polymorphic relationships.
 
   <div class="field-unit__field">
     <%= pf.hidden_field(:type, value: field.class.name) %>
-    <%= pf.select(:value) do %>
+    <%= pf.select(:value, nil, {}, data: {controller: field.html_controller}) do %>
       <%= grouped_options_for_select(field.associated_resource_grouped_options, field.selected_global_id, prompt: true) %>
     <% end %>
   </div>

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

@@ -0,0 +1,22 @@
+<%#
+# Rich Text Form Partial
+
+This partial renders a trix-editor element for ActionText::RichText attributes.
+
+## Local variables:
+
+- `f`:
+  A Rails form generator, used to help create the appropriate trix-editor fields.
+- `field`:
+  An instance of [Administrate::Field::RichText][1].
+  A wrapper around the tmie attributes pulled from the model.
+
+[1]: http://www.rubydoc.info/gems/administrate/Administrate/Field/RichText
+%>
+
+<div class="field-unit__label">
+  <%= f.label field.attribute %>
+</div>
+<div class="field-unit__field">
+  <%= f.rich_text_area(field.attribute) %>
+</div>

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

@@ -0,0 +1,18 @@
+<%#
+# RichText Index Partial
+
+This partial renders a rich_text attribute
+to be displayed on a resource's index page.
+
+By default, the attribute is rendered as a plain text truncated string.
+
+## Local variables:
+
+- `field`:
+  An instance of [Administrate::Field::RichText][1].
+  A wrapper around the RichText pulled from the database.
+
+[1]: http://www.rubydoc.info/gems/administrate/Administrate/Field/RichText
+%>
+
+<%= field.truncate %>

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

@@ -0,0 +1,18 @@
+<%#
+# RichText Show Partial
+
+This partial renders a rich_text attribute,
+to be displayed on a resource's show page.
+
+By default, the attribute is rendered as HTML.
+
+## Local variables:
+
+- `field`:
+  An instance of [Administrate::Field::RichText][1].
+  A wrapper around the RichText object pulled from the database.
+
+[1]: http://www.rubydoc.info/gems/administrate/Administrate/Field/RichText
+%>
+
+<%= field.data %>

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

@@ -26,7 +26,8 @@ to be displayed on a resource's edit form page.
         field.selectable_options,
         field.data,
       ),
-      include_blank: field.include_blank_option
+      {include_blank: field.include_blank_option},
+      data: {controller: field.html_controller}
     )
   %>
 </div>

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

@@ -18,5 +18,5 @@ This partial renders a textarea element for a text attribute.
   <%= f.label field.attribute %>
 </div>
 <div class="field-unit__field">
-  <%= f.text_area field.attribute %>
+  <%= f.text_area field.attribute, field.options.fetch(:input_options, {}) %>
 </div>

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

@@ -24,6 +24,7 @@ By default, it renders:
   <%= render "stylesheet" %>
   <%= csrf_meta_tags %>
   <%= csp_meta_tag if defined?(csp_meta_tag) %>
+  <%= render "javascript" %>
 </head>
 <body>
   <%= render "icons" %>
@@ -36,7 +37,5 @@ By default, it renders:
       <%= yield %>
     </main>
   </div>
-
-  <%= render "javascript" %>
 </body>
 </html>

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,15 +106,18 @@ 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. 
+`: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,
@@ -123,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**
 
@@ -144,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.
 
-`:class_name` (deprecated) - Specifies the name of the associated class.
+`:sortable` - Specifies if sorting should be enabled in the table views.  
+Default is `true`.  
+
+`: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**
 
@@ -161,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 `""`.
@@ -209,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.
 
@@ -219,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.
 
@@ -248,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**
@@ -255,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`.
 
@@ -263,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`.
 
@@ -282,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`.
 
@@ -436,3 +509,133 @@ en:
 ```
 
 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

@@ -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/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"
@@ -79,7 +80,7 @@ module Administrate
         attribute_types[attr].permitted_attribute(
           attr,
           resource_class: self.class.model,
-          action: action,
+          action: action
         )
       end.uniq
     end
@@ -110,18 +111,12 @@ 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
       attributes = if show_page_attributes.is_a?(Hash)
-                     show_page_attributes.values.flatten
-                   else
-                     show_page_attributes
-                   end
+        show_page_attributes.values.flatten
+      else
+        show_page_attributes
+      end
       attribute_associated attributes
     end