administrate 1.0.0.beta1 → 1.0.0.beta2

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`.
@@ -113,7 +114,7 @@ association `belongs_to :country`, from your model.
 
 **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,
@@ -144,14 +145,14 @@ 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.
 
@@ -266,6 +267,9 @@ Default is `false`.
 `: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.
@@ -436,3 +440,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,28 @@ 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 %>
+```

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"

data/lib/administrate/engine.rb

@@ -24,6 +24,12 @@ module Administrate
       ]
     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

data/lib/administrate/field/associative.rb

@@ -46,6 +46,10 @@ module Administrate
         end
       end
 
+      def html_controller
+        "select"
+      end
+
       private
 
       def associated_dashboard

data/lib/administrate/field/base.rb

@@ -34,20 +34,38 @@ module Administrate
 
       def initialize(attribute, data, page, options = {})
         @attribute = attribute
-        @data = data
         @page = page
         @resource = options.delete(:resource)
         @options = options
+        @data = read_value(data)
       end
 
       def html_class
         self.class.html_class
       end
 
+      def html_controller
+        nil
+      end
+
       def name
         attribute.to_s
       end
 
+      def read_value(data)
+        if options.key?(:getter)
+          if options[:getter].respond_to?(:call)
+            options[:getter].call(self)
+          else
+            resource.try(options[:getter])
+          end
+        elsif data.nil?
+          resource.try(attribute)
+        else
+          data
+        end
+      end
+
       def to_partial_path
         "/fields/#{self.class.field_type}/#{page}"
       end

data/lib/administrate/field/belongs_to.rb

@@ -41,7 +41,12 @@ module Administrate
       private
 
       def candidate_resources
-        scope = options[:scope] ? options[:scope].call : associated_class.all
+        scope =
+          if options[:scope]
+            options[:scope].arity.positive? ? options[:scope].call(self) : options[:scope].call
+          else
+            associated_class.all
+          end
 
         order = options.delete(:order)
         order ? scope.reorder(order) : scope

data/lib/administrate/field/deferred.rb

@@ -21,6 +21,10 @@ module Administrate
           options == other.options
       end
 
+      def getter
+        options.fetch(:getter, nil)
+      end
+
       def associative?
         deferred_class.associative?
       end
@@ -30,7 +34,11 @@ module Administrate
       end
 
       def searchable?
-        options.fetch(:searchable, deferred_class.searchable?)
+        if options.key?(:getter)
+          false
+        else
+          options.fetch(:searchable, deferred_class.searchable?)
+        end
       end
 
       def searchable_field

data/lib/administrate/field/has_one.rb

@@ -48,6 +48,10 @@ module Administrate
         data.try(:persisted?)
       end
 
+      def html_controller
+        "select"
+      end
+
       private
 
       def resolver

data/lib/administrate/field/rich_text.rb

@@ -0,0 +1,21 @@
+require "administrate/field/base"
+
+module Administrate
+  module Field
+    class RichText < Administrate::Field::Base
+      def to_s
+        data&.to_plain_text
+      end
+
+      def truncate
+        to_s.truncate(truncation_length)
+      end
+
+      private
+
+      def truncation_length
+        options.fetch(:truncate, 50)
+      end
+    end
+  end
+end

data/lib/administrate/field/select.rb

@@ -35,6 +35,10 @@ module Administrate
       def active_record_enum_values
         resource.class.defined_enums[attribute.to_s].map(&:first)
       end
+
+      def html_controller
+        "select"
+      end
     end
   end
 end

data/lib/administrate/order.rb

@@ -75,7 +75,7 @@ module Administrate
 
     def order_by_belongs_to(relation)
       if ordering_by_association_column?(relation)
-        order_by_attribute(relation)
+        order_by_association_attribute(relation)
       else
         order_by_id(relation)
       end
@@ -83,26 +83,16 @@ module Administrate
 
     def order_by_has_one(relation)
       if ordering_by_association_column?(relation)
-        order_by_attribute(relation)
+        order_by_association_attribute(relation)
       else
         order_by_association_id(relation)
       end
     end
 
-    def order_by_attribute(relation)
-      relation.joins(
-        attribute.to_sym
-      ).reorder(order_by_attribute_query)
-    end
-
     def order_by_id(relation)
       relation.reorder(order_by_id_query(relation))
     end
 
-    def order_by_association_id(relation)
-      relation.reorder(order_by_association_id_query)
-    end
-
     def ordering_by_association_column?(relation)
       association_attribute &&
         column_exist?(
@@ -115,16 +105,26 @@ module Administrate
     end
 
     def order_by_id_query(relation)
-      relation.arel_table[foreign_key(relation)].public_send(direction)
+      relation.arel_table[association_foreign_key(relation)].public_send(direction)
+    end
+
+    def order_by_association_id(relation)
+      order_by_association_column(relation, association_primary_key(relation))
+    end
+
+    def order_by_association_attribute(relation)
+      order_by_association_column(relation, association_attribute)
     end
 
-    def order_by_association_id_query
-      Arel::Table.new(association_table_name)[:id].public_send(direction)
+    def order_by_association_column(relation, column_name)
+      relation.joins(
+        attribute.to_sym
+      ).reorder(order_by_association_column_query(relation, column_name))
     end
 
-    def order_by_attribute_query
-      table = Arel::Table.new(association_table_name)
-      table[association_attribute].public_send(direction)
+    def order_by_association_column_query(relation, column)
+      table = Arel::Table.new(association_table_name(relation))
+      table[column].public_send(direction)
     end
 
     def relation_type(relation)
@@ -135,12 +135,16 @@ module Administrate
       relation.klass.reflect_on_association(attribute.to_s)
     end
 
-    def foreign_key(relation)
+    def association_foreign_key(relation)
       reflect_association(relation).foreign_key
     end
 
-    def association_table_name
-      attribute.tableize
+    def association_primary_key(relation)
+      reflect_association(relation).association_primary_key
+    end
+
+    def association_table_name(relation)
+      reflect_association(relation).table_name
     end
   end
 end

data/lib/administrate/page/base.rb

@@ -30,13 +30,8 @@ module Administrate
       private
 
       def attribute_field(dashboard, resource, attribute_name, page)
-        value = get_attribute_value(resource, attribute_name)
         field = dashboard.attribute_type_for(attribute_name)
-        field.new(attribute_name, value, page, resource: resource)
-      end
-
-      def get_attribute_value(resource, attribute_name)
-        resource.public_send(attribute_name)
+        field.new(attribute_name, nil, page, resource: resource)
       end
 
       attr_reader :dashboard, :options

data/lib/administrate/version.rb

@@ -1,3 +1,3 @@
 module Administrate
-  VERSION = "1.0.0.beta1".freeze
+  VERSION = "1.0.0.beta2".freeze
 end

data/lib/generators/administrate/dashboard/dashboard_generator.rb

@@ -37,15 +37,18 @@ module Administrate
       source_root File.expand_path("../templates", __FILE__)
 
       def create_dashboard_definition
+        scope = regular_class_path.join("/")
+
         template(
           "dashboard.rb.erb",
-          Rails.root.join("app/dashboards/#{file_name}_dashboard.rb")
+          Rails.root.join("app/dashboards/#{scope}/#{file_name}_dashboard.rb")
         )
       end
 
       def create_resource_controller
+        scope = "#{namespace}/#{regular_class_path.join("/")}"
         destination = Rails.root.join(
-          "app/controllers/#{namespace}/#{file_name.pluralize}_controller.rb"
+          "app/controllers/#{scope}/#{file_name.pluralize}_controller.rb"
         )
 
         template("controller.rb.erb", destination)

data/lib/generators/administrate/views/index_generator.rb

@@ -9,6 +9,7 @@ module Administrate
         def copy_template
           copy_resource_template("index")
           copy_resource_template("_collection")
+          copy_resource_template("_index_header")
         end
       end
     end

data/lib/generators/administrate/views/layout_generator.rb

@@ -9,7 +9,7 @@ module Administrate
         def copy_template
           copy_file(
             "../../layouts/administrate/application.html.erb",
-            "app/views/layouts/admin/application.html.erb"
+            "app/views/layouts/#{namespace}/application.html.erb"
           )
 
           call_generator("administrate:views:navigation")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: administrate
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta1
+  version: 1.0.0.beta2
 platform: ruby
 authors:
 - Nick Charlton
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-05 00:00:00.000000000 Z
+date: 2024-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -115,9 +115,10 @@ files:
 - app/assets/config/administrate_manifest.js
 - app/assets/javascripts/administrate/add_jquery.js
 - app/assets/javascripts/administrate/application.js
-- app/assets/javascripts/administrate/components/associative.js
-- app/assets/javascripts/administrate/components/select.js
-- app/assets/javascripts/administrate/components/table.js
+- app/assets/javascripts/administrate/controllers/application.js
+- app/assets/javascripts/administrate/controllers/index.js
+- app/assets/javascripts/administrate/controllers/select_controller.js
+- app/assets/javascripts/administrate/controllers/table_controller.js
 - app/assets/stylesheets/administrate-internal/docs.scss
 - app/assets/stylesheets/administrate/application.scss
 - app/assets/stylesheets/administrate/base/_forms.scss
@@ -140,7 +141,6 @@ files:
 - app/assets/stylesheets/administrate/library/_data-label.scss
 - app/assets/stylesheets/administrate/library/_variables.scss
 - app/assets/stylesheets/administrate/reset/_normalize.scss
-- app/assets/stylesheets/administrate/utilities/_text-color.scss
 - app/controllers/administrate/application_controller.rb
 - app/controllers/concerns/administrate/punditize.rb
 - app/helpers/administrate/application_helper.rb
@@ -190,6 +190,9 @@ files:
 - app/views/fields/polymorphic/_form.html.erb
 - app/views/fields/polymorphic/_index.html.erb
 - app/views/fields/polymorphic/_show.html.erb
+- app/views/fields/rich_text/_form.html.erb
+- app/views/fields/rich_text/_index.html.erb
+- app/views/fields/rich_text/_show.html.erb
 - app/views/fields/select/_form.html.erb
 - app/views/fields/select/_index.html.erb
 - app/views/fields/select/_show.html.erb
@@ -264,6 +267,7 @@ files:
 - lib/administrate/field/number.rb
 - lib/administrate/field/password.rb
 - lib/administrate/field/polymorphic.rb
+- lib/administrate/field/rich_text.rb
 - lib/administrate/field/select.rb
 - lib/administrate/field/string.rb
 - lib/administrate/field/text.rb
@@ -283,9 +287,6 @@ files:
 - lib/administrate/search.rb
 - lib/administrate/version.rb
 - lib/administrate/view_generator.rb
-- lib/generators/administrate/assets/assets_generator.rb
-- lib/generators/administrate/assets/javascripts_generator.rb
-- lib/generators/administrate/assets/stylesheets_generator.rb
 - lib/generators/administrate/dashboard/USAGE
 - lib/generators/administrate/dashboard/dashboard_generator.rb
 - lib/generators/administrate/dashboard/templates/controller.rb.erb
@@ -325,11 +326,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.4.20
+rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
 summary: A Rails engine for creating super-flexible admin dashboards

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

@@ -1,5 +0,0 @@
-$(function() {
-  $('.field-unit--belongs-to select').selectize({});
-  $(".field-unit--has-many select").selectize({});
-  $('.field-unit--polymorphic select').selectize({});
-});

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

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

data/app/assets/stylesheets/administrate/utilities/_text-color.scss

@@ -1,3 +0,0 @@
-.text-color-red {
-  color: $red;
-}

data/lib/generators/administrate/assets/assets_generator.rb

@@ -1,12 +0,0 @@
-require "administrate/view_generator"
-
-module Administrate
-  module Generators
-    class AssetsGenerator < Administrate::ViewGenerator
-      def copy_assets
-        call_generator("administrate:assets:javascripts")
-        call_generator("administrate:assets:stylesheets")
-      end
-    end
-  end
-end

data/lib/generators/administrate/assets/javascripts_generator.rb

@@ -1,17 +0,0 @@
-require "rails/generators/base"
-
-module Administrate
-  module Generators
-    module Assets
-      class JavascriptsGenerator < Rails::Generators::Base
-        JAVASCRIPTS_PATH = "app/assets/javascripts/administrate"
-
-        source_root File.expand_path("../../../../../", __FILE__)
-
-        def copy_javascripts
-          directory JAVASCRIPTS_PATH, JAVASCRIPTS_PATH
-        end
-      end
-    end
-  end
-end

data/lib/generators/administrate/assets/stylesheets_generator.rb

@@ -1,17 +0,0 @@
-require "rails/generators/base"
-
-module Administrate
-  module Generators
-    module Assets
-      class StylesheetsGenerator < Rails::Generators::Base
-        STYLESHEETS_PATH = "app/assets/stylesheets/administrate"
-
-        source_root File.expand_path("../../../../../", __FILE__)
-
-        def copy_stylesheets
-          directory STYLESHEETS_PATH, STYLESHEETS_PATH
-        end
-      end
-    end
-  end
-end