hungryform 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4c86c2c1ea0c43d499e7e0ace99b385e64f9f907
-  data.tar.gz: f12a4223b04ba00cf056c3ec9f1ff135b4abb6c5
+  metadata.gz: 301fe1318d8aec9203be048d49946604a9c90826
+  data.tar.gz: 58eed16ad2bf95ffd8453d6225c32e79234beaf1
 SHA512:
-  metadata.gz: 528cf1d7b5809415a13b518526fcef94ab2a48e379e8870b398a582694c230c3222c19ccf603d4f0c51419192a257a123086e552e426a0a92fe862b2e85f8a07
-  data.tar.gz: 37600c6257d3b50c5b456f8a534c7abde7c14a6024b19aa12d564286684f21f0c847103cf7978865ee38b96e6841f9f0f07a95ed9a3b8c4290d7b06ea85fba0e
+  metadata.gz: d4da2b5138ddbbad90956b0bd0fbbbfa885f7ae3d25518951629d8d98c46518d1e81f759f523222e52075c89e69312f6d9417ec5cdd2ff55c2f105c5ef624fb0
+  data.tar.gz: 7a443c26c7fe85572cb9a15f70df473f59ccdca5f02aab2ed676ea49f98eebe01cbe428603ea0560ac39edeb73a4e2a7ac24ff82772ee69de471a31c5a7379ca

data/.rspec

@@ -1 +1,2 @@
+--format documentation
 --color

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    hungryform (0.0.2)
+    hungryform (0.0.4)
       activesupport
 
 GEM
@@ -13,10 +13,16 @@ GEM
       minitest (~> 5.1)
       thread_safe (~> 0.1)
       tzinfo (~> 1.1)
+    coderay (1.1.0)
     diff-lcs (1.2.5)
     i18n (0.6.11)
     json (1.8.1)
+    method_source (0.8.2)
     minitest (5.4.2)
+    pry (0.9.12.6)
+      coderay (~> 1.0)
+      method_source (~> 0.8)
+      slop (~> 3.4)
     rake (10.3.2)
     rspec (3.1.0)
       rspec-core (~> 3.1.0)
@@ -30,6 +36,7 @@ GEM
     rspec-mocks (3.1.3)
       rspec-support (~> 3.1.0)
     rspec-support (3.1.2)
+    slop (3.6.0)
     thread_safe (0.3.4)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
@@ -40,5 +47,6 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 1.6)
   hungryform!
+  pry
   rake
   rspec (~> 3.0)

data/README.md

@@ -1,27 +1,28 @@
 # HungryForm
 
+[![Build Status](https://travis-ci.org/andrba/hungryform.svg?branch=master)](https://travis-ci.org/andrba/hungryform)
+
 HungryForm is a gem for managing multiple page forms. The main purpose of this gem is to give developers an easy DSL to build complex forms.
 
 ## Usage
 
 ```ruby
-require 'hungryform'
-
-form = HungryForm.new do
+form = HungryForm::Form.new do
   page :first do
-    text_field :first_name
-    text_field :last_name
+    text_field :first_name, required: true
+    text_field :last_name, required: true
   end
   page :second, do 
     text_field :address
+    select_field :gender, options: { "M" => "Male", "F" => "Female" }, required: true
   end
   page :third do 
     text_field :occupation
     
     # Show this group only when the occupation field is not empty
-    group :employment_history, visible: false, dependency: '{"SET": "third_occupation"}' do
+    group :employment_history, dependency: '{"SET": "third_occupation"}' do
       html :before, value: "Employment history over the last 5 years"
-      text_field :history, value: "Default value"
+      text_area :history, value: "Default value"
     end
   end 
 end
@@ -38,7 +39,7 @@ params = {
   "third_employment_history_history" => "John's employment hisotory"
 }
 
-form = HungryForm.new :params => params do
+form = HungryForm::Form.new :params => params do
 ...
 end
 
@@ -85,7 +86,7 @@ Each element of HungryForm, including pages and groups, can have a dependency pa
 If the dependency is resolved positively it makes the element visible. Otherwise the element will be hidden and not required. It is allowed to use element names or params keys as parameters inside expressions.
 
 ```ruby
-HungryForm.new do
+HungryForm::Form.new do
   page :about do
     text_field :age
     text_field :favourite_alcohol, required: true, dependency: '{"GT": ["about_age", "18"]}'
@@ -106,11 +107,11 @@ text_field :name, required: true
 text_field :email, validation: ->(el) { "is unexpected email" unless el.value == "me@yahoo.com"  }
 ```
 
-You can extend the list of validation rules by opening the HungryForm::Validator singleton class and creating your own validation methods:
+You can extend the list of validation rules by creating your own validation methods:
 
 ```ruby
-class HungryForm
-  class Validator
+module HungryForm
+  module Validator
     class << self
       def my_validation_method(element, rule)
         "is not #{rule}" unless element.value == rule
@@ -123,6 +124,41 @@ end
 text_field :vegetable, value: "tomato", my_validation_method: "potato" # => is not potato
 ```
 
+## Custom form fields
+You can create your own field type by adding a new class into the HungryForm::Elements module. There are three base classes that you can choose to inherit from:
+
+- Base::Element - use this class when you don't need the field to have a value and validation. As an example it can be used for text/html output
+- Base::ActiveElement - use this class when you need the field to have a value and validation
+- Base::OptionsElement - this class inherits the Base::ActiveElement. Use it when you need to create an element with an options hash, like a dropdown
+
+```ruby
+module HungryForm
+  module Elements
+    class MyField < Base::ActiveElement
+      attr_accessor :my_param
+
+      hashable :my_param
+      
+      def initialize(name, parent, resolver, options = {}, &block)
+        self.my_param = options[:my_param] || true
+        
+        super
+      end
+      
+      def valid?
+        self.value == 'valid_value'
+      end
+    end
+  end
+end
+
+form = HungryForm::Form.new do
+  page :main do
+    my_field :my_field_name, my_param: "Param Value"
+  end
+end
+```
+
 ## Contributing
 
 1. Fork it ( https://github.com/andrba/hungryform/fork )

data/Rakefile

@@ -1,2 +1,4 @@
 require "bundler/gem_tasks"
-
+require 'rspec/core/rake_task'
+task :default => :spec
+RSpec::Core::RakeTask.new

data/hungryform.gemspec

@@ -17,8 +17,11 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
+  spec.required_ruby_version = '>= 1.9.2'
+  
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency 'pry'
   spec.add_dependency "activesupport"
 end

data/lib/hungryform/elements/base/active_element.rb

@@ -0,0 +1,53 @@
+module HungryForm
+  module Elements::Base
+    # The ActiveElement class is used as a base class for all
+    # form fields that can contain values and be validated
+    class ActiveElement < Element
+      attr_accessor :error, :value, :required
+      alias_method :required?, :required
+
+      hashable :required, :value, :error
+
+      def initialize(name, parent, resolver, attributes = {}, &block)
+        super
+
+        clear_error
+
+        # Leave only the attributes that are being methods of the HungryForm::Validator class
+        @validation_rules = @attributes.select { |key, _| HungryForm::Validator.respond_to?(key) }
+
+        if parent.visible?
+          self.required = @attributes[:required] || false
+        else
+          self.required = false
+        end
+
+        set_value
+      end
+
+      def valid?
+        clear_error
+        is_valid = true
+        return true unless visible?
+
+        @validation_rules.each do |key, rule|
+          error = HungryForm::Validator.send(key, self, rule) || ''
+          unless error.empty?
+            is_valid = false
+            break
+          end
+        end
+
+        is_valid
+      end
+
+      def set_value
+        self.value = resolver.params.key?(name) ? resolver.params[name] : @attributes[:value]
+      end
+
+      def clear_error
+        self.error = ''
+      end
+    end
+  end
+end

data/lib/hungryform/elements/base/element.rb

@@ -0,0 +1,57 @@
+module HungryForm
+  module Elements::Base
+    # The Element class is used in every form element. It contains the attrs
+    # and methods used by all form elements, such as name, visible, dependency etc
+    class Element
+      include HungryForm::Elements::Base::Hashable
+      attr_accessor :name, :placeholders, :resolver, :visible, :label, :dependency
+      alias_method :visible?, :visible
+
+      hashable :visible, :dependency, :name, :label
+
+      def initialize(name, parent, resolver, attributes = {})
+        @attributes = attributes.dup
+
+        @placeholders ||= {}
+        @resolver = resolver
+
+        self.dependency ||= @attributes[:dependency]
+
+        # The element is visible if no visible parameter passed or
+        # visible param equals true and the dependency is resolved positively
+        self.visible = @attributes.key?(:visible) ? @attributes[:visible] : true
+
+        if dependency
+          json_dependency = ::JSON.parse(dependency)
+          self.visible &&= resolver.resolve_dependency(json_dependency)
+        end
+
+        # An element's name is prefixed with all parents names up to the page
+        self.name = resolver.get_value(name, self)
+        self.name = "#{parent.name}_#{name}" unless parent.nil?
+
+        # Label can be created from name if there is no label given
+        if @attributes[:label]
+          self.label = resolver.get_value(@attributes[:label], self)
+        else
+          self.label = resolver.get_value(name, self).humanize
+        end
+      end
+
+      def method_missing(method_name, *args, &block)
+        # Check if an option exists
+        if method_name.to_s[-1] == '?'
+          return @attributes.key?(method_name.to_s[0..-2].to_sym)
+        end
+
+        # Return an attribute
+        return @attributes[method_name] if @attributes.key?(method_name)
+        super
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @attributes.key?(method_name) || super
+      end
+    end
+  end
+end

data/lib/hungryform/elements/base/group.rb

@@ -0,0 +1,89 @@
+module HungryForm
+  module Elements::Base
+    # A base group object is used to handle nested elements.
+    # Nested element can be a regular BaseElement or BaseActiveElement,
+    # as well as a BaseGroup element.
+    # 
+    # The following sample has three BaseGroup elements (page, group and nested group)
+    # that define a structure of a single form page
+    #
+    # page :about do
+    #   group :about_yourself do
+    #     html :about, value: "Tell us about yourself"
+    #     group :address do
+    #       text_field :street
+    #       text_field :city
+    #     end
+    #     group :contact do
+    #       text_field :phone
+    #     end
+    #   end
+    # end
+    class Group < Element
+      attr_accessor :elements, :errors
+
+      hashable :elements
+
+      def initialize(name, parent, resolver, attributes = {}, &block)
+        unless block_given?
+          fail HungryFormException, 'No group structure block given'
+        end
+
+        super
+
+        @elements = []
+        @errors = {}
+
+        instance_eval(&block)
+      end
+
+      # Validates an entire group. If a group consists of nested groups
+      # they will be validated recursively
+      def valid?
+        errors.clear
+        is_valid = true
+
+        elements.each do |el|
+          next if el.valid?
+
+          is_valid = false
+          case el
+          when BaseActiveElement
+            errors[el.name] = el.error
+          when BaseGroupObject
+            errors.merge!(el.errors)
+          end
+        end
+
+        is_valid
+      end
+
+      def invalid?
+        !valid?
+      end
+
+      def to_hash
+        super.merge(elements: elements.map(&:to_hash))
+      end
+
+      def method_missing(method_name, *args, &block)
+        # Find a matching class
+        klass = HungryForm::Elements.constants.find { |c| Class === HungryForm::Elements.const_get(c) && c.to_s.underscore.to_sym == method_name }
+        return super if klass.nil?
+
+        # Create a new element based on a symbol provided and push it into the group elements array
+        element = HungryForm::Elements.const_get(klass).send(:new, args[0], self, @resolver, *(args[1..-1]), &block)
+        elements << element
+
+        # Resolver keeps a hash of all elements of the form
+        @resolver.elements[element.name] = element
+
+        element
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        HungryForm::Elements.constants.any? { |c| Class === HungryForm::Elements.const_get(c) && c.to_s.underscore.to_sym == method_name } || super
+      end
+    end
+  end
+end

data/lib/hungryform/elements/base/hashable.rb

@@ -0,0 +1,39 @@
+module HungryForm
+  module Elements::Base
+    # This module adds hashing capabilities to form elements.
+    # Do not include this module in your classes. It is already
+    # included in the base_element class.
+    #
+    # Sample usage:
+    #
+    # class MyField
+    #   attr_accessor :param1, :param2
+    #   hashable :param1, :param2
+    #   ...
+    # end
+    #
+    # Any instance of MyField class will have the "to_hash" method
+    # that will contain only the accessor/reader params defined in
+    # the hashable macro.
+    module Hashable
+      def self.included(base)
+        base.extend ClassMethods
+        base.class_attribute :hashable_attributes
+        base.hashable_attributes = []
+      end
+
+      def to_hash
+        hash = self.class.hashable_attributes.each_with_object({}) do |param, h|
+          h[param] = send(param) unless send(param).nil?
+        end
+        hash.merge(_type: self.class.name.demodulize)
+      end
+
+      module ClassMethods
+        def hashable(*params)
+          self.hashable_attributes = hashable_attributes.dup.concat params
+        end
+      end
+    end
+  end
+end

data/lib/hungryform/elements/base/options_element.rb

@@ -0,0 +1,35 @@
+module HungryForm
+  module Elements::Base
+    # The BaseOptionsElement class can be used as a base class for
+    # fields with options, such as select or radio
+    class OptionsElement < ActiveElement
+      attr_accessor :options
+
+      hashable :options
+
+      def initialize(name, parent, resolver, attributes = {}, &block)
+        if attributes.key?(:options)
+          self.options = attributes[:options].dup
+        else
+          fail HungryFormException, "No options provided for #{name}"
+        end
+
+        unless options.is_a?(Hash)
+          self.options = resolver.get_value(options, self)
+        end
+
+        super
+      end
+
+      # Sets a value of the element
+      # Checks the value from the resolver params against the available options
+      def set_value
+        if resolver.params.key?(name) && options.key?(resolver.params[name])
+          self.value = resolver.params[name]
+        else
+          self.value = @attributes[:value]
+        end
+      end
+    end
+  end
+end

data/lib/hungryform/elements/group.rb

@@ -1,4 +1,6 @@
-class HungryForm
-  class Group < BaseGroup
+module HungryForm
+  module Elements
+    class Group < Base::Group
+    end
   end
-end
+end

data/lib/hungryform/elements/html.rb

@@ -1,4 +1,13 @@
-class HungryForm
-  class Html < BaseElement
+module HungryForm
+  module Elements
+    class Html < Base::Element
+      attr_accessor :value
+      hashable :value
+
+      def initialize(name, parent, resolver, attributes = {}, &block)
+        super
+        self.value = @attributes[:value] || ''
+      end
+    end
   end
-end
+end

data/lib/hungryform/elements/page.rb

@@ -1,27 +1,31 @@
-class HungryForm
-  # Page is a main element of a form.
-  # Each page can include a page structure, defined in the block
-  # 
-  # A sample page could look like this:
-  #   page :about do
-  #     html :before, value: "Please fill out the following fields"
-  #     text_field :first_name
-  #     text_field :last_name
-  #   end
-  # 
-  # The only required argument of a page is its name.
-  # You can specify a title and a label in the options like this:
-  # 
-  # page :about, title: "About me", label: "About"
-  # 
-  # If there is no title or label specified, they will be created
-  # from the :name argument
-  class Page < BaseGroup
-    attr_accessor :title
+module HungryForm
+  module Elements
+    # Page is a main element of a form.
+    # Each page can include a page structure, defined in the block
+    #
+    # A sample page could look like this:
+    #   page :about do
+    #     html :before, value: "Please fill out the following fields"
+    #     text_field :first_name
+    #     text_field :last_name
+    #   end
+    #
+    # The only required argument of a page is its name.
+    # You can specify a title and a label in the attributes like this:
+    #
+    # page :about, title: "About me", label: "About"
+    #
+    # If there is no title or label specified, they will be created
+    # from the :name argument
+    class Page < Base::Group
+      attr_accessor :title
 
-    def initialize(name, parent, resolver, options = {}, &block)
-      super
-      self.title = self.title || self.label
+      hashable :title
+
+      def initialize(name, parent, resolver, attributes = {}, &block)
+        super
+        self.title ||= label
+      end
     end
   end
-end
+end

data/lib/hungryform/elements/radio_group.rb

@@ -0,0 +1,17 @@
+module HungryForm
+  module Elements
+    class RadioGroup < Base::OptionsElement
+      # Sets a value of the element
+      # Checks the value from the resolver params against the available options
+      def set_value
+        if resolver.params.key?(name)
+          if options.keys.include?(resolver.params[name])
+            self.value = resolver.params[name]
+          end
+        else
+          self.value = @attributes[:value]
+        end
+      end
+    end
+  end
+end

data/lib/hungryform/elements/select_field.rb

@@ -0,0 +1,33 @@
+module HungryForm
+  module Elements
+    class SelectField < Base::OptionsElement
+      attr_accessor :multiple
+      alias_method :multiple?, :multiple
+
+      hashable :multiple
+
+      def initialize(name, parent, resolver, attributes = {}, &block)
+        self.multiple = attributes[:multiple] || false
+        super
+      end
+
+      # Sets a value of the element
+      # Checks the value from the resolver params against the available options
+      def set_value
+        if resolver.params.key?(name)
+
+          # Check if all values present in the options
+          if multiple?
+            acceptable_values = (resolver.params[name] - options.keys).empty?
+          else
+            acceptable_values = options.keys.include?(resolver.params[name])
+          end
+
+          self.value = resolver.params[name] if acceptable_values
+        else
+          self.value = @attributes[:value]
+        end
+      end
+    end
+  end
+end

data/lib/hungryform/elements/text_area_field.rb

@@ -0,0 +1,6 @@
+module HungryForm
+  module Elements
+    class TextAreaField < Base::ActiveElement
+    end
+  end
+end

data/lib/hungryform/elements/text_field.rb

@@ -1,4 +1,6 @@
-class HungryForm
-  class TextField < BaseActiveElement
+module HungryForm
+  module Elements
+    class TextField < Base::ActiveElement
+    end
   end
-end
+end

data/lib/hungryform/elements.rb

@@ -1,9 +1,17 @@
-require_relative 'elements/base_element'
-require_relative 'elements/base_active_element'
-require_relative 'elements/base_options_element'
-require_relative 'elements/base_group'
+module HungryForm
+  module Elements
+  end
+end
+
+require_relative 'elements/base/hashable'
+require_relative 'elements/base/element'
+require_relative 'elements/base/active_element'
+require_relative 'elements/base/options_element'
+require_relative 'elements/base/group'
 require_relative 'elements/page'
 require_relative 'elements/group'
 require_relative 'elements/html'
 require_relative 'elements/text_field'
-require_relative 'elements/select'
+require_relative 'elements/select_field'
+require_relative 'elements/text_area_field'
+require_relative 'elements/radio_group'