Some Updates on Representable: 1.2.3 Released

{{{
Hi everyone, just wanted to give you a quick update. As always, we were hard-working – several versions of “representable”:https://github.com/apotonick/representable were released in the last weeks, we even “got featured on Ruby5”:http://ruby5.envylabs.com/episodes/281-episode-277-june-1st-2012/stories/2466-representable, yo! Here’s what changed.

h3. Nil Properties Are Ignored

In 1.2, uninitialized properties or properties explicitely set to @nil@ are *no longer considered* when rendering a representation or parsing an incoming document.

Let’s use the same old song example. Sing along, everybody!

class Song
  attr_accessor :name
end

module SongRepresenter
  include Representable::JSON
  property :name
end

First, I create a @Song@ instance and extend it with the representer module.

song = Song.new.extend(SongRepresenter)

An uninitialized @name@ will now result in an empty property since the *nil property is skipped when rendering*.

song.to_json
#=> {}

h3. But I Want The Nil!

You may explicitely tell representable to include nil properties in representations using the new option @:render_nil@ as “discussed in this thread”:https://github.com/apotonick/representable/pull/2.

module SongRepresenter
  include Representable::JSON
  property :name, :render_nil => true
end

Check how the uninitialized (or, _nil_) is included now.

song.to_json
#=> {"name":null}

h3. Parsing Became Ignorant.

Another change was introduced in parsing. Properties that are not found in the incoming document are ignored, it is up to the represented object to handle with that.

song.from_json("{}")
#=> #

Note how the @name instance variable is not even created. Beware that this might break your API. In former versions, non-existent properties were initialized with @nil@ in the parsing process. That no longer happens!

h3. False Values Are Included, Now!

One consequence is that @false@ values now get a meaning and are included in rendering and parsing.

song.name = false
song.to_json #=> {"name":false}

To summarize, *representable got a little bit dumber.* @nil@ or non-existant values are simply skipped. You may include them using @:render_nil@. False values are treated just like any other “valid” property.

h3. Representing Hashes in XML.

A cool newly added feature is the @AttributeHash@ for XML when you want to map a hash to a single XML tag with attributes. Check this example.

require "representable/xml/hash"

module SongHashRepresenter
  include Representable::XML::AttributeHash
  self.representation_wrap= :song
end

Rendering is just as simple as calling @to_xml@.

{:name => "Roxanne", :artist => "The Police"}.
  extend(SongHashRepresenter).to_xml

#=> 

Now that is cool. And it works the other way, too!

{}.extend(SongHashRepresenter).
  from_xml('')

#=> {"name"=>"Roxanne", "artist"=>"The Police"}

That is heavily utilized in the roar gem, I will blog about it separately.

h3. More Changes?

Yeah, we replaced the @:except@ option with @:exclude@ as it is more consistent. Who came up with that @:except@ bs at all???

Hope you’re enjoying our little changes – have a nice day!
}}}

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s