README.md in representable-2.2.3 vs README.md in representable-2.3.0

- old
+ new

@@ -13,10 +13,27 @@ ```ruby gem 'representable' ``` +### Dependencies + +Representable does a great job with JSON, it also features support for XML, YAML and pure ruby +hashes. But Representable did not bundle dependencies for JSON and XML. + +If you want to use JSON, add the following to your Gemfile: + +```ruby +gem 'multi_json' +``` + +If you want to use XML, add the following to your Gemfile: + +```ruby +gem 'nokogiri' +``` + ## Example What if we're writing an API for music - songs, albums, bands. ```ruby @@ -173,9 +190,40 @@ Album.new.extend(AlbumRepresenter). from_json(%{{"name":"Offspring","songs":[{"title":"Genocide"},{"title":"Nitro","composers":["Offspring"]}]}}) #=> #<Album name="Offspring", songs=[#<Song title="Genocide">, #<Song title="Nitro", composers=["Offspring"]>]> ``` + +## Suppressing Nested Wraps + +When reusing a representer for a nested document, you might want to suppress the wrap for the nested fragment. + +```ruby +module SongRepresenter + include Representable::JSON + + self.representation_wrap = :songs + property :title +end +``` + +When reusing `SongRepresenter` in a nested setup you can suppress the wrapping using the `:wrap` option. + +```ruby +module AlbumRepresenter + include Representable::JSON + + collection :songs, extend: SongRepresenter, wrap: false +end +``` + +The `representation_wrap` from the nested representer now won't be rendered and parsed. + +```ruby +album.extend(AlbumRepresenter).to_json #=> "{\"songs\": [{\"name\": \"Roxanne\"}]}" +``` + +Note that this only works for JSON and Hash at the moment. ## Parse Strategies When parsing `collection`s (also applies to single `property`s), representable usually iterates the incoming list and creates a new object per array item.