Module: ActiveRecord::Serialization

Defined in:
lib/active_record/serialization.rb,
lib/active_record/serializers/xml_serializer.rb,
lib/active_record/serializers/json_serializer.rb

Defined Under Namespace

Classes: Serializer

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object 



6
7
8
 
# File 'lib/active_record/serializers/json_serializer.rb', line 6

def self.included(base)
  base.cattr_accessor :include_root_in_json, :instance_writer => false
end

Instance Method Details

#as_json(options = nil) ⇒ Object

:nodoc:



80
81
82
83
84
 
# File 'lib/active_record/serializers/json_serializer.rb', line 80

def as_json(options = nil) #:nodoc:
  hash = Serializer.new(self, options).serializable_record
  hash = { options[:root] || self.class.model_name.element => hash } if include_root_in_json
  hash
end

#from_json(json) ⇒ Object 



86
87
88
89
 
# File 'lib/active_record/serializers/json_serializer.rb', line 86

def from_json(json)
  self.attributes = ActiveSupport::JSON.decode(json)
  self
end

#from_xml(xml) ⇒ Object 



159
160
161
162
 
# File 'lib/active_record/serializers/xml_serializer.rb', line 159

def from_xml(xml)
  self.attributes = Hash.from_xml(xml).values.first
  self
end

#to_json(options = {}) ⇒ Object

Returns a JSON string representing the model. Some configuration is available through options.

The option ActiveRecord::Base.include_root_in_json controls the top-level behavior of to_json. In a new Rails application, it is set to true in initializers/new_rails_defaults.rb. When it is true, to_json will emit a single root node named after the object’s type. For example:

konata = User.find(1)
ActiveRecord::Base.include_root_in_json = true
konata.to_json
# => { "user": {"id": 1, "name": "Konata Izumi", "age": 16,
                "created_at": "2006/08/01", "awesome": true} }

ActiveRecord::Base.include_root_in_json = false
konata.to_json
# => {"id": 1, "name": "Konata Izumi", "age": 16,
      "created_at": "2006/08/01", "awesome": true}

The remainder of the examples in this section assume include_root_in_json is set to false.

Without any options, the returned JSON string will include all the model’s attributes. For example:

konata = User.find(1)
konata.to_json
# => {"id": 1, "name": "Konata Izumi", "age": 16,
      "created_at": "2006/08/01", "awesome": true}

The :only and :except options can be used to limit the attributes included, and work similar to the attributes method. For example:

konata.to_json(:only => [ :id, :name ])
# => {"id": 1, "name": "Konata Izumi"}

konata.to_json(:except => [ :id, :created_at, :age ])
# => {"name": "Konata Izumi", "awesome": true}

To include any methods on the model, use :methods.

konata.to_json(:methods => :permalink)
# => {"id": 1, "name": "Konata Izumi", "age": 16,
      "created_at": "2006/08/01", "awesome": true,
      "permalink": "1-konata-izumi"}

To include associations, use :include.

konata.to_json(:include => :posts)
# => {"id": 1, "name": "Konata Izumi", "age": 16,
      "created_at": "2006/08/01", "awesome": true,
      "posts": [{"id": 1, "author_id": 1, "title": "Welcome to the weblog"},
                {"id": 2, author_id: 1, "title": "So I was thinking"}]}

2nd level and higher order associations work as well:

konata.to_json(:include => { :posts => {
                               :include => { :comments => {
                                             :only => :body } },
                               :only => :title } })
# => {"id": 1, "name": "Konata Izumi", "age": 16,
      "created_at": "2006/08/01", "awesome": true,
      "posts": [{"comments": [{"body": "1st post!"}, {"body": "Second!"}],
                 "title": "Welcome to the weblog"},
                {"comments": [{"body": "Don't think too hard"}],
                 "title": "So I was thinking"}]}



76
77
78
 
# File 'lib/active_record/serializers/json_serializer.rb', line 76

def to_json(options = {})
  super
end

#to_xml(options = {}, &block) ⇒ Object

Builds an XML document to represent the model. Some configuration is available through options. However more complicated cases should override ActiveRecord::Base#to_xml.

By default the generated XML document will include the processing instruction and all the object’s attributes. For example:

<?xml version="1.0" encoding="UTF-8"?>
<topic>
  <title>The First Topic</title>
  <author-name>David</author-name>
  <id type="integer">1</id>
  <approved type="boolean">false</approved>
  <replies-count type="integer">0</replies-count>
  <bonus-time type="datetime">2000-01-01T08:28:00+12:00</bonus-time>
  <written-on type="datetime">2003-07-16T09:28:00+1200</written-on>
  <content>Have a nice day</content>
  <author-email-address>[email protected]</author-email-address>
  <parent-id></parent-id>
  <last-read type="date">2004-04-15</last-read>
</topic>

This behavior can be controlled with :only, :except, :skip_instruct, :skip_types, :dasherize and :camelize . The :only and :except options are the same as for the attributes method. The default is to dasherize all column names, but you can disable this setting :dasherize to false. Setting :camelize to true will camelize all column names - this also overrides :dasherize. To not have the column type included in the XML output set :skip_types to true.

For instance:

topic.to_xml(:skip_instruct => true, :except => [ :id, :bonus_time, :written_on, :replies_count ])

<topic>
  <title>The First Topic</title>
  <author-name>David</author-name>
  <approved type="boolean">false</approved>
  <content>Have a nice day</content>
  <author-email-address>[email protected]</author-email-address>
  <parent-id></parent-id>
  <last-read type="date">2004-04-15</last-read>
</topic>

To include first level associations use :include:

firm.to_xml :include => [ :account, :clients ]

<?xml version="1.0" encoding="UTF-8"?>
<firm>
  <id type="integer">1</id>
  <rating type="integer">1</rating>
  <name>37signals</name>
  <clients type="array">
    <client>
      <rating type="integer">1</rating>
      <name>Summit</name>
    </client>
    <client>
      <rating type="integer">1</rating>
      <name>Microsoft</name>
    </client>
  </clients>
  <account>
    <id type="integer">1</id>
    <credit-limit type="integer">50</credit-limit>
  </account>
</firm>

To include deeper levels of associations pass a hash like this:

firm.to_xml :include => {:account => {}, :clients => {:include => :address}}
<?xml version="1.0" encoding="UTF-8"?>
<firm>
  <id type="integer">1</id>
  <rating type="integer">1</rating>
  <name>37signals</name>
  <clients type="array">
    <client>
      <rating type="integer">1</rating>
      <name>Summit</name>
      <address>
        ...
      </address>
    </client>
    <client>
      <rating type="integer">1</rating>
      <name>Microsoft</name>
      <address>
        ...
      </address>
    </client>
  </clients>
  <account>
    <id type="integer">1</id>
    <credit-limit type="integer">50</credit-limit>
  </account>
</firm>

To include any methods on the model being called use :methods:

firm.to_xml :methods => [ :calculated_earnings, :real_earnings ]

<firm>
  # ... normal attributes as shown above ...
  <calculated-earnings>100000000000000000</calculated-earnings>
  <real-earnings>5</real-earnings>
</firm>

To call any additional Procs use :procs. The Procs are passed a modified version of the options hash that was given to to_xml:

proc = Proc.new { |options| options[:builder].tag!('abc', 'def') }
firm.to_xml :procs => [ proc ]

<firm>
  # ... normal attributes as shown above ...
  <abc>def</abc>
</firm>

Alternatively, you can yield the builder object as part of the to_xml call:

firm.to_xml do |xml|
  xml.creator do
    xml.first_name "David"
    xml.last_name "Heinemeier Hansson"
  end
end

<firm>
  # ... normal attributes as shown above ...
  <creator>
    <first_name>David</first_name>
    <last_name>Heinemeier Hansson</last_name>
  </creator>
</firm>

As noted above, you may override to_xml in your ActiveRecord::Base subclasses to have complete control about what’s generated. The general form of doing this is:

class IHaveMyOwnXML < ActiveRecord::Base
  def to_xml(options = {})
    options[:indent] ||= 2
    xml = options[:builder] ||= Builder::XmlMarkup.new(:indent => options[:indent])
    xml.instruct! unless options[:skip_instruct]
    xml.level_one do
      xml.tag!(:second_level, 'content')
    end
  end
end



154
155
156
157
 
# File 'lib/active_record/serializers/xml_serializer.rb', line 154

def to_xml(options = {}, &block)
  serializer = XmlSerializer.new(self, options)
  block_given? ? serializer.to_s(&block) : serializer.to_s
end