form_obj 0.4.0 → 0.5.0

data/README.md

@@ -12,7 +12,8 @@ Ruby: 2.2.8+
 ActiveSupport: 3.2+
 ActiveModel: 3.2+
 
-The gem is tested against all ruby versions and all versions of its dependencies.
+The gem is tested against all ruby versions and all versions of its dependencies 
+except ActiveSupport and ActiveModel version 4.0.x because they requires Minitest 4 which is not compatible with Minitest 5.
 
 ## Installation
 
@@ -32,9 +33,9 @@ Or install it yourself as:
 
 ## Usage
 
-**WARNING!!!** The gem is still under development. Expect braking changes.<br/>
+**WARNING!!!** The gem is still under development. Expect braking changes in `FormObj::ModelMapper` module.<br/>
 
-Class `FormObj::Struct` allows to describe complicated data structure.
+Class `FormObj::Struct` allows to describe complicated data structure, to update it with `update_attributes` method and to get its hash representation with `to_hash` method.
 
 Class `FormObj::Form` inherits from `FormObj::Struct` and adds form builder compatibility and includes ActiveModel validations.
 
@@ -48,58 +49,139 @@ model attributes name) and
 
 ### Table of Contents
 
-1. [Definition](#1-definition)
-   1. [Nested Form Objects](11-nested-form-objects)
-   2. [Array of Form Objects](12-array-of-form-objects)
-2. [Update Attributes](2-update-attributes)
-   1. [Nested Form Objects](21-nested-form-objects)
-   2. [Array of Form Objects](22-array-of-form-objects)
-3. [Serialize to Hash](3-serialize-to-hash)
-   1. [Nested Form Objects](31-nested-form-objects)
-   2. [Array of Form Objects](32-array-of-form-objects)
-4. [Map Form Object to Models](4-map-form-objects-to-models)
-   1. [Multiple Models Example](41-multiple-models-example)
-   2. [Skip Attribute Mapping](42-skip-attribute-mapping)
-      1. [Map Nested Form Object Attribute to Parent Level Model Attribute](421-map-nested-form-object-attribute-to-parent-level-model-attribute)
-   3. [Map Nested Form Object to A Hash Model](43-map-nested-form-object-to-a-hash-model)
-5. [Load Form Object from Models](5-load-form-object-from-models)
-6. [Save Form Object to Models](6-save-form-object-to-models)
-   1. [Array of Form Objects and Models](61-array-of-form-objects-and-models)
-7. [Serialize Form Object to Model Hash](7-serialize-form-object-to-model-hash)
-8. [Validation and Coercion](8-validation-and-coercion)
-9. [Copy Model Validation Errors into Form Object](9-copy-model-validation-errors-into-form-object)   
-10. [Rails Example](10-rails-example)
-11. [Reference Guide](11-reference-guide-attribute-parameters)
-
-### 1. Definition
-
-Inherit your class from `FormObj::Form` and define its attributes.
-
-```ruby
-class SimpleForm < FormObj::Form
+1. [`FormObj::Struct`](#1-formobjstruct)
+   1. [Nesting `FormObj::Struct`](#11-nesting-formobjstruct)
+   2. [Array of `FormObj::Struct`](#12-array-of-formobjstruct)
+   3. [Serialize `FormObj::Struct` to Hash](#13-serialize-formobjstruct-to-hash)
+2. [`FormObj::Form`](#2-formobjform)
+   1. [`FormObj::Form` Validation](#21-formobjform-validation)
+   2. [`FormObj::Form` Persistence](#22-formobjform-persistence)
+   3. [Delete from Array of `FormObj::Form` via `update_attributes` method](#23-delete-from-array-of-formobjform-via-update_attributes-method)
+   4. [Using `FormObj::Form` in Form Builder](#24-using-formobjform-in-form-builder)
+3. [`FormObj::ModelMapper`](#3-formobjmodelmapper)
+   1. [`load_from_model` - Initialize Form Object from Model](#31-load_from_model---initialize-form-object-from-model)
+   2. [`load_from_models` - Initialize Form Object from Few Models](#32-load_from_models---initialize-form-object-from-few-models)
+   3. [Do Not Map Certain Attribute](#33-do-not-map-certain-attribute)
+   4. [Map Nested Form Objects](#34-map-nested-form-objects)
+   5. [Map Nested Form Objects to A Hash Model](#35-map-nested-form-object-to-a-hash-model)
+   6. [Custom Implementation of Loading of Array of Models](#36-custom-implementation-of-loading-of-array-of-models)
+   7. [Sync Form Object to Models](#37-sync-form-object-to-models)
+      1. [Array of Form Objects and Models](#371-array-of-form-objects-and-models)
+   8. [Serialize Form Object to Model Hash](#38-serialize-form-object-to-model-hash)
+   9. [Copy Model Validation Errors into Form Object](#39-copy-model-validation-errors-into-form-object)   
+4. [Rails Example](#4-rails-example)
+5. [Reference Guide](#5-reference-guide-attribute-parameters)
+
+### 1. `FormObj::Struct`
+
+Inherit your class from `FormObj::Struct` and define its attributes.
+
+```ruby
+class Team < FormObj::Struct
   attribute :name
   attribute :year
 end
 ```
 
-Use it in a form builder.
+Read and write attribute values using dot-notation.
 
-```erb
-<%= form_for(@simple_form) do |f| %>
-  <%= f.label :name %>
-  <%= f.text_field :name %>
+```ruby
+team = Team.new             # => #<Team name: nil, year: nil> 
+team.name = 'Ferrari'       # => "Ferrari"
+team.year = 1950            # => 1950
 
-  <%= f.label :year %>
-  <%= f.text_field :year %>
-<% end %>
+team.name                   # => "Ferrari"
+team.year                   # => 1950
 ```
 
-#### 1.1. Nested Form Objects
+Initialize attributes in constructor.
+
+```ruby
+team = Team.new(
+    name: 'Ferrari', 
+    year: 1950
+)                           # => #<Team name: "Ferrari", year: 1950>  
+team.name                   # => "Ferrari"
+team.year                   # => 1950
+```
 
-Use blocks to define nested forms.
+Update attributes using `update_attributes` method.
 
 ```ruby
-class NestedForm < FormObj::Form
+team.update_attributes(
+    name: 'McLaren',
+    year: 1966
+)                           # => #<Team name: "McLaren", year: 1966>
+team.name                   # => "McLaren"
+team.year                   # => 1966
+```
+
+In both cases (initialization or `update_attributes`) hash is transformed to `HashWithIndifferentAccess` before applying its values
+so it doesn't matter whether keys are symbols or strings.
+
+```ruby
+team.update_attributes(
+    'name' => 'Ferrari', 
+    'year' => 1950
+)                           # => #<Team name: "Ferrari", year: 1950>
+```
+
+Attribute value stays unchanged if hash doesn't have corresponding key.
+
+```ruby
+team = Team.new(name: 'Ferrari')    # => #<Team name: "Ferrari", year: nil>
+team.update_attributes(year: 1950)  # => #<Team name: "Ferrari", year: 1950>
+```
+
+Exception `UnknownAttributeError` is raised if there is key that doesn't correspond to any attribute.
+
+```ruby
+Team.new(name: 'Ferrari', a: 1)     # => FormObj::UnknownAttributeError: a
+Team.new.update_attributes(a: 1)    # => FormObj::UnknownAttributeError: a
+```
+
+Use parameter `raise_if_not_found: false` in order to avoid exception and silently skip unknown key in the hash.
+
+```ruby
+team = Team.new({
+    name: 'Ferrari', 
+    a: 1
+}, raise_if_not_found: false)    # => #<Team name: "Ferrari", year: nil> 
+
+team.update_attributes({
+    name: 'McLaren',
+    a: 1
+}, raise_if_not_found: false)    # => #<Team name: "McLaren", year: nil>
+```
+
+Define default attribute value using `default` parameter.
+Use `Proc` to calculate default value dynamically. 
+`Proc` is calculated only once at the moment of first access to attribute. 
+`Proc` receives two arguments:
+- `struct_class` - class (!!! not an instance) where attribute is defined
+- `attribute` - internal representation of attribute 
+
+```ruby
+class Team < FormObj::Struct
+  attribute :name, default: 'Ferrari'
+  attribute :year, default: ->(struct_class, attribute) { struct_class.default_year(attribute) }
+  
+  def self.default_year(attribute)
+    "#{attribute.name} = 1950"
+  end
+end
+
+team = Team.new      # => #<Team name: "Ferrari", year: "year = 1950"> 
+team.name            # => "Ferrari"  
+team.year            # => "year = 1950" 
+```
+
+#### 1.1. Nesting `FormObj::Struct`
+
+Use blocks to define nested structs.
+
+```ruby
+class Team < FormObj::Struct
   attribute :name
   attribute :year
   attribute :car do
@@ -113,62 +195,163 @@ class NestedForm < FormObj::Form
 end
 ```
 
-Or explicitly define nested form class.
+Or explicitly define nested struct classes.
 
 ```ruby
-class EngineForm < FormObj::Form
+class Engine < FormObj::Struct
   attribute :power
   attribute :volume
 end
-class CarForm < FormObj::Form
+class Car < FormObj::Struct
   attribute :code
   attribute :driver
-  attribute :engine, class: EngineForm
+  attribute :engine, class: Engine
 end
-class NestedForm < FormObj::Form
+class Team < FormObj::Struct
   attribute :name
   attribute :year
-  attribute :car, class: CarForm
+  attribute :car, class: Car
 end
 ```
 
-Use nested forms in form builder.
+Read and write attribute values using dot-notation.
 
-```erb
-<%= form_for(@nested_form) do |f| %>
-  <%= f.label :name %>
-  <%= f.text_field :name %>
+```ruby
+team = Team.new                # => #<Team name: nil, year: nil, car: #< code: nil, driver: nil, engine: #< power: nil, volume: nil>>> 
+team.name = 'Ferrari'          # => "Ferrari"
+team.year = 1950               # => 1950
+team.car.code = '340 F1'       # => "340 F1"
+team.car.driver = 'Ascari'     # => "Ascari"
+team.car.engine.power = 335    # => 335
+team.car.engine.volume = 4.1   # => 4.1
+
+team.name                      # => "Ferrari"
+team.year                      # => 1950
+team.car.code                  # => "340 F1"
+team.car.driver                # => "Ascari"
+team.car.engine.power          # => 335
+team.car.engine.volume         # => 4.1
+```
 
-  <%= f.label :year %>
-  <%= f.text_field :year %>
+Initialize nested struct using nested hash.
 
-  <%= f.fields_for(:car) do |fc| %>
-    <%= fc.label :code %>
-    <%= fc.text_field :code %>
+```ruby
+team = Team.new(
+    name: 'Ferrari',
+    year: 1950,
+    car: {
+        code: '340 F1',
+        driver: 'Ascari',
+        engine: {
+            power: 335,
+            volume: 4.1,
+        }
+    }
+)                        # => #<Team name: "Ferrari", year: 1950, car: #< code: "340 F1", driver: "Ascari", engine: #< power: 335, volume: 4.1>>>  
+
+team.name                # => "Ferrari"
+team.year                # => 1950
+team.car.code            # => "340 F1"
+team.car.driver          # => "Ascari"
+team.car.engine.power    # => 335
+team.car.engine.volume   # => 4.1
+```
 
-    <%= fc.label :driver %>
-    <%= fc.text_field :driver %>
+Update nested struct using nested hash.
 
-    <%= fc.field_for(:engine) do |fce| %>
-      <%= fce.label :power %>
-      <%= fce.text_field :power %>
+```ruby
+team.update_attributes(
+    name: 'McLaren',
+    year: 1966,
+    car: {
+      code: 'M2B',
+      driver: 'Bruce McLaren',
+      engine: {
+        power: 300,
+        volume: 3.0
+      }
+    }
+)                           # => #<Team name: "McLaren", year: 1966, car: #< code: "M2B", driver: "Bruce McLaren", engine: #< power: 300, volume: 3.0>>>
+
+team.name                   # => "McLaren"
+team.year                   # => 1966
+team.car.code               # => "M2B"
+team.car.driver             # => "Bruce McLaren"
+team.car.engine.power       # => 300
+team.car.engine.volume      # => 3.0
+```
 
-      <%= fce.label :volume %>
-      <%= fce.text_field :volume %>
-    <% end %>
-  <% end %>
-<% end %>
+Use hash to define default value of nested struct defined with block.
+
+```ruby
+class Team < FormObj::Struct
+  attribute :car, default: { code: '340 F1', driver: 'Ascari' } do
+    attribute :code
+    attribute :driver
+  end
+end
+
+team = Team.new      # => #<Team car: #< code: "340 F1", driver: "Ascari">>  
+team.car.code        # => "340 F1"  
+team.car.driver      # => "Ascari" 
+```
+
+Use hash or struct instance to define default value of nested struct defined with class. 
+
+```ruby
+class Car < FormObj::Struct
+  attribute :code
+  attribute :driver
+end
+
+class Team < FormObj::Struct
+  attribute :car, class: Car, default: Car.new(code: '340 F1', driver: 'Ascari')
+end
+
+team = Team.new      # => #<Team car: #<Car code: "340 F1", driver: "Ascari">>  
+team.car.code        # => "340 F1"  
+team.car.driver      # => "Ascari" 
+```
+
+The struct instance class should correspond to nested attribute class!
+
+```ruby
+class Team < FormObj::Struct
+  attribute :car, class: Car, default: 36
+end
+
+Team.new      # => FormObj::WrongDefaultValueClass: FormObj::WrongDefaultValueClass  
 ```
 
-#### 1.2. Array of Form Objects
+#### 1.2. Array of `FormObj::Struct`
 
-Specify attribute parameter `array: true` in order to define an array of form objects
+Use parameter `array: true` in order to define an array of nested structs.
+Define `primary_key` so that `update_attribute` method be able to distinguish 
+whether to update existing array element or create a new one. 
+By default attribute `id` is considered to be a primary key.
 
 ```ruby
-class ArrayForm < FormObj::Form
+class Team < FormObj::Struct
   attribute :name
   attribute :year
   attribute :cars, array: true do
+    attribute :code, primary_key: true     # <- primary key is specified on attribute level
+    attribute :driver
+    attribute :engine do
+      attribute :power
+      attribute :volume
+    end
+  end
+end
+```
+
+or
+
+```ruby
+class Team < FormObj::Struct
+  attribute :name
+  attribute :year
+  attribute :cars, array: true, primary_key: :code do     # <- primary key is specified on struct level
     attribute :code
     attribute :driver
     attribute :engine do
@@ -182,130 +365,294 @@ end
 or
 
 ```ruby
-class EngineForm < FormObj::Form
+class Engine < FormObj::Struct
   attribute :power
   attribute :volume
 end
-class CarForm < FormObj::Form
-  attribute :code
+class Car < FormObj::Struct
+  attribute :code, primary_key: true      # <- primary key is specified on attribute level
   attribute :driver
-  attribute :engine, class: EngineForm
+  attribute :engine, class: Engine
 end
-class ArrayForm < FormObj::Form
+class Team < FormObj::Struct
   attribute :name
   attribute :year
-  attribute :cars, array: true, class: CarForm
+  attribute :cars, array: true, class: Car
 end
 ```
 
-Add new elements in the array by using method :create.
+or
 
 ```ruby
-@array_form = ArrayForm.new
-@array_form.cars.size 				# => 0
-@array_form.cars.create
-@array_form.cars.size 				# => 1
+class Engine < FormObj::Struct
+  attribute :power
+  attribute :volume
+end
+class Car < FormObj::Struct
+  attribute :code
+  attribute :driver
+  attribute :engine, class: Engine
+end
+class Team < FormObj::Struct
+  attribute :name
+  attribute :year
+  attribute :cars, array: true, class: Car, primary_key: :code      # <- primary key is specified on struct level 
+end
 ```
 
-Use array of nested forms in the form builder.
+Read and write attribute values using dot-notation.
+Add new elements in the array using method `create`.
 
-```erb
-<%= form_for(@array_form) do |f| %>
-  <%= f.label :name %>
-  <%= f.text_field :name %>
+```ruby
+team = Team.new               # => #<Team name: nil, year: nil, cars: []>
+team.name = 'Ferrari'         # => "Ferrari"
+team.year = 1950              # => 1950
+
+team.cars.size 				  # => 0
+car1 = team.cars.create       # => #< code: nil, driver: nil, engine: #< power: nil, volume: nil>> 
+team.cars.size 				  # => 1
+car1.code = '340 F1'          # => "340 F1"
+car1.driver = 'Ascari'        # => "Ascari"
+car1.engine.power = 335       # => 335
+car1.engine.volume = 4.1      # => 4.1
+
+car2 = team.cars.create       # => #< code: nil, driver: nil, engine: #< power: nil, volume: nil>>
+team.cars.size 				  # => 2
+car2.code = '275 F1'          # => "275 F1"        
+car2.driver = 'Villoresi'     # => "Villoresi"                
+car2.engine.power = 330       # => 330              
+car2.engine.volume = 3.3      # => 3.3                
+
+team.name                     # => "Ferrari"
+team.year                     # => 1950
+
+team.cars[0].code             # => "340 F1"
+team.cars[0].driver           # => "Ascari"
+team.cars[0].engine.power     # => 335
+team.cars[0].engine.volume    # => 4.1
+
+team.cars[1].code             # => "275 F1"
+team.cars[1].driver           # => "Villoresi"
+team.cars[1].engine.power     # => 330
+team.cars[1].engine.volume    # => 3.3
+```
 
-  <%= f.label :year %>
-  <%= f.text_field :year %>
+Initialize attributes using hash with array of hashes.
 
-  <% f.cars.each do |car| %>
-    <%= f.fields_for(:cars, car, index: '') do |fc| %>
-      <%= fc.label :code %>
-      <%= fc.text_field :code %>
+```ruby
+team = Team.new(
+    name: 'Ferrari',
+    year: 1950,
+    cars: [
+      {
+          code: '340 F1',
+          driver: 'Ascari',
+          engine: {
+              power: 335,
+              volume: 4.1,
+          }
+      }, {
+          code: '275 F1',
+          driver: 'Villoresi',
+          engine: {
+              power: 330,
+              volume: 3.3,
+          }
+      }
+    ],
+)                             # => #<Team name: "Ferrari", year: 1950, cars: [#< code: "340 F1", driver: "Ascari", engine: #< power: 335, volume: 4.1>>, #< code: "275 F1", driver: "Villoresi", engine: #< power: 330, volume: 3.3>>]>
+                            
+team.name                     # => "Ferrari"
+team.year                     # => 1950
+
+team.cars[0].code             # => "340 F1"
+team.cars[0].driver           # => "Ascari"
+team.cars[0].engine.power     # => 335
+team.cars[0].engine.volume    # => 4.1
+
+team.cars[1].code             # => "275 F1"
+team.cars[1].driver           # => "Villoresi"
+team.cars[1].engine.power     # => 330
+team.cars[1].engine.volume    # => 3.3
+```
 
-      <%= fc.label :driver %>
-      <%= fc.text_field :driver %>
+Update attributes using hash with array of hashes.
 
-      <%= fc.field_for(:engine) do |fce| %>
-        <%= fce.label :power %>
-        <%= fce.text_field :power %>
+```ruby
+team.update_attributes(
+    name: 'McLaren',
+    year: 1966,
+    cars: [
+      {
+          code: '275 F1',
+          driver: 'Bruce McLaren',
+          engine: {
+              volume: 3.0
+          }
+      }, {
+          code: 'M7A',
+          driver: 'Denis Hulme',
+          engine: {
+              power: 415,
+          }
+      }
+    ],
+)                               # => #<Team name: "McLaren", year: 1966, cars: [#< code: "M2B", driver: "Bruce McLaren", engine: #< power: nil, volume: 3.0>>, #< code: "M7A", driver: "Denis Hulme", engine: #< power: 415, volume: nil>>]>
+                            
+team.name                       # => "McLaren"
+team.year                       # => 1966
+
+team.cars[0].code               # => "275 F1"
+team.cars[0].driver             # => "Bruce McLaren"
+team.cars[0].engine.power       # => 330    - this value was not updated in :update_attributes method
+team.cars[0].engine.volume      # => 3.0
+
+team.cars[1].code               # => "M7A"
+team.cars[1].driver             # => "Denis Hulme"
+team.cars[1].engine.power       # => 415
+team.cars[1].engine.volume      # => nil    - this value is nil because this car was created in :updated_attributes method
+```
 
-        <%= fce.label :volume %>
-        <%= fce.text_field :volume %>
-      <% end %>
-    <% end %>
-  <% end %>
-<% end %>
+Use `primary_key` method on class to get primary key attribute name.
+Use `primary_key` and `primary_key=` method on instance to get and set primary key attribute value.
+
+```ruby
+Team.primary_key                # => :id  - By default primary key is :id even if there is no such attribute
+Car.primary_key                 # => :code 
+team.cars.first.primary_key     # => "275 F1"
+team.cars.last.primary_key      # => "M7A"
 ```
 
-### 2. Update Attributes
+`update_attributes` compares present elements in the array with new elements in hash by using primary key.
+By default `update_attributes`:
+- calls attribute setter under hood to update attribute value of present elements,
+- calls `FormObj::Struct` constructor to create all new elements (that exists in the hash but absent in the present array),
+- calls `delete_if` to delete all removed elements (that exists in the present array but absent in the hash).
+
+Default behaviour could be easily redefined by overwriting corresponding methods.
+
+```ruby
+class MyStruct < FormObj::Struct
+  class Array < FormObj::Struct::Array
+    private
 
-Update form object attributes with the parameter hash received from the browser. 
-Method `update_attributes(new_attrs_hash, options)` returns self so one can chain calls.
+    def create_item(hash, raise_if_not_found:)
+      puts "Create new element from #{hash}"
+      super
+    end
 
-`options` hash can have `:raise_if_not_found` key which has `true` value by default.
-If `new_attrs_hash` has key that does not correspond to any attributes 
-and `raise_if_not_found` is `true` than `UnknownAttributeError` will be generated.
-`raise_if_not_found` equals to `false` prevents error generation 
-and non existent attribute will be just ignored.
+    def delete_items(ids)
+      each do |item|
+        if ids.include? item.primary_key
+          item._destroy = true
+          puts "Mark item #{item.primary_key} for deletion"
+        end
+      end
+    end
+  end
+
+  def self.array_class
+    MyStruct::Array
+  end
+
+  def self.nested_class
+    MyStruct
+  end
+
+  private
+
+  def update_attribute(attribute, new_value)
+    puts "Update attribute :#{attribute.name} value from #{send(attribute.name)} to #{new_value}"
+    super
+  end
+end
+
+class Team < MyStruct
+  attribute :name
+  attribute :year
+  attribute :cars, array: true, primary_key: :code do
+    attribute :code
+    attribute :driver
+    attribute :engine do
+      attribute :power
+      attribute :volume
+    end
+    attr_accessor :_destroy
+  end
+end
+
+team = Team.new(name: 'Ferrari', cars: [{ code: '340 F1' }, { code: '275 F1' }])
+# => Update attribute :name value from  to Ferrari
+# => Create new element from {"code"=>"340 F1"}
+# => Update attribute :code value from  to 340 F1
+# => Create new element from {"code"=>"275 F1"}
+# => Update attribute :code value from  to 275 F1
+# => => #<Team name: "Ferrari", year: nil, cars: [#< code: "340 F1", driver: nil, engine: #< power: nil, volume: nil>>, #< code: "275 F1", driver: nil, engine: #< power: nil, volume: nil>>]> 
+
+team.update_attributes(cars: [{ code: '275 F1' }])
+# => Update attribute :code value from 275 F1 to 275 F1
+# => Mark item 340 F1 for deletion
+# => => #<Team name: "Ferrari", year: nil, cars: [#< code: "340 F1", driver: nil, engine: #< power: nil, volume: nil>>, #< code: "275 F1", driver: nil, engine: #< power: nil, volume: nil>>]> 
+``` 
+
+Use array of hashes to define default array of nested structs defined with block.
 
 ```ruby
-simple_form = SimpleForm.new
-simple_form.name = 'Ferrari'
-simple_form.year = 1950
-simple_form.update_attributes(
-                                name: 'McLaren',
-                                year: 1966
-                             )
-simple_form.name      # => "McLaren"                             
-simple_form.year      # => 1966                             
+class Team < FormObj::Struct
+  attribute :cars, array: true, default: [{ code: '340 F1', driver: 'Ascari' }, { code: '275 F1', driver: 'Villoresi' }] do
+    attribute :code
+    attribute :driver
+  end
+end
+
+team = Team.new         # => #<Team cars: [#< code: "340 F1", driver: "Ascari">, #< code: "275 F1", driver: "Villoresi">]>   
+team.cars.size          # => 2  
+team.cars[0].code       # => "340 F1"  
+team.cars[0].driver     # => "Ascari"  
+team.cars[1].code       # => "275 F1"  
+team.cars[1].driver     # => "Villoresi"  
 ```
 
-#### 2.1. Nested Form Objects
+Use array of hashes or struct instances to define default array of nested structs defined with class.
 
 ```ruby
-nested_form = NestedForm.new
-nested_form.name = 'Ferrari'
-nested_form.year = 1950
-nested_form.car.code = '340 F1'
-nested_form.car.driver = 'Ascari'
-nested_form.car.engine.power = 335
-nested_form.car.engine.volume = 4.1
-nested_form.update_attributes(
-                                name: 'McLaren',
-                                year: 1966,
-                                car: {
-                                  code: 'M2B',
-                                  driver: 'Bruce McLaren',
-                                  engine: {
-                                    power: 300,
-                                    volume: 3.0
-                                  }
-                                }
-                             )
-nested_form.name                  # => "McLaren"
-nested_form.year                  # => 1966
-nested_form.car.code              # => "M2B"
-nested_form.car.driver            # => "Bruce McLaren"
-nested_form.car.engine.power      # => 300
-nested_form.car.engine.volume     # => 3.0
+class Car < FormObj::Struct
+  attribute :code
+  attribute :driver
+end
+
+class Team < FormObj::Struct
+  attribute :cars, class: Car, array: true, default: [Car.new(code: '340 F1', driver: 'Ascari'), { code: '275 F1', driver: 'Villoresi' }]
+end
+
+team = Team.new         # => #<Team cars: [#<Car code: "340 F1", driver: "Ascari">, #<Car code: "275 F1", driver: "Villoresi">]>    
+team.cars.size          # => 2  
+team.cars[0].code       # => "340 F1"  
+team.cars[0].driver     # => "Ascari"  
+team.cars[1].code       # => "275 F1"  
+team.cars[1].driver     # => "Villoresi"  
 ```
 
-#### 2.2. Array of Form Objects
+The struct instance class should correspond to nested attribute class!
+
+```ruby
+class Team < FormObj::Struct
+  attribute :cars, class: Car, array: true, default: [36]
+end
+
+Team.new      # => FormObj::WrongDefaultValueClass: FormObj::WrongDefaultValueClass  
+```
 
-Updating an array of form objects will compare the existing array with the new one.
-New array elements will be added, existing array elements will be updated, absent array elements will be deleted 
-(deleting behavior is the subject of changes in future releases - only elements with flag `_destroy == true` will be deleted).
+#### 1.3. Serialize `FormObj::Struct` to Hash
 
-In order to compare old and new array its elements have to be identified via the primary key.
-Primary key can be specified either on the attribute level or on the form level.
-If it is not specified the :id field is supposed to be the primary key.
+Call `to_hash()` method in order to get a hash representation of `FormObj::Struct`
 
 ```ruby
-class ArrayForm < FormObj::Form
+class Team < FormObj::Struct
   attribute :name
   attribute :year
   attribute :cars, array: true do
-    attribute :code, primary_key: true     # <- primary key is specified on attribute level
+    attribute :code, primary_key: true
     attribute :driver
     attribute :engine do
       attribute :power
@@ -313,14 +660,82 @@ class ArrayForm < FormObj::Form
     end
   end
 end
-``` 
+
+team = Team.new(
+    name: 'Ferrari',
+    year: 1950,
+    cars: [
+      {
+          code: '340 F1',
+          driver: 'Ascari',
+          engine: {
+              power: 335,
+              volume: 4.1,
+          }
+      }, {
+          code: '275 F1',
+          driver: 'Villoresi',
+          engine: {
+              power: 330,
+              volume: 3.3,
+          }
+      }
+    ],
+)                 # => #<Team name: "Ferrari", year: 1950, cars: [#< code: "340 F1", driver: "Ascari", engine: #< power: 335, volume: 4.1>>, #< code: "275 F1", driver: "Villoresi", engine: #< power: 330, volume: 3.3>>]>
+
+team.to_hash      # => {
+                  # =>    :name => "Ferrari",
+                  # =>    :year => 1950,
+                  # =>    :cars => [{
+                  # =>      :code => "340 F1",
+                  # =>      :driver => "Ascari",
+                  # =>      :engine => {
+                  # =>        :power => 335,
+                  # =>        :volume => 4.1
+                  # =>      }
+                  # =>    }, {
+                  # =>      :code => "275 F1",
+                  # =>      :driver => "Villoresi",
+                  # =>      :engine => {
+                  # =>        :power => 330,
+                  # =>        :volume => 3.3
+                  # =>      }
+                  # =>    }] 
+                  # => }
+```
+
+### 2. `FormObj::Form`
+
+`FormObj::Form` is inherited from `FormObj::Struct` and adds support for Rails compatible form builders and ActiveModel validations. 
+
+#### 2.1. `FormObj::Form` Validation
 
 ```ruby
-class ArrayForm < FormObj::Form
+class Team < FormObj::Form
   attribute :name
   attribute :year
-  attribute :cars, array: true, primary_key: :code do     # <- primary key is specified on form level
-    attribute :code
+  
+  validates :name, length: { minimum: 10 }
+end
+
+team = Team.new(name: 'Ferrari')      # => #<Team name: "Ferrari", year: nil> 
+team.valid?                           # => false
+team.errors.messages                  # => {:name=>["is too short (minimum is 10 characters)"]} 
+```
+
+#### 2.2. `FormObj::Form` Persistence
+
+In order to make `FormObj::Form` compatible with form builder it has to respond to `:persisted?` message.
+It maintains persistence status. Initial form is not persisted. 
+It can be marked as persisted by assigning `persisted = true` which marks as persisted only form itself or
+by calling `mark_as_persisted` method which marks as persisted the form itself and all nested forms and arrays.
+
+```ruby
+class Team < FormObj::Form
+  attribute :name
+  attribute :year
+  attribute :cars, array: true do
+    attribute :code, primary_key: true
     attribute :driver
     attribute :engine do
       attribute :power
@@ -328,182 +743,295 @@ class ArrayForm < FormObj::Form
     end
   end
 end
-``` 
 
-```ruby
-array_form = ArrayForm.new
-array_form.name = 'Ferrari'
-array_form.year = 1950
+team = Team.new(cars: [{code: 1}])
 
-car1 = array_form.cars.create
-car1.code = '340 F1'
-car1.driver = 'Ascari'
-car1.engine.power = 335
-car1.engine.volume = 4.1
+team.persisted?                         # => false
+team.cars[0].persisted?                 # => false
+team.cars[0].engine.persisted?          # => false
 
-car2 = array_form.cars.create
-car2.code = 'M2B'
-car2.driver = 'Villoresi'
-car2.engine.power = 300
-car2.engine.volume = 3.3
+team.persisted = true
 
-array_form.update_attributes(
-                              name: 'McLaren',
-                              year: 1966,
-                              cars: [
-                                  {
-                                      code: 'M2B',
-                                      driver: 'Bruce McLaren',
-                                      engine: {
-                                          volume: 3.0
-                                      }
-                                  }, {
-                                      code: 'M7A',
-                                      driver: 'Denis Hulme',
-                                      engine: {
-                                          power: 415,
-                                      }
-                                  }
-                              ],
-                            )
-                            
-array_form.name                     # => "McLaren"
-array_form.year                     # => 1966
+team.persisted?                         # => false  - because nested forms are not persisted
+team.cars[0].persisted?                 # => false
+team.cars[0].engine.persisted?          # => false
+
+team.cars[0].engine.persisted = true
+
+team.persisted?                         # => false  - because nested forms are not persisted
+team.cars[0].persisted?                 # => false
+team.cars[0].engine.persisted?          # => true
+
+team.mark_as_persisted
+
+team.persisted?                         # => true
+team.cars[0].persisted?                 # => true
+team.cars[0].engine.persisted?          # => true
+```
+
+Change of attribute value (directly or by `update_attributes` call) will change persistence status to `false`.
+
+```ruby
+team.name = 'Ferrari'
+team.persisted?                         # => false
 
-array_form.cars[0].code             # => "M2B"
-array_form.cars[0].driver           # => "Bruce McLaren"
-array_form.cars[0].engine.power     # => 300    - this value was not updated in update_attributes
-array_form.cars[0].engine.volume    # => 3.0
+team.mark_as_persisted
+team.persisted?                         # => true
 
-array_form.cars[1].code             # => "M7A"
-array_form.cars[1].driver           # => "Denis Hulme"
-array_form.cars[1].engine.power     # => 415
-array_form.cars[1].engine.volume    # => nil    - this value is nil because this car was created in updated_attributes
+team.update_attributes(name: 'McLaren')
+team.persisted?                         # => false
 ```
 
-### 3. Serialize to Hash
+#### 2.3. Delete from Array of `FormObj::Form` via `update_attributes` method
 
-Call `to_hash()` method in order to get a hash representation of the form object
+`FormObj::Struct` `update_attributes` method by default deletes all array elements that are not present in the new hash.
 
 ```ruby
-simple_form.to_hash     # => {
-                        # =>    :name => "McLaren",
-                        # =>    :year => 1966  
-                        # => }
+class Team < FormObj::Struct
+  attribute :cars, array: true, primary_key: :code do
+    attribute :code
+    attribute :driver
+  end
+end
+
+team = Team.new(cars: [{code: 1, driver: 'Ascari'}, {code: 2, driver: 'Villoresi'}])
+team.update_attributes(cars: [{code: 1}])
+team.cars     # => [#< code: 1, driver: "Ascari">]                                     
 ```
 
-#### 3.1. Nested Form Objects
+In oppose to this `FormObj::Form` `update_attributes` method ignores elements that are absent in the hash but
+marks for destruction those elements that has `_destroy: true` key in the hash.
 
 ```ruby
-nested_form.to_hash     # => {
-                        # =>    :name => "McLaren",
-                        # =>    :year => 1966,
-                        # =>    :car  => {
-                        # =>      :code => "340 F1",
-                        # =>      :driver => "Ascari",
-                        # =>      :engine => {
-                        # =>        :power => 335,
-                        # =>        :volume => 4.1
-                        # =>      }   
-                        # =>    }
-                        # => }
+class Team < FormObj::Form
+  attribute :cars, array: true, primary_key: :code do
+    attribute :code
+    attribute :driver
+  end
+end
+
+team = Team.new(cars: [{code: 1, driver: 'Ascari'}, {code: 2, driver: 'Villoresi'}])
+team.update_attributes(cars: [{code: 2, driver: 'James Hunt'}])
+
+team.cars[0].code                       # => 1
+team.cars[0].driver                     # => 'Ascari'
+team.cars[0].marked_for_destruction?    # => false
+
+team.cars[1].code                       # => 2
+team.cars[1].driver                     # => 'James Hunt'
+team.cars[1].marked_for_destruction?    # => false
+
+team.update_attributes(cars: [{code: 1, _destroy: true}])
+
+team.cars[0].code                       # => 2
+team.cars[0].driver                     # => 'James Hunt'
+team.cars[0].marked_for_destruction?    # => false
+
+team.cars[1].code                       # => 1
+team.cars[1].driver                     # => 'Ascari'
+team.cars[1].marked_for_destruction?    # => true                                 
 ```
 
-#### 3.2. Array of Form Objects
+Use `mark_for_destruction` in order to forcefully mark an array element for destruction.
 
 ```ruby
-array_form.to_hash      # => {
-                        # =>    :name => "McLaren",
-                        # =>    :year => 1966,
-                        # =>    :cars => [{
-                        # =>      :code => "M2B",
-                        # =>      :driver => "Bruce McLaren",
-                        # =>      :engine => {
-                        # =>        :power => 300,
-                        # =>        :volume => 3.0
-                        # =>      }
-                        # =>    }, {
-                        # =>      :code => "M7A",
-                        # =>      :driver => "Denis Hulme",
-                        # =>      :engine => {
-                        # =>        :power => 415,
-                        # =>        : volume => nil
-                        # =>      }
-                        # =>    }] 
-                        # => }
+team.cars[0].marked_for_destruction?    # => false
+team.cars[0].mark_for_destruction      
+team.cars[0].marked_for_destruction?    # => true
 ```
 
-### 4. Map Form Object to/from Models
+#### 2.4. Using `FormObj::Form` in Form Builder
 
-Include `DataMapper` mix-in and map form object attributes to one or more models by using `:model` and `:model_attribute` parameters.
-By default each form object attribute is mapped to the model attribute with the same name of the `:default` model. 
+```ruby
+class Team < FormObj::Form
+  attribute :name
+  attribute :year
+  attribute :cars, array: true, primary_key: :code do
+    attribute :code
+    attribute :driver
+    attribute :engine do
+      attribute :power
+      attribute :volume
+    end
+  end
+end
+
+@team = Team.new
+```
+
+```erb
+<%= form_for(@team) do |f| %>
+  <%= f.label :name %>
+  <%= f.text_field :name %>
+
+  <%= f.label :year %>
+  <%= f.text_field :year %>
+
+  <% f.cars.each do |car| %>
+    <%= f.fields_for(:cars, car, index: '') do |fc| %>
+      <%= fc.label :code %>
+      <%= fc.text_field :code %>
+
+      <%= fc.label :driver %>
+      <%= fc.text_field :driver %>
+
+      <%= fc.field_for(:engine) do |fce| %>
+        <%= fce.label :power %>
+        <%= fce.text_field :power %>
+
+        <%= fce.label :volume %>
+        <%= fce.text_field :volume %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
+### 3. `FormObj::ModelMapper`
+
+Include `FormObj::ModelMapper` module and map form object attributes to one or more models by using `:model` and `:model_attribute` parameters.
+Use dot notation to map model attribute to a nested model. Use colon to specify a "hash's attribute".
 
-Use dot notation to map model attribute to a nested model. Use colon to specify a "hash" attribute.
+#### 3.1. `load_from_model` - Initialize Form Object from Model
+
+Use `load_from_model(model)` method to initialize form object from the model.
 
 ```ruby
-class SingleForm < FormObj::Form
-  include DataMapper
+class Team < FormObj::Form
+  include FormObj::ModelMapper
   
   attribute :name, model_attribute: :team_name
   attribute :year
   attribute :engine_power, model_attribute: 'car.:engine.power'
 end
+
+car_model = { engine: Struct.new(:power).new(335) }
+team_model = Struct.new(:team_name, :year, :car).new('Ferrari', 1950, car_model)
+
+team = Team.new.load_from_model(team_model)
+team.to_hash      # => {
+                  # =>    :name => "Ferrari"
+                  # =>    :year => 1950
+                  # =>    :engine_power => 335
+                  # => }
 ```
 
-Suppose `single_form = SingleForm.new` and `model` to be an instance of a model.
+So attributes are mapped as follows:
 
 | Form Object attribute | Model attribute |
 | --------------------- | --------------- |
-| `single_form.name` | `model.team_name` |
-| `single_form.year` | `model.year` |
-| `single_form.engine_power` | `model.car[:engine].power` |
+| `team.name` | `team_model.team_name` |
+| `team.year` | `team_model.year` |
+| `team.engine_power` | `team_model.car[:engine].power` |
 
-#### 4.1. Multiple Models Example
+
+#### 3.2. `load_from_models` - Initialize Form Object from Few Models
+
+Use `load_from_models(models)` method to initialize form object from few models. 
+`models` parameter is a hash where keys are the name of models and values are models themselves. 
+
+By default each form object attribute is mapped to `:default` model.
+Use parameter `:model` to map it to another model. 
 
 ```ruby
-class MultiForm < FormObj::Form
-  include ModelMapper
+class Team < FormObj::Form
+  include FormObj::ModelMapper
   
   attribute :name, model_attribute: :team_name
   attribute :year
   attribute :engine_power, model: :car, model_attribute: ':engine.power'
 end
+
+car_model = { engine: Struct.new(:power).new(335) }
+team_model = Struct.new(:team_name, :year).new('Ferrari', 1950)    # <- doesn't have car attribute !!!
+
+team = Team.new.load_from_models(default: team_model, car: car_model)
+team.to_hash      # => {
+                  # =>    :name => "Ferrari"
+                  # =>    :year => 1950
+                  # =>    :engine_power => 335
+                  # => }
 ```
 
-Suppose `multi_form = MultiForm.new` and `default`, `car` to be instances of two models.
+So attributes are mapped as follows:
 
 | Form Object attribute | Model attribute |
 | --------------------- | --------------- |
-| `multi_form.name` | `default.team_name` |
-| `multi_form.year` | `default.year` |
-| `multi_form.engine_power` | `car[:engine].power` |
+| `team.name` | `team_model.team_name` |
+| `team.year` | `team_model.year` |
+| `team.engine_power` | `car_model[:engine].power` |
 
-#### 4.2. Skip Attribute Mapping
+#### 3.3. Do Not Map Certain Attribute
 
-Use `model_attribute: false` in order to avoid attribute mapping to the model.
+Use `model_attribute: false` in order to avoid mapping of this attribute.
 
 ```ruby
-class SimpleForm < FormObj::Form
+class Team < FormObj::Form
   include ModelMapper
   
-   attribute :name, model_attribute: :team_name
+  attribute :name, model_attribute: :team_name
   attribute :year
   attribute :engine_power, model_attribute: false
 end
+
+team_model = Struct.new(:team_name, :year, :engine_power).new('Ferrari', 1950, 335)
+
+team = Team.new.load_from_model(team_model)
+team.to_hash      # => {
+                  # =>    :name => "Ferrari"
+                  # =>    :year => 1950
+                  # =>    :engine_power => nil
+                  # => }
 ```
 
-Suppose `form = SimpleForm.new` and `model` to be an instance of a model.
+So attributes are mapped as follows:
 
 | Form Object attribute | Model attribute |
 | --------------------- | --------------- |
-| `form.name` | `model.team_name` |
-| `form.year` | `model.year` |
+| `form.name` | `team_model.team_name` |
+| `form.year` | `team_model.year` |
 | `form.engine_power` | - |
 
-##### 4.2.1. Map Nested Form Object Attribute to Parent Level Model Attribute
+#### 3.4. Map Nested Form Objects
+
+Nested forms are mapped by default to corresponding nested models.
+
+```ruby
+class Team < FormObj::Form
+  include ModelMapper
+    
+  attribute :name, model_attribute: :team_name
+  attribute :year
+  attribute :car do
+    attribute :code
+    attribute :driver
+  end
+end
 
-TODO: replace `model_attribute` by `model`
-Use `model_attribute: false` for nested form object in order to map its attributes to the parent level of the model.
+car_model = Struct.new(:code, :driver).new('340 F1', 'Ascari')
+team_model = Struct.new(:team_name, :year, :car).new('Ferrari', 1950, car_model)
+
+team = Team.new.load_from_model(team_model)
+team.to_hash      # => {
+                  # =>    :name => "Ferrari",
+                  # =>    :year => 1950,
+                  # =>    :car => {
+                  # =>        :code => "340 F1",
+                  # =>        :driver => "Ascari"   
+                  # =>    }
+                  # => }
+```
+
+So attributes are mapped as follows:
+
+| Form Object attribute | Model attribute |
+| --------------------- | --------------- |
+| `team.name` | `team_model.team_name` |
+| `team.year` | `team_model.year` |
+| `team.car.code` | `team_model.car.code` |
+| `team.car.driver` | `team_model.car.driver` |
+
+Use `model_nesting: false` parameter to map nested form object to map parent level model.
 
 ```ruby
 class NestedForm < FormObj::Form
@@ -511,34 +1039,40 @@ class NestedForm < FormObj::Form
     
   attribute :name, model_attribute: :team_name
   attribute :year
-  attribute :car, model_attribute: false do   # nesting only in form object but not in a model
+  attribute :car, model_nesting: false do   # nesting only in form object but not in a model
     attribute :code
     attribute :driver
-    attribute :engine do
-      attribute :power
-      attribute :volume
-    end
   end
 end
+
+team_model = Struct.new(:team_name, :year, :code, :driver).new('Ferrari', 1950, '340 F1', 'Ascari')
+
+team = Team.new.load_from_model(team_model)
+team.to_hash      # => {
+                  # =>    :name => "Ferrari",
+                  # =>    :year => 1950,
+                  # =>    :car => {
+                  # =>        :code => "340 F1",
+                  # =>        :driver => "Ascari"   
+                  # =>    }
+                  # => }
 ```
 
-Suppose `form = NestedForm.new` and `model` to be an instance of a model.
+So attributes are mapped as follows:
 
 | Form Object attribute | Model attribute |
 | --------------------- | --------------- |
-| `form.name` | `model.team_name` |
-| `form.year` | `model.year` |
-| `form.car.code` | `model.code` |
-| `form.car.driver` | `model.driver` |
-| `form.car.engine.power` | `model.engine.power` |
-| `form.car.engine.volume` | `model.engine.volume` |
+| `team.name` | `team_model.team_name` |
+| `team.year` | `team_model.year` |
+| `team.car.code` | `team_model.code` |
+| `team.car.driver` | `team_model.driver` |
 
-#### 4.3. Map Nested Form Object to A Hash Model
+#### 3.5. Map Nested Form Object to A Hash Model
 
 Use `model_hash: true` in order to map a nested form object to a hash as a model.
 
 ```ruby
-class NestedForm < FormObj::Form
+class Team < FormObj::Form
   include ModelMapper
   
   attribute :name, model_attribute: :team_name
@@ -546,60 +1080,191 @@ class NestedForm < FormObj::Form
   attribute :car, model_hash: true do   # nesting only in form object but not in a model
     attribute :code
     attribute :driver
-    attribute :engine do
-      attribute :power
-      attribute :volume
-    end
   end
 end
+
+car_model = { code: '340 F1', driver: 'Ascari' }
+team_model = Struct.new(:team_name, :year, :car).new('Ferrari', 1950, car_model)
+
+team = Team.new.load_from_model(team_model)
+team.to_hash      # => {
+                  # =>    :name => "Ferrari",
+                  # =>    :year => 1950,
+                  # =>    :car => {
+                  # =>        :code => "340 F1",
+                  # =>        :driver => "Ascari"   
+                  # =>    }
+                  # => }
 ```
 
-Suppose `form = NestedForm.new` and `model` to be an instance of a model.
+So attributes are mapped as follows:
 
 | Form Object attribute | Model attribute |
 | --------------------- | --------------- |
-| `form.name` | `model.team_name` |
-| `form.year` | `model.year` |
-| `form.car.code` | `model.car[:code]` |
-| `form.car.driver` | `model.car[:driver]` |
-| `form.car.engine.power` | `model.car[:engine].power` |
-| `form.car.engine.volume` | `model.car[:engine].volume` |
+| `team.name` | `team_model.team_name` |
+| `team.year` | `team_model.year` |
+| `team.car.code` | `team_model.car[:code]` |
+| `team.car.driver` | `team_model.car[:driver]` |
 
-### 5. Load Form Object from Models
+#### 3.6. Custom Implementation of Loading of Array of Models  
 
-Use `load_from_models(models)` to load form object attributes from mapped models. 
-Method returns self so one can chain calls.
+By default `load_from_model(s)` methods loads all models from arrays.
 
 ```ruby
-class MultiForm < FormObj::Form
+class Team < FormObj::Form
   include ModelMapper
-  
+    
   attribute :name, model_attribute: :team_name
   attribute :year
-  attribute :engine_power, model: :car, model_attribute: ':engine.power'
+  attribute :cars, array: true do
+    attribute :code
+    attribute :driver
+  end
+  attribute :colours, array: true do
+    attribute :name
+    attribute :rgb
+  end
 end
 
-default_model = Struct.new(:team_name, :year).new('Ferrari', 1950)
-car_model = { engine: Struct.new(:power).new(335) }
+CarModel = Struct.new(:code, :driver)
+ColourModel = Struct.new(:name, :rgb)
+
+cars_model = [CarModel.new('340 F1', 'Ascari'), CarModel.new('275 F1', 'Villoresi')]
+colours_model = [ColourModel.new(:red, 0xFF0000), ColourModel.new(:white, 0xFFFFFF)]
+team_model = Struct.new(:team_name, :year, :cars, :colours).new('Ferrari', 1950, cars_model, colours_model)
+
+team = Team.new.load_from_model(team_model)
+team.to_hash      # => {
+                  # =>    :name => "Ferrari",
+                  # =>    :year => 1950,
+                  # =>    :cars => [{
+                  # =>        :code => "340 F1",
+                  # =>        :driver => "Ascari"   
+                  # =>    }, {
+                  # =>        :code => "275 F1",
+                  # =>        :driver => "Villoresi"   
+                  # =>    }],
+                  # =>    :colours => [{
+                  # =>        :name => :red,
+                  # =>        :rgb => 0xFF0000   
+                  # =>    }, {
+                  # =>        :name => :white,
+                  # =>        :rgb => 0xFFFFFF   
+                  # =>    }]
+                  # => }
+```
 
-multi_form = MultiForm.new.load_from_models(default: default_model, car: car_model)
-multi_form.to_hash    # => {
-                      # =>    :name => "Ferrari"
-                      # =>    :year => 1950
-                      # =>    :engine_power => 335
-                      # => }
-``` 
+`FormObj::ModelMapper::Array` class implements method (where `*args` are additional params passed to `load_from_model(s)` methods)
+
+```ruby
+  def iterate_through_models_to_load_them(models, *args, &block)
+    models.each { |model| block.call(model) }
+  end
+```
 
-Use `load_from_models(default: model)` or `load_from_model(model)` to load from single model.
+This method should iterate through all models that has to be loaded and call a block for each of them.
+In the example above it will receive `cars_model` as the value of `models` parameter. 
+Overwrite this method in order to implement your own logic.
 
-### 6. Sync Form Object to Models
+```ruby
+class ArrayLoadLimit < FormObj::ModelMapper::Array
+  private
+  
+  def iterate_through_models_to_load_them(models, params = {}, &block)
+    models = models.slice(params[:offset] || 0, params[:limit] || 999999999) if model_attribute.names.last == :cars
+    super(models, &block)
+  end
+end
+
+class LoadLimitForm < FormObj::Form
+  include FormObj::ModelMapper
+
+  def self.array_class
+    ArrayLoadLimit
+  end
+end
+
+class Team < LoadLimitForm
+  attribute :name, model_attribute: :team_name
+  attribute :year
+  attribute :cars, array: true do
+    attribute :code
+    attribute :driver
+  end
+  attribute :colours, array: true do
+    attribute :name
+    attribute :rgb
+  end
+end
+
+CarModel = Struct.new(:code, :driver)
+ColourModel = Struct.new(:name, :rgb)
+
+cars_model = [CarModel.new('340 F1', 'Ascari'), CarModel.new('275 F1', 'Villoresi')]
+colours_model = [ColourModel.new(:red, 0xFF0000), ColourModel.new(:white, 0xFFFFFF)]
+team_model = Struct.new(:team_name, :year, :cars, :colours).new('Ferrari', 1950, cars_model, colours_model)
+
+team = Team.new.load_from_model(team_model, offset: 0, limit: 1)
+team.to_hash      # => {
+                  # =>    :name => "Ferrari",
+                  # =>    :year => 1950,
+                  # =>    :cars => [{
+                  # =>        :code => "340 F1",
+                  # =>        :driver => "Ascari"   
+                  # =>    }],
+                  # =>    :colours => [{
+                  # =>        :name => :red,
+                  # =>        :rgb => 0xFF0000   
+                  # =>    }, {
+                  # =>        :name => :white,
+                  # =>        :rgb => 0xFFFFFF   
+                  # =>    }] 
+                  # => }
+
+team = Team.new.load_from_model(team_model, offset: 1, limit: 1)
+team.to_hash      # => {
+                  # =>    :name => "Ferrari",
+                  # =>    :year => 1950,
+                  # =>    :cars => [{
+                  # =>        :code => "275 F1",
+                  # =>        :driver => "Villoresi"   
+                  # =>    }],
+                  # =>    :colours => [{
+                  # =>        :name => :red,
+                  # =>        :rgb => 0xFF0000   
+                  # =>    }, {
+                  # =>        :name => :white,
+                  # =>        :rgb => 0xFFFFFF   
+                  # =>    }]
+                  # => }
+```
+
+Note that our new implementation of `iterate_through_models_to_load_them` limits only cars but not colours.
+It identifies requested model attribute using `model_attribute.names` which returns 
+an array of model attribute accessors (in our example `[:cars]`)
+ 
+In case of `ActiveRecord` model `iterate_through_models_to_load_them` will receive an instance of `ActiveRecord::Relation` as `models` parameter.
+This allows to load in the memory only necessary association models.
+
+```ruby
+class ArrayLoadLimit < FormObj::ModelMapper::Array
+  private
+  
+  def iterate_through_models_to_load_them(models, params = {}, &block)
+    models = models.offset(params[:offset] || 0).limit(params[:limit] || 999999999) if model_attribute.names.last == :cars
+    super(models, &block)
+  end
+end
+```
+     
+#### 3.7. Sync Form Object to Models
 
 Use `sync_to_models(models)` to sync form object attributes to mapped models.
 Method returns self so one can chain calls.
 
 ```ruby
 class MultiForm < FormObj::Form
-  include ModelMapper
+  include FormObj::ModelMapper
   
   attribute :name, model_attribute: :team_name
   attribute :year
@@ -627,7 +1292,7 @@ using `<attribute_name>=` accessors on the model(s).
 
 It is completely up to developer to do any additional validations on the model(s) and save it(them).
 
-#### 6.1. Array of Form Objects and Models
+##### 3.7.1. Array of Form Objects and Models
 
 Saving array of form objects to corresponding array of models requires the class of the model to be known by the form object
 because it could create new instances of the model array elements.
@@ -636,7 +1301,7 @@ Form object will try to guess the name of the class from the name of the attribu
 
 ```ruby
 class ArrayForm < FormObj::Form
-  include ModelMapper
+  include FormObj::ModelMapper
   
   attribute :name
   attribute :year
@@ -652,7 +1317,7 @@ nested models the value of `:model_class` parameter should be an array of corres
 
 ```ruby
 class ArrayForm < FormObj::Form
-  include ModelMapper
+  include FormObj::ModelMapper
   
   attribute :name
   attribute :year
@@ -663,13 +1328,13 @@ class ArrayForm < FormObj::Form
 end
 ``` 
 
-### 7. Serialize Form Object to Model Hash
+#### 3.8. Serialize Form Object to Model Hash
 
 Use `to_model_hash(model = :default)` to get hash representation of the model that mapped to the form object.
 
 ```ruby
 class MultiForm < FormObj::Form
-  include ModelMapper
+  include FormObj::ModelMapper
   
   attribute :name, model_attribute: :team_name
   attribute :year
@@ -697,7 +1362,7 @@ If array of form objects mapped to the parent model (`model_attribute: false`) i
 
 ```ruby
 class ArrayForm < FormObj::Form
-  include ModelMapper
+  include FormObj::ModelMapper
   
   attribute :name
   attribute :year
@@ -733,38 +1398,7 @@ array_form.to_model_hash    # => {
                             # => }
 ```
 
-### 8. Validation and Coercion
-
-Form Object is just a Ruby class. By default it includes (could be changed in future releases):
-
-```ruby
-  extend ::ActiveModel::Naming
-  extend ::ActiveModel::Translation
-
-  include ::ActiveModel::Conversion
-  include ::ActiveModel::Validations
-```
-
-So add ActiveModel validations directly to Form Object class definition.
-
-```ruby
-class MultiForm < FormObj::Form
-  include ModelMapper
-  
-  attribute :name, model_attribute: :team_name
-  attribute :year
-  attribute :engine_power, model: :car, model_attribute: ':engine.power'
-  
-  validates :name, :year, presence: true
-end
-```
-
-There is no coercion during assigning/updating form object attributes. 
-Coercion can be done manually by redefining assigning methods `<attribute_name>=`
-or it will happen in the model when the form object will be saved to it. 
-This is the standard way how coercion happens in Rails for example.  
-
-### 9. Copy Model Validation Errors into Form Object
+#### 3.9. Copy Model Validation Errors into Form Object
 
 Even though validation could and should happen in the form object it is possible to have (additional) validation(s) in the model(s).
 In this case it is handy to copy model validation errors to form object in order to be able to present them to the user in a standard way.
@@ -781,7 +1415,7 @@ In case of single model:
 single_form.copy_errors_from_model(model)
 ```
 
-### 10. Rails Example
+### 4. Rails Example
 
 ```ruby
 # db/migrate/yyyymmddhhmiss_create_team.rb
@@ -825,7 +1459,7 @@ end
 ```ruby
 # app/form_objects/team_form.rb
 class TeamForm < FormObj::Form
-  include ModelMapper
+  include FormObj::ModelMapper
   
   attribute :id
   attribute :name, model_attribute: :team_name
@@ -922,18 +1556,20 @@ end
 <% end %>
 ```
 
-### 11. Reference Guide: `attribute` parameters
+### 5. Reference Guide: `attribute` parameters
 
 | Parameter | Condition | Default value | Defined in | Description |
 | --- |:---:|:---:|:---:| --- |
-| array | block* or `:class`** | `false` | `TreeStruct` | This attribute is an array of form objects. The structure of array element form object is described either in the block or in the separate class referenced by `:class` parameter |
-| class | - | - | `TreeStruct` | This attribute is either nested form object or array of form objects. The value of this parameter is the class of this form object or the name of the class. |
+| array | block* or `:class`** | `false` | `FormObj::Struct` | This attribute is an array of form objects. The structure of array element form object is described either in the block or in the separate class referenced by `:class` parameter |
+| class | - | - | `FormObj::Struct` | This attribute is either nested form object or array of form objects. The value of this parameter is the class of this form object or the name of the class. |
+| default | - | - | `FormObj::Struct` | Defines default value for the attribute. Nested structures default value can be defined either with Hash or with object. | 
 | model_hash | block* or `:class`** | `false` | `FormObj::ModelMapper` | This attribute is either nested form object or array of form objects. This form object is mapped to a model of the class `Hash` so all its attributes should be accessed by `[:<attribute_name>]` instead of `.<attribute_name>` | 
 | model | - | `:default` | `FormObj::ModelMapper` | The name of the model to which this attribute is mapped |
-| model_attribute | - | `<attribute_name>` | `FormObj::ModelMapper` | The name of the model attribute to which this form object attribute is mapped. Dot notation is used in order to map to nested model, ex. `"car.engine.power"`. Colon is used in front of the name if the model is hash, ex. `"car.:engine.power"` - means call to `#car` returns `Hash` so the model attribute should be accessed like `car[:engine].power`. `false` value means that attribute is not mapped. If attribute describes nested form object and has `model_attribute: false` the attributes of nested form will be called on the parent (upper level) model. If attribute describes array of form objects and has `model_attribute: false` the methods to access array elements (`:[]` etc.) will be called on the parent (upper level) model. |
+| model_attribute | - | `<attribute_name>` | `FormObj::ModelMapper` | The name of the model attribute to which this form object attribute is mapped. Dot notation is used in order to map to nested model, ex. `"car.engine.power"`. Colon is used in front of the name if the model is hash, ex. `"car.:engine.power"` - means call to `#car` returns `Hash` so the model attribute should be accessed like `car[:engine].power`. `false` value means that attribute is not mapped. |
 | model_class | block* or `:class`** or dot notation for `:model_attribute`*** | `<attribute_name>.classify` | `FormObj::ModelMapper` | The class (or the name of the class) of the mapped model. |
-| primary_key | no block* and no `:class`** | `false` | `FormObj::Form` | This attribute is the primary key of the form object. The mapped model attribute is considered to be a primary key for the corresponding model. |
-| primary_key | block* or `:class`** | - | `FormObj::Form` | This attribute is either nested form object or array of form objects. The value of this parameter is the name of the primary key attribute of this form object. |
+| model_nesting | block* or `:class`** | `true` | `FornObj::ModelMapper` | If attribute describes nested form object and has `model_nesting: false` the attributes of nested form will be called on the parent (upper level) model. If attribute describes array of form objects and has `model_nesting: false` the methods to access array elements (`:[]` etc.) will be called on the parent (upper level) model. | 
+| primary_key | no block* and no `:class`** | `false` | `FormObj::Struct` | This attribute is the primary key of the form object. The mapped model attribute is considered to be a primary key for the corresponding model. |
+| primary_key | block* or `:class`** | - | `FormObj::Struct` | This attribute is either nested form object or array of form objects. The value of this parameter is the name of the primary key attribute of this form object. |
 \* block - means that there is block definition for the attribute
 
 \** `:class` - means that this attribute has `:class` parameter specified