README.md in hungryform-0.0.4 vs README.md in hungryform-0.0.6
- old
+ new
@@ -1,11 +1,9 @@
-# HungryForm
+# HungryForm [](https://travis-ci.org/andrba/hungryform) [](https://codeclimate.com/github/andrba/hungryform)
-[](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.
-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
form = HungryForm::Form.new do
page :first do
@@ -18,83 +16,114 @@
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
+ 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
-```
-To assign values to the form elements pass them as a hash on form initialization. The params hash must consist of elements names and their values. Please note, that the elements names must contain the full path to the element, starting from the page name.
-
-```ruby
-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 hisotory"
-}
-
-form = HungryForm::Form.new :params => params do
-...
+if form.valid?
+ form.to_json
end
-
```
+## Field Dependencies
-You can assign default value to a form element:
+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:
```ruby
-text_field :email, value: "john.doe@yahoo.com"
-```
-## Dependencies
-
-Each element of HungryForm, including pages and groups, can have a dependency parameter. This parameter must be a json string with an expression, that resolves to a boolean result. Within this expression you can use and combine the following operators, creating complex dependencies that can involve multiple elements:
-
-```json
# val1 == val2
-{"EQ": ["val1", "val2"]}
+{ eq: ["val1", "val2"] }
# val1 > val2
-{"GT": ["val1", "val2"]}
+{ gt: ["val1", "val2"] }
# val1 < val2
-{"LT": ["val1", "val2"]}
+{ lt: ["val1", "val2"] }
# val1 is not empty
-{"SET": "val1"}
+{ set: "val1" }
# Get the opposite result of the expression
-{"NOT": {"EQ": ["1", "1"]}}
+{ not: { eq: [1, 1] } }
# Check if all the expressions are true
-{"AND": [
- {"EQ": ["1", "1"]},
- {"EQ": ["2", "2"]}
-]}
+{
+ and: [
+ { eq: [1, 1] },
+ { eq: [2, 2] }
+ ]
+}
# Check if any of the expressions is true
-{"OR": [
- {"NOT": {"EQ": ["1", "1"]}},
- {"EQ": ["2", "2"]}
-]}
+{
+ 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 and not required. It is allowed to use element names or params keys as parameters inside expressions.
+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.
```ruby
HungryForm::Form.new do
page :about do
text_field :age
- text_field :favourite_alcohol, required: true, dependency: '{"GT": ["about_age", "18"]}'
+ 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.
+
+```ruby
+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:
+
+```ruby
+text_field :email, value: "john.doe@yahoo.com"
+```
+
+You can assign any attribute to the field and it will be included into the field attributes during rendering:
+
+```ruby
+text_field :email, my_attribute: "attribute value"
+```
+
+## Configuration
+
+To configure the gem use the configuration block:
+
+```ruby
+HungryForm.configure do |config|
+ config.views_prefix = 'myform'
+ config.text_field maxlength: 100
+end
+```
+
+```views_prefix```: Set this option in case you want to override the standard elements templates with your own ones. The prefix must match the folder name in your views folder where you keep the elements partials.
+
+```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.