superform 0.4.6 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cc4c3770a5f974a8d12b494dc0c62674f61d17e566585a145e4d02abcc02047
-  data.tar.gz: 04b1a10d9d7a2349d31117362cfcc1a12b854dfe9e8e666e5fd67534fea1cc3d
+  metadata.gz: 625660f353f992d6002a6dc8c21912cd9f21bd28e63a0b64f9b135d10ce6bb7d
+  data.tar.gz: b6c3bf4c93146a80676c8c6f4bc05d5059b6f45d14fa2ff6a7bcb2005671fc6e
 SHA512:
-  metadata.gz: dbb5d91b7e49b8357e33fd4f3178ea658b51fa44e46496c4e03fffc1c4801155f8953c80a223cc1d8c4dc2d3d48ea59f51b711f17d64ea2fba31e4344c8949e4
-  data.tar.gz: 70ee4cbbd71fb9e995d9d03a7c5c556ee6e62ddc1beb2d06826a071511d2052a711b0dc453c3e4f25f984092783c3c56b749b68a34ff55104609a7393ec4444e
+  metadata.gz: 3dd0f0dd8f6ceed91419c6dad2234c72adcb12fcd4262d6b1309064ec3c67b5427af434e375b73ec02fd117b0d6f16df27f1c7b80e9091189d080a6e53582c1d
+  data.tar.gz: ab30922107e8d7258e6610240703a351edc02d264c8a56087e2ff35205c0e080aab997b06c621d0f22b3c8de0f758a3f3e098cff9b2982f3fee94ee6a4f245f5

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    superform (0.4.6)
+    superform (0.4.7)
       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,7 +276,25 @@ 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 client_provided_value?
+          case type
+          when "file", "image"
+            false
+          else
+            true
+          end
+        end
+
+        def value
+          dom.value unless client_provided_value?
         end
 
         def type

data/lib/superform/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Superform
-  VERSION = "0.4.6"
+  VERSION = "0.4.7"
 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.7
 platform: ruby
 authors:
 - Brad Gessler
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-04 00:00:00.000000000 Z
+date: 2024-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex-rails
@@ -84,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
 summary: Build forms in Rails