= acts_as_serializable

by Birkir A. Barkarson <birkirb@stoicviking.net>

== Description

A gem/rails plugin for handling versioning of serialization methods (to_xml, to_json).
Uses the builder pattern for a one stop multi-format serialization method, which can be
versioned in-class, in a module or in seperately managed class files.

Works with Builder::XmlMarkup <= 2.1.2

== Installation from source

  git clone git://github.com/birkirb/acts_as_serializable.git
  cd acts_as_serializable
  rake install

=== Rails Plugin Installation

  script/plugin install git://github.com/birkirb/acts_as_serializable.git

=== Gem Installation

  gem install birkirb-acts_as_serializable --source http://gems.github.com

== Examples

First:

  require 'rubygems'
  require 'acts_as_serializable'


Define your own serialization method:

  class SimpleClass
    include Serializable
    acts_as_serializable

    def serialize(builder, options)
      builder.root do
        builder.text 'hello world'
      end
    end
  end

  SimpleClass.new.to_xml => "<root><text>hello world</text></root>"
  SimpleClass.new.to_hash => {:text=>"hello world"}
  SimpleClass.new.to_json => "{\"text\": \"hello world\"}"

Use versioned serialization methods:

  class SimpleClass
    include Serializable

    def serialize_to_version_1_0(builder, options)
      builder.root do
        builder.text 'hello world'
      end
    end

    def serialize_to_version_2_0(builder, options)
      builder.texts do
        builder.text "It's a brave new world"
      end
    end

    acts_as_serializable
  end

  SimpleClass.new.to_xml => "<texts><text>It's a brave new world</text></texts>" 
  SimpleClass.new.to_hash(:version => '1.0') => {:text=>"hello world"}

Use classes containing versioned serialization methods:

Given a model in app/models:

  class Person < ActiveRecord::Base
    acts_as_serializable
  end

And a serialization in app/serializations/person

  module Serializable
    module Person
      class Version_1_1_0
        def self.serialize(person, builder, options)
          builder.person do
            builder.name(person.name)
          end
        end
      end
    end
  end

  Person.new(:name => "Birkir").to_xml => "<person><name>Birkir</name></person>" 

== Copyright

Author::    Birkir A. Barkarson <birkirb@stoicviking.net>
Copyright:: Copyright (c) 2009
License::   MIT License