1. Technology
You can opt-out at any time. Please refer to our privacy policy for contact information.

Spotlight on RubyGems: Builder

Using Builder to Generate HTML

By

The Builder library allows you to generate HTML, XML or CSS markup without having to rely on a mixed text and a Ruby code library (such as eruby). It's an example of what's called a "meta language" or "domain specific language," in which the Ruby code itself heavily resembles the output but allows much greater flexibility. With Builder code you can generate tags, call methods, use loops or conditionals and do many other tasks. In addition to making it simpler to write HTML code, builder also produces nicely formatted output for easy reading.

Installing the Builder Gem

To use builder, first install the Builder gem.

 $ sudo gem install builder 

Using Builder

First, create a new Builder::XmlMarkup object. This builder object uses a technique called method_missing to be able to respond to any method call whether or not there is already a method defined with the object name. To add a new HTML tag to the output, simply call the method with the name of that tag. For instance, to generate the tag <comment>Builder is fun!</comment> with a Builder object called b, you would do something like this: b.comment "Builder is fun!". There's no method called comment anywhere in the builder code; the method_missing functionality catches this and knows you wanted to add a comment tag to the output. Though it might seem a bit odd at first, it's a very effective technique to create, with a minimal amount of work, a meta-language that resembles your target language.

Creating HTML Documents

HTML code can frequently be messy, but using a Builder is one way to keep that code clean. In the following example, we'll create a complete HTML document using Builder. You can see that the Builder object's ability to take blocks as arguments preserves the hierarchal structure of the document. Any tags generated by the block argument will be added to the output inside the current tag. You'll also notice that the output HTML code is not only very clean, but also correctly indented.

 #!/usr/bin/env ruby
 require 'rubygems'
 require_gem 'builder'
 
 b = Builder::XmlMarkup.new(
   :indent => 2
 )
 
 html = b.html {
   b.head {
     b.title "XML Builder Test"
   }
   b.body {
     b.h1 "Title of Page"
     b.p "Sample paragraph text"
   }
 }
 
 puts html
 

Generating Tags

The example code doesn't illustrate one of the other feature of the Builder Gem--generating a tag with attribute. The reason for this is that it's not very easy to type, nor is is particularly intuitive. In addition to passing the attribute name/value pairs as a hash, you need to pass the text to be displayed in your link. For example, to generate a link to Ruby.about.com, the following code can be used: h.a( { :href => 'http://ruby.about.com/' }, 'Ruby guide' ). Since creating links is so commonplace, it would be much easier to create your own custom link-building method.

In the following example, that's just what we'll do--add a link! method to the Builder object. That object will now be able to generate link tags using a much more friendly interface. While you can use a similar method to wrap any non-trivial tags in friendly interfaces, be sure to use the exclamation point at the end of the method name. This convention is used in Builder objects so these methods don't conflict with tag-generating methods.

 #!/usr/bin/env ruby
 require 'rubygems'
 require_gem 'builder'
 
 h = Builder::XmlMarkup.new(
   :indent => 2
 )
 
 class <<h
   def link!( url, text )
     a( {:href => url}, text )
   end
 end
 
 html = h.link!( 'http://ruby.about.com', 'Ruby' )
 puts html
 
  1. About.com
  2. Technology
  3. Ruby
  4. Gems
  5. Spotlight on RubyGems: Builder

©2014 About.com. All rights reserved.