Add custom look

Author: goosys

docs/adding_custom_field_types.md

@@ -58,6 +58,21 @@ Since we want to display an image, we can change it to:
 You can customize the other generated partials in the same way
 for custom behavior on the index and form pages.
 
+## Using a Custom Look
+
+If you want to generate a different look, run the following:
+
+```bash
+rails generate administrate:field gravatar --look custom
+```
+
+This will generate three files:
+
+- `app/fields/gravatar_field.rb`
+- `app/views/fields/gravatar_field/looks/custom/_show.html.erb`
+- `app/views/fields/gravatar_field/looks/custom/_index.html.erb`
+- `app/views/fields/gravatar_field/looks/custom/_form.html.erb`
+
 ## Using your custom field
 
 We need to tell Administrate which attributes we'd like to be displayed as a

docs/customizing_attribute_partials.md

@@ -54,3 +54,17 @@ Changing numbers to display to three decimal places might look like this:
 
 If you only want to change how an attribute appears
 on a single page (e.g. `index`), you may delete the unnecessary templates.
+
+## Using a Custom Look
+
+If you want to generate a different look, run the following:
+
+```bash
+rails generate administrate:views:field number --look custom
+```
+
+This will generate three files:
+
+- `app/view/fields/number/looks/custom/_form.html.erb`
+- `app/view/fields/number/looks/custom/_index.html.erb`
+- `app/view/fields/number/looks/custom/_show.html.erb`

docs/customizing_dashboards.md

@@ -647,3 +647,28 @@ end
   <%= button_to "some action 3", [:some_action_3, namespace, field.resource] %>
 <% end %>
 ```
+
+## Custom Look
+
+You can use the `look` option to change the field template.
+
+```ruby
+ATTRIBUTE_TYPES = {
+  customer: Field::BelongsTo.with_options(look: :customer_card)
+}
+```
+
+The template path is derived from the class name of the field and falls back sequentially to its ancestor classes.
+For example, the path lookup order for a `BelongsTo` field is as follows:
+
+```
+fields/belongs_to/looks/customer_card/
+fields/belongs_to/looks/default/
+fields/belongs_to/
+fields/associative/looks/customer_card/
+fields/associative/looks/default/
+fields/associative/
+fields/base/looks/customer_card/
+fields/base/looks/default/
+fields/base/
+```

lib/administrate/field/base.rb

@@ -4,6 +4,17 @@
 module Administrate
   module Field
     class Base
+      @partial_prefixes = {}
+
+      class << self
+        attr_writer :partial_prefixes
+      end
+
+      def self.inherited(subclass)
+        super
+        subclass.partial_prefixes = {}
+      end
+
       def self.with_options(options = {})
         Deferred.new(self, options)
       end
@@ -36,17 +47,22 @@ def self.permitted_attribute(attr, _options = nil)
         attr
       end
 
-      def self.partial_prefixes
-        @partial_prefixes ||=
+      def self.partial_prefixes(look: :default)
+        @partial_prefixes[look] ||=
           if superclass.respond_to?(:partial_prefixes)
-            local_partial_prefixes + superclass.partial_prefixes
+            local_partial_prefixes(look:) + superclass.partial_prefixes(look:)
           else
-            local_partial_prefixes
+            local_partial_prefixes(look:)
           end
       end
 
-      def self.local_partial_prefixes
-        ["fields/#{field_type}"]
+      def self.local_partial_prefixes(look: :default)
+        fallback = ["fields/#{field_type}/looks/default", "fields/#{field_type}"]
+        if look == :default
+          fallback
+        else
+          ["fields/#{field_type}/looks/#{look}"] + fallback
+        end
       end
 
       def initialize(attribute, data, page, options = {})
@@ -84,7 +100,11 @@ def read_value(data)
       end
 
       def partial_prefixes
-        self.class.partial_prefixes
+        self.class.partial_prefixes(look: look)
+      end
+
+      def look
+        (options.fetch(:look, :default).presence || :default).to_sym
       end
 
       def required?

lib/generators/administrate/field/field_generator.rb

@@ -1,6 +1,13 @@
 module Administrate
   module Generators
     class FieldGenerator < Rails::Generators::NamedBase
+      class_option(
+        :look,
+        type: :string,
+        desc: "Specify the look for the field",
+        default: ""
+      )
+
       source_root File.expand_path("../templates", __FILE__)
 
       def template_field_object
@@ -18,12 +25,17 @@ def copy_partials
 
       private
 
+      def look
+        options[:look]
+      end
+
       def copy_partial(partial_name)
         partial = "_#{partial_name}.html.erb"
+        looks_dir = look.present? ? "looks/#{look}/" : ""
 
         copy_file(
           partial,
-          "app/views/fields/#{file_name}_field/#{partial}"
+          "app/views/fields/#{file_name}_field/#{looks_dir}#{partial}"
         )
       end
     end

lib/generators/administrate/views/field_generator.rb

@@ -4,6 +4,13 @@ module Administrate
   module Generators
     module Views
       class FieldGenerator < Administrate::ViewGenerator
+        class_option(
+          :look,
+          type: :string,
+          desc: "Specify the look for the field",
+          default: ""
+        )
+
         def self.template_source_path
           File.expand_path(
             "../../../../../app/views/fields/",
@@ -30,6 +37,10 @@ def copy_partials
 
         private
 
+        def look
+          options[:look]
+        end
+
         def copy_field_partials(resource_path)
           copy_field_partial(resource_path, :index)
           copy_field_partial(resource_path, :show)
@@ -38,10 +49,11 @@ def copy_field_partials(resource_path)
 
         def copy_field_partial(resource_path, partial_name)
           template_file = "#{resource_path}/_#{partial_name}.html.erb"
+          looks_dir = look.present? ? "looks/#{look}/" : ""
 
           copy_file(
             template_file,
-            "app/views/fields/#{template_file}"
+            "app/views/fields/#{resource_path}/#{looks_dir}_#{partial_name}.html.erb"
           )
         end
       end

spec/example_app/app/dashboards/line_item_dashboard.rb

@@ -12,7 +12,7 @@ class LineItemDashboard < Administrate::BaseDashboard
     created_at: Field::DateTime,
     updated_at: Field::DateTime,
     order: Field::BelongsTo,
-    product: Field::BelongsTo.with_options(sorting_column: :name),
+    product: Field::BelongsTo.with_options(sorting_column: :name, look: :product_card),
     quantity: Field::Number,
     total_price: Field::Number.with_options(prefix: "$", decimals: 2),
     unit_price: Field::Number.with_options(prefix: "$", decimals: 2)

spec/example_app/app/dashboards/page_dashboard.rb

@@ -2,7 +2,7 @@
 
 class PageDashboard < Administrate::BaseDashboard
   ATTRIBUTE_TYPES = {
-    product: Field::BelongsTo,
+    product: Field::BelongsTo.with_options(look: :product_card),
     id: Field::Number,
     title: Field::String,
     body: Field::Text,
@@ -12,6 +12,7 @@ class PageDashboard < Administrate::BaseDashboard
 
   COLLECTION_ATTRIBUTES = %i[
     id
+    product
     title
   ].freeze
 

spec/example_app/app/views/fields/belongs_to/looks/product_card/_index.html.erb

@@ -0,0 +1,19 @@
+<% if field.data %>
+  <span>
+    <% if field.data.image_url.present? %>
+      <%= image_tag(
+        field.data.image_url,
+        alt: field.data.name,
+        style: 'max-height: 2em; max-width: 2em;',
+      ) %>
+    <% end %>
+    <% if accessible_action?(field.data, :show) %>
+      <%= link_to(
+        field.display_associated_resource,
+        [namespace, field.data],
+      ) %>
+    <% else %>
+      <%= field.display_associated_resource %>
+    <% end %>
+  </span>
+<% end %>

spec/example_app/app/views/fields/belongs_to/looks/product_card/_show.html.erb

@@ -0,0 +1,19 @@
+<% if field.data %>
+  <span style="display: flex; align-items: center; gap: 0.2em;">
+    <% if field.data.image_url.present? %>
+      <%= image_tag(
+        field.data.image_url,
+        alt: field.data.name,
+        style: 'max-height: 2em; max-width: 2em;',
+      ) %>
+    <% end %>
+    <% if accessible_action?(field.data, :show) %>
+      <%= link_to(
+        field.display_associated_resource,
+        [namespace, field.data],
+      ) %>
+    <% else %>
+      <%= field.display_associated_resource %>
+    <% end %>
+  </span>
+<% end %>