<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Module: ActiveRecord::Serialization</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="classHeader">
<table class="header-table">
<tr class="top-aligned-row">
<td><strong>Module</strong></td>
<td class="class-name-in-header">ActiveRecord::Serialization</td>
</tr>
<tr class="top-aligned-row">
<td><strong>In:</strong></td>
<td>
<a href="../../files/lib/active_record/serializers/json_serializer_rb.html">
lib/active_record/serializers/json_serializer.rb
</a>
<br />
<a href="../../files/lib/active_record/serializers/xml_serializer_rb.html">
lib/active_record/serializers/xml_serializer.rb
</a>
<br />
<a href="../../files/lib/active_record/serialization_rb.html">
lib/active_record/serialization.rb
</a>
<br />
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
</div>
<div id="method-list">
<h3 class="section-bar">Methods</h3>
<div class="name-list">
<a href="#M000079">from_json</a>
<a href="#M000081">from_xml</a>
<a href="#M000077">included</a>
<a href="#M000078">to_json</a>
<a href="#M000080">to_xml</a>
</div>
</div>
</div>
<!-- if includes -->
<div id="section">
<!-- if method_list -->
<div id="methods">
<h3 class="section-bar">Public Class methods</h3>
<div id="method-M000077" class="method-detail">
<a name="M000077"></a>
<div class="method-heading">
<a href="Serialization.src/M000077.html" target="Code" class="method-signature"
onclick="popupCode('Serialization.src/M000077.html');return false;">
<span class="method-name">included</span><span class="method-args">(base)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<h3 class="section-bar">Public Instance methods</h3>
<div id="method-M000079" class="method-detail">
<a name="M000079"></a>
<div class="method-heading">
<a href="Serialization.src/M000079.html" target="Code" class="method-signature"
onclick="popupCode('Serialization.src/M000079.html');return false;">
<span class="method-name">from_json</span><span class="method-args">(json)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<div id="method-M000081" class="method-detail">
<a name="M000081"></a>
<div class="method-heading">
<a href="Serialization.src/M000081.html" target="Code" class="method-signature"
onclick="popupCode('Serialization.src/M000081.html');return false;">
<span class="method-name">from_xml</span><span class="method-args">(xml)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<div id="method-M000078" class="method-detail">
<a name="M000078"></a>
<div class="method-heading">
<a href="Serialization.src/M000078.html" target="Code" class="method-signature"
onclick="popupCode('Serialization.src/M000078.html');return false;">
<span class="method-name">to_json</span><span class="method-args">(options = {})</span>
</a>
</div>
<div class="method-description">
<p>
Returns a JSON string representing the model. Some configuration is
available through <tt>options</tt>.
</p>
<p>
The option <tt>ActiveRecord::Base.include_root_in_json</tt> controls the
top-level behavior of <a href="Serialization.html#M000078">to_json</a>. In
a new Rails application, it is set to <tt>true</tt> in
initializers/new_rails_defaults.rb. When it is <tt>true</tt>, <a
href="Serialization.html#M000078">to_json</a> will emit a single root node
named after the object‘s type. For example:
</p>
<pre>
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}
</pre>
<p>
The remainder of the examples in this section assume include_root_in_json
is set to <tt>false</tt>.
</p>
<p>
Without any <tt>options</tt>, the returned JSON string will include all the
model‘s attributes. For example:
</p>
<pre>
konata = User.find(1)
konata.to_json
# => {"id": 1, "name": "Konata Izumi", "age": 16,
"created_at": "2006/08/01", "awesome": true}
</pre>
<p>
The <tt>:only</tt> and <tt>:except</tt> options can be used to limit the
attributes <a href="Serialization.html#M000077">included</a>, and work
similar to the <tt>attributes</tt> method. For example:
</p>
<pre>
konata.to_json(:only => [ :id, :name ])
# => {"id": 1, "name": "Konata Izumi"}
konata.to_json(:except => [ :id, :created_at, :age ])
# => {"name": "Konata Izumi", "awesome": true}
</pre>
<p>
To include any methods on the model, use <tt>:methods</tt>.
</p>
<pre>
konata.to_json(:methods => :permalink)
# => {"id": 1, "name": "Konata Izumi", "age": 16,
"created_at": "2006/08/01", "awesome": true,
"permalink": "1-konata-izumi"}
</pre>
<p>
To include associations, use <tt>:include</tt>.
</p>
<pre>
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"}]}
</pre>
<p>
2nd level and higher order associations work as well:
</p>
<pre>
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"}]}
</pre>
</div>
</div>
<div id="method-M000080" class="method-detail">
<a name="M000080"></a>
<div class="method-heading">
<a href="Serialization.src/M000080.html" target="Code" class="method-signature"
onclick="popupCode('Serialization.src/M000080.html');return false;">
<span class="method-name">to_xml</span><span class="method-args">(options = {}, &block)</span>
</a>
</div>
<div class="method-description">
<p>
Builds an XML document to represent the model. Some configuration is
available through <tt>options</tt>. However more complicated cases should
override ActiveRecord::Base#to_xml.
</p>
<p>
By default the generated XML document will include the processing
instruction and all the object‘s attributes. For example:
</p>
<pre>
<?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>
</pre>
<p>
This behavior can be controlled with <tt>:only</tt>, <tt>:except</tt>,
<tt>:skip_instruct</tt>, <tt>:skip_types</tt>, <tt>:dasherize</tt> and
<tt>:camelize</tt> . The <tt>:only</tt> and <tt>:except</tt> options are
the same as for the <tt>attributes</tt> method. The default is to dasherize
all column names, but you can disable this setting <tt>:dasherize</tt> to
<tt>false</tt>. Setting <tt>:camelize</tt> to <tt>true</tt> will camelize
all column names - this also overrides <tt>:dasherize</tt>. To not have the
column type <a href="Serialization.html#M000077">included</a> in the XML
output set <tt>:skip_types</tt> to <tt>true</tt>.
</p>
<p>
For instance:
</p>
<pre>
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>
</pre>
<p>
To include first level associations use <tt>:include</tt>:
</p>
<pre>
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>
</pre>
<p>
To include deeper levels of associations pass a hash like this:
</p>
<pre>
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>
</pre>
<p>
To include any methods on the model being called use <tt>:methods</tt>:
</p>
<pre>
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>
</pre>
<p>
To call any additional Procs use <tt>:procs</tt>. The Procs are passed a
modified version of the options hash that was given to <tt><a
href="Serialization.html#M000080">to_xml</a></tt>:
</p>
<pre>
proc = Proc.new { |options| options[:builder].tag!('abc', 'def') }
firm.to_xml :procs => [ proc ]
<firm>
# ... normal attributes as shown above ...
<abc>def</abc>
</firm>
</pre>
<p>
Alternatively, you can yield the builder object as part of the <tt><a
href="Serialization.html#M000080">to_xml</a></tt> call:
</p>
<pre>
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>
</pre>
<p>
As noted above, you may override <tt><a
href="Serialization.html#M000080">to_xml</a></tt> in your <a
href="Base.html">ActiveRecord::Base</a> subclasses to have complete control
about what‘s generated. The general form of doing this is:
</p>
<pre>
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
</pre>
</div>
</div>
</div>
</div>
<div id="validator-badges">
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
d51872cc0e1fdee944d71993f94ac764
>
files
>
706
