File: README.rdoc [dm-serializer-1.2.2 Documentation]

### Home Classes Methods

### Files

- LICENSE
- README.rdoc

### Class Index

Quicksearch

- DataMapper
- DataMapper::Collection
- DataMapper::Serializer
- DataMapper::Serializer::Collection
- DataMapper::Serializer::Collection::ToYaml
- DataMapper::Serializer::ValidationErrors
- DataMapper::Serializer::ValidationErrors::ToCsv
- DataMapper::Serializer::ValidationErrors::ToJson
- DataMapper::Serializer::ValidationErrors::ToXml
- DataMapper::Serializer::ValidationErrors::ToYaml
- DataMapper::Serializer::XML
- DataMapper::Serializer::XML::LibXML
- DataMapper::Serializer::XML::Nokogiri
- DataMapper::Serializer::XML::REXML
- DataMapper::Validations
- DataMapper::Validations::ValidationErrors
- Object

No matching classes.

# dm-serializer

## Overview

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

## 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.

    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" }

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:

    require 'dm-serializer/to_json'

## to_xml

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

    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>

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.

## to_csv

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

## 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*.

    Cow.all.to_a.to_yaml(:only => 'name') # WILL NOT WORK

## 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]

Generated with the Darkfish Rdoc Generator 2.