form_obj 0.5.0 → 1.0.0

data/README.md

@@ -15,6 +15,8 @@ ActiveModel: 3.2+
 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.
 
+This gem follows [Semantic Versioning](https://semver.org/).
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -33,8 +35,6 @@ Or install it yourself as:
 
 ## Usage
 
-**WARNING!!!** The gem is still under development. Expect braking changes in `FormObj::ModelMapper` module.<br/>
-
 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.
@@ -62,15 +62,38 @@ model attributes name) and
    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. [Do Not Map Certain Attribute For Reading From Model](#34-do-not-map-certain-attribute-for-reading-from-model)
+   5. [Do Not Map Certain Attribute For Writing to Model](#35-do-not-map-certain-attribute-for-writing-to-model)
+   6. [Map Nested Form Objects](#36-map-nested-form-objects)
+   7. [Map Nested Form Object to Parent Level Model](#37-map-nested-form-object-to-parent-level-model)
+   8. [Map Nested Form Objects to A Hash Model](#38-map-nested-form-object-to-a-hash-model)
+   9. [Map Array of Nested Form Objects](#39-map-array-of-nested-form-objects)
+   10. [Map Array of Nested Form Objects to Nested Array of Nested Models](#310-map-array-of-nested-form-objects-to-nested-array-of-nested-models)
+   11. [Default Implementation of Loading of Array of Models](#311-default-implementation-of-loading-of-array-of-models)
+   12. [Custom Implementation of Loading of Array of Models](#312-custom-implementation-of-loading-of-array-of-models)
+   13. [Sync Form Object to Model(s)](#313-sync-form-object-to-models)
+   14. [Sync Array of Nested Form Objects to Model(s)](#314-sync-array-of-nested-form-objects-to-models)
+   15. [Sync Array of Nested Form Objects to `ActiveRecord`-like Models](#315-sync-array-of-nested-form-objects-to-activerecord-like-models)
+   16. [Customize Sync to Array of Models](#316-customize-sync-to-array-of-models)
+   17. [Model Validation and Persistence](#317-model-validation-and-persistence)
+   18. [Copy Model Validation Errors into Form Object](#318-copy-model-validation-errors-into-form-object)   
+   19. [Serialize Form Object to Model Hash](#319-serialize-form-object-to-model-hash)
 4. [Rails Example](#4-rails-example)
-5. [Reference Guide](#5-reference-guide-attribute-parameters)
+5. [Reference Guide: `attribute`'s paremeters](#5-reference-guide-attributes-parameters)
+   1. [`FormObj::Struct`](#51-formobjstruct)
+      1. [Parameter `array`](#511-parameter-array)
+      2. [Parameter `class`](#512-parameter-class)
+      3. [Parameter `default`](#513-parameter-default)
+      4. [Parameter `primary_key`](#514-parameter-primary_key)
+   2. [`FormObj::Form`](#52-formobjform)
+   3. [`FormObj::Form` with included `FormObj::ModelMapper`](#53-formobjform-with-included-formobjmodelmapper)
+      1. [Parameter `model`](#531-parameter-model)
+      2. [Parameter `model_attribute`](#532-parameter-model_attribute)
+      3. [Parameter `model_class`](#533-parameter-model_class)
+      4. [Parameter `model_hash`](#534-parameter-model_hash)
+      5. [Parameter `model_nesting`](#535-parameter-model_nesting)
+      6. [Parameter `read_from_model`](#536-parameter-read_from_model)
+      7. [Parameter `write_to_model`](#537-parameter-write_to_model)
 
 ### 1. `FormObj::Struct`
 
@@ -320,7 +343,7 @@ class Team < FormObj::Struct
   attribute :car, class: Car, default: 36
 end
 
-Team.new      # => FormObj::WrongDefaultValueClass: FormObj::WrongDefaultValueClass  
+Team.new      # => FormObj::WrongDefaultValueClassError: FormObj::WrongDefaultValueClassError  
 ```
 
 #### 1.2. Array of `FormObj::Struct`
@@ -640,7 +663,7 @@ class Team < FormObj::Struct
   attribute :cars, class: Car, array: true, default: [36]
 end
 
-Team.new      # => FormObj::WrongDefaultValueClass: FormObj::WrongDefaultValueClass  
+Team.new      # => FormObj::WrongDefaultValueClassError: FormObj::WrongDefaultValueClassError  
 ```
 
 #### 1.3. Serialize `FormObj::Struct` to Hash
@@ -801,6 +824,7 @@ team.cars     # => [#< code: 1, driver: "Ascari">]
 
 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.
+New elements with `_destroy: true` are not created at all. 
 
 ```ruby
 class Team < FormObj::Form
@@ -821,7 +845,9 @@ 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.update_attributes(cars: [{code: 1, _destroy: true}, {code: 3, _destroy: true}])
+
+team.cars.size                          # => 2
 
 team.cars[0].code                       # => 2
 team.cars[0].driver                     # => 'James Hunt'
@@ -894,7 +920,8 @@ Use dot notation to map model attribute to a nested model. Use colon to specify
 
 #### 3.1. `load_from_model` - Initialize Form Object from Model
 
-Use `load_from_model(model)` method to initialize form object from the model.
+Use `load_from_model(model)` method to initialize form object from the model. 
+This method available both as class method and as instance method.
 
 ```ruby
 class Team < FormObj::Form
@@ -908,12 +935,14 @@ 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
-                  # => }
+team = Team.load_from_model(team_model)
+team.to_hash                    # => {
+                                # =>    :name => "Ferrari"
+                                # =>    :year => 1950
+                                # =>    :engine_power => 335
+                                # => }
+
+team.load_from_model(team_model) 
 ```
 
 So attributes are mapped as follows:
@@ -924,10 +953,10 @@ So attributes are mapped as follows:
 | `team.year` | `team_model.year` |
 | `team.engine_power` | `team_model.car[:engine].power` |
 
-
 #### 3.2. `load_from_models` - Initialize Form Object from Few Models
 
 Use `load_from_models(models)` method to initialize form object from few models. 
+This method available both as class method and as instance method.
 `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.
@@ -945,12 +974,14 @@ 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
-                  # => }
+team = Team.load_from_models(default: team_model, car: car_model)
+team.to_hash                    # => {
+                                # =>    :name => "Ferrari"
+                                # =>    :year => 1950
+                                # =>    :engine_power => 335
+                                # => }
+
+team.load_from_models(default: team_model, car: car_model) 
 ```
 
 So attributes are mapped as follows:
@@ -976,12 +1007,12 @@ 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
-                  # => }
+team = Team.load_from_model(team_model)
+team.to_hash                    # => {
+                                # =>    :name => "Ferrari"
+                                # =>    :year => 1950
+                                # =>    :engine_power => nil
+                                # => }
 ```
 
 So attributes are mapped as follows:
@@ -992,7 +1023,53 @@ So attributes are mapped as follows:
 | `form.year` | `team_model.year` |
 | `form.engine_power` | - |
 
-#### 3.4. Map Nested Form Objects
+It also works for other methods: `sync_to_model(s)`, `to_model(s)_hash`, `copy_errors_from_model(s)`. 
+
+#### 3.4. Do Not Map Certain Attribute For Reading From Model
+
+Use `read_from_model: false` in order to avoid mapping of the attribute only in `load_from_model(s)` methods.
+
+```ruby
+class Team < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :name
+  attribute :year, read_from_model: false
+end
+
+team_model = Struct.new(:name, :year).new('Ferrari', 1950)
+team = Team.new(name: 'McLaren', year: 1966)
+
+team.load_from_model(team_model)
+
+team.name                       # => "Ferrari"
+team.year                       # => 1966
+```
+
+#### 3.5. Do Not Map Certain Attribute For Writing to Model
+
+Use `write_to_model: false` in order to avoid mapping of the attribute only in `sync_to_model(s)`, `to_model(s)_hash`, `copy_errors_from_model(s)` methods.
+
+```ruby
+class Team < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :name
+  attribute :year, write_to_model: false
+end
+
+team_model = Struct.new(:name, :year).new('Ferrari', 1950)
+team = Team.new(name: 'McLaren', year: 1966)
+
+team.sync_to_model(team_model)
+
+team_model.name                 # => "McLaren"
+team_model.year                 # => 1950
+
+team.to_model_hash              # => {:name => "McLaren"}
+```
+
+#### 3.6. Map Nested Form Objects
 
 Nested forms are mapped by default to corresponding nested models.
 
@@ -1011,15 +1088,15 @@ end
 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"   
-                  # =>    }
-                  # => }
+team = Team.load_from_model(team_model)
+team.to_hash                    # => {
+                                # =>    :name => "Ferrari",
+                                # =>    :year => 1950,
+                                # =>    :car => {
+                                # =>        :code => "340 F1",
+                                # =>        :driver => "Ascari"   
+                                # =>    }
+                                # => }
 ```
 
 So attributes are mapped as follows:
@@ -1031,7 +1108,11 @@ So attributes are mapped as follows:
 | `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.
+It also works for other methods: `sync_to_model(s)` and `to_model(s)_hash` 
+
+#### 3.7. Map Nested Form Object to Parent Level Model
+
+Use `model_nesting: false` parameter to map nested form object to parent level model.
 
 ```ruby
 class NestedForm < FormObj::Form
@@ -1047,15 +1128,15 @@ 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"   
-                  # =>    }
-                  # => }
+team = Team.load_from_model(team_model)
+team.to_hash                    # => {
+                                # =>    :name => "Ferrari",
+                                # =>    :year => 1950,
+                                # =>    :car => {
+                                # =>        :code => "340 F1",
+                                # =>        :driver => "Ascari"   
+                                # =>    }
+                                # => }
 ```
 
 So attributes are mapped as follows:
@@ -1067,7 +1148,9 @@ So attributes are mapped as follows:
 | `team.car.code` | `team_model.code` |
 | `team.car.driver` | `team_model.driver` |
 
-#### 3.5. Map Nested Form Object to A Hash Model
+It also works for other methods: `sync_to_model(s)` and `to_model(s)_hash` 
+
+#### 3.8. 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.
 
@@ -1086,15 +1169,15 @@ 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"   
-                  # =>    }
-                  # => }
+team = Team.load_from_model(team_model)
+team.to_hash                    # => {
+                                # =>    :name => "Ferrari",
+                                # =>    :year => 1950,
+                                # =>    :car => {
+                                # =>        :code => "340 F1",
+                                # =>        :driver => "Ascari"   
+                                # =>    }
+                                # => }
 ```
 
 So attributes are mapped as follows:
@@ -1106,7 +1189,44 @@ So attributes are mapped as follows:
 | `team.car.code` | `team_model.car[:code]` |
 | `team.car.driver` | `team_model.car[:driver]` |
 
-#### 3.6. Custom Implementation of Loading of Array of Models  
+It also works for other methods: `sync_to_model(s)` and `to_model(s)_hash` 
+
+#### 3.9. Map Array of Nested Form Objects
+
+Array of nested forms is mapped by default to corresponding array (or for example to `ActiveRecord::Relation` in case of Rails) of nested models.
+
+```ruby
+class Team < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :name
+  attribute :year
+  attribute :cars, array: true, model_class: CarModel do
+    attribute :code, primary_key: true
+    attribute :driver
+  end
+end
+``` 
+
+#### 3.10. Map Array of Nested Form Objects to Nested Array of Nested Models
+
+If corresponding `:model_attribute` parameter uses dot notations to reference
+nested models the value of `:model_class` parameter should be an array of corresponding model classes.
+
+```ruby
+class ArrayForm < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :name
+  attribute :year
+  attribute :cars, array: true, model_attribute: 'equipment.cars', model_class: [Equipment, CarModel] do
+    attribute :code, primary_key: true
+    attribute :driver
+  end
+end
+``` 
+
+#### 3.11. Default Implementation of Loading of Array of Models 
 
 By default `load_from_model(s)` methods loads all models from arrays.
 
@@ -1133,27 +1253,29 @@ cars_model = [CarModel.new('340 F1', 'Ascari'), CarModel.new('275 F1', 'Villores
 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   
-                  # =>    }]
-                  # => }
+team = Team.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   
+                                # =>    }]
+                                # => }
 ```
 
+#### 3.12. Custom Implementation of Loading of Array of Models  
+
 `FormObj::ModelMapper::Array` class implements method (where `*args` are additional params passed to `load_from_model(s)` methods)
 
 ```ruby
@@ -1204,39 +1326,39 @@ cars_model = [CarModel.new('340 F1', 'Ascari'), CarModel.new('275 F1', 'Villores
 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   
-                  # =>    }]
-                  # => }
+team = Team.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.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.
@@ -1244,7 +1366,7 @@ It identifies requested model attribute using `model_attribute.names` which retu
 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.
+This allows to load in the memory only necessary associated models.
 
 ```ruby
 class ArrayLoadLimit < FormObj::ModelMapper::Array
@@ -1257,13 +1379,13 @@ class ArrayLoadLimit < FormObj::ModelMapper::Array
 end
 ```
      
-#### 3.7. Sync Form Object to Models
+#### 3.13. Sync Form Object to Model(s)
 
 Use `sync_to_models(models)` to sync form object attributes to mapped models.
-Method returns self so one can chain calls.
+Method returns self so calls could be chained.
 
 ```ruby
-class MultiForm < FormObj::Form
+class Team < FormObj::Form
   include FormObj::ModelMapper
   
   attribute :name, model_attribute: :team_name
@@ -1274,66 +1396,196 @@ end
 default_model = Struct.new(:team_name, :year).new('Ferrari', 1950)
 car_model = { engine: Struct.new(:power).new(335) }
 
-multi_form = MultiForm.new
-multi_form.update_attributes(name: 'McLaren', year: 1966, engine_power: 415)
-multi_form.sync_to_models(default: default_model, car: car_model)
+team = Team.new
+team.update_attributes(name: 'McLaren', year: 1966, engine_power: 415)
+team.sync_to_models(default: default_model, car: car_model)
 
-default_model.name          # => "McLaren"
-default_model.year          # => 1966
-car_model[:engine].power    # => 415 
+default_model.team_name         # => "McLaren"
+default_model.year              # => 1966
+car_model[:engine].power        # => 415 
 ``` 
 
-Use `sync_to_models(default: model)` or `sync_to_model(model)` to sync to single model.
+Use `sync_to_model(model)` if form object is mapped to single model.
 
-Neither `sync_to_models` nor `sync_to_model` calls `save` method on the model(s).
-Also they don't call `valid?` method on the model(s). 
-Instead they just assign form object attributes value to mapped model attributes
-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).
+#### 3.14. Sync Array of Nested Form Objects to Model(s)
 
-##### 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.
-Use `:model_class` parameter to specify it. 
-Form object will try to guess the name of the class from the name of the attribute if this parameter is absent.
+By default `FormObj::Form` with included `FormObj::ModelMapper` will try to match Form Objects and Models by primary key.
+Therefore Form Object primary key attribute has to be mapped to top level Model attribute.
 
 ```ruby
-class ArrayForm < FormObj::Form
+TeamModel = Struct.new(:cars)
+CarModel = Struct.new(:code, :driver)
+
+class Team < FormObj::Form
   include FormObj::ModelMapper
   
-  attribute :name
-  attribute :year
-  attribute :cars, array: true, model_class: Car do
-    attribute :code, primary_key: true     # <- primary key is specified on attribute level
+  attribute :cars, array: true, model_class: CarModel do
+    attribute :code, primary_key: true
     attribute :driver
   end
 end
-``` 
+```
 
-If corresponding `:model_attribute` parameter uses dot notations to reference
-nested models the value of `:model_class` parameter should be an array of corresponding model classes.
+Attributes of successfully matched models will be updated from corresponding form objects. 
 
 ```ruby
-class ArrayForm < FormObj::Form
+team_model = TeamModel.new([CarModel.new('275 F1', 'Ascari')])
+team = Team.new(cars: [{ code: '275 F1', driver: 'Villoresi' }])
+
+team_model.cars                     # => [#<struct CarModel code="275 F1", driver="Ascari">]
+team.sync_to_model(team_model)  
+team_model.cars                     # => [#<struct CarModel code="275 F1", driver="Villoresi">]
+```
+
+New models will be created for form object that doesn't have corresponding models. 
+In order to create a new model the model class has to be known.
+It can be specified by `:model_class` parameter. 
+Otherwise form object will try to guess it from the attribute name.
+
+```ruby
+team_model = TeamModel.new([])
+team = Team.new(cars: [{ code: '275 F1', driver: 'Villoresi' }])
+
+team_model.cars                     # => []
+team.sync_to_model(team_model)  
+team_model.cars                     # => [#<struct CarModel code="275 F1", driver="Villoresi">]
+```
+
+Models that does not have corresponding objects will stay without changes.
+
+```ruby
+team_model = TeamModel.new([CarModel.new('275 F1', 'Ascari')])
+team = Team.new(cars: [{ code: '275 F1', driver: 'Villoresi' }, { code: '340 F1', driver: 'Hunt' }])
+
+team_model.cars                     # => [#<struct CarModel code="275 F1", driver="Ascari">]
+team.sync_to_model(team_model)  
+team_model.cars                     # => [#<struct CarModel code="275 F1", driver="Villoresi">, #<struct CarModel code="340 F1", driver="Hunt">]
+```
+
+If array does not respond to `:where` models that correspond to form objects marked for destruction will be destroyed.
+
+```ruby
+team_model = TeamModel.new([CarModel.new('275 F1', 'Ascari')])
+team = Team.load_from_model(team_model)                           # => #<Team cars: [#< code: "275 F1", driver: nil>]>
+team.update_attributes(cars: [{ code: '275 F1', _destroy: true }])    # => #<Team cars: [#< code: "275 F1", driver: nil marked_for_destruction>]>
+
+team_model.cars                                                       # => [#<struct CarModel code="275 F1", driver="Ascari">]
+team.sync_to_model(team_model)  
+team_model.cars                                                       # => []
+```
+
+#### 3.15. Sync Array of Nested Form Objects to `ActiveRecord`-like Models
+
+if array respond to `:where` (aka `ActiveRecord`) models that correspond to form objects marked for destruction will be also marked for destruction.
+
+```ruby
+class TeamModel < ApplicationRecord
+  has_many :cars
+end
+
+class Team < FormObj::Form
   include FormObj::ModelMapper
   
-  attribute :name
-  attribute :year
-  attribute :cars, array: true, model_attribute: 'equipment.cars', model_class: [Equipment, Car] do
-    attribute :code, primary_key: true     # <- primary key is specified on attribute level
+  attribute :cars, array: true, model_class: CarModel do
+    attribute :id
+    attribute :code
     attribute :driver
   end
 end
+
+team_model = TeamModel.find(1)
+team_model.cars                                   # => #<ActiveRecord::Associations::CollectionProxy [#<Car id: 1, code: "275 F1", driver: "Ascari">]>
+team_model.cars.first.marked_for_destruction?     # => false
+
+team = Team.load_from_model(team_model).update_attributes(cars: [{ id: 1, _destroy: true }])
+team.sync_to_model(team_model)
+
+team_model.cars                                   # => #<ActiveRecord::Associations::CollectionProxy [#<Car id: 1, code: "275 F1", driver: "Ascari">]>
+team_model.cars.first.marked_for_destruction?     # => true
+```
+
+#### 3.16. Customize Sync to Array of Models
+
+`FormObj::ModelMapper::Array` has private methods: `sync_creation_to_models`, `sync_update_to_models`, `sync_destruction_to_models`.
+They are called during syncing process and could be overwritten. 
+The new descendant of `FormObj::ModelMapper::Array` class has to be returned from `array_class` class method.
+As well as the `FormObj::Form` descendant class itself has to be returned from `nested_class` class method.
+
+```ruby
+  class MyForm < FormObj::Form
+    class Array < FormObj::ModelMapper::Array
+      private
+
+      def sync_destruction_to_models(models, ids_to_destroy)
+        if models[:default].respond_to? :where
+          models[:default].where(model_primary_key.name => ids_to_destroy).each { |model| puts "Mark for deletion model #{model}" }
+        else
+          models[:default].select { |model| ids_to_destroy.include? model_primary_key.read_from_model(model) }.each { |model| puts "Delete model #{model}" }
+        end
+        super
+      end
+
+      def sync_update_to_models(models, items_to_update)
+        items_to_update.each_pair do |model, form_object|
+          puts "Update model #{model} with #{form_object.to_model_hash}"
+        end
+        super
+      end
+
+      def sync_creation_to_models(models, form_objects_to_create)
+        form_objects_to_create.each do |form_object|
+          puts "Create model from #{form_object.to_model_hash}"
+        end
+        super
+      end
+    end
+
+    include FormObj::ModelMapper
+
+    def self.array_class
+      Array
+    end
+
+    def self.nested_class
+      MyForm
+    end
+  end
+```
+
+#### 3.17. Model Validation and Persistence
+
+`sync_to_model(s)` do not call `save` method on the model(s).
+Also they don't call `valid?` method on the model(s). 
+Instead they just assign form object attributes value to mapped model attributes
+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).
+
+#### 3.18. 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.
+
+Use `copy_errors_from_models(models)` or `copy_errors_from_model(model)` in order to do it.
+Methods return self so one can chain calls.
+
+```ruby
+team.copy_errors_from_models(default: default_model, car: car_model)
 ``` 
 
-#### 3.8. Serialize Form Object to Model Hash
+In case of single model:
+```ruby
+team.copy_errors_from_model(model)
+```
+
+For the moment `copy_errors_from_model(s)` do not support nested form object/model and array of nested form objects/models. 
+
+#### 3.19. 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
+class Team < FormObj::Form
   include FormObj::ModelMapper
   
   attribute :name, model_attribute: :team_name
@@ -1341,39 +1593,37 @@ class MultiForm < FormObj::Form
   attribute :engine_power, model: :car, model_attribute: ':engine.power'
 end
 
-multi_form = MultiForm.new
-multi_form.update_attributes(name: 'McLaren', year: 1966, engine_power: 415)
+team = Team.new(name: 'McLaren', year: 1966, engine_power: 415)
 
-multi_form.to_model_hash              # => { :team_name => "McLaren", :year => 1966 }
-multi_form.to_model_hash(:default)    # => { :team_name => "McLaren", :year => 1966 }
-multi_form.to_model_hash(:car)        # => { :engine => { :power => 415 } }
+team.to_model_hash              # => { :team_name => "McLaren", :year => 1966 }
+team.to_model_hash(:default)    # => { :team_name => "McLaren", :year => 1966 }
+team.to_model_hash(:car)        # => { :engine => { :power => 415 } }
 ``` 
 
 Use `to_models_hash()` to get hash representation of all models that mapped to the form object.
 
 ```ruby
-multi_form.to_models_hash             # => {
-                                      # =>   default: { :team_name => "McLaren", :year => 1966 }
-                                      # =>   car: { :engine => { :power => 415 } }
-                                      # => } 
+team.to_models_hash             # => {
+                                # =>   default: { :team_name => "McLaren", :year => 1966 }
+                                # =>   car: { :engine => { :power => 415 } }
+                                # => } 
 ``` 
 
-If array of form objects mapped to the parent model (`model_attribute: false`) it is serialized to `:self` key.
+If array of form objects mapped to the parent model (`model_nesting: false`) it is serialized to `:self` key.
 
 ```ruby
-class ArrayForm < FormObj::Form
+class Team < FormObj::Form
   include FormObj::ModelMapper
   
   attribute :name
   attribute :year
-  attribute :cars, array: true, model_attribute: false do
+  attribute :cars, array: true, model_nesting: false do
     attribute :code, primary_key: true
     attribute :driver
   end
 end
 
-array_form = ArrayForm.new
-array_form.update_attributes(
+team = Team.new(
     name: 'McLaren', 
     year: 1966, 
     cars: [{
@@ -1385,34 +1635,17 @@ array_form.update_attributes(
     }]
 )
 
-array_form.to_model_hash    # => { 
-                            # =>    :team_name => "McLaren", 
-                            # =>    :year => 1966,
-                            # =>    :self => {
-                            # =>      :code => "M2B",
-                            # =>      :driver => "Bruce McLaren"
-                            # =>    }, {    
-                            # =>      :code => "M7A",
-                            # =>      :driver => "Denis Hulme"
-                            # =>    }  
-                            # => }
-```
-
-#### 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.
-
-Use `copy_errors_from_models(models)` or `copy_errors_from_model(model)` in order to do it.
-Methods return self so one can chain calls.
-
-```ruby
-multi_form.copy_errors_from_models(default: default_model, car: car_model)
-``` 
-
-In case of single model:
-```ruby
-single_form.copy_errors_from_model(model)
+team.to_model_hash    # => { 
+                      # =>    :team_name => "McLaren", 
+                      # =>    :year => 1966,
+                      # =>    :self => {
+                      # =>      :code => "M2B",
+                      # =>      :driver => "Bruce McLaren"
+                      # =>    }, {    
+                      # =>      :code => "M7A",
+                      # =>      :driver => "Denis Hulme"
+                      # =>    }  
+                      # => }
 ```
 
 ### 4. Rails Example
@@ -1556,29 +1789,351 @@ end
 <% end %>
 ```
 
-### 5. Reference Guide: `attribute` parameters
+### 5. Reference Guide: `attribute`'s parameters
+
+#### 5.1 `FormObj::Struct`
+
+##### 5.1.1. Parameter `array`
+
+*Default value:* `false` 
+
+Specifies attribute as an array of nested `FormObj::Struct`. 
+The attribute shuld have either a block which describes the structure of array item 
+or `class` parameter which refers to another `FormObj::Struct` which describes the structure of array item.
+
+```ruby
+class Team < FormObj::Struct
+  attribute :cars, array: true do
+    attribute :id
+    attribute :driver
+  end
+end
+```
+
+##### 5.1.2. Parameter `class`
+
+Specifies the class of nested `FormObj::Struct`. Cannot be used if there is block definition of nested structure.
+Could be either class constant itself or the name of the class.
+
+```ruby
+class Car < FormObj::Struct
+    attribute :id
+    attribute :driver
+end
+class Team < FormObj::Struct
+  attribute :cars, array: true, class: Car
+end
+```
+
+##### 5.1.3. Parameter `default`
+
+Specifies the default value of an attribute. 
+For nested `FormObj::Struct` could be specified either by its instance or by its hash representation.
+
+```ruby
+class Team < FormObj::Struct
+  attribute :name, default: 'Ferrari'
+  attribute :cars, array: true, default: [{ id: 1, driver: 'Ascari' }] do
+    attribute :id
+    attribute :driver
+  end
+end
+```
+
+or 
+
+```ruby
+class Car < FormObj::Struct
+  attribute :id
+  attribute :driver
+end
+class Team < FormObj::Struct
+  attribute :name, default: 'Ferrari'
+  attribute :cars, array: true, class: 'Car', default: [Car.new(id: 1, driver: 'Ascari')]
+end
+```
+
+##### 5.1.4. Parameter `primary_key`
+
+*Default value:* `:id`
+
+Specifies the primary key of nested `FormObj::Struct` for the array attribute. 
+Could be specified either on the primary key attribute itself (`primary_key: true`)
+
+```ruby
+class Team < FormObj::Struct
+  attribute :cars, array: true do
+    attribute :code, primary_key: true
+    attribute :driver
+  end
+end
+```
+
+or on the array attribute. 
+In latter case the value of the parameter should the name of the primary key attribute (e.g. `primary_key: :team_name`).
+
+```ruby
+class Team < FormObj::Struct
+  attribute :cars, array: true, primary_key: :code do
+    attribute :code
+    attribute :driver
+  end
+end
+```
+ 
+If both ways are mixed, than parameter specified on the array attribute will take precedence.
+
+Composite primary key is not supported.
+
+#### 5.2. `FormObj::Form`
+
+All `FormObj::Struct` parameters can be used with `FormObj::Form`
+
+#### 5.3. `FormObj::Form` with included `FormObj::ModelMapper`
+
+All `FormObj::Form` parameters can be together with following.
+
+##### 5.3.1. Parameter `model`
+
+*Default value:* `:default`
+
+Specifies the name of the model which this attribute is mapped on to. 
+By default each attribute is mapped on to the `:default` model.
+
+```ruby
+class TeamForm < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :name
+  attribute :engine, model: :car 
+end
+
+Car = Struct.new(:engine)
+Team = Struct.new(:name) 
+
+team = Team.new('McLaren')
+car = Car.new('Ford')
+
+team.name                                     # => "McLaren"
+car.engine                                    # => "Ford"
+team_form = TeamForm.load_from_models(default: team, car: car)
+team_form.name                                # => "McLaren"
+team_form.engine                              # => "Ford"
+```
+
+##### 5.3.2. Parameter `model_attribute`
+
+*Default value:* `<attribute name>`
+
+Specifies the name of the model attribute which this attribute is mapped on.
+It supports dot-notation for mapping on the nested model attribute.
+
+```ruby
+class TeamForm < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :car_power, model_attribute: 'car.engine_power' 
+end
+
+Car = Struct.new(:engine_power)
+Team = Struct.new(:car) 
+
+team = Team.new(Car.new(350))
+team.car.engine_power                         # => 350
+team_form = TeamForm.load_from_model(team)
+team_form.car_power                           # => 350
+```
+
+Colon has to be used in front of corresponding `model_attribute` element if the nested model is a hash.
+
+```ruby
+class TeamForm < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :car_power, model_attribute: 'car.:engine_power' 
+end
+
+Team = Struct.new(:car) 
+
+team = Team.new(engine_power: 350)
+team.car[:engine_power]                       # => 350
+team_form = TeamForm.load_from_model(team)
+team_form.car_power                           # => 350
+```
+
+##### 5.3.3. Parameter `model_class`
+
+*Default value:* `<attribute name>.to_s.classify`
+
+This parameter can be used only for nested form objects.
+Specifies the class of the model which the nested form object is mapped on.
+  
+```ruby
+class TeamForm < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :name
+  attribute :engine, model: :car 
+end
+
+Car = Struct.new(:engine)
+Team = Struct.new(:name) 
+
+team = Team.new('McLaren')
+car = Car.new('Ford')
+team.name                                     # => "McLaren"
+car.engine                                    # => "Ford"
+team_form = TeamForm.load_from_models(default: team, car: car)
+team_form.name                                # => "McLaren"
+team_form.engine                              # => "Ford"
+```
+
+##### 5.3.4. Parameter `model_hash`
+
+*Default value:* `false`
+
+If nested model is hash it could be specified by means of this parameter.
+
+```ruby
+class TeamForm < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :car, model_hash: true do
+    attribute :power
+  end   
+end
+
+Team = Struct.new(:car) 
+
+team = Team.new(power: 350)
+team.car[:power]                              # => 350
+team_form = TeamForm.load_from_model(team)
+team_form.car.power                           # => 350
+```
+
+The same result could be achieved by using `:`-notation in `model_attribute` parameter.
+
+```ruby
+class TeamForm < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :car do
+    attribute :power, model_attribute: ':power'
+  end 
+end
+
+Team = Struct.new(:car) 
+
+team = Team.new(power: 350)
+team.car[:power]                              # => 350
+team_form = TeamForm.load_from_model(team)
+team_form.car.power                           # => 350
+```
+
+##### 5.3.5. Parameter `model_nesting`
+
+*Default value:* `true`
+
+This parameter can be used only for nested form objects.
+By default nested form object is mapped to nested model. 
+If this parameter has value `false` the nested form object will be mapped to the same model as the parent form object is.
+
+```ruby
+class TeamForm < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :car, model_nesting: false do
+    attribute :power
+  end   
+end
+
+Team = Struct.new(:power) 
+
+team = Team.new(350)
+team.power                                    # => 350
+team_form = TeamForm.load_from_model(team)
+team_form.car.power                           # => 350
+```
+
+Compare with example where `model_nesting: true`.
+
+```ruby
+class TeamForm < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :car, model_nesting: true do
+    attribute :power
+  end   
+end
+
+Car = Struct.new(:power)
+Team = Struct.new(:car) 
+
+team = Team.new(Car.new(350))
+team.car.power                                # => 350
+team_form = TeamForm.load_from_model(team)
+team_form.car.power                           # => 350
+```
+
+`model_nesting: true` can be omitted since it is its default value.
 
-| Parameter | Condition | Default value | Defined in | Description |
-| --- |:---:|:---:|:---:| --- |
-| 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. |
-| 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. |
-| 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
+##### 5.3.6. Parameter `read_from_model`
 
-\** `:class` - means that this attribute has `:class` parameter specified
+*Default value:* `true`
 
-\*** dot notation for `:model_attribute` - means that this attribute is mapped to nested model attribute (using dot notation)
+`false` value of this parameter prevents from reading attribute value from the model in
+`load_from_model(s)` methods.
+
+```ruby
+class TeamForm < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :name
+  attribute :year, read_from_model: false
+end
+
+Team = Struct.new(:name, :year)
+
+team = Team.new('Ferrari', 1950)
+team_form = TeamForm.new(name: 'McLaren', year: 1966)
+
+team_form.load_from_model(team)
+team_form.name                                # => "Ferrari"
+team_form.year                                # => 1966 
+```
+
+##### 5.3.7. Parameter `write_to_model`
+
+*Default value:* `true`
+
+`false` value of this parameter 
+- will prevent from writing attribute value to the model in `sync_to_model(s)` methods, 
+- attribute will not be present in the hash generated by `to_model(s)_hash` methods, 
+- attribute errors will not be copied from the model by `copy_errors_from_model(s)` methods.
+
+```ruby
+class TeamForm < FormObj::Form
+  include FormObj::ModelMapper
+  
+  attribute :name
+  attribute :year, write_to_model: false
+end
+
+Team = Struct.new(:name, :year)
+
+team = Team.new('Ferrari', 1950)
+team_form = TeamForm.new(name: 'McLaren', year: 1966)
+
+team_form.sync_to_model(team)
+team.name                                     # => "McLaren"
+team.year                                     # => 1950
+
+team_form.to_model_hash                       # => {:name=>"McLaren"} 
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).