formality 0.0.1 → 0.0.2

data/lib/formality.rb

@@ -0,0 +1,284 @@
+require "set"
+
+require "active_model"
+require "active_support"
+require "active_support/hash_with_indifferent_access"
+
+module Formality
+  VERSION = "0.0.2"
+
+  extend ActiveSupport::Concern
+
+  #
+  # ActiveModel Compliance
+  # ======================
+  #
+
+  # Gives classes including Formality the standard validations
+  # framework plus the :valid? and :invalid? methods
+  include ActiveModel::Validations
+
+  module ClassMethods
+    # :model_name must be defined on the class and return a
+    # String with various convenience methods. ActiveModel::Name
+    # gives us that.
+    #
+    # By default, :model_name uses the name of the Form class.
+    def model_name
+      @__model_name ||= ActiveModel::Name.new(self)
+    end
+  end
+
+  # More ActiveModel compliance shenanigans.
+  def to_key; end
+  def to_param; end
+  def to_partial_path; "" end
+
+  # When Formality is included into a class, it defines an
+  # attr_accessor for :id. This in combination with the
+  # definition of :persisted? helps Formality forms work
+  # cleanly with :form_for.
+  included do
+    attr_accessor :id
+  end
+
+  # :form_for calls :persisted? on the object it receives
+  # to determine whether to :post or :put.
+  #
+  # We assume we're persisted (i.e. editing an object) if
+  # we have an id.
+  def persisted?
+    id.present?
+  end
+
+  #
+  # Attributes
+  # ==========
+  #
+
+  module ClassMethods
+    # Declare an attribute.
+    #
+    # Defines a reader and writer. Accepts a :default options
+    # for the default value of the attribute.
+    def attribute(name, options={})
+      attributes << name.to_s
+      define_reader(name, options[:default])
+      attr_writer name
+    end
+
+    # A Set of attribute names, stored on the form class.
+    def attributes
+      @__attributes ||= Set.new
+    end
+
+    # A convenience class method for creating and assigning
+    # a Hash to a form.
+    def assign(attrs)
+      new.assign(attrs)
+    end
+
+    private
+
+    # Defines an attribute reader with an
+    # optional default value.
+    def define_reader(name, default=nil)
+      class_eval <<-reader
+        def #{name}
+          @#{name} ||= #{default.inspect}
+        end
+      reader
+    end
+  end
+
+  # Returns an Array of attribute names (Strings).
+  def attribute_names
+    self.class.attributes.to_a
+  end
+
+  # Returns a HashWithIndifferentAccess of all the
+  # defined attributes and their values.
+  def attributes
+    hash = ActiveSupport::HashWithIndifferentAccess.new
+    attribute_names.each_with_object({}) do |name|
+      hash[name] = send(name)
+    end
+    hash
+  end
+
+  # Assigns a hash of attributes to the form. Only assigns
+  # values if the key for that value is a declared
+  # attribute. It silently ignores non-declared keys.
+  def assign(new_attributes)
+    new_attributes.each do |name, value|
+      next unless attribute?(name)
+      send("#{name}=", value)
+    end
+    self.id = new_attributes[:id]
+    self
+  end
+
+  # Returns a Boolean that answers the question: Is this `name`
+  # a declared attribute?
+  def attribute?(name)
+    attribute_names.include?(name.to_s)
+  end
+
+  #
+  # Working with models
+  # ===================
+  #
+
+  module ClassMethods
+    # Declare the model that this form object represents.
+    #
+    # Purely a convenience so that you don't have to
+    # specify the :url parameter in your :form_for calls.
+    def model(name_sym)
+      model_klass = name_sym.to_s.capitalize.constantize
+      @__model_name = ActiveModel::Name.new(model_klass)
+    end
+
+    # Build a form object from an existing model.
+    #
+    # If nested forms were declared with the
+    # :from_model_attribute option, it will also
+    # build the nested form object(s).
+    def from_model(model)
+      new.tap do |form|
+        form.id = model.id
+        form.assign(model.attributes)
+        nested_forms.each do |nested|
+          form.send("#{nested}=", model)
+        end
+      end
+    end
+  end
+
+  #
+  # Some Controller Sugar
+  # =====================
+  #
+  #     class FooController < ApplicationController
+  #       def create
+  #         form = FooForm.new.assign(params[:foo_form])
+  #
+  #         form.valid do
+  #           current_user.foos.create(@form.attributes)
+  #         end
+  #
+  #         form.invalid do
+  #           @form = form
+  #           render :new
+  #         end
+  #       end
+  #     end
+  #
+
+  # Yields to its block if the form is valid.
+  def valid;   yield if valid?   end
+
+  # Same as :valid, but in reverse: only yields to
+  # the block if the form is invalid.
+  def invalid; yield if invalid? end
+
+  #
+  # Nesting
+  # =======
+  #
+  # Allows forms to have forms nested within them that
+  # work nicely with Rails' :fields_for method.
+  #
+  # Validations are called on nested forms, so that if
+  # any nested form is invalid, so is the parent.
+  #
+
+  module ClassMethods
+    # Singular Nesting.
+    def nest_one(child, options={})
+      add_nested_form(child)
+      define_nested_form_one(child, options)
+    end
+
+    # Plural nesting.
+    #
+    # Works just like :nest_one, except it works for
+    # an Array of nested forms.
+    def nest_many(children, options={})
+      add_nested_form(children)
+      define_nested_form_many(children, options)
+    end
+
+    # Keep track of what forms we've nested.
+    def nested_forms
+      @__nested_forms ||= Set.new
+    end
+
+    private
+
+    def add_nested_form(nested)
+      attributes << "#{nested}_attributes"
+      nested_forms << nested
+    end
+
+    # Define the accessors for a singular nested form.
+    def define_nested_form_one(name, options={})
+      define_reader(name)
+      from_model_attribute = options[:from_model_attribute]
+      class_eval <<-one
+        def #{name}_attributes
+          self.#{name} ? @#{name}.attributes : nil
+        end
+
+        def #{name}_attributes=(attrs)
+          form_klass = "#{name}".classify.constantize
+          @#{name} = form_klass.new.assign(attrs)
+        end
+
+        def #{name}=(model)
+          return unless #{from_model_attribute.inspect}
+          nested_model = model.send(#{from_model_attribute.inspect})
+          self.#{name}_attributes = nested_model.attributes
+        end
+      one
+    end
+
+    # Define the accessors for a plural nested form.
+    def define_nested_form_many(name, options={})
+      define_reader(name, [])
+      from_model_attribute = options[:from_model_attribute]
+      class_eval <<-many
+        def #{name}_attributes
+          self.#{name}.map { |form| form.attributes }
+        end
+
+        def #{name}_attributes=(attrs_array)
+          form_klass = "#{name}".classify.constantize
+          @#{name} = attrs_array.map do |attrs|
+            form_klass.new.assign(attrs)
+          end
+        end
+
+        def #{name}=(model)
+          return unless #{from_model_attribute.inspect}
+          nested_models = model.send(#{from_model_attribute.inspect})
+          self.#{name}_attributes = nested_models.map { |m| m.attributes }
+        end
+      many
+    end
+  end
+
+  # A Formality form object is valid if its attributes
+  # validate and all of its children are valid.
+  def valid?(context=nil)
+    nested_forms_valid?(context) && super(context)
+  end
+
+  # If there are nested forms, call :valid? on them.
+  def nested_forms_valid?(context)
+    self.class.nested_forms.all? do |name|
+      nested = Array(send(name))
+      nested.all? { |form| form.valid?(context) }
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: formality
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-04 00:00:00.000000000 Z
+date: 2012-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
-  requirement: &70175687157900 !ruby/object:Gem::Requirement
+  requirement: &70323137369080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *70175687157900
+  version_requirements: *70323137369080
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70175687157400 !ruby/object:Gem::Requirement
+  requirement: &70323137368580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *70175687157400
+  version_requirements: *70323137368580
 - !ruby/object:Gem::Dependency
   name: actionpack
-  requirement: &70175687156940 !ruby/object:Gem::Requirement
+  requirement: &70323137368120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: 3.0.0
   type: :development
   prerelease: false
-  version_requirements: *70175687156940
+  version_requirements: *70323137368120
 - !ruby/object:Gem::Dependency
   name: tst
-  requirement: &70175687156560 !ruby/object:Gem::Requirement
+  requirement: &70323137367740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +54,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70175687156560
+  version_requirements: *70323137367740
 description: ! 'ActiveModel-compliant form objects for rails app.
 
 
@@ -74,6 +74,7 @@ files:
 - LICENSE
 - Rakefile
 - README.md
+- lib/formality.rb
 - test/attributes.rb
 - test/compliance.rb
 - test/lint.rb