active_fields 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e668baeb2df705293feec23b2948fd6ca762bd3e5f6671aec273579133cfb368
-  data.tar.gz: a7eac6f5cb2a46e9d246e2d3d8023a9e1995446d92d9c2cf93ab1100f265d283
+  metadata.gz: bd75dc9f715c95766a238fd268c8174c7920e2b64ddce086f4bd7eed9ea2c36a
+  data.tar.gz: 74ba8eaf11a578067d0c45730a59aa60dc23363b9e5ffcce5bfca7795ee12da3
 SHA512:
-  metadata.gz: 1c7007b25907d9f0a25b5ef76bb4b031772a0cdf859243676c242fb57f457dab768b5f629760b68661a3b00aa60601b0bf856911a816313a36a53b74206dbb4b
-  data.tar.gz: 83595ef579ea24057de81a0f5b07563eaf77a0e8e2a78da3b30bbf4f0312246c6ca237590f77d279c990c9765f982e8293958b1df73d92996e2f63dc567990c8
+  metadata.gz: 4cc1b2984a7912497bc1b26cec3fc793bb897cc813c76440b5a8513834acae27d5c4df5da9c5f87cf9b36ae79351cacb52ab60965195fa6b44ce6ec8fc4f3c4e
+  data.tar.gz: 2f03d79bb28e91af86a99d36ff60a992b14ecf9c13d6d8a13eb92490790c4cd71afb11465173ba8a2a756cc24c3cf50c488a13bc8fca90d619b1079ec88fe216

data/.rubocop.yml

@@ -11,7 +11,7 @@ inherit_gem:
 
 AllCops:
   TargetRubyVersion: 3.3
-  TargetRailsVersion: 7.1
+  TargetRailsVersion: 7.2
   NewCops: enable
   Exclude:
     - "spec/dummy/db/schema.rb"

data/CHANGELOG.md

@@ -1,4 +1,10 @@
 ## [Unreleased]
+
+## [1.1.0] - 2024-09-10
+- Added scaffold generator
+- Disabled models reloading to prevent STI issues
+
+## [1.0.0] - 2024-09-07
 - Precision configuration for decimal fields
 - Added array field types mix-in `ActiveFields::FieldArrayConcern`
 - Fixed enum types behavior for blank values

data/README.md

@@ -9,9 +9,9 @@ enabling the addition of custom fields to any model at runtime without requiring
 
 ## Key Concepts
 
-- **Active Field**: A record with the definition of a custom field.
-- **Active Value**: A record that stores the value of an _Active Field_ for a specific _Customizable_.
-- **Customizable**: A record that has custom fields.
+- **Customizable**: A record that has custom fields (_Entity_).
+- **Active Field**: A record with the definition of a custom field (_Attribute_).
+- **Active Value**: A record that stores the value of an _Active Field_ for a specific _Customizable_ (_Value_).
 
 ## Models Structure
 
@@ -24,11 +24,11 @@ classDiagram
         + string name
         + string type
         + string customizable_type
-        + json default_value
+        + json default_value_meta
         + json options
     }
     class ActiveValue {
-        + json value
+        + json value_meta
     }
     class Customizable {
         // This is your model
@@ -56,78 +56,90 @@ such as booleans, strings, numbers, arrays, etc.
 3. Add the `has_active_fields` method to any models where you want to enable custom fields:
 
     ```ruby
-    class Author < ApplicationRecord
+    class Post < ApplicationRecord
       has_active_fields
     end
     ```
 
-4. Implement the necessary code to work with _Active Fields_.
+4. Run scaffold generator.
 
-    This plugin provides a convenient API and helpers, allowing you to write code that meets your specific needs
+    This plugin provides a convenient API, allowing you to write code that meets your specific needs
     without being forced to use predefined implementations that is hard to extend.
 
-    Generally, you should:
-     - Implement a controller and UI for managing _Active Fields_.
-     - Add inputs for _Active Values_ in _Customizable_ forms and permit their params in the controller.
-
-     To set _Active Values_ for your _Customizable_, use the `active_fields_attributes=` method,
-     that integrates with Rails `fields_for` to generate appropriate form fields.
-     Alternatively, the alias `active_fields=` can be used in contexts without `fields_for`, such as APIs.
-
-     To prepare a collection of _Active Values_ for use with the `fields_for` builder,
-     call the `initialize_active_values` method.
-
-     **Note:** By default, Rails form fields insert an empty string into array (multiple) parameters.
-     You’ll need to handle the removal of these empty strings.
-
-     ```ruby
-     # app/controllers/posts_controller.rb
-     # ...
-
-     def new
-       @post = Post.new
-       @post.initialize_active_values
-     end
-
-     def edit
-       @post.initialize_active_values
-     end
-
-     def post_params
-       permitted_params = params.require(:post).permit(
-         # ...
-         active_fields_attributes: [:name, :value, :_destroy, value: []],
-       )
-       permitted_params[:active_fields_attributes]&.each do |_index, value_attrs|
-         value_attrs[:value] = compact_array_param(value_attrs[:value]) if value_attrs[:value].is_a?(Array)
-       end
-
-       permitted_params
-     end
-
-     def compact_array_param(value)
-       if value.first == ""
-         value[1..-1]
-       else
-         value
-       end
-     end
-     ```
-
-     ```erb
-     # app/views/posts/_form.html.erb
-     # ...
-
-     <%= form.fields_for :active_fields, post.active_values.sort_by(&:active_field_id), include_id: false do |active_fields_form| %>
-       <%= active_fields_form.hidden_field :name %>
-       # Render appropriate Active Value input and (optionally) destroy flag here
-     <% end %>
-
-     # ...
-     ```
-
-    You can find a detailed [example](https://github.com/lassoid/active_fields/blob/main/spec/dummy) 
-    of how to implement this in a full-stack Rails application.
+    However, for a quick start, you can generate a scaffold by running the following command:
+
+    ```shell
+    bin/rails generate active_fields:scaffold
+    ```
+
+    This command generates a controller, routes and views for managing _Active Fields_,
+    along with form inputs for _Active Values_ and some useful helper methods.
+
+    **Note:** Don't forget to add available _Customizable_ types in generated _Active Fields_ forms.
+
+    **Note:** The array field helper uses _Stimulus_ for interactivity.
+    If your app doesn't already include _Stimulus_, you can [easily add it](https://github.com/hotwired/stimulus-rails).
+    Alternatively, if you prefer not to use _Stimulus_, you should implement your own JavaScript code.
+
+5. Add _Active Fields_ inputs in _Customizables_ forms and permit their params in controllers.
+
+    There are two methods available on _Customizable_ models for retrieving _Active Values_:
+    - `active_values` returns collection of only existing _Active Values_.
+    - `initialize_active_values` builds any missing _Active Values_ and returns the full collection.
+
+    Choose the method that suits your requirements.
+    In most cases, however, `initialize_active_values` is the more suitable option.
+
+    ```erb
+    # app/views/posts/_form.html.erb
+    # ...
+
+    <%= form.fields_for :active_fields, post.initialize_active_values.sort_by(&:active_field_id), include_id: false do |active_fields_form| %>
+      <%= active_fields_form.hidden_field :name %>
+      <%= render_active_value_input(form: active_fields_form, active_value: active_fields_form.object) %>
+    <% end %>
+
+    # ...
+    ```
+
+    Finally, permit the _Active Fields_ attributes in your _Customizables_ controllers:
+
+    ```ruby
+    # app/controllers/posts_controller.rb
+    # ...
+
+    def post_params
+      permitted_params = params.require(:post).permit(
+        # ...
+        active_fields_attributes: [:name, :value, :_destroy, value: []],
+      )
+      permitted_params[:active_fields_attributes]&.each do |_index, value_attrs|
+        value_attrs[:value] = compact_array_param(value_attrs[:value]) if value_attrs[:value].is_a?(Array)
+      end
+    
+      permitted_params
+    end
+
+    # Removes an empty string from the beginning of the array parameter
+    def compact_array_param(value)
+      if value.first == ""
+        value[1..-1]
+      else
+        value
+      end
+    end
+    ```
+
+    **Note:** Here we use the `active_fields_attributes=` method (as a permitted parameter),
+    that integrates well with Rails `fields_for` to generate appropriate form fields.
+    Alternatively, the alias `active_fields=` can be used in contexts without `fields_for`, such as API controllers.
+
+    That's it!
+    You can now add _Active Fields_ to _Customizables_ at `http://localhost:3000/active_fields`
+    and fill in _Active Values_ within _Customizable_ forms.
+
+    You can also explore the [Demo app](https://github.com/lassoid/active_fields/blob/main/spec/dummy)
+    where the plugin is fully integrated into a full-stack Rails application.
     Feel free to explore the source code and run it locally:
 
     ```shell
@@ -251,7 +263,7 @@ classDiagram
 - `name`(`string`)
 - `type`(`string`)
 - `customizable_type`(`string`)
-- `default_value` (`json`)
+- `default_value_meta` (`json`)
 
 ### Field Types Summary
 
@@ -495,6 +507,8 @@ For an example, refer to the [locale file](https://github.com/lassoid/active_fie
     leading to the associated _Customizables_ also becoming invalid,
     which could potentially result in update failures.
 
+3. Only _Zeitwerk_ autoloading mode is supported.
+
 ## API Overview
 
 ### Fields API
@@ -510,7 +524,7 @@ active_field.type # Class name of this Active Field (utilizing STI)
 active_field.customizable_type # Name of the Customizable model this Active Field is registered to
 active_field.name # Identifier of this Active Field, it should be unique in scope of customizable_type
 active_field.default_value_meta # JSON column declaring the default value. Consider using `default_value` instead
-active_field.options # A hash (json) containing type-specific attributes for this Active Field
+active_field.options # JSON column containing type-specific attributes for this Active Field
 
 # Methods:
 active_field.default_value # Default value for all Active Values associated with this Active Field
@@ -523,7 +537,7 @@ active_field.customizable_model # Customizable model class
 active_field.type_name # Identifier of the type of this Active Field (instead of class name)
 
 # Scopes:
-ActiveFields::Field::Boolean.for("Author") # Collection of Active Fields registered for the specified Customizable type
+ActiveFields::Field::Boolean.for("Post") # Collection of Active Fields registered for the specified Customizable type
 ```
 
 ### Values API
@@ -546,7 +560,7 @@ active_value.name # Name of the associated Active Field
 ### Customizable API
 
 ```ruby
-customizable = Author.take
+customizable = Post.take
 
 # Associations:
 customizable.active_values # `has_many` association with Active Values linked to this Customizable
@@ -577,9 +591,10 @@ customizable.active_fields = [
 # Please use `active_fields_attributes=`/`active_fields=` instead.
 customizable.active_values_attributes = attributes
 
-# Build an Active Value, if it doesn't exist, with the default value for each Active Field.
+# Build not existing Active Values, with the default value for each Active Field.
+# Returns full collection of Active Values.
 # This method is useful with `fields_for`, allowing you to pass the collection as an argument to render new Active Values:
-# `form.fields_for :active_values, customizable.active_values`.
+# `form.fields_for :active_fields, customizable.initialize_active_values`.
 customizable.initialize_active_values
 ```
 
@@ -602,7 +617,7 @@ ActiveFields.config.register_field(:ip, "IpField") # Register a custom Active Fi
 ### Customizable Config
 
 ```ruby
-customizable_model = Author
+customizable_model = Post
 customizable_model.active_fields_config # Access the Customizable's configuration
 customizable_model.active_fields_config.customizable_model # The Customizable model itself
 customizable_model.active_fields_config.types # Allowed Active Field types (e.g., `[:boolean]`)

data/app/models/concerns/active_fields/customizable_concern.rb

@@ -80,7 +80,8 @@ module ActiveFields
 
     alias_method :active_fields=, :active_fields_attributes=
 
-    # Build an active_value, if it doesn't exist, with a default value for each available active_field
+    # Build an active_value, if it doesn't exist, with a default value for each available active_field.
+    # Returns active_values collection.
     def initialize_active_values
       existing_field_ids = active_values.map(&:active_field_id)
 
@@ -89,6 +90,8 @@ module ActiveFields
 
         active_values.new(active_field: active_field, value: active_field.default_value)
       end
+
+      active_values
     end
   end
 end

data/lib/active_fields/engine.rb

@@ -4,6 +4,12 @@ module ActiveFields
   class Engine < ::Rails::Engine
     isolate_namespace ActiveFields
 
+    config.eager_load_namespaces << ActiveFields
+
+    # Disable models reloading to avoid STI issues.
+    # Reloading can prevent subclasses from recognizing the base class.
+    config.autoload_once_paths = %W[#{root}/app/models #{root}/app/models/concerns]
+
     initializer "active_fields.active_record" do
       ActiveSupport.on_load(:active_record) do
         include HasActiveFields

data/lib/active_fields/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveFields
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/active_fields.rb

@@ -4,42 +4,62 @@ require_relative "active_fields/version"
 require_relative "active_fields/engine"
 
 module ActiveFields
-  autoload :Config, "active_fields/config"
-  autoload :CustomizableConfig, "active_fields/customizable_config"
-  autoload :HasActiveFields, "active_fields/has_active_fields"
+  extend ActiveSupport::Autoload
+
+  class << self
+    def eager_load!
+      super
+      Casters.eager_load!
+      Validators.eager_load!
+    end
+  end
+
+  eager_autoload do
+    autoload :Config
+    autoload :CustomizableConfig
+    autoload :HasActiveFields
+  end
 
   module Casters
-    autoload :BaseCaster, "active_fields/casters/base_caster"
-    autoload :BooleanCaster, "active_fields/casters/boolean_caster"
-    autoload :DateCaster, "active_fields/casters/date_caster"
-    autoload :DateArrayCaster, "active_fields/casters/date_array_caster"
-    autoload :DateTimeCaster, "active_fields/casters/date_time_caster"
-    autoload :DateTimeArrayCaster, "active_fields/casters/date_time_array_caster"
-    autoload :DecimalCaster, "active_fields/casters/decimal_caster"
-    autoload :DecimalArrayCaster, "active_fields/casters/decimal_array_caster"
-    autoload :EnumCaster, "active_fields/casters/enum_caster"
-    autoload :EnumArrayCaster, "active_fields/casters/enum_array_caster"
-    autoload :IntegerCaster, "active_fields/casters/integer_caster"
-    autoload :IntegerArrayCaster, "active_fields/casters/integer_array_caster"
-    autoload :TextCaster, "active_fields/casters/text_caster"
-    autoload :TextArrayCaster, "active_fields/casters/text_array_caster"
+    extend ActiveSupport::Autoload
+
+    eager_autoload do
+      autoload :BaseCaster
+      autoload :BooleanCaster
+      autoload :DateCaster
+      autoload :DateArrayCaster
+      autoload :DateTimeCaster
+      autoload :DateTimeArrayCaster
+      autoload :DecimalCaster
+      autoload :DecimalArrayCaster
+      autoload :EnumCaster
+      autoload :EnumArrayCaster
+      autoload :IntegerCaster
+      autoload :IntegerArrayCaster
+      autoload :TextCaster
+      autoload :TextArrayCaster
+    end
   end
 
   module Validators
-    autoload :BaseValidator, "active_fields/validators/base_validator"
-    autoload :BooleanValidator, "active_fields/validators/boolean_validator"
-    autoload :DateValidator, "active_fields/validators/date_validator"
-    autoload :DateArrayValidator, "active_fields/validators/date_array_validator"
-    autoload :DateTimeValidator, "active_fields/validators/date_time_validator"
-    autoload :DateTimeArrayValidator, "active_fields/validators/date_time_array_validator"
-    autoload :DecimalValidator, "active_fields/validators/decimal_validator"
-    autoload :DecimalArrayValidator, "active_fields/validators/decimal_array_validator"
-    autoload :EnumValidator, "active_fields/validators/enum_validator"
-    autoload :EnumArrayValidator, "active_fields/validators/enum_array_validator"
-    autoload :IntegerValidator, "active_fields/validators/integer_validator"
-    autoload :IntegerArrayValidator, "active_fields/validators/integer_array_validator"
-    autoload :TextValidator, "active_fields/validators/text_validator"
-    autoload :TextArrayValidator, "active_fields/validators/text_array_validator"
+    extend ActiveSupport::Autoload
+
+    eager_autoload do
+      autoload :BaseValidator
+      autoload :BooleanValidator
+      autoload :DateValidator
+      autoload :DateArrayValidator
+      autoload :DateTimeValidator
+      autoload :DateTimeArrayValidator
+      autoload :DecimalValidator
+      autoload :DecimalArrayValidator
+      autoload :EnumValidator
+      autoload :EnumArrayValidator
+      autoload :IntegerValidator
+      autoload :IntegerArrayValidator
+      autoload :TextValidator
+      autoload :TextArrayValidator
+    end
   end
 
   class << self

data/lib/generators/active_fields/install/install_generator.rb

@@ -5,7 +5,7 @@ require "rails/generators"
 module ActiveFields
   module Generators
     class InstallGenerator < ::Rails::Generators::Base
-      desc "This generator creates an create_initializer and copies plugin migrations"
+      desc "This generator creates an initializer and copies plugin migrations"
 
       def create_initializer
         initializer "active_fields.rb", <<~RUBY

data/lib/generators/active_fields/scaffold/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Creates a controller, routes and views for managing Active Fields,
+    along with form inputs for Active Values and some useful helper methods.
+
+    The code it generates is unlikely to be a perfect fit for your application.
+    You’ll most probably want to customize the generated code.
+
+Examples:
+    `bin/rails generate active_fields:scaffold`

data/lib/generators/active_fields/scaffold/scaffold_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module ActiveFields
+  module Generators
+    class ScaffoldGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "This generator creates some useful templates"
+
+      def copy_files
+        Dir.glob("**/*", base: self.class.source_root).each do |path|
+          next unless File.file?(File.expand_path(path, self.class.source_root))
+
+          copy_file path, File.join("app", path)
+        end
+      end
+
+      def add_routes
+        route "resources :active_fields"
+      end
+    end
+  end
+end

data/lib/generators/active_fields/scaffold/templates/controllers/active_fields_controller.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+class ActiveFieldsController < ApplicationController
+  helper ActiveFieldsHelper
+
+  before_action :set_active_field, only: %i[show edit update destroy]
+
+  def index
+    @active_fields = ActiveFields.config.field_base_class.order(:customizable_type, :id)
+  end
+
+  def show; end
+
+  def new
+    @active_field = model_class.new
+  end
+
+  def create
+    @active_field = model_class.new(active_field_create_params(model_class))
+
+    if @active_field.save
+      redirect_to edit_active_field_path(@active_field), status: :see_other
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def edit; end
+
+  def update
+    if @active_field.update(active_field_update_params(@active_field.class))
+      redirect_to edit_active_field_path(@active_field), status: :see_other
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  def destroy
+    @active_field.destroy!
+
+    redirect_to active_fields_path, status: :see_other
+  end
+
+  private
+
+  def active_field_create_params(model_class)
+    params.require(:active_field).permit(*permitted_attributes_for_create(model_class)).tap do |attrs|
+      attrs.transform_values! do |value|
+        value.is_a?(Array) ? compact_array_param(value) : value
+      end
+    end
+  end
+
+  def active_field_update_params(model_class)
+    params.require(:active_field).permit(*permitted_attributes_for_update(model_class)).tap do |attrs|
+      attrs.transform_values! do |value|
+        value.is_a?(Array) ? compact_array_param(value) : value
+      end
+    end
+  end
+
+  def compact_array_param(value)
+    if value.first == ""
+      value[1..-1]
+    else
+      value
+    end
+  end
+
+  # It is strongly recommended to move it to, for example, policies.
+  def permitted_attributes_for_create(model_class)
+    if model_class == ActiveFields::Field::Boolean
+      %i[customizable_type name required nullable default_value]
+    elsif model_class == ActiveFields::Field::Date
+      %i[customizable_type name required min max default_value]
+    elsif model_class == ActiveFields::Field::DateArray
+      [:customizable_type, :name, :min_size, :max_size, :min, :max, default_value: []]
+    elsif model_class == ActiveFields::Field::DateTime
+      %i[customizable_type name required min max precision default_value]
+    elsif model_class == ActiveFields::Field::DateTimeArray
+      [:customizable_type, :name, :min_size, :max_size, :min, :max, :precision, default_value: []]
+    elsif model_class == ActiveFields::Field::Decimal
+      %i[customizable_type name required min max precision default_value]
+    elsif model_class == ActiveFields::Field::DecimalArray
+      [:customizable_type, :name, :min_size, :max_size, :min, :max, :precision, default_value: []]
+    elsif model_class == ActiveFields::Field::Enum
+      [:customizable_type, :name, :required, :default_value, allowed_values: []]
+    elsif model_class == ActiveFields::Field::EnumArray
+      [:customizable_type, :name, :min_size, :max_size, allowed_values: [], default_value: []]
+    elsif model_class == ActiveFields::Field::Integer
+      %i[customizable_type name required min max default_value]
+    elsif model_class == ActiveFields::Field::IntegerArray
+      [:customizable_type, :name, :min_size, :max_size, :min, :max, default_value: []]
+    elsif model_class == ActiveFields::Field::Text
+      %i[customizable_type name min_length max_length default_value]
+    elsif model_class == ActiveFields::Field::TextArray
+      [:customizable_type, :name, :min_size, :max_size, :min_length, :max_length, default_value: []]
+    else
+      raise ArgumentError, "undefined model_class `#{model_class.inspect}`"
+    end
+  end
+
+  # It is strongly recommended to move it to, for example, policies.
+  def permitted_attributes_for_update(model_class)
+    if model_class == ActiveFields::Field::Boolean
+      %i[name default_value]
+    elsif model_class == ActiveFields::Field::Date
+      %i[name default_value]
+    elsif model_class == ActiveFields::Field::DateArray
+      [:name, default_value: []]
+    elsif model_class == ActiveFields::Field::DateTime
+      %i[name default_value]
+    elsif model_class == ActiveFields::Field::DateTimeArray
+      [:name, default_value: []]
+    elsif model_class == ActiveFields::Field::Decimal
+      %i[name default_value]
+    elsif model_class == ActiveFields::Field::DecimalArray
+      [:name, default_value: []]
+    elsif model_class == ActiveFields::Field::Enum
+      %i[name default_value]
+    elsif model_class == ActiveFields::Field::EnumArray
+      [:name, default_value: []]
+    elsif model_class == ActiveFields::Field::Integer
+      %i[name default_value]
+    elsif model_class == ActiveFields::Field::IntegerArray
+      [:name, default_value: []]
+    elsif model_class == ActiveFields::Field::Text
+      %i[name default_value]
+    elsif model_class == ActiveFields::Field::TextArray
+      [:name, default_value: []]
+    else
+      raise ArgumentError, "undefined model_class `#{model_class.inspect}`"
+    end
+  end
+
+  def set_active_field
+    @active_field = ActiveFields.config.field_base_class.find(params[:id])
+  end
+
+  def model_class
+    (ActiveFields.config.fields[params[:type]&.to_sym] || ActiveFields.config.type_class_names.first).constantize
+  end
+end

data/lib/generators/active_fields/scaffold/templates/helpers/active_fields_helper.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActiveFieldsHelper
+  def render_array_field(form:, name:, value:, field_method:, field_opts: {})
+    render partial: "shared/array_field", locals: {
+      form: form,
+      name: name,
+      value: value,
+      field_method: field_method,
+      field_opts: field_opts,
+    }
+  end
+
+  def render_active_field_form(active_field:)
+    partial = active_field_form(active_field)
+
+    render partial: partial, locals: { active_field: active_field }
+  end
+
+  def render_active_value_input(form:, active_value:)
+    partial = active_value_input(active_value.active_field)
+
+    render partial: partial, locals: { form: form, active_value: active_value, active_field: active_value.active_field }
+  end
+
+  def active_field_form(active_field)
+    "active_fields/forms/#{active_field.type_name}"
+  end
+
+  def active_value_input(active_field)
+    "active_fields/values/inputs/#{active_field.type_name}"
+  end
+end