reform 1.2.6 → 2.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ad4504340052787a18f70b1249517dfd7ccc443
-  data.tar.gz: 7bae41c59ff9cc4b242a0eb0855f7fa382c2e4ac
+  metadata.gz: 719c0d3aec98a161756c38012b620944cf19fa22
+  data.tar.gz: f7adb9cb663ea890809b3606a3ab01376fe4453d
 SHA512:
-  metadata.gz: b11cfe1184db4d697a87397acaaa2791ff8c8bdffd89682116aa17e6b91d51c0c5b3de44c4e923266fcf8db9cc994c72c49312210c092d8c54e0bf0d62301e2d
-  data.tar.gz: 42823db698bc87293a992987df02305ce8069459e707847cafb686c5477798a79a9f1b61c27825d8e5bb254bb6e58b005830b481ab64855312b5999d60e5d7c9
+  metadata.gz: 78d3c8711d9a337ca128e6e0cf14ebfe4df94230c4e1180110bd419ef7d4d0951be2a5f3823be807e2daf68f483a02f149e8bea212bfcac7d59613a115fbabc3
+  data.tar.gz: 9434d975625b3719bcd47a1a31da9be8feda733c3af43a78237fdbe1fa5e90805cefb88e9e707ec4c9f050a2615a1626ae345477076d1b235c9107f9c388f8cd

data/.travis.yml

@@ -1,6 +1,7 @@
 language: ruby
 rvm:
-  - 2.1.4
+  - 2.2.0
+  - 2.1.5
   - 2.0.0
   - 1.9.3
 gemfile:
@@ -8,3 +9,7 @@ gemfile:
   - gemfiles/Gemfile.rails-3.2
   - gemfiles/Gemfile.rails-3.1
   - gemfiles/Gemfile.rails-3.0
+matrix:
+  fast_finish: true
+  allow_failures:
+    - rvm: ruby-head

data/CHANGES.md

@@ -1,3 +1,17 @@
+## 2.0.0
+
+* The `::reform_2_0!` is no longer there. Guess why.
+* :populator => lambda { |fragment, index, args|
+#           songs[index] or songs[index] = args.binding[:form].new(Song.new)
+#         }
+is now :populator => lambda { |fragment, index, args|
+#           songs[index] or songs.insert(index) = Song.new
+#         }
+you don't need to know about forms anymore, the twin handles that using #insert.
+
+* `:as` option removed. Use `:from`.
+* With `Composition` included, `Form#model` would give you a composition object. You can grab that using `Form#mapper` now.
+
 ## 1.2.6
 
 * Added `:prepopulate` to fill out form properties for presentation. Note that you need to call `Form#prepopulate!` to trigger the prepopulation.

data/Gemfile

@@ -2,5 +2,6 @@ source 'https://rubygems.org'
 
 gemspec
 
-# gem 'representable', path: "../representable"
-# gem "disposable", path: "../disposable"
+#gem 'representable', path: "../representable"
+gem "disposable", path: "../disposable"
+# gem "disposable", github: "apotonick/disposable"

data/README.md

@@ -1,73 +1,34 @@
 # Reform
 
-Decouple your models from forms. Reform gives you a form object with validations and nested setup of models. It is completely framework-agnostic and doesn't care about your database.
+_Form objects decoupled from your models._
 
-Although reform can be used in any Ruby framework, it comes with [Rails support](#rails-integration), works with [simple_form and other form gems](#formbuilder-support), allows nesting forms to implement [has_one](#nesting-forms-1-1-relations) and [has_many](#nesting-forms-1-n-relations) relationships, can [compose a form](#compositions) from multiple objects and gives you [coercion](#coercion).
-
-<a href="https://leanpub.com/trailblazer">
-![](https://raw.githubusercontent.com/apotonick/trailblazer/master/doc/trb.jpg)
-</a>
-
-Reform is part of the [Trailblazer project](https://github.com/apotonick/trailblazer). Please [buy my book](https://leanpub.com/trailblazer) to support the development and learn everything about Reform. Currently the book discusses:
-
-* Form objects, the DSL and basic API (chapter 2 and 3)
-* Basic validations and rendering forms (chapter 3)
-* Nested forms, prepopulating and validation populating and pre-selecting values (chapter 5)
+Reform gives you a form object with validations and nested setup of models. It is completely framework-agnostic and doesn't care about your database.
 
-More chapters are coming!
+Although reform can be used in any Ruby framework, it comes with [Rails support](#rails-integration), works with [simple_form and other form gems](#formbuilder-support), allows nesting forms to implement [has_one](#nesting-forms-1-1-relations) and [has_many](#nesting-forms-1-n-relations) relationships, can [compose a form](#compositions) from multiple objects and gives you [coercion](#coercion).
 
+## This is not Reform 1.x!
 
-## Installation
+Temporary note: This is the README and API for Reform 2. On the public API, only a few tiny things have changed. When in trouble, join us on the IRC (Freenode) #trailblazer channel.
 
-Add this line to your Gemfile:
 
-```ruby
-gem 'reform'
-```
+## Disposable
 
-## Nomenclature
-
-Reform comes with two base classes.
-
-* `Form` is what made you come here - it gives you a form class to handle all validations, wrap models, allow rendering with Rails form helpers, simplifies saving of models, and more.
-* `Contract` gives you a sub-set of `Form`: [this class](#contracts) is meant for API validation where already populated models get validated without having to maintain validations in the model classes.
+Every form in Reform is a _twin_. Twins are non-persistent domain objects from the [Disposable gem](https://github.com/apotonick/disposable). All features of Disposable, like renaming fields, change tracking, etc. are available in Reform, too.
 
 
 ## Defining Forms
 
-You're working at a famous record label and your job is archiving all the songs, albums and artists. You start with a form to populate your `songs` table.
+Forms are defined in separate classes. Often, these classes partially map to a model.
 
 ```ruby
-class SongForm < Reform::Form
+class AlbumForm < Reform::Form
   property :title
-  property :length
-
   validates :title, presence: true
-  validates :length, numericality: true
 end
 ```
 
-Define your form's fields using `::property`. Validations no longer go into the model, but into the form.
+Fields are declared using `::property`. Validations work exactly as you know it from Rails or other frameworks. Note that validations no longer got into the model.
 
-Luckily, this can be shortened as follows.
-
-```ruby
-class SongForm < Reform::Form
-  property :title, validates: {presence: true}
-  property :length, validates: {numericality: true}
-end
-```
-
-Use `properties` to bulk-specify fields.
-
-```ruby
-class SongForm < Reform::Form
-  properties :title, :length, validates: {presence: true} # both required!
-  validates :length, numericality: true
-end
-```
-
-After explicitely defining your fields, you're ready to use the form.
 
 ## The API
 
@@ -75,50 +36,34 @@ Forms have a ridiculously simple API with only a handful of public methods.
 
 1. `#initialize` always requires a model that the form represents.
 2. `#validate(params)` updates the form's fields with the input data (only the form, _not_ the model) and then runs all validations. The return value is the boolean result of the validations.
-3. `#errors` returns validation messages in a classy ActiveModel style.
+3. `#errors` returns validation messages in a classic ActiveModel style.
 4. `#sync` writes form data back to the model. This will only use setter methods on the model(s).
 5. `#save` (optional) will call `#save` on the model and nested models. Note that this implies a `#sync` call.
+6. `#present!` (optional) will run pre-population hooks to "fill out" your form before rendering.
 
 In addition to the main API, forms expose accessors to the defined properties. This is used for rendering or manual operations.
 
 
 ## Setup
 
-In your controller you'd create a form instance and pass in the models you want to work on.
+In your controller or operation you create a form instance and pass in the models you want to work on.
 
 ```ruby
-class SongsController
+class AlbumsController
   def new
-    @form = SongForm.new(Song.new)
-  end
-```
-
-You can also setup the form for editing existing items.
-
-```ruby
-class SongsController
-  def edit
-    @form = SongForm.new(Song.find(1))
+    @form = AlbumForm.new(Album.new)
   end
 ```
 
-Reform will read property values from the model in setup. Given the following form class.
+This will also work as an editing form with an existing album.
 
 ```ruby
-class SongForm < Reform::Form
-  property :title
-```
-
-Internally, this form will call `song.title` to populate the title field.
-
-If you, for whatever reasons, want to use a different public name, use `:from`.
-
-```ruby
-class SongForm < Reform::Form
-  property :name, from: :title
+def edit
+  @form = AlbumForm.new(Album.find(1))
+end
 ```
 
-This will still call `song.title` but expose the attribute as `name`.
+Reform will read property values from the model in setup. In our example, the `AlbumForm` will call `album.title` to populate the `title` field.
 
 ## Rendering Forms
 
@@ -126,18 +71,17 @@ Your `@form` is now ready to be rendered, either do it yourself or use something
 
 ```haml
 = form_for @form do |f|
-
-  = f.input :name
   = f.input :title
 ```
 
-Nested forms and collections can be easily rendered with `fields_for`, etc. Just use Reform as if it would be an ActiveModel instance in the view layer.
+Nested forms and collections can be easily rendered with `fields_for`, etc. Note that you no longer pass the model to the form builder, but the Reform instance.
+
+Optionally, you might want to use the [#present!](#present) method to pre-populate fields and prepare the form for rendering.
 
-Note that you have a mechanism to [prepopulate forms](#prepopulating-forms) for rendering.
 
 ## Validation
 
-After a form submission, you want to validate the input.
+After form submission, you need to validate the input.
 
 ```ruby
 class SongsController
@@ -168,145 +112,89 @@ It's then up to you what to do with the updated models - they're still unsaved.
 The easiest way to save the data is to call `#save` on the form.
 
 ```ruby
-    @form.save  #=> populates song with incoming data
-                #   by calling @form.song.title= and @form.song.length=.
+    @form.save  #=> populates album with incoming data
+                #   by calling @form.album.title=.
 ```
 
-This will sync the data to the model and then call `song.save`.
-
-Sometimes, you need to do stuff manually.
+This will sync the data to the model and then call `album.save`.
 
+Sometimes, you need to do saving manually.
 
 ## Saving Forms Manually
 
-Calling `#save` with a block doesn't do anything but providing you a nested hash with all the validated input. This allows you to implement the saving yourself.
+Calling `#save` with a block doesn't do anything but provide you with a nested hash with all the validated input. This allows you to implement the saving yourself.
 
 The block parameter is a nested hash of the form input.
 
 ```ruby
   @form.save do |hash|
-    hash      #=> {title: "Rio", length: "366"}
-
-    Song.create(hash)
+    hash      #=> {title: "Greatest Hits"}
+    Album.create(hash)
   end
 ```
 
 You can always access the form's model. This is helpful when you were using populators to set up objects when validating.
 
 ```ruby
-  @form.save do |nested|
+  @form.save do |hash|
     album = @form.model
 
-    album.update_attributes(nested[:album])
-  end
-```
-
-If the form wraps multiple models, via [composition](#compositions), you can access them like this:
-
-```ruby
-  @form.save do |nested|
-    song = @form.model[:song]
-    label = @form.model[:label]
-  end
-```
-
-Note that you can call `#sync` and _then_ call `#save { |hsh| }` to save models yourself.
-
-
-## Contracts
-
-Contracts give you a sub-set of the `Form` API.
-
-1. `#initialize` accepts an already populated model.
-2. `#validate` will run defined validations (without accepting a params hash as in `Form`).
-
-Contracts can be used to completely remove validation logic from your model classes. Validation should happen in a separate layer - a `Contract`.
-
-### Defining Contracts
-
-A contract looks like a form.
-
-```ruby
-class AlbumContract < Reform::Contract
-  property :title
-  validates :title, length: {minimum: 9}
-
-  collection :songs do
-    property :title
-    validates :title, presence: true
+    album.update_attributes(hash[:album])
   end
 ```
 
-It defines the validations and the object graph to be inspected.
 
-In future versions and with the upcoming [Trailblazer framework](https://github.com/apotonick/trailblazer), contracts can be inherited from forms, representers, and cells, and vice-versa. Actually this already works with representer inheritance - let me know if you need help.
+## Nesting
 
-### Using Contracts
-
-Applying a contract is simple, all you need is a populated object (e.g. an album after `#assign_attributes`).
+Reform provides support for nested objects. Let's say the `Album` model keeps some associations.
 
 ```ruby
-album.assign_attributes(..)
-
-contract = AlbumContract.new(album)
-
-if contract.validate
-  album.save
-else
-  raise contract.errors.messages.inspect
+class Album < ActiveRecord::Base
+  has_one  :artist
+  has_many :songs
 end
 ```
 
-Contracts help you to make your data layer a dumb persistance tier. My [upcoming book discusses that in detail](http://nicksda.apotomo.de).
-
-
-## Nesting Forms: 1-1 Relations
-
-Songs have artists to compose them. Let's say your `Song` model would implement that as follows.
-
-```ruby
-class Song < ActiveRecord::Base
-  has_one :artist
-end
-```
+The implementation details do not really matter here, as long as your album exposes readers and writes like `Album#artist` and `Album#songs`, this allows you to define nested forms.
 
-The edit form should allow changing data for artist and song.
 
 ```ruby
-class SongForm < Reform::Form
+class AlbumForm < Reform::Form
   property :title
-  property :length
+  validates :title, presence: true
 
   property :artist do
-    property :name
-
-    validates :name, presence: true
+    property :full_name
+    validates :full_name, presence: true
   end
 
-  #validates :title, ...
+  collection :songs do
+    property :name
+  end
 end
 ```
 
-See how simple nesting forms is? By passing a block to `::property` you can define another form nested into your main form.
+You can also reuse an existing form from elsewhere using `:form`.
 
+```ruby
+property :artist, form: ArtistForm
+```
 
-### has_one: Setup
+## Nested Setup
 
-This setup's only requirement is having a working `Song#artist` reader.
+Reform will wrap defined nested objects in their own forms. This happens automatically when instantiating the form.
 
 ```ruby
-class SongsController
-  def edit
-    song = Song.find(1)
-    song.artist #=> <0x999#Artist title="Duran Duran">
+album.songs #=> [<Song name:"Run To The Hills">]
 
-    @form = SongForm.new(song)
-  end
+form = AlbumForm.new(album)
+form.songs[0] #=> <SongForm model: <Song name:"Run To The Hills">>
+form.songs[0].name #=> "Run To The Hills"
 ```
 
-### has_one: Rendering
+### Nested Rendering
 
-When rendering this form you could use the form's accessors manually.
+When rendering a nested form you can use the form's readers to access the nested forms.
 
 ```haml
 = text_field :title,         @form.title
@@ -318,155 +206,238 @@ Or use something like `#fields_for` in a Rails environment.
 ```haml
 = form_for @form do |f|
   = f.text_field :title
-  = f.text_field :length
 
   = f.fields_for :artist do |a|
     = a.text_field :name
 ```
 
-### has_one: Processing
+## Nested Processing
+
+`validate` will assign values to the nested forms. `sync` and `save` work analogue to the non-nested form, just in a recursive way.
 
 The block form of `#save` would give you the following data.
 
 ```ruby
 @form.save do |nested|
-
-  nested #=> {title:  "Hungry Like The Wolf",
-         #    artist: {name: "Duran Duran"}}
-end
+  nested #=> {title:  "Greatest Hits",
+         #    artist: {name: "Duran Duran"},
+         #    songs: [{title: "Hungry Like The Wolf"},
+         #            {title: "Last Chance On The Stairways"}]
+         #   }
+  end
 ```
 
-Supposed you use reform's automatic save without a block, the following assignments would be made.
+The manual saving with block is not encouraged. You should rather check the Disposable docs to find out how to implement your manual tweak with the official API.
+
+
+## Populating Forms for Validation
+
+This topic is thorougly covered in the [Trailblazer book](https://leanpub.com/trailblazer) in chapters _Nested Forms_ and _Mastering Forms_.
+
+With a complex nested setup it can sometimes be painful to setup the model object graph.
+
+Let's assume you rendered the following form.
 
 ```ruby
-form.song.title       = "Hungry Like The Wolf"
-form.song.artist.name = "Duran Duran"
-form.song.save
+@form = AlbumForm.new(Album.new(songs: [Song.new, Song.new]))
 ```
 
-## Nesting Forms: 1-n Relations
+This will render two nested forms to create new songs.
 
-Reform also gives you nested collections.
+In `validate`, you're supposed to setup the very same object graph, again. Reform has no way of remembering what the object setup was like a request ago.
 
-Let's have Albums with songs!
+So, the following code will fail.
 
 ```ruby
-class Album < ActiveRecord::Base
-  has_many :songs
-end
+@form = AlbumForm.new(Album.new).validate(params[:album])
 ```
 
-The form might look like this.
+However, you can advise Reform to setup the correct objects for you.
 
 ```ruby
 class AlbumForm < Reform::Form
-  property :title
+  collection :songs, populate_if_empty: Song do
+    # ..
+  end
+```
 
-  collection :songs do
-    property :title
+This works for both `property` and `collection` and instantiates `Song` objects where they're missing when calling `#validate`.
 
-    validates :title, presence: true
+If you want to create the objects yourself, because you're smarter than Reform, do it with a lambda.
+
+```ruby
+class AlbumForm < Reform::Form
+  collection :songs, populate_if_empty: lambda { |fragment, args| Song.new } do
+    # ..
   end
-end
 ```
 
-This basically works like a nested `property` that iterates over a collection of songs.
+Reform also allows to completely override population using the `:populator` options. This is [documented here](http://trailblazerb.org/gems/reform/populators.html), and also in the Trailblazer book.
 
-### has_many: Rendering
+## Installation
 
-Reform will expose the collection using the `#songs` method.
+Add this line to your Gemfile:
 
-```haml
-= text_field :title,         @form.title
-= text_field "songs[0][title]", @form.songs[0].title
+```ruby
+gem 'reform'
 ```
 
-However, `#fields_for` works just fine, again.
 
-```haml
-= form_for @form do |f|
-  = f.text_field :title
+## Compositions
 
-  = f.fields_for :songs do |s|
-    = s.text_field :title
-```
+Reform allows to map multiple models to one form. The [complete documentation](https://github.com/apotonick/disposable#composition) is here, however, this is how it works.
 
-### has_many: Processing
+```ruby
+class AlbumTwin < Reform::Form
+  include Composition
 
-The block form of `#save` will expose the data structures already discussed.
+  property :id,    on: :album
+  property :title, on: :album
+  property :songs, on: :cd
+  property :cd_id, on: :cd, from: :id
+end
+```
+When initializing a composition, you have to pass a hash that contains the composees.
 
 ```ruby
-@form.save do |nested|
+AlbumForm.new(album: album, cd: CD.find(1))
+```
+
+=> rendering
+=> sync with block
+
+## Hash Fields
+
+Reform can also handle deeply nested hash fields from serialized hash columns. This is [documented here](https://github.com/apotonick/disposable#struct).
+
+=> Example
+
+<a href="https://leanpub.com/trailblazer">
+![](https://raw.githubusercontent.com/apotonick/trailblazer/master/doc/trb.jpg)
+</a>
+
+Reform is part of the [Trailblazer project](https://github.com/apotonick/trailblazer). Please [buy my book](https://leanpub.com/trailblazer) to support the development and learn everything about Reform. Currently the book discusses:
+
+* Form objects, the DSL and basic API (chapter 2 and 3)
+* Basic validations and rendering forms (chapter 3)
+* Nested forms, prepopulating and validation populating and pre-selecting values (chapter 5)
+
+More chapters are coming!
+
+
+
 
-  nested #=> {title: "Rio"
-         #   songs: [{title: "Hungry Like The Wolf"},
-         #          {title: "Last Chance On The Stairways"}]
+## Nomenclature
+
+Reform comes with two base classes.
+
+* `Form` is what made you come here - it gives you a form class to handle all validations, wrap models, allow rendering with Rails form helpers, simplifies saving of models, and more.
+* `Contract` gives you a sub-set of `Form`: [this class](#contracts) is meant for API validation where already populated models get validated without having to maintain validations in the model classes.
+
+
+
+Luckily, this can be shortened as follows.
+
+```ruby
+class SongForm < Reform::Form
+  property :title, validates: {presence: true}
+  property :length, validates: {numericality: true}
 end
 ```
 
+Use `properties` to bulk-specify fields.
+
+```ruby
+class SongForm < Reform::Form
+  properties :title, :length, validates: {presence: true} # both required!
+  validates :length, numericality: true
+end
+```
 
-## Nesting Configuration
 
-### Turning Off Autosave
 
-You can assign Reform to _not_ call `save` on a particular nested model (per default, it is called automatically on all nested models).
+If the form wraps multiple models, via [composition](#compositions), you can access them like this:
 
 ```ruby
-class AlbumForm < Reform::Form
-  # ...
-
-  collection :songs, save: false do
-    # ..
+  @form.save do |nested|
+    song = @form.model[:song]
+    label = @form.model[:label]
   end
 ```
 
-The `:save` options set to false won't save models.
+Note that you can call `#sync` and _then_ call `#save { |hsh| }` to save models yourself.
 
 
-### Populating Forms For Validation
+## Contracts
 
-With a complex nested setup it can sometimes be painful to setup the model object graph.
+Contracts give you a sub-set of the `Form` API.
 
-Let's assume you rendered the following form.
+1. `#initialize` accepts an already populated model.
+2. `#validate` will run defined validations (without accepting a params hash as in `Form`).
+
+Contracts can be used to completely remove validation logic from your model classes. Validation should happen in a separate layer - a `Contract`.
+
+### Defining Contracts
+
+A contract looks like a form.
 
 ```ruby
-@form = AlbumForm.new(Album.new(songs: [Song.new, Song.new]))
+class AlbumContract < Reform::Contract
+  property :title
+  validates :title, length: {minimum: 9}
+
+  collection :songs do
+    property :title
+    validates :title, presence: true
+  end
 ```
 
-This will render two nested forms to create new songs.
+It defines the validations and the object graph to be inspected.
 
-When **validating**, you're supposed to setup the very same object graph, again. Reform has no way of remembering what the object setup was like a request ago.
+In future versions and with the upcoming [Trailblazer framework](https://github.com/apotonick/trailblazer), contracts can be inherited from forms, representers, and cells, and vice-versa. Actually this already works with representer inheritance - let me know if you need help.
 
-So, the following code will fail.
+### Using Contracts
+
+Applying a contract is simple, all you need is a populated object (e.g. an album after `#assign_attributes`).
 
 ```ruby
-@form = AlbumForm.new(Album.new).validate(params[:album])
-```
+album.assign_attributes(..)
 
-However, you can advise Reform to setup the correct objects for you.
+contract = AlbumContract.new(album)
 
-```ruby
-class AlbumForm < Reform::Form
-  # ...
+if contract.validate
+  album.save
+else
+  raise contract.errors.messages.inspect
+end
+```
+
+Contracts help you to make your data layer a dumb persistance tier. My [upcoming book discusses that in detail](http://nicksda.apotomo.de).
 
-  collection :songs, populate_if_empty: Song do
-    # ..
-  end
 ```
 
-This works for both `property` and `collection` and instantiates `Song` objects where they're missing when calling `#validate`.
+This basically works like a nested `property` that iterates over a collection of songs.
+
 
-If you want to create the objects yourself, because you're smarter than Reform, do it with a lambda.
+
+### Turning Off Autosave
+
+You can assign Reform to _not_ call `save` on a particular nested model (per default, it is called automatically on all nested models).
 
 ```ruby
 class AlbumForm < Reform::Form
   # ...
 
-  collection :songs, populate_if_empty: lambda { |fragment, args| Song.new } do
+  collection :songs, save: false do
     # ..
   end
 ```
 
+The `:save` options set to false won't save models.
+
+
+
+
 
 ## Compositions
 
@@ -516,7 +487,7 @@ After you configured your composition in the form, reform hides the fact that yo
 
 When using `#save' without a block reform will use writer methods on the different objects to push validated data to the properties.
 
-Here's how the block parameters look like.
+Here's what the block parameters look like.
 
 ```ruby
 @form.save do |nested|
@@ -854,22 +825,6 @@ property :song, form: SongForm
 The nested `SongForm` is a stand-alone form class you have to provide.
 
 
-## Overriding Setters For Coercion
-
-When "real" coercion is too much and you simply want to convert incoming data yourself, override the setter.
-
-```ruby
-class SongForm < Reform::Form
-  property :title
-
-  def title=(v)
-    super(v.upcase)
-  end
-```
-
-This will capitalize the title _after_ calling `form.validate` but _before_ validation happens. Note that you can use `super` to call the original setter.
-
-
 ## Default Values For Presentation
 
 In case you want to change a value for presentation or provide a default value, override the reader. This is only considered when the form is rendered (e.g. in `form_for`).
@@ -904,49 +859,34 @@ form.changed?(:title) #=> true
 When including `Sync::SkipUnchanged`, the form won't assign unchanged values anymore in `#sync`.
 
 
-## Dynamically Syncing And Saving Properties
-
-Both `#sync` and `#save` can be configured to run a dynamical lambda per property.
-
-The `sync:` option allows to statically add a lambda to a property.
-
-```ruby
-property :title, sync: lambda { |value, options| model.set_title(value) }
-```
-
-Instead of running Reform's built-in sync for this property the block is run.
-
-You can also provide the sync lambda at run-time.
+## Undocumented Features
 
-```ruby
-form.sync(title: lambda { |value, options| form.model.title = "HOT: #{value}" })
-```
+_(Please don't read this section!)_
 
-This block is run in the caller's context allowing you to access environment variables. Note that the dynamic sync happens _before_ save, so the model id may be unavailable.
+### Skipping Properties when Validating
 
-You can do the same for saving.
+In `#validate`, you can ignore properties now using `:skip_if` for deserialization.
 
 ```ruby
-form.save(title: lambda { |value, options| form.model.title = "#{form.model.id} --> #{value}" })
+property :hit, skip_if: lambda { |fragment, *| fragment["title"].blank? }
 ```
-Again, this block is run in the caller's context.
-
-The two features are an excellent way to handle file uploads without ActiveRecord's horrible callbacks.
 
+This works for both properties and nested forms. The property will simply be ignored when deserializing, as if it had never been in the incoming hash/document.
 
-## Undocumented Features
-
-_(Please don't read this section!)_
+For nested properties you can use `:skip_if: :all_blank` as a macro to ignore a nested form if all values are blank.
 
+Note that this still runs validations for the property, though.
 
 ### Prepopulating Forms
 
+Docs: http://trailblazerb.org/gems/reform/prepopulator.html
+
 When rendering a new form for an empty object, nested forms won't show up. The [Trailblazer book, chapter 5](https://leanpub.com/trailblazer), discusses this in detail.
 
-You can use the `:prepopulate` option to configure how to populate a nested form (this also works for scalar properties).
+You can use the `:prepopulator` option to configure how to populate a nested form (this also works for scalar properties).
 
 ```ruby
-property :song, prepopulate: ->(*) { Song.new } do
+property :song, prepopulator: ->(options) { self.song = Song.new } do
   # ..
 end
 ```
@@ -957,6 +897,8 @@ This option is only executed when being instructed to do so, using the `#prepopu
 form.prepopulate!
 ```
 
+You can also pass options to `#prepopulate`.
+
 Only do this for forms that are about to get rendered, though.
 
 Collections and partial collection population is covered in chapter 5.