andrba/hungryform

Ruby gem for building complex multi page forms

HungryForm

HungryForm is a gem for managing multipage forms. The main purpose of this gem is to give developers an easy DSL to build complex forms. Rails integration can be done via the hungryform-rails gem.

Usage

form = HungryForm::Form.new do
  page :first do
    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, dependency: { set: "third_occupation" } do
      html :before, value: "Employment history over the last 5 years"
      text_area :history, value: "Default value"
    end
  end 
end

if form.valid?
  form.to_json
end

Field Dependencies

Each element of HungryForm, including pages and groups, can have a dependency parameter. This parameter must be a hash, containing a tree of basic operations. The dependency tree eventually resolves into to a boolean result. Within this tree you can use and combine the following operators, creating complex dependencies that can involve multiple elements:

# val1 == val2
{ eq: ["val1", "val2"] }

# val1 > val2
{ gt: ["val1", "val2"] }

# val1 < val2
{ lt: ["val1", "val2"] }

# val1 is not empty
{ set: "val1" }

# Get the opposite result of the expression
{ not: { eq: [1, 1] } }

# Check if all the expressions are true
{ 
  and: [
    { eq: [1, 1] },
    { eq: [2, 2] }
  ] 
}

# Check if any of the expressions is true
{ 
  or: [
    { not: { eq: [1, 1] } },
    { eq: [2, 2] }
  ] 
}

If the dependency is resolved positively it makes the element visible. Otherwise the element will be hidden with all its validation rules omited. It is allowed to use element names or params keys as parameters inside expressions.

HungryForm::Form.new do
  page :about do
    text_field :age
    text_field :favourite_alcohol, required: true, dependency: { gt: ["about_age", 18] }
  end
end
    

Assigning values

To assign values to form fields pass them as a hash on form initialization. The params hash must consist of field names and their values. Please note, that the field names must contain the full path to the field, starting from the page name.

params = {
  "first_first_name" => "John",
  "first_last_name" => "Doe",
  "second_address" => "John's address",
  "third_occupation" => "Software engineer",
  "third_employment_history_history" => "John's employment history"
}

form = HungryForm::Form.new :params => params do
...
end

Assign a default value to a form field:

text_field :email, value: "[email protected]"

You can assign any attribute to the field and it will be included into the field attributes during rendering:

text_field :email, my_attribute: "attribute value"

Configuration

To configure the gem use the configuration block:

HungryForm.configure do |config|
  config.text_field maxlength: 100
end

text_field (or any other element name): Assign an attribute to all elements of this type

Validation

Each active element of a form can be assigned with validation rules.

• required - accepts boolean or proc
• validation - accepts proc

text_field :name, required: true
text_field :email, validation: ->(el) { "is unexpected email" unless el.value == "[email protected]"  }

You can extend the list of validation rules by creating your own validation methods:

module HungryForm
  module Validator
    class << self
      def my_validation_method(element, rule)
        "is not #{rule}" unless element.value == rule
      end
    end
  end
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

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 )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

hungryform's Issues

Generation of multiple groups of the same structure

Sometimes it is necessary to create multiple groups of the same type. Imagine we have a form that asks about the addresses a person lived at within 10 years. Each address should consist of the following fields:

text_field :line_1
text_field :line_2
text_field :city
text_field country

Rather than copy-pasting 10..20 groups in the form definition we could set a quantity: 10 or multiple: true parameter which will render these groups automatically. Each group will have its number in the name, like page_mygroup_1 with field names like page_mygroup_1_city.

The question is how it will be rendered in the Rails app. Obviously we should not show to a user 10 groups all at once. I see two ways of doing it:

1. Controlling dropdown
   Link group visibility to a dropdown with numbers 0..10. When a user selects the quantity of groups the corresponding amount of groups become visible.
2. Add more / Delete buttons
   A group is rendered as a template that will be used by js to generate more groups. When a user clicks on "Add More" a new group is generated and becomes visible. Next to the group will be a button to delete this group.

Any other ideas are welcome!

Dependency param to accept a hash

If a hash is given as a dependency parameter it should be converted to a proper json string.

Route helpers

Currently it is required to define two routes to handle forms:

  get 'hungryform/:page' => 'hungryform#show'
  post 'hungryform/:page' => 'hungryform#update'

It would be worth creating some sort of a helper to define all form routes in one line.

Default settings

It would be good to have some sort of form elements configuration, where we could set up default attributes.

Rather than doing this every time we define a new field in a form

text_field :first_name, max_length: 100
text_field :last_name, max_length: 100

we could configure it like this

HungryForm::Elements::TextField.configure do |c|
  c.max_length = 100
end

Namespaced form field classes

It would be better to create a namespace for form fields. Currently they are all located under the HungryForm class, that has some other classes such as Validator or Resolver. A class lookup loops through these classes every time a new field is created.

Rendering HTML

A decision needs to be made to what extent this gem will be responsible for rendering HTML. If it is used extensively with frameworks like Rails or Sinatra, it will be better to delegate all this work to their template engines. However, this delegation will require extra work to be done each time it is used in a project.

Another option is to create a gem for each framework individually. If it is based on a current gem it can make integration easier.

Js module

Create a js module for dependency handling and form navigation.

New elements

We need to create more elements:

• text_area
• radio_group
• check_box
• check_box_group