Module: ActiveRecord::Serialization

Module | ActiveRecord::Serialization
In: | lib/active_record/serialization.rb lib/active_record/serializers/json_serializer.rb lib/active_record/serializers/xml_serializer.rb

### Methods

from_json from_xml included to_json to_xml

### Public Class methods

included(base)

### Public Instance methods

from_json(json)
from_xml(xml)
to_json(options = {})

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

to_xml(options = {}, &block)

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>david@loudthinking.com</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>david@loudthinking.com</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

[Validate]