File: README.textile

# README.textile

Path: | README.textile
Last Update: | Tue Mar 03 00:22:08 -0700 2009

h1. dm-serializer

h2. Overview

dm-serializer allows DataMapper models and collections to be serialized to a variety of formats (currently JSON, XML, YAML and CSV).

h2. How it works

One method is added to each model/collection for each serialization type - @to_json@, @to_xml@, @to_yaml@, and @to_csv@. With the exception of @to_csv@, all of these methods share the same interface. @to_json@ will be used for examples. Any method specific behaviour is documented in its own section below.

<pre><code>require ‘dm-serializer‘

class Cow

      include DataMapper::Resource

      property :id,        Integer, :key => true
      property :name,      String

      def description
        "A Cow"
      end

end

cow = Cow.create(

      :id    => 1,
      :name  => "Berta"

)

cow.to_json # => { "id": 1, "name": "Berta" } cow.to_json(:only => [:name]) # => { "name": "Berta" } cow.to_json(:exclude => [:id]) # => { "name": "Berta" } cow.to_json(:methods => [:desc]) # => { "id": 1, "name": "Berta", "desc": "A Cow" }</code></pre>

You can include associations by passing the association accessor the @:methods@ option.

If you want to only load a particular serialization method, that‘s cool, you can do that:

<pre>`require ‘dm-serializer/to_json‘`</pre>

h2. to_xml

@to_xml@ supports some extra options to allow you to override the element names

<pre>`cow.to_xml( :element_name => ‘bovine’) # => <bovine><id>1</id><name>Berta</name></bovine> cows.to_xml(:collection_element_name => ‘kine’) # => <kine><bovine><id>1</id><name>Berta</name></bovine></kine>`</pre>

If you would like a nice speed boost (~5x), require @libxml@ or @nokogiri@ before @dm-serializer@, and that library will be used rather than REXML.

h2. to_csv

@to_csv@ currently doesn‘t support any options yet. It will in the future. It will not support serializing child associations.

h2. Arrays, Hashes, and other core classes

@dm-serializer@ only adds serialization methods to DataMapper objects and collections, however some libraries used (json, yaml) add methods to core classes, such as @Array@. Note that passing @dm-serializer@ options (such as @:only@) to these methods is *not supported*.

<pre>`Cow.all.to_a.to_yaml(:only => ‘name’) # WILL NOT WORK`</pre>

h2. Beware

If you go spelunking through the code you will find other undocumented options. Use at your own risk, I plan on removing or changing these in the near future.

[Validate]