on_form 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b6aada85f9b13d5b28592d880d3cfebd1f5ef8e4
-  data.tar.gz: 9d15cc5152cb460307365fe91dadb63c8ca72370
+  metadata.gz: 3d7dd5ed97fb50b463cd137f4e37cd54a6b5039f
+  data.tar.gz: cf2be44d209f36980cb248e89498060ae50374a8
 SHA512:
-  metadata.gz: ab8c256758e5eebecf4e3f2fd2f93ab85c763fed8924e61629cd3e7765a12527f911c22341d484bacdacc0347de62804f06c8ff20ecc3a52aac85b0e6f539d4e
-  data.tar.gz: 43ee6c65289f1194bb92076c517a28fcdd10733517c8dc0d4e3dd702f625d8bbe629659d047f3b887b4e25154c64880db85a3b29e619e517a8dd751a09b02022
+  metadata.gz: c967c12d103f110b2932b03e06b4c8e708e1623abc970270c0dc4fdd2f33ccab5936ecccc440e0b8b4922cdac099258eb37b735bd068cef5727c7b62ea2108f1
+  data.tar.gz: b26ae23736314ecfa179e4c380fa4d8e91ea7a09cd18ccd6fae5c9b9c64778225698b040e7bfbe41f67027cfcb90d2176b6f6bc1e0299373c441cc7eb1857756

data/CHANGES.md

@@ -0,0 +1,10 @@
+Changelog
+=========
+
+2.00
+----
+* New expose syntax to support prefix:, suffix:, and as: options
+
+1.00
+----
+* First public release

data/README.md

@@ -38,87 +38,119 @@ This version of OnForm depends on both the `activemodel` and `activerecord` gems
 
 Let's say you have a big fat legacy model called `Customer`, and you have a preferences controller:
 
-	class PreferencesController
-	  def show
-	    @customer = Customer.find(params[:id])
-	  end
-
-	  def update
-	    @customer = Customer.find(params[:id])
-	    @customer.update!(params[:customer].permit(:name, :email, :phone_number)
-	    redirect_to preferences_path(@customer)
-	  rescue ActiveRecord::RecordInvalid
-	    render :show
-	  end
-	end
+```ruby
+class PreferencesController
+  def show
+    @customer = Customer.find(params[:id])
+  end
+
+  def update
+    @customer = Customer.find(params[:id])
+    @customer.update!(params[:customer].permit(:name, :email, :phone_number)
+    redirect_to preferences_path(@customer)
+  rescue ActiveRecord::RecordInvalid
+    render :show
+  end
+end
+```
 
 Let's wrap the customer object in a form object.  Ideally we'd call this `@customer_form`, but you may not feel you have time to go and update all your view code, so in this example we'll keep calling it `@customer`.
 
-	class PreferencesController
-	  def show
-	    @customer = PreferencesForm.new(Customer.find(params[:id]))
-	  end
-
-	  def update
-	    @customer = PreferencesForm.new(Customer.find(params[:id]))
-	    @customer.update!(params[:customer])
-	  rescue ActiveRecord::RecordInvalid
-	    render :show
-	  end
-	end
+```ruby
+class PreferencesController
+  def show
+    @customer = PreferencesForm.new(Customer.find(params[:id]))
+  end
+
+  def update
+    @customer = PreferencesForm.new(Customer.find(params[:id]))
+    @customer.update!(params[:customer])
+  rescue ActiveRecord::RecordInvalid
+    render :show
+  end
+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.)
 
-	class PreferencesForm < OnForm::Form
-	  expose :customer => %i(name email phone_number)
+```ruby
+class PreferencesForm < OnForm::Form
+  expose %i(name email phone_number), on: :customer
 
-	  def initialize(customer)
-	    @customer = customer
-	  end
-	end
+  def initialize(customer)
+    @customer = customer
+  end
+end
+```
 
 The form object responds to the usual persistance methods like `email`, `email=`, `save`, `save!`, `update`, and `update!`.  
 
-It will automatically write those exposed attributes back onto the models, and *it exposes any validation errors from those fields on the form object itself* - you don't have to copy them back manually or move your field validation code over to get started.  It'll also expose any errors on base on the models whose attributes you exposed.
+It will automatically write those exposed attributes back onto the models, and *it exposes any validation errors from those fields on the form object itself* - you don't have to copy them back manually or move your field validation code over to get started.  It'll also expose any errors on base on the models whose attributes you exposed.  See the Validations section below for more.
 
 ### A multi-model form
 
-You aren't limited to having one primary model - if your form is made up of multiple models pass more than one key to `expose`, or call it multiple times if you prefer.  They'll automatically be saved in the same order you declared them.
+You aren't limited to having one primary model - if your form is backed by multiple models just call `expose` for each one.  They'll automatically be saved in the same order you declared them.
 
 In this example, the new models we're exposing are associated with the first one, so we don't need to pass them in to the constructor.
 
-	class HouseListingForm < OnForm::Form
-	  expose :house => %i(street_number street_name city),
-	         :vendor => %i(name phone_number)
-
-	  def initialize(house)
-	    @house = house
-	    @vendor = house.vendor
-	  end
-	end
+```ruby
+class HouseListingForm < OnForm::Form
+  expose %i(street_number street_name city), on: :house
+  expose %i(name phone_number), on: :vendor
+
+  def initialize(house)
+    @house = house
+    @vendor = house.vendor
+  end
+end
+```
 
 Transactions will automatically be started so that _all_ database updates will be rolled back if _any_ record fails to save (for example, due to a validation error).
 
-Note that the keys are the name of the methods on the form object which return the records, not the class names.  In this example, vendor might actually be an instance of our `Customer` model from the earlier examples.
+Note that the `on:` kwarg gives the name of the method on the form object which returns the record - nothing to do with class names.  In this example, vendor might actually be an instance of our `Customer` model from the earlier examples.
 
 ### Model accessor methods
 
-In the previous example, the constructor set `@house` and `@vendor` because these variables correspond to the names passed to `expose`.  `expose` will automatically add an `attr_reader` for each key it's given, meaning you only need to set the instance variables.
+In the previous example, the constructor set `@house` and `@vendor` because these variables correspond to the name passed to `expose` in the `on` option.  `expose` will automatically add an `attr_reader` for this name, meaning you only need to set the instance variables.
 
 But if you prefer, you can define a method with the same name yourself, for example using delegation.  `expose` won't run `attr_reader` if you've already defined the method, and there's no requirement to set an instance variable.
 
-	class HouseListingForm < OnForm::Form
-	  delegate :vendor, :to => :house
+```ruby
+class HouseListingForm < OnForm::Form
+  delegate :vendor, :to => :house
+
+  expose %i(street_number street_name city), on: :house
+  expose %i(name phone_number), on: :vendor
+
+  def initialize(house)
+    @house = house
+  end
+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.
+
+### Renaming attributes
 
-	  expose :house => %i(street_number street_name city),
-	         :vendor => %i(name phone_number)
+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.
 
-	  def initialize(house)
-	    @house = house
-	  end
-	end
+To address this you can use the `prefix` and/or `suffix` options to `expose`.
 
-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 should be idempotent.
+```ruby
+class AccountHolderForm < OnForm::Form
+  expose %i(name date_of_birth), on: :customer, prefix: "account_holder_"
+  expose %i(email), on: :customer, suffix: "_for_billing"
+  expose %i(phone_number), on: :customer, as: "mobile_number"
+
+  def initialize(customer)
+    @customer = customer
+  end
+end
+```
+
+This is especially useful if you like to use helpers like `error_messages_on` which will "humanize" the attribute names and use them in the human-readable page.
+
+Try to use this only when it makes the attribute names more meaningful.  In particular, automatically renaming all of your attributes with a prefix matching the backing model is considered a bad habit because it leads to unnecessary coupling between the views and the current backing data model schema.
 
 ### Validations
 
@@ -126,15 +158,17 @@ Validations on the underlying models not only get used, but their validation err
 
 But you can also declare validations on the form object itself, which is useful when you have business rules applicable to this form that aren't intrinsic to the domain model.
 
-	class AddEmergencyContactForm < OnForm::Form
-	  expose :customer => %i(next_of_kin_name next_of_kin_phone_number)
+```ruby
+class AddEmergencyContactForm < OnForm::Form
+  expose %i(next_of_kin_name next_of_kin_phone_number), on: :customer
 
-	  validates_presence_of :next_of_kin_name, :next_of_kin_phone_number
+  validates_presence_of :next_of_kin_name, :next_of_kin_phone_number
 
-	  def initialize(customer)
-	    @customer = customer
-	  end
-	end
+  def initialize(customer)
+    @customer = customer
+  end
+end
+```
 
 Note that when you call `save!`, `update!`, or `update_attributes!` on the form object, validation errors from records will still raise `ActiveRecord::RecordInvalid`, but validation errors from validations defined on the form itself will raise `ActiveModel::ValidationError`.  You will usually want to rescue both.
 
@@ -142,16 +176,18 @@ Note that when you call `save!`, `update!`, or `update_attributes!` on the form
 
 You can also use the `before_validation`, `before_save`, `after_save`, and `around_save` validations.  Like ActiveRecord, these will run inside the database transaction when you're calling one of the save or update methods, which is especially useful if you need to take locks on parent records.
 
-	class NewBranchForm < OnForm::Form
-	  expose :branch => %w(bank_id branch_number branch_name)
+```ruby
+class NewBranchForm < OnForm::Form
+  expose %w(bank_id branch_number branch_name), on: :branch
 
-	  before_save :lock_bank
+  before_save :lock_bank
 
-	protected
-	  def lock_bank
-	    branch.bank.lock!
-      end
-	end
+protected
+  def lock_bank
+    branch.bank.lock!
+  end
+end
+```
 
 Note that model save calls are nested inside the form save calls, which means that although form validation takes place before form save starts, model validation takes place after form saving begins.
 
@@ -173,39 +209,43 @@ Note that model save calls are nested inside the form save calls, which means th
 
 You can descend form classes from other form classes and expose additional models or additional attributes on existing models.
 
-	class AdminHouseListingForm < HouseListingForm
-	  expose :house => %i(listing_approved)
-	end
+```ruby
+class AdminHouseListingForm < HouseListingForm
+  expose %i(listing_approved), on: :house
+end
+```
 
 This works well for some use cases, but can quickly become cumbersome if you have a lot of partial form reuse, and it may not be obvious to other developers that the parent form is also used to derive the other forms.  Consider breaking your form parts into reuseable modules, and defining each form separately.
 
 You can use standard Ruby hooks for this:
 
-	module AccountFormComponent
-	  def self.included(form)
-	    form.expose :customer => %i(email phone_number)
-	  end
-	end
+```ruby
+module AccountFormComponent
+  def self.included(form)
+    form.expose %i(email phone_number), on: :customer
+  end
+end
 
-	class NewAccountForm < OnForm::Form
-	  include AccountFormComponent
+class NewAccountForm < OnForm::Form
+  include AccountFormComponent
 
-	  expose :customer => %i(name)
+  expose %i(name), on: :customer
 
-	  def initialize(customer)
-	    @customer = customer
-	  end
-	end
+  def initialize(customer)
+    @customer = customer
+  end
+end
 
-	class EditAccountForm < OnForm::Form
-	  include AccountFormComponent
+class EditAccountForm < OnForm::Form
+  include AccountFormComponent
 
-	  delegate :name, to: :customer
+  delegate :name, to: :customer
 
-	  def initialize(customer)
-	    @customer = customer
-	  end
-	end
+  def initialize(customer)
+    @customer = customer
+  end
+end
+```
 
 In this example the initialize method could actually be moved to the module as well, but that makes it harder to compose forms from multiple modules.
 
@@ -215,11 +255,11 @@ If you prefer, you can use the Rails `included` block syntax in the module inste
 
 After checking out the repo, pick the rails version you'd like to run tests against, and run:
 
-	RAILS_VERSION=5.0.0.1 bundle update
+    RAILS_VERSION=5.0.0.1 bundle update
 
 You should then be able to run the test suite:
 
-	bundle exec rake
+    bundle exec rake
 
 ## Contributing
 
@@ -227,7 +267,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/powers
 
 ## Roadmap
 
-* For version 2, the author is looking into support for declaring attributes on the form.  (You can use plain old Ruby object `attr_accessor` for untyped attributes in the meantime.)
+* Currently, the author is looking into support for declaring attributes on the form.  (You can use plain old Ruby object `attr_accessor` for untyped attributes in the meantime.)
 * After that we'll need to tackle the other use cases for ActiveRecord nested attributes, such as one-to-many associations and auto-building/deleting associated records.
 
 ## License

data/lib/on_form/attributes.rb

@@ -20,7 +20,7 @@ module OnForm
     end
 
     def attribute_names
-      self.class.exposed_attributes.values.reduce(:+).collect(&:to_s)
+      self.class.exposed_attributes.values.flat_map(&:keys).collect(&:to_s)
     end
 
     def attributes
@@ -46,17 +46,17 @@ module OnForm
     end
 
   private
-    def backing_model(backing_model_name)
+    def backing_model_instance(backing_model_name)
       send(backing_model_name)
     end
 
-    def backing_models
-      self.class.exposed_attributes.keys.collect { |backing_model_name| backing_model(backing_model_name) }
+    def backing_model_instances
+      self.class.exposed_attributes.keys.collect { |backing_model_name| backing_model_instance(backing_model_name) }
     end
 
-    def backing_object_for_attribute(attribute_name)
-      self.class.exposed_attributes.each do |backing_model_name, attribute_names|
-        return backing_model(backing_model_name) if attribute_names.include?(attribute_name.to_sym)
+    def backing_model_for_attribute(exposed_name)
+      self.class.exposed_attributes.each do |backing_model_name, attribute_mappings|
+        return backing_model_instance(backing_model_name) if attribute_mappings[exposed_name.to_sym]
       end
       nil
     end

data/lib/on_form/errors.rb

@@ -10,13 +10,19 @@ module OnForm
     end
 
     def collect_errors
-      self.class.exposed_attributes.each do |backing_model_name, exposed_attributes_on_backing_model|
-        backing_model(backing_model_name).errors.each do |backing_attribute, attribute_errors|
-          if backing_attribute == :base || exposed_attributes_on_backing_model.include?(backing_attribute)
-            Array(attribute_errors).each { |error| errors[backing_attribute] << error }
-          end
+      self.class.exposed_attributes.each do |backing_model_name, attribute_mappings|
+        backing_model = backing_model_instance(backing_model_name)
+
+        collect_errors_on(backing_model, :base, :base)
+
+        attribute_mappings.each do |exposed_name, backing_name|
+          collect_errors_on(backing_model, exposed_name, backing_name)
         end
       end
     end
+
+    def collect_errors_on(backing_model, exposed_name, backing_name)
+      Array(backing_model.errors[backing_name]).each { |error| errors[exposed_name] << error }
+    end
   end
 end

data/lib/on_form/form.rb

@@ -9,22 +9,22 @@ module OnForm
     include Saving
 
     def self.exposed_attributes
-      @exposed_attributes ||= Hash.new { |h, k| h[k] = [] }
+      @exposed_attributes ||= Hash.new { |h, k| h[k] = {} }
     end
 
     class << self
       def inherited(child)
-        exposed_attributes.each { |k, v| child.exposed_attributes[k].concat(v) }
+        exposed_attributes.each { |k, v| child.exposed_attributes[k].merge!(v) }
       end
     end
 
-    def self.expose(backing_models_and_attribute_names)
-      backing_models_and_attribute_names.each do |backing_model_name, attribute_names|
-        backing_model_name = backing_model_name.to_sym
-        expose_backing_model(backing_model_name)
-        attribute_names.each do |attribute_name|
-          expose_attribute(backing_model_name, attribute_name)
-        end
+    def self.expose(backing_attribute_names, on:, prefix: nil, suffix: nil, as: nil)
+      raise ArgumentError, "can't expose multiple attributes as the same form attribute!" if as && backing_attribute_names.size != 1
+      on = on.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)
       end
     end
 
@@ -34,15 +34,13 @@ module OnForm
       end
     end
 
-    def self.expose_attribute(backing_model_name, attribute_name)
-      exposed_attributes[backing_model_name] << attribute_name.to_sym
+    def self.expose_attribute(backing_model_name, exposed_name, backing_name)
+      exposed_attributes[backing_model_name][exposed_name.to_sym] = backing_name.to_sym
 
-      [attribute_name, "#{attribute_name}_before_type_cast", "#{attribute_name}?"].each do |attribute_method|
-        define_method(attribute_method) { backing_model(backing_model_name).send(attribute_method) }
-      end
-      ["#{attribute_name}="].each do |attribute_method|
-        define_method(attribute_method) { |arg| backing_model(backing_model_name).send(attribute_method, arg) }
-      end
+      define_method(exposed_name)                       { backing_model_instance(backing_model_name).send(backing_name) }
+      define_method("#{exposed_name}_before_type_cast") { backing_model_instance(backing_model_name).send("#{backing_name}_before_type_cast") }
+      define_method("#{exposed_name}?")                 { backing_model_instance(backing_model_name).send("#{backing_name}?") }
+      define_method("#{exposed_name}=")                 { |arg| backing_model_instance(backing_model_name).send("#{backing_name}=", arg) }
     end
   end
 end

data/lib/on_form/multiparameter_attributes.rb

@@ -22,7 +22,7 @@ module OnForm
           if defined?(ActiveRecord::AttributeAssignment::MultiparameterAttribute)
             # ActiveRecord 4.2 and below: you must use MultiparameterAttribute to construct the attribute value.
             # we therefore have to look up which model the attribute actually lives on.
-            send("#{name}=", ActiveRecord::AttributeAssignment::MultiparameterAttribute.new(backing_object_for_attribute(name), name, values_with_empty_parameters).read_value)
+            send("#{name}=", ActiveRecord::AttributeAssignment::MultiparameterAttribute.new(backing_model_for_attribute(name), name, values_with_empty_parameters).read_value)
           else
             # ActiveRecord 5.0+: you can assign the indexed hash to the column and it will construct the value for you.
             if values_with_empty_parameters.each_value.all?(&:nil?)

data/lib/on_form/saving.rb

@@ -5,7 +5,7 @@ module OnForm
     end
 
     def transaction(&block)
-      with_transactions(backing_models, &block)
+      with_transactions(backing_model_instances, &block)
     end
 
     def invalid?
@@ -21,7 +21,7 @@ module OnForm
         end
         run_callbacks :save do
           begin
-            backing_models.each { |backing_model| backing_model.save! }
+            backing_model_instances.each { |backing_model| backing_model.save! }
           rescue ActiveRecord::RecordInvalid, ActiveModel::ValidationError
             collect_errors
             raise
@@ -72,7 +72,7 @@ module OnForm
     end
 
     def run_backing_model_validations
-      backing_models.collect { |backing_model| backing_model.valid? }
+      backing_model_instances.collect { |backing_model| backing_model.valid? }
       collect_errors
     end
   end

data/lib/on_form/version.rb

@@ -1,3 +1,3 @@
 module OnForm
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: on_form
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Will Bryant
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-17 00:00:00.000000000 Z
+date: 2016-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -89,6 +89,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- CHANGES.md
 - Gemfile
 - LICENSE.txt
 - README.md