action_form 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93e16fca08cba7ced7cf05dfe08e026f45d9ed6fd03d1210de7b82959ee13c13
-  data.tar.gz: 21034909b984567b9ba419474c8afc296b44c86543d881881b69f2600560743d
+  metadata.gz: a83d578e9d0fbf58ccb568473d8a94e1ccb087df4b8f8e5ee2871f2a4689c7b0
+  data.tar.gz: e155e0fada05ece59a1e501fe6d6e52ca0cbd652292f0b243e7e59999760562d
 SHA512:
-  metadata.gz: 16162478587b84ae6cdccbc3d3f62c01c7b1c9fe2657e8f1f1ec3486df05f30d45798c46700c7790d49c68b8cade708d730dfbea2f57726e1d5e472ed87b9d78
-  data.tar.gz: 064b00adb4bffe1b124eaf2e0e12f14028fb50648e161a98cfe933c9e19207b40f6e59fa69134018d1a540dce11c7c383a7ccc2781738a6b9aebd7097e9b49c4
+  metadata.gz: 91b6b047b9ac52d7e1d9162ed4b555456466fa7f59e94d54242492f2e515ad352f145aa179027d51753ec78ed1f12150628e23ab156a56de29b29998e1ae968a
+  data.tar.gz: e64a656d32e8d9ddc91d37d4913c30c513e37854d8f77e368a0acf27e66a1a12a579b8c81bdd4ffd79f4c1ff508850834a256ad93728d762963c8bd317a9c612

data/README.md

@@ -8,6 +8,7 @@ This library allows you to build complex forms in Ruby with a simple DSL. It pro
 
 - A clean, declarative syntax for defining form fields and validations
 - Support for nested forms
+- Custom parameter validation with the `params` method
 - Automatic form rendering with customizable HTML/CSS
 - Built-in error handling and validation
 - Integration with Rails and other Ruby web frameworks
@@ -61,6 +62,7 @@ ActionForm is built around a modular architecture that separates form definition
 
 - **Declarative DSL**: Define forms with simple, readable syntax
 - **Nested Forms**: Support for complex nested structures with `subform` and `many`
+- **Custom Parameter Validation**: Use the `params` method to add custom validation logic and schema modifications
 - **Dynamic Collections**: JavaScript-powered add/remove functionality for many relationships
 - **Flexible Rendering**: Each element can be configured with custom input types, labels, and HTML attributes
 - **Error Integration**: Built-in support for displaying validation errors
@@ -86,6 +88,7 @@ ActionForm follows a bidirectional data flow pattern that handles both form disp
 #### **Key Benefits:**
 - **Single Source of Truth**: The same form definition handles both displaying existing data and processing new data
 - **Automatic Parameter Handling**: [EasyParams](https://github.com/andriy-baran/easy_params) classes are automatically generated to mirror your form structure
+- **Custom Parameter Validation**: Use the `params` method to add custom validation logic and schema modifications
 - **Error Integration**: Failed validations can re-render the form with submitted data and error messages
 - **Nested Support**: Both phases support complex nested structures through `subform` and `many` relationships
 
@@ -250,6 +253,374 @@ class UserForm < ActionForm::Base
 end
 ```
 
+### Custom Parameter Validation
+
+ActionForm provides a `params` method that allows you to add custom validation logic and schema modifications to your form's parameter handling. This is particularly useful for complex validation rules that depend on context or require cross-field validation.
+
+#### **Basic Usage**
+
+Use the `params` method to define custom validation logic:
+
+```ruby
+class UserForm < ActionForm::Base
+  element :email do
+    input type: :email
+    output type: :string, presence: true
+  end
+
+  element :password do
+    input type: :password
+    output type: :string
+  end
+
+  element :password_confirmation do
+    input type: :password
+    output type: :string
+  end
+
+  # Custom parameter validation
+  params do
+    validates :password, presence: true
+    validates :password_confirmation, presence: true
+    validates :password, confirmation: true
+  end
+end
+```
+
+#### **Conditional Validation**
+
+You can add conditional validation logic based on context:
+
+```ruby
+class UserForm < ActionForm::Base
+  element :email do
+    input type: :email
+    output type: :string, presence: true
+  end
+
+  element :password do
+    input type: :password
+    output type: :string
+  end
+
+  # Conditional validation based on external context
+  params do
+    secure_mode = true  # This could come from configuration or request context
+
+    validates :password, presence: true, if: -> { secure_mode }
+    validates :password, length: { minimum: 8 }, if: -> { secure_mode }
+  end
+end
+```
+
+#### **Nested Form Validation**
+
+The `params` method also supports validation for nested forms using schema blocks:
+
+```ruby
+class UserForm < ActionForm::Base
+  element :email do
+    input type: :email
+    output type: :string, presence: true
+  end
+
+  subform :profile, default: {} do
+    element :name do
+      input type: :text
+      output type: :string
+    end
+  end
+
+  many :addresses, default: [{}] do
+    subform do
+      element :street do
+        input type: :text
+        output type: :string
+      end
+
+      element :city do
+        input type: :text
+        output type: :string
+      end
+    end
+  end
+
+  params do
+    # Validate nested subform
+    profile_attributes_schema do
+      validates :name, presence: true
+    end
+
+    # Validate nested collection
+    addresses_attributes_schema do
+      validates :street, presence: true
+      validates :city, presence: true
+    end
+  end
+end
+```
+
+#### **Dynamic Form Classes**
+
+You can create dynamic form classes with different validation rules:
+
+```ruby
+class BaseUserForm < ActionForm::Base
+  element :email do
+    input type: :email
+    output type: :string, presence: true
+  end
+
+  element :password do
+    input type: :password
+    output type: :string
+  end
+end
+
+# Create a secure version with additional validation
+SecureUserForm = Class.new(BaseUserForm)
+SecureUserForm.params do
+  validates :password, presence: true, length: { minimum: 8 }
+  validates :password, format: { with: /\A(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/ }
+end
+
+# Create a basic version with minimal validation
+BasicUserForm = Class.new(BaseUserForm)
+BasicUserForm.params do
+  validates :password, presence: true
+end
+```
+
+#### **Integration with Controllers**
+
+The custom parameter validation integrates seamlessly with your controllers:
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    user_params = UserForm.params_definition.new(params)
+
+    if user_params.valid?
+      @user = User.create!(user_params.to_h)
+      redirect_to @user
+    else
+      @form = @form.with_params(user_params)
+      render :new
+    end
+  end
+end
+```
+
+The `params` method provides a powerful way to extend ActionForm's parameter handling with custom validation logic while maintaining the declarative nature of form definition.
+
+### Modifying Element Definitions
+
+ActionForm allows you to modify existing element, subform, and `many` definitions after they have been declared. This feature enables you to extend or customize form definitions without altering the original class structure, making it perfect for conditional modifications, inheritance patterns, and dynamic form customization.
+
+#### **Modifying Elements**
+
+Use the `{element_name}_element` method to modify an existing element definition:
+
+```ruby
+class UserForm < ActionForm::Base
+  element :email do
+    input type: :email
+    output type: :string
+  end
+
+  element :password do
+    input type: :password
+    output type: :string
+  end
+end
+
+# Modify existing element definitions
+UserForm.email_element do
+  output type: :string, presence: true, format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
+end
+
+UserForm.password_element do
+  output type: :string, presence: true, length: { minimum: 8 }
+end
+```
+
+#### **Modifying Subforms**
+
+Use the `{subform_name}_subform` method to modify an existing subform definition:
+
+```ruby
+class UserForm < ActionForm::Base
+  subform :profile do
+    element :bio do
+      input type: :textarea
+      output type: :string
+    end
+  end
+end
+
+# Modify the subform to add validation or change defaults
+UserForm.profile_subform default: {} do
+  bio_element do
+    output type: :string, presence: true
+  end
+
+  # You can also add new elements
+  element :avatar do
+    input type: :file
+    output type: :string
+  end
+end
+```
+
+#### **Modifying Many Relationships**
+
+Use the `{many_name}_subforms` method to modify an existing `many` definition:
+
+```ruby
+class OrderForm < ActionForm::Base
+  many :items do
+    subform do
+      element :name do
+        input type: :text
+        output type: :string
+      end
+
+      element :quantity do
+        input type: :number
+        output type: :integer
+      end
+    end
+  end
+end
+
+# Modify the many relationship to add validation or change defaults
+OrderForm.items_subforms default: [{}] do
+  subform do
+    name_element do
+      output type: :string, presence: true
+    end
+
+    quantity_element do
+      output type: :integer, presence: true, inclusion: { in: 1..100 }
+    end
+
+    # Add new elements to existing many subforms
+    element :price do
+      input type: :number
+      output type: :float, presence: true
+    end
+  end
+end
+```
+
+#### **Inheritance and Modifications**
+
+Element modifications work seamlessly with class inheritance:
+
+```ruby
+class BaseForm < ActionForm::Base
+  element :name do
+    input type: :text
+    output type: :string
+  end
+end
+
+class UserForm < BaseForm
+  element :email do
+    input type: :email
+    output type: :string
+  end
+end
+
+# Modify inherited elements
+UserForm.name_element do
+  output type: :string, presence: true
+end
+
+# Modify elements defined in subclass
+UserForm.email_element do
+  output type: :string, presence: true
+end
+```
+
+Here's a complete example showing element modifications in action:
+
+```ruby
+class OrderForm < ActionForm::Base
+  element :name do
+    input(type: :text)
+    output(type: :string)
+  end
+
+  subform :customer do
+    element :name do
+      input(type: :text)
+      output(type: :string)
+    end
+  end
+
+  many :items do
+    subform do
+      element :name do
+        input(type: :text)
+        output(type: :string)
+      end
+
+      element :quantity do
+        input(type: :number)
+        output(type: :integer)
+      end
+
+      element :price do
+        input(type: :number)
+        output(type: :float)
+      end
+    end
+  end
+end
+
+# Apply modifications to add validation
+secure = true
+
+OrderForm.name_element do
+  output(type: :string, presence: true, if: -> { secure })
+end
+
+OrderForm.customer_subform default: {} do
+  name_element do
+    output(type: :string, presence: true, if: -> { secure })
+  end
+end
+
+OrderForm.items_subforms default: [{}] do
+  subform do
+    name_element do
+      output(type: :string, presence: true, if: -> { secure })
+    end
+    quantity_element do
+      output(type: :integer, presence: true, if: -> { secure })
+    end
+    price_element do
+      output(type: :float, presence: true, if: -> { secure })
+    end
+  end
+end
+
+# Now the form has validation enabled
+params = OrderForm.params_definition.new({})
+expect(params).to be_invalid
+```
+
+#### **Key Benefits**
+
+- **Non-Destructive**: Modify form definitions without changing the original class
+- **Conditional Logic**: Apply modifications based on runtime conditions
+- **Inheritance Support**: Works seamlessly with class inheritance
+- **Flexible Extension**: Add validation, change defaults, or add new elements to existing definitions
+- **Reusability**: Create base forms and customize them for specific use cases
+
+This feature provides a powerful way to customize and extend form definitions while maintaining the declarative nature of ActionForm.
+
 ### Tagging system
 
 ActionForm includes a flexible tagging system that allows you to add custom metadata to form elements and control rendering behavior. Tags serve multiple purposes:
@@ -800,6 +1171,22 @@ class UserForm < ActionForm::Rails::Base
     input type: :email
     output type: :string, presence: true
   end
+
+  element :password do
+    input type: :password
+    output type: :string
+  end
+
+  element :password_confirmation do
+    input type: :password
+    output type: :string
+  end
+
+  # Custom parameter validation for Rails integration
+  params do
+    validates :password, presence: true, length: { minimum: 6 }
+    validates :password, confirmation: true
+  end
 end
 ```
 
@@ -910,6 +1297,7 @@ class UsersController < ApplicationController
       @user = User.create!(user_params.user.to_h)
       redirect_to @user
     else
+      # Custom validation errors are automatically available
       @form = @form.with_params(user_params)
       render :new
     end
@@ -927,6 +1315,7 @@ class UsersController < ApplicationController
       @user.update!(user_params.user.to_h)
       redirect_to @user
     else
+      # Custom validation errors (like password confirmation) are displayed
       @form = @form.with_params(user_params)
       render :edit
     end

data/lib/action_form/elements_dsl.rb

@@ -26,6 +26,9 @@ module ActionForm
       def element(name, &block)
         elements[name] = Class.new(ActionForm::Element)
         elements[name].class_eval(&block)
+        define_singleton_method(:"#{name}_element") do |klass = nil, &block|
+          update_element_definition(name, klass, &block)
+        end
       end
 
       def many(name, default: nil, &block)
@@ -34,12 +37,26 @@ module ActionForm
         subform_definition.class_eval(&block) if block
         elements[name] = subform_definition
         elements[name].default = default if default
+        define_singleton_method(:"#{name}_subforms") do |klass = nil, default: nil, &block|
+          update_element_definition(name, klass, default: default, &block)
+        end
       end
 
       def subform(name, default: nil, &block)
         elements[name] = Class.new(subform_class)
         elements[name].class_eval(&block)
         elements[name].default = default if default
+        define_singleton_method(:"#{name}_subform") do |klass = nil, default: nil, &block|
+          update_element_definition(name, klass, default: default, &block)
+        end
+      end
+
+      private
+
+      def update_element_definition(name, klass = nil, default: nil, &block)
+        elements[name] = klass if klass
+        elements[name] = Class.new(elements[name], &block) if block
+        elements[name].default = default if default
       end
     end
   end

data/lib/action_form/subform.rb

@@ -11,6 +11,13 @@ module ActionForm
 
     class << self
       attr_accessor :default
+      attr_writer :elements
+
+      def inherited(subclass)
+        super
+        subclass.elements = elements.dup
+        subclass.default = default.dup
+      end
     end
 
     attr_reader :elements_instances, :tags, :name, :object

data/lib/action_form/subforms_collection.rb

@@ -12,13 +12,19 @@ module ActionForm
     attr_accessor :helpers
 
     class << self
-      attr_reader :subform_definition
-      attr_accessor :default, :host_class
+      attr_accessor :default, :host_class, :subform_definition
 
       def subform(subform_class = nil, &block)
-        @subform_definition = subform_class || Class.new(host_class.subform_class)
+        @subform_definition ||= subform_class || Class.new(host_class.subform_class)
         @subform_definition.class_eval(&block) if block
       end
+
+      def inherited(subclass)
+        super
+        subclass.subform_definition = subform_definition
+        subclass.default = default
+        subclass.host_class = host_class
+      end
     end
 
     def initialize(name)

data/lib/action_form/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_form
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Andrii Baran