administratum 0.2.4 → 0.3.0

data/app/helpers/administratum/form_helper.rb

@@ -56,13 +56,52 @@ module Administratum
     end
 
     # Options for select-style fields. `collection` may be an array, a
-    # relation, or a lambda (optionally receiving the record).
+    # relation, or a lambda (optionally receiving the record). `group_by:` (an
+    # attribute name, or a lambda receiving each item) groups them into optgroups.
     def field_collection(field, record)
       collection = field.options[:collection]
       collection = collection.arity.zero? ? instance_exec(&collection) : instance_exec(record, &collection) if collection.respond_to?(:call)
       collection ||= association_collection(field, record)
       collection = collection.to_a if collection.is_a?(ActiveRecord::Relation)
-      collection.map { |item| item.is_a?(ActiveRecord::Base) ? [record_title(item), item.id] : item }
+      group_by = field.options[:group_by]
+      return collection.map { |item| collection_choice(item) } unless group_by
+
+      collection.group_by { |item| collection_group(group_by, item) }
+                .map { |group, items| [group, items.map { |item| collection_choice(item) }] }
+    end
+
+    # The `searchable:` option of a select field, resolved: nil, or a hash with
+    # the search `url:` (a string, or a lambda optionally receiving the record) and `min:`.
+    def field_search(field, record)
+      option = field.options[:searchable]
+      return unless option
+
+      option = {} if option == true
+      url = option[:url]
+      url = url.arity.zero? ? instance_exec(&url) : instance_exec(record, &url) if url.respond_to?(:call)
+      { url:, min: option[:min] }
+    end
+
+    # Choices for a select field. One that searches remotely only renders the
+    # current value; the rest come from the search URL.
+    def select_field_choices(field, record, search = field_search(field, record))
+      return field_collection(field, record) unless search&.dig(:url)
+
+      value = record.try(field.name)
+      return [] if value.blank?
+
+      reflection = field_reflection(field, record)
+      return [[value.to_s, value]] unless reflection
+
+      reflection.klass.where(reflection.klass.primary_key => value).map { |item| collection_choice(item) }
+    end
+
+    # Data attributes that make a select searchable (see administratum.js).
+    # Use them on hand-written selects too: `data: adm_combobox_data(url: …)`.
+    def adm_combobox_data(url: nil, min: nil)
+      { adm_combobox: true, adm_combobox_url: url, adm_combobox_min: min,
+        adm_combobox_empty: t("administratum.combobox.empty"), adm_combobox_loading: t("administratum.combobox.loading"),
+        adm_combobox_short: t("administratum.combobox.short"), adm_combobox_error: t("administratum.combobox.error") }.compact
     end
 
     # HTML options for a field's input: the partial's defaults, then the
@@ -101,11 +140,24 @@ module Administratum
     end
 
     def association_collection(field, record)
-      name = field.name.to_s.delete_suffix("_ids").delete_suffix("_id")
-      reflection = record.class.reflect_on_association(name.to_sym) || record.class.reflect_on_association(name.pluralize.to_sym)
+      reflection = field_reflection(field, record)
       reflection ? reflection.klass.all : []
     end
 
+    def field_reflection(field, record)
+      name = field.name.to_s.delete_suffix("_ids").delete_suffix("_id")
+      record.class.reflect_on_association(name.to_sym) || record.class.reflect_on_association(name.pluralize.to_sym)
+    end
+
+    def collection_choice(item)
+      item.is_a?(ActiveRecord::Base) ? [record_title(item), item.id] : item
+    end
+
+    def collection_group(group_by, item)
+      group = group_by.respond_to?(:call) ? instance_exec(item, &group_by) : item.public_send(group_by)
+      group.is_a?(ActiveRecord::Base) ? record_title(group) : group.to_s
+    end
+
     # Dates and times are formatted; anything else (such as a submitted
     # string that failed validation) is shown as typed.
     def iso_value(value, format)

data/app/helpers/administratum/reorder_helper.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Administratum
+  # Controls for putting records in order. Mark the list's container with
+  # data-adm-sortable and each record's element with data-adm-sortable-item,
+  # put reorder_controls in each, and submit them with reorder_form and
+  # reorder_save_button:
+  #
+  #   <%= reorder_form id: "chapter-order", url: action_path(:reorder) %>
+  #   <ol data-adm-sortable>
+  #     <% chapters.each do |chapter| %>
+  #       <li data-adm-sortable-item><%= reorder_controls chapter, form: "chapter-order" %> <%= chapter.title %></li>
+  #     <% end %>
+  #   </ol>
+  #   <%= reorder_save_button form: "chapter-order" %>
+  module ReorderHelper
+    # An empty form. The position fields and the save button join it through
+    # their form="…" attribute, so the list can sit anywhere, even around rows
+    # that hold forms of their own.
+    def reorder_form(id:, url:, method: :patch)
+      form_with(url:, method:, id:, class: "adm-reorder-form") { "" }
+    end
+
+    # A drag handle and move up/down buttons, shown by administratum.js, and
+    # the positions[id] number field they keep up to date. Without JS only the
+    # number field shows.
+    def reorder_controls(record, form:, column: :position, position: record.public_send(column))
+      input_id = "#{form}-position-#{record.id}"
+      fallback = tag.span(data: { adm_sortable_fallback: true }) do
+        label_tag(input_id, t("administratum.reorder.position"), class: "adm-sr-only") +
+          number_field_tag("positions[#{record.id}]", position, id: input_id, form:, min: 1,
+                                                                class: "adm-input adm-sortable-position", data: { adm_sortable_position: true })
+      end
+
+      tag.span(class: "adm-sortable-controls", data: { adm_sortable_moved: t("administratum.reorder.moved") }) do
+        safe_join([
+                    reorder_button("⠿", :handle, class: "adm-icon-btn adm-sortable-handle", data: { adm_sortable_handle: true }),
+                    reorder_button("↑", :up, class: "adm-icon-btn", data: { adm_sortable_up: true }),
+                    reorder_button("↓", :down, class: "adm-icon-btn", data: { adm_sortable_down: true }),
+                    fallback
+                  ])
+      end
+    end
+
+    def reorder_save_button(form:, label: t("administratum.reorder.save"), **options)
+      tag.button(label, **options.except(:class), type: "submit", form:, class: class_names("adm-btn adm-btn-primary", options[:class]))
+    end
+
+    private
+
+    def reorder_button(symbol, name, **)
+      tag.button(symbol, type: "button", hidden: true, aria: { label: t("administratum.reorder.#{name}") }, **)
+    end
+  end
+end

data/app/views/administratum/fields/_belongs_to.html.erb

@@ -1 +1,2 @@
-<%= form.select field.name, field_collection(field, resource), { include_blank: field.options[:placeholder] || field.options.fetch(:include_blank, true) }, **input_options(field, form:, class: "adm-input") %>
+<% search = field_search(field, resource) %>
+<%= form.select field.name, select_field_choices(field, resource, search), { include_blank: field.options[:placeholder] || field.options.fetch(:include_blank, true) }, **input_options(field, form:, class: "adm-input", data: search ? adm_combobox_data(**search) : {}) %>

data/app/views/administratum/fields/_select.html.erb

@@ -1 +1,2 @@
-<%= form.select field.name, field_collection(field, resource), { include_blank: field.options[:placeholder] || field.options.fetch(:include_blank, false) }, **input_options(field, form:, class: "adm-input") %>
+<% search = field_search(field, resource) %>
+<%= form.select field.name, select_field_choices(field, resource, search), { include_blank: field.options[:placeholder] || field.options.fetch(:include_blank, false) }, **input_options(field, form:, class: "adm-input", data: search ? adm_combobox_data(**search) : {}) %>

data/app/views/administratum/resources/_table.html.erb

@@ -1,17 +1,24 @@
+<% reorderable = index_reorderable? %>
 <section class="adm-card">
   <div class="adm-table-wrap">
     <table class="adm-table">
       <thead>
         <tr>
+          <% if reorderable %>
+            <th scope="col" class="w-px whitespace-nowrap"><%= t("administratum.reorder.column") %></th>
+          <% end %>
           <% definition.index_columns.each do |column| %>
             <th scope="col"><%= column.sortable ? sort_link(@search, column.name, column_label(column)) : column_label(column) %></th>
           <% end %>
           <th scope="col" class="adm-table-actions"><span class="adm-sr-only"><%= t("administratum.actions.title") %></span></th>
         </tr>
       </thead>
-      <tbody>
+      <tbody<% if reorderable %> data-adm-sortable<% end %>>
         <% @resources.each do |record| %>
-          <tr>
+          <tr<% if reorderable %> data-adm-sortable-item<% end %>>
+            <% if reorderable %>
+              <td class="w-px whitespace-nowrap"><%= reorder_controls record, form: "adm-reorder", column: definition.reorder_column %></td>
+            <% end %>
             <% definition.index_columns.each_with_index do |column, index| %>
               <td>
                 <% if index.zero? && !column.block && definition.action_enabled?(:show) %>
@@ -25,7 +32,7 @@
           </tr>
         <% end %>
         <% if @resources.empty? %>
-          <tr><td colspan="<%= definition.index_columns.size + 1 %>" class="adm-empty"><%= t("administratum.empty", resources: resource_class.plural_label.downcase) %></td></tr>
+          <tr><td colspan="<%= definition.index_columns.size + (reorderable ? 2 : 1) %>" class="adm-empty"><%= t("administratum.empty", resources: resource_class.plural_label.downcase) %></td></tr>
         <% end %>
       </tbody>
     </table>
@@ -37,6 +44,12 @@
         · <%= link_to t("administratum.download_csv"), url_for(format: :csv, q: request.query_parameters[:q], scope: current_index_scope&.name), class: "adm-link" %>
       <% end %>
     </div>
+    <% if reorderable %>
+      <div class="adm-form-footer">
+        <%= reorder_form id: "adm-reorder", url: action_path(:reorder) %>
+        <%= reorder_save_button form: "adm-reorder", class: "adm-btn-sm" %>
+      </div>
+    <% end %>
     <div class="adm-pagy"><%== pagy_nav(@pagy) if @pagy.pages > 1 %></div>
   </footer>
 </section>

data/config/locales/en.yml

@@ -21,6 +21,7 @@ en:
       created: "%{resource} was created."
       updated: "%{resource} was updated."
       destroyed: "%{resource} was deleted."
+      reordered: "%{resources} were reordered."
     errors:
       title:
         one: 1 error prevented saving
@@ -33,6 +34,19 @@ en:
       any: Any
       from: "%{field} from"
       to: "%{field} to"
+    combobox:
+      empty: No matches
+      loading: Searching…
+      short: Type at least %{count} characters
+      error: Search failed
+    reorder:
+      handle: Reorder (drag, or use the arrow keys)
+      up: Move up
+      down: Move down
+      position: Position
+      moved: Moved to position %{position} of %{count}
+      save: Save order
+      column: Order
     upload:
       file: File
       submit: Upload

data/lib/administratum/definition.rb

@@ -101,7 +101,7 @@ module Administratum
     end
 
     attr_accessor :model, :title_attribute, :permitted, :parent, :form_template, :scope_block, :route_key, :label,
-                  :plural_label, :per_page, :default_sort, :csv
+                  :plural_label, :per_page, :default_sort, :csv, :reorder_column
     attr_reader :fields, :columns, :custom_actions, :buttons, :show_attributes, :enabled_actions, :menu, :index_scopes
 
     def initialize
@@ -206,6 +206,7 @@ module Administratum
       names = filters.map { |filter| filter.name.to_s }
       names += index_columns.select(&:sortable).map { |column| column.name.to_s }
       names << title.to_s if title
+      names << reorder_column.to_s if reorder_column
       names += Array(default_sort).map { |sort| sort.to_s.split.first }
       names.uniq & model.column_names
     end

data/lib/administratum/dsl.rb

@@ -152,6 +152,15 @@ module Administratum
       definition.enable_actions(only:, except:)
     end
 
+    # Records are put in order by an integer column. Adds a PATCH `reorder`
+    # collection action taking positions[id]=n, sorts the index by the column,
+    # and shows reorder controls there while every record is on the page.
+    def reorderable(column = :position)
+      definition.reorder_column = column.to_sym
+      definition.default_sort ||= "#{column} asc"
+      collection_action :reorder, method: :patch
+    end
+
     def member_action(name, method: :get)
       definition.add_action(name, http_method: method, scope: :member)
     end

data/lib/administratum/reorder.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Administratum
+  # Puts records in order from a positions[id]=n payload.
+  module Reorder
+    module_function
+
+    # Only records in `relation` move. Each submitted record is put at its
+    # number among the others (ties keep the current order); records left out
+    # keep their order around them. Positions are then renumbered from 1, and
+    # changed records saved with update!, so validations and callbacks run.
+    # Returns the records in their new order.
+    def call(relation, positions, column: :position)
+      positions = positions.to_unsafe_h if positions.respond_to?(:to_unsafe_h)
+      positions = {} unless positions.is_a?(Hash)
+      wanted = positions.to_h { |id, value| [id.to_s, Integer(value.to_s, exception: false)] }.compact
+
+      moved, sorted = relation.reorder(column, relation.klass.primary_key).to_a.partition { |record| wanted.key?(record.id.to_s) }
+      index = -1
+      moved.sort_by.with_index { |record, current| [wanted[record.id.to_s], current] }.each do |record|
+        index = (wanted[record.id.to_s] - 1).clamp(index + 1, sorted.size)
+        sorted.insert(index, record)
+      end
+
+      relation.klass.transaction do
+        sorted.each.with_index(1) do |record, position|
+          record.update!(column => position) unless record.public_send(column) == position
+        end
+      end
+      sorted
+    end
+  end
+end

data/lib/administratum/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Administratum
-  VERSION = "0.2.4"
+  VERSION = "0.3.0"
 end

data/lib/administratum.rb

@@ -12,6 +12,7 @@ require "administratum/definition"
 require "administratum/dsl"
 require "administratum/page_dsl"
 require "administratum/paths"
+require "administratum/reorder"
 require "administratum/registry"
 require "administratum/ransackable"
 require "administratum/routing"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: administratum
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - buffpojken
@@ -114,6 +114,7 @@ files:
 - app/helpers/administratum/form_helper.rb
 - app/helpers/administratum/island_helper.rb
 - app/helpers/administratum/layout_helper.rb
+- app/helpers/administratum/reorder_helper.rb
 - app/helpers/administratum/resource_helper.rb
 - app/mailers/administratum/application_mailer.rb
 - app/mailers/administratum/user_mailer.rb
@@ -172,6 +173,7 @@ files:
 - lib/administratum/paths.rb
 - lib/administratum/ransackable.rb
 - lib/administratum/registry.rb
+- lib/administratum/reorder.rb
 - lib/administratum/routing.rb
 - lib/administratum/tailwind.rb
 - lib/administratum/version.rb