content_processor.builder

Description

This content processor can be used to programatically create XHTML/XML documents. One could, for example, use it to easily build RSS or ATOM feeds without worrying about unclosed elements and the such.

This extension can only be used if the builder library is installed. The preferred way to do this is via Rubygems:

$ gem install builder

Usage

When using this processor, the content needs to be valid Ruby code since the builder library is used that way. The builder object is provided by the xml object which is an instance of the Builder::XmlMarkup class (see the reference for more information).

Once the content is processed, it is replaced by the result of xml.target! which returns the generated XML document.

The Webgen::Context object is available, as usual, through the context object.

Examples

Generating XHTML

Following is an example page file that uses this processor as the sole content processor in its pipeline to generate some HTML elements:

xml.h1("This a h1 header", :id => 'myid')

xml.p do |p|
  p.text! "You can just write "
  p.b "your"
  p.text! "paragraphs here and"
  p.a("link", :href => "http://someurl.com")
  p.text! "them below. This is also a"
  p.i "nice"
  p.text! "format!"
end

xml.blockquote(:class => 'information') do |bq|
  bq.text! "Citations are easy too."
  bq.text! "Really. And you can assign them attributes."
end

xml.ul do |ul|
  ul.li "Lists"
  ul.li "aren't"
  ul.li "difficult"
  ul.li "either."
end

The output would look like this:

<h1 id="myid">This a h1 header</h1>
<p>
You can just write   <b>your</b>
paragraphs here and  <a href="http://someurl.com">link</a>
them below. This is also a  <i>nice</i>
format!</p>
<blockquote class="information">
Citations are easy too.Really. And you can assign them attributes.</blockquote>
<ul>
  <li>Lists</li>
  <li>aren't</li>
  <li>difficult</li>
  <li>either.</li>
</ul>

Generating XML

Following is another page file that is now used to generate a custom XML document:

---
dest_path: '<parent><basename>(-<version>)(.<lang>).xml'
cn: <basename>(-<version>).xml
title: Person Object
template: ~
--- pipeline:builder
xml.persons(:path => context.node.alcn) do |p|
  p.person do |b|
    b.firstname('Thomas')
    b.lastname('Leitner')
  end
  p.person do |b|
    b.firstname('Other first')
    b.lastname('Other last')
  end
end

The above page file will produce the following destination file (the alcn in the path attribute would be different of course):

<persons path="/documentation/reference/extensions/content_processor/builder.en.html">
  <person>
    <firstname>Thomas</firstname>
    <lastname>Leitner</lastname>
  </person>
  <person>
    <firstname>Other first</firstname>
    <lastname>Other last</lastname>
  </person>
</persons>