superform 0.4.6 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cc4c3770a5f974a8d12b494dc0c62674f61d17e566585a145e4d02abcc02047
-  data.tar.gz: 04b1a10d9d7a2349d31117362cfcc1a12b854dfe9e8e666e5fd67534fea1cc3d
+  metadata.gz: 643e70b30f9cc8c74210e4d5312d7c0244e789065f41393d7e51925734fb5a1c
+  data.tar.gz: f96d2d84b65d93d1b330946b7b68f16b019ac87a6a4fb016a6edb2b77f66c5a8
 SHA512:
-  metadata.gz: dbb5d91b7e49b8357e33fd4f3178ea658b51fa44e46496c4e03fffc1c4801155f8953c80a223cc1d8c4dc2d3d48ea59f51b711f17d64ea2fba31e4344c8949e4
-  data.tar.gz: 70ee4cbbd71fb9e995d9d03a7c5c556ee6e62ddc1beb2d06826a071511d2052a711b0dc453c3e4f25f984092783c3c56b749b68a34ff55104609a7393ec4444e
+  metadata.gz: 13d6666058ca3235fb6a2b858a55c1b7b72a5e337d7a77e3828e01a36689c9965bafa20db1b78f62302672b93b174f33a40f9a3bf69085359afc7a7cb0016f1e
+  data.tar.gz: 7813f51fecc29744ba90fe20ffb9314d4c676d5f9512a18827a8e217003481335d1ec8e1d44d70351e545452022b4f0f2af14208d12617f170d8c33e04281b83

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    superform (0.4.6)
+    superform (0.4.8)
       phlex-rails (~> 1.0)
       zeitwerk (~> 2.6)
 

data/README.md

@@ -104,9 +104,60 @@ Then render it from Erb.
 
 Much better!
 
-### Namespacing forms
+## Namespaces & Collections
 
-By default Superform will namespace a form based on the ActiveModel model name param key.
+Superform uses a different syntax for namespacing and collections than Rails, which can be a bit confusing since the same terminology is used but the application is slightly different.
+
+Consider a form for an account that lets people edit the names and email of the owner and users of an account.
+
+```ruby
+class AccountForm < Superform::Rails::Form
+  def template
+    # Account#owner returns a single object
+    namespace :owner do |owner|
+      # Renders input with the name `account[owner][name]`
+      render owner.field(:name).input
+      # Renders input with the name `account[owner][email]`
+      render owner.field(:email).input(type: :email)
+    end
+
+    # Account#members returns a collection of objects
+    collection(:members).each do |member|
+      # Renders input with the name `account[members][0][name]`,
+      # `account[members][1][name]`, ...
+      render member.field(:name).input
+      # Renders input with the name `account[members][0][email]`,
+      # `account[members][1][email]`, ...
+      render member.field(:email).input(type: :email)
+
+      # Member#permissions returns an array of values like
+      # ["read", "write", "delete"].
+      member.field(:permissions).collection do |permission|
+        # Renders input with the name `account[members][0][permissions][]`,
+        # `account[members][1][permissions][]`, ...
+        render permission.label do
+          plain permisson.value.humanize
+          render permission.checkbox
+        end
+      end
+    end
+  end
+end
+```
+
+One big difference between Superform and Rails is the `collection` methods require the use of the `each` method to enumerate over each item in the collection.
+
+There's three different types of namespaces and collections to consider:
+
+1. **Namespace** - `namespace(:field_name)` is used to map form fields to a single object that's a child of another object. In ActiveRecord, this could be a `has_one` or `belongs_to` relationship.
+
+2. **Collection** - `collection(:field_name).each` is used to map a collection of objects to a form. In this case, the members of the account. In ActiveRecord, this could be a `has_many` relationship.
+
+3. **Field Collection** - `field(:field_name).collection.each` is used when the value of a field is enumerable, like an array of values. In ActiveRecord, this could be an attribute that's an Array type.
+
+### Change a form's root namespace
+
+By default Superform namespaces a form based on the ActiveModel model name param key.
 
 ```ruby
 class UserForm < Superform::Rails::Form
@@ -116,13 +167,13 @@ class UserForm < Superform::Rails::Form
 end
 
 render LoginForm.new(User.new)
-# This will render inputs with the name `user[email]`
+# Renders input with the name `user[email]`
 
 render LoginForm.new(Admin::User.new)
-# This will render inputs with the name `admin_user[email]`
+# Renders input with the name `admin_user[email]`
 ```
 
-If you want to customize the form namespace, you can override the `key` method in your form.
+To customize the form namespace, like an ActiveRecord model nested within a module, the `key` method can be overriden.
 
 ```ruby
 class UserForm < Superform::Rails::Form
@@ -136,11 +187,11 @@ class UserForm < Superform::Rails::Form
 end
 
 render UserForm.new(User.new)
-# This will render inputs with the name `user[email]`
+# Renders input with the name `user[email]`
 
 render UserForm.new(Admin::User.new)
 # This will also render inputs with the name `user[email]`
-````
+```
 
 ## Form field guide
 
@@ -200,6 +251,24 @@ class SignupForm < ApplicationForm
 end
 ```
 
+### Upload fields
+If you want to add file upload fields to your form you will need to initialize your form with the `enctype` attribute set to `multipart/form-data` as shown in the following example code:
+
+```ruby
+class User::ImageForm < ApplicationForm
+  def template
+    # render label
+    render field(:image).label { "Choose file" }
+    # render file input with accept attribute for png and jpeg images
+    render field(:image).input(type: "file", accept: "image/png, image/jpeg")
+  end
+end
+
+# IMPORTANT
+# When rendering the form remember to init the User::ImageForm like that
+render User::ImageForm.new(@usermodel, enctype: "multipart/form-data")
+```
+
 
 ## Extending Superforms
 

data/lib/superform/rails.rb

@@ -128,7 +128,11 @@ module Superform
         end
 
         def _method_field_value
-          @method || @model.persisted? ? "patch" : "post"
+          @method || resource_method_field_value
+        end
+
+        def resource_method_field_value
+          @model.persisted? ? "patch" : "post"
         end
 
         def submit_value
@@ -272,23 +276,52 @@ module Superform
         end
 
         def field_attributes
-          { id: dom.id, name: dom.name, value: dom.value, type: type }
+          {
+            id: dom.id,
+            name: dom.name,
+            type: type,
+            value: value
+          }
+        end
+
+        def has_client_provided_value?
+          case type.to_sym
+          when :file, :image
+            true
+          else
+            false
+          end
+        end
+
+        def value
+          dom.value unless has_client_provided_value?
         end
 
         def type
-          case field.value
-          when URI
-            "url"
-          when Integer
-            "number"
-          when Date, DateTime
-            "date"
-          when Time
-            "time"
-          else
-            "text"
-          end
+          @type ||= ActiveSupport::StringInquirer.new(attribute_type || value_type)
         end
+
+        protected
+          def value_type
+            case field.value
+            when URI
+              "url"
+            when Integer, Float
+              "number"
+            when Date, DateTime
+              "date"
+            when Time
+              "time"
+            else
+              "text"
+            end
+          end
+
+          def attribute_type
+            if type = @attributes[:type] || @attributes["type"]
+              type.to_s
+            end
+          end
       end
 
       class TextareaComponent < FieldComponent

data/lib/superform/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Superform
-  VERSION = "0.4.6"
+  VERSION = "0.4.8"
 end

data/lib/superform.rb

@@ -305,4 +305,4 @@ end
 
 def Superform(...)
   Superform::Namespace.root(...)
-end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: superform
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.4.8
 platform: ruby
 authors:
 - Brad Gessler
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-04 00:00:00.000000000 Z
+date: 2024-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex-rails