AS guide: documents Array#to_xml

1 files changed, 99 insertions, 0 deletions

diff --git a/railties/guides/source/active_support_overview.textile b/railties/guides/source/active_support_overview.textile
index ca1480b626..7adaafceff 100644
--- a/railties/guides/source/active_support_overview.textile
+++ b/railties/guides/source/active_support_overview.textile
@@ -859,6 +859,105 @@ invoice.lines.to_formatted_s(:db) # => "23,567,556,12"
 
 Integers in the example above are supposed to come from the respective calls to +id+.
 
+h5. +to_xml+
+
+The method +to_xml+ returns a string containing an XML representation of its receiver:
+
+<ruby>
+Contributor.all(:limit => 2, :order => 'rank ASC').to_xml
+# =>
+# <?xml version="1.0" encoding="UTF-8"?>
+# <contributors type="array">
+#   <contributor>
+#     <id type="integer">4356</id>
+#     <name>Jeremy Kemper</name>
+#     <rank type="integer">1</rank>
+#     <url-id>jeremy-kemper</url-id>
+#   </contributor>
+#   <contributor>
+#     <id type="integer">4404</id>
+#     <name>David Heinemeier Hansson</name>
+#     <rank type="integer">2</rank>
+#     <url-id>david-heinemeier-hansson</url-id>
+#   </contributor>
+# </contributors>
+</ruby>
+
+To do so it sends +to_xml+ to every item in turn, and collects the results under a root node. All items must respond to +to_xml+, an exception is raised otherwise.
+
+By default, the name of the root element is the underscorized and dasherized plural of the name of the class of the first item, provided the rest of elements belong to that type (checked with <tt>is_a?</tt>) and they are not hashes. In the example above that's "contributors".
+
+If there's any element that does not belong to the type of the first one the root node becomes "records":
+
+<ruby>
+[Contributor.first, Commit.first].to_xml
+# =>
+# <?xml version="1.0" encoding="UTF-8"?>
+# <records type="array">
+#   <record>
+#     <id type="integer">4583</id>
+#     <name>Aaron Batalion</name>
+#     <rank type="integer">53</rank>
+#     <url-id>aaron-batalion</url-id>
+#   </record>
+#   <record>
+#     <author>Joshua Peek</author>
+#     <authored-timestamp type="datetime">2009-09-02T16:44:36Z</authored-timestamp>
+#     <branch>origin/master</branch>
+#     <committed-timestamp type="datetime">2009-09-02T16:44:36Z</committed-timestamp>
+#     <committer>Joshua Peek</committer>
+#     <git-show nil="true"></git-show>
+#     <id type="integer">190316</id>
+#     <imported-from-svn type="boolean">false</imported-from-svn>
+#     <message>Kill AMo observing wrap_with_notifications since ARes was only using it</message>
+#     <sha1>723a47bfb3708f968821bc969a9a3fc873a3ed58</sha1>
+#   </record>
+# </records>
+</ruby>
+
+If the receiver is an array of hashes the root element is by default also "records":
+
+<ruby>
+[{:a => 1, :b => 2}, {:c => 3}].to_xml
+# =>
+# <?xml version="1.0" encoding="UTF-8"?>
+# <records type="array">
+#   <record>
+#     <b type="integer">2</b>
+#     <a type="integer">1</a>
+#   </record>
+#   <record>
+#     <c type="integer">3</c>
+#   </record>
+# </records>
+</ruby>
+
+WARNING. If the collection is empty the root element is by default "nil-classes". That's a gotcha, for example the root element of the list of contributors above would not be "contributors" if the collection was empty, but "nil-classes". You may use the <tt>:root</tt> option to ensure a consistent root element.
+
+The name of children nodes is by default the name of the root node singularized. In the examples above we've seen "contributor" and "record". The option <tt>:children</tt> allows you to set these node names.
+
+The default XML builder is a fresh instance of <tt>Builder::XmlMarkup</tt>. You can configure your own builder via the <tt>:builder</tt> option. The method also accepts options like <tt>:dasherize</tt> and friends, they are forwarded to the builder:
+
+<ruby>
+Contributor.all(:limit => 2, :order => 'rank ASC').to_xml(:skip_types => true)
+# =>
+# <?xml version="1.0" encoding="UTF-8"?>
+# <contributors>
+#   <contributor>
+#     <id>4356</id>
+#     <name>Jeremy Kemper</name>
+#     <rank>1</rank>
+#     <url-id>jeremy-kemper</url-id>
+#   </contributor>
+#   <contributor>
+#     <id>4404</id>
+#     <name>David Heinemeier Hansson</name>
+#     <rank>2</rank>
+#     <url-id>david-heinemeier-hansson</url-id>
+#   </contributor>
+# </contributors>
+</ruby>
+
 h4. Wrapping
 
 The class method +Array.wrap+ behaves like the function +Array()+ except that it does not try to call +to_a+ on its argument. That changes the behaviour for enumerables: