on_form 2.2.2 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fc9552629f219a60bdb440b73aeaff5bab8ee8a7
-  data.tar.gz: 30fe72e471a35b622fd9203899b175a554f85785
+  metadata.gz: 05e792fbba20f1c4d82034000b2e49f2f5e01586
+  data.tar.gz: d8841bae2c6429b08945385a899d89b64e19f3a1
 SHA512:
-  metadata.gz: 31cae4ebd42811962196cc71da3e0b44d549a30d906b4be52cf88f6dfc6342d24bcbeab9971b91025a799732786a427dfbbc4566be1e84643cc1771be6f1718e
-  data.tar.gz: 1336b1e8f6d98778ab2d836dbbfba0986f3a76e7641676386443a4b1d71f667c015537d602d97964af57857b943976961a2364b0f794ed3cdbdf73c948401941
+  metadata.gz: c6557351f0b77e782903e27985c77afd88a6a9872fd506acfb26dd80464fc090337962aa5eead731175a9983fbe9c991590dfd16ae3151eff769927dccafb349
+  data.tar.gz: 65bd1b58e606758dce47bf865a7debe2bb602286cf79c7d025fd28472223553f54b0a2322a9a319f806ce027f55775827dcab27b3cf0209992e4663bd0b664de

data/CHANGES.md

@@ -1,6 +1,10 @@
 Changelog
 =========
 
+2.3.0
+-----
+* Add `take_identity_from` to improve interoperability with standard resource ('RESTful') controllers and form helpers
+
 2.2.2
 -----
 * Support non-array argument to `expose`.

data/README.md

@@ -71,7 +71,7 @@ class PreferencesController
 end
 ```
 
-Now we need to make our form object.  At this point we need to tell the form object which attributes on the model we want to expose.  (In this example we have just one model and a couple of attributes, but you wouldn't bother using this library if this was all you had.)
+Now we need to make our form object.  At this point we need to tell the form object which attributes on the model we want to `expose`.  (In this example we have just one model and a couple of attributes, but you wouldn't bother using this library if this was all you had.)
 
 ```ruby
 class PreferencesForm < OnForm::Form
@@ -130,6 +130,76 @@ end
 
 You can also define your own method over the top of the `attr_reader`.  Just remember it will be called more than once, so it must be idempotent.
 
+### View helpers & acting like ActiveModel/ActiveRecord
+
+Since OnForm doesn't require a single "main" model, forms don't automatically have any particular identity value (ie. an `id` attribute or a value to return from `to_param`).
+
+So although by default forms will work fine with all the 'raw' form field helpers and with helpers like `fields_for`, they're not automatically usable with the resource form methods like `form_for`, which assumes you have a one-to-one correspondance between your models and your views (in other words, that you have no form object layer).
+
+You have several options.  First, you can start your form tags completely manually, optionally choosing the name for the params:
+
+```erb
+<%= form_tag customer_path(edit_details_form.customer), method: :put do %>
+  <%# if the controller has set an ivar called @edit_details_form %>
+  <%= fields_for :edit_details_form do |f| %>
+    <%# produces a field called edit_details_form[name] %>
+    <%= f.text_field :name %>
+  <% end %>
+
+  <%# or you can give it a different name, to control what the form params will be named %>
+  <%= fields_for :customer, @edit_details_form do |f| %>
+    <%# produces a field called customer[name], which is what a normal resource controller expects %>
+    <%= f.text_field :name %>
+  <% end %>
+<% end %>
+```
+
+Secondly, you can combine these calls into a `form_for` call using some of its optional arguments:
+
+```erb
+<%= form_for @edit_details_form, as: :customer, url: customer_path(edit_details_form.customer), method: :put do |f| %>
+  <%# produces a field called customer[name] %>
+  <%= f.text_field :name %>
+<% end %>
+```
+
+Thirdly, you can delegate the identity question to one of the models that backs the form using `takes_identity_from`.  When you do this, the form objects start to return that model from `to_model` and the `to_key` and `to_param` values of that model as their own.  This is the recommended approach when dealing with standard resource ('RESTful') controllers.
+
+```ruby
+class EditPostForm < OnForm::Form
+  take_identity_from :post
+
+  expose %i(title body), on: :post
+
+  def initialize(post)
+    @post = post
+  end
+end
+```
+
+```erb
+<%= form_for @edit_details_form do |f| %>
+  <%# produces a field called customer[name] %>
+  <%= f.text_field :name %>
+<% end %>
+```
+
+Note that we no longer have to specify the `as` ,`url`, or `method` options, because these will be automatically derived from the `customer` model instead of from the form object itself.
+
+When you choose an identity model, it will also become the default model for `expose` calls, which helps DRY up single-model form objects.
+
+```ruby
+class EditPostForm < OnForm::Form
+  take_identity_from :post
+
+  expose %i(title body)
+
+  def initialize(post)
+    @post = post
+  end
+end
+```
+
 ### Renaming attributes
 
 By default the attribute names exposed on the form object are the same as the attributes on the backing models.  Sometimes this leads to unclear meanings, and sometimes you'll have duplicate attribute names in a multi-model form.

data/lib/on_form/form.rb

@@ -16,6 +16,10 @@ module OnForm
       @introduced_attribute_types ||= {}
     end
 
+    def self.identity_model_name
+      @identity_model_name
+    end
+
     class << self
       def inherited(child)
         exposed_attributes.each { |k, v| child.exposed_attributes[k].merge!(v) }
@@ -23,11 +27,14 @@ module OnForm
       end
     end
 
-    def self.expose(backing_attribute_names, on:, prefix: nil, suffix: nil, as: nil)
+    def self.expose(backing_attribute_names, on: nil, prefix: nil, suffix: nil, as: nil)
       backing_attribute_names = Array(backing_attribute_names)
       raise ArgumentError, "can't expose multiple attributes as the same form attribute!" if as && backing_attribute_names.size != 1
-      on = on.to_sym
+
+      raise ArgumentError, "must choose the model to expose the attributes on" unless on || identity_model_name
+      on = (on || identity_model_name).to_sym
       expose_backing_model(on)
+
       backing_attribute_names.each do |backing_name|
         exposed_name = as || "#{prefix}#{backing_name}#{suffix}"
         expose_attribute(on, exposed_name, backing_name)
@@ -61,6 +68,12 @@ module OnForm
       define_method("#{name}=")                 { |arg| introduced_attribute_values.delete(name); introduced_attribute_values_before_type_cast[name] = arg }
     end
 
+    def self.take_identity_from(backing_model_name)
+      @identity_model_name = backing_model_name.to_sym
+      expose_backing_model(@identity_model_name)
+      delegate :to_model, :to_key, :to_param, :persisted?, to: backing_model_name
+    end
+
   protected
     def introduced_attribute_values
       @introduced_attribute_values ||= {}

data/lib/on_form/version.rb

@@ -1,3 +1,3 @@
 module OnForm
-  VERSION = "2.2.2"
+  VERSION = "2.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: on_form
 version: !ruby/object:Gem::Version
-  version: 2.2.2
+  version: 2.3.0
 platform: ruby
 authors:
 - Will Bryant
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-10-03 00:00:00.000000000 Z
+date: 2016-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel