README.md in representable-2.0.0.rc2 vs README.md in representable-2.0.0
- old
+ new
@@ -525,10 +525,12 @@
* `class: lambda { |fragment, [i], args| }` ([see Nesting](#nesting))
* `extend: lambda { |object, args| }` ([see Nesting](#nesting))
* `instance: lambda { |fragment, [i], args| }` ([see Object Creation](#polymorphic-object-creation))
* `reader: lambda { |document, args| }` ([see Read And Write](#overriding-read-and-write))
* `writer: lambda { |document, args| }` ([see Read And Write](#overriding-read-and-write))
+* `parse_filter: lambda { |fragment, document, args| }` ([see Filters](#filters)))
+* `render_filter: lambda { |value, document, args| }` ([see Filters](#filters))
* `if: lambda { |args| }` ([see Conditions](#conditions))
* `prepare: lambda { |object, args| }` ([see docs](#rendering-and-parsing-without-extend))
* `serialize: lambda { |object, args| }` ([see docs](#overriding-serialize-and-deserialize))
* `deserialize: lambda { |object, fragment, args| }` ([see docs](#overriding-serialize-and-deserialize))
* `representation_wrap` is a dynamic option, too: `self.representation_wrap = lambda do { |args| }` ([see Wrapping](#wrapping))
@@ -546,9 +548,51 @@
```
The `Options` instance exposes the following readers: `#binding`, `#represented`, `#decorator` and `#user_options` which is the hash you usually have as `args`.
Option-specific arguments (e.g. `fragment`, [see here](#available-options)) are still prepended, making the `Options` object always the *last* argument.
+
+
+## Filters
+
+Representabe offers you `:render_filter` and `:parse_filter` to modify the value to be rendered or parsed.
+
+Filters are implemented using `Pipeline`, which means you can add as many as you want. The result from the former filter will be passed to the next.
+
+```ruby
+property :title, render_filter: lambda { |value, doc, *args| value.html_safe }
+```
+
+This will be executed right before the fragment gets rendered into the document.
+
+```ruby
+property :title, parse_filter: lambda { |fragment, doc, *args| Sanitizer.call(fragment) }
+```
+
+Just before setting the fragment to the object via the `:setter`, the `:parse_filter` is called.
+
+
+## Callable Options
+
+While lambdas are one option for dynamic options, you might also pass a "callable" object to a directive.
+
+```ruby
+class Sanitizer
+ include Uber::Callable
+
+ def call(represented, fragment, doc, *args)
+ fragment.sanitize
+ end
+end
+```
+
+Note how including `Uber::Callable` marks instances of this class as callable. No `respond_to?` or other magic takes place here.
+
+```ruby
+property :title, parse_filter: Santizer.new
+```
+
+This is enough to have the `Sanitizer` class run with all the arguments that are usually passed to the lambda (preceded by the represented object as first argument).
## XML Support
While representable does a great job with JSON, it also features support for XML, YAML and pure ruby hashes.