Recipe 5.7. Generating XML with Builder Templates

Problem

Instead of generating HTML with ERb, you want to generate XML or XHTML. And you'd rather not have to type all those tags.

Solution

To make a Builder template in Rails, create a file with an extension of .rxml. Place this file in the views directory. For example, the following Builder template is rendered when the show action of the DocBook controller is invoked.

app/views/docbook/show.rxml:

xml.instruct! xml.declare! :DOCTYPE, :article, :PUBLIC,   "-//OASIS//DTD DocBook XML V4.4//EN",    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" xml.article do   xml.title("What Is Web 2.0")   xml.section do     xml.title("Design Patterns and Business Models for the Next Generation       of Software")     xml.para("The bursting of the dot-com bubble in the fall of 2001 marked       a turning point for the web. Many people concluded that the web was       overhyped, when in fact bubbles and consequent shakeouts appear to be       a common feature of all technological revolutions. Shakeouts       typically mark the point at which an ascendant technology is ready to       take its place at center stage. The pretenders are given the bum's       rush, the real success stories show their strength, and there begins       to be an understanding of what separates one from the other.")   end end

Discussion

The solution renders the following output when the show action of the DocBook controller is called:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"          "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <article>   <title>What Is Web 2.0</title>   <section>     <title>Design Patterns and Business Models for the Next Generation       of Software</title>     <para>The bursting of the dot-com bubble in the fall of 2001 marked       a turning point for the web. Many people concluded that the web was        overhyped, when in fact bubbles and consequent shakeouts appear to be       a common feature of all technological revolutions. Shakeouts       typically mark the point at which an ascendant technology is ready to       take its place at center stage. The pretenders are given the bum's       rush, the real success stories show their strength, and there begins       to be an understanding of what separates one from the other.</para>   </section> </article>

Builder templates work by transforming method calls on a Builder::XmlMarkup object into tags that surround the first argument to that object. The optional remaining argument is a hash that is interpreted as the attributes for the tag being created. Here's an example:

xml = Builder::XmlMarkup.new xml.h1('Ruby on Rails', {:class => 'framework'})

This code generates this tag:

<h1 >Ruby on Rails</h1>

In Rails, Builder templates are automatically supplied with a Builder::XmlMarkup object named xml, so there's no need to instantiate it. The first parameter is commonly passed in as a block, which makes creating nested tags simple and readable. Here's an example of subelements being created within a parent element using the block syntax:

xml.h1 do   xml.comment! "with a little emphasis on Ruby..."   xml.span("Ruby", :style => "color: red;")   xml.text! " on Rails!" end

This template produces:

<h1>   <!-- with a little emphasis on Ruby... -->   <span style="color: red;">Ruby</span>   on Rails! </h1>

The comment! and text! methods have special meanings; they create XML comments or plain text (respectively) instead of being interpreted as tag names. Note that these method names don't follow the Ruby convention of naming "destructive" methods that modify the underlying object in-place (like the String class's gsub! or strip! methods) with a !. These Builder::XmlMarkup methods just create output; they don't modify the underlying object.

Problem

Solution

Discussion

See Also