Builderoo

v0.7, by Dan Sanderson

Visit the Builderoo home page.



Introduction

Builderoo is a text formatting system for Movable Type, the personal web publishing system from Six Apart. With Builderoo, you can:

With Builderoo, text filter plugins are building blocks for quickly assembling sophisticated weblog content. A filter can perform small functions, such as replacing ASCII characters with HTML typographic characters, without concern for compatibility with other plugins. A filter can perform time-consuming functions, such as accessing a web service, without slowing down the site building process. A filter can perform specialized functions, such as generating images based on mark-up, without having to manage clean-up of unused resources.

Here is an example of Builderoo in action, using Brad Choate's MTTextile plugin as the "base" filter, and the RooLilypond plugin, one of several example plugins included with Builderoo, to generate musical score from Lilypond mark-up:

p. In his __Arabesque No. 1__, Claude Debussy uses triplets in
the melody against quarter notes like a waterfall against stones, not
always touching but always in tandem on the way down.

<% Roo:lilypond %>
\notes \new PianoStaff <<
  \new Staff {
    \key e \major
    \clef treble
    r4 \relative c' {
      \times 2/3 { e'8 fis cis } \times 2/3 { e b cis }
      \times 2/3 { gis b fis }   \times 2/3 { gis e gis }
      dis2 cis4
    }
  }
  \new Staff {
    \key e \major
    \clef bass
    \relative c, { e8 b' e gis b gis e b e, cis' e gis cis gis e cis }
  }
 >>

</% Roo %>

p. A talented pianist can emphasize the detachment of the melody from the
accompaniment without deviating from the rhythm as written.

This example will appear in the blog entry as:

In his Arabesque No. 1, Claude Debussy uses triplets in the melody against quarter notes like a waterfall against stones, not always touching but always in tandem on the way down.

RooLilypond example

A talented pianist can emphasize the detachment of the melody from the accompaniment without deviating from the rhythm as written.

Several plugins are included with Builderoo to demonstrate its features. See plugins.html for more information.


Installing Builderoo

Requirements

Builderoo requires Movable Type 3.2 or later.

Builderoo v0.7 was tested with Perl 5.6.1 and Perl 5.8.1. It should work with all versions of Perl later than 5.6.1.

Some of the plugins included with Builderoo depend on other applications. See the documentation for the plugins for more information.

Installation

To install Builderoo, do the following:

Step 1: Find Perl on your server. The first line of builderoo/builderoo-console.cgi must have the correct path to "perl," typically #!/usr/bin/perl. Check the first line of mt.cgi. If the path is different from /usr/bin/perl, modify builderoo/builderoo-console.cgi accordingly.

Step 2: Upload the builderoo directory into the plugins directory in your Movable Type installation.

Step 3: Change the file permissions of builderoo-console.cgi so it can be executed by the web server. At a Unix/Linux command line, the following command should set the correct permissions:

chmod 755 builderoo-console.cgi

These first three steps are similar to those used to install Movable Type. See the Movable Type installation instructions for more details on Perl and file permissions.

Step 4: Configure Builderoo from your weblog's Settings, under the "Plugins" panel. Choose "base" filters to use by default for all entries that use Builderoo.

Step 5: (optional) Make Builderoo the default text filter for new entries. In your weblog's Settings, under the "New Entry Defaults" panel, set "Text Formatting" to Builderoo.

Step 6: (optional) Install Builderoo text formatting plugins according to their instructions. Builderoo comes with several useful plugins that take advantage of Builderoo's features. See plugins.html for more information. For news about other plugins designed for Builderoo, visit the Builderoo home page.


Using Roo Tags

When Builderoo is selected as the text formatter for an entry, the entry will be formatted using the base filters, as set in the Builderoo configuration for the weblog. To use a different set of filters—or no filters at all—for a section of the entry, surround the section in a "Roo" tag:

<% Roo:filterkey %> This is a special section. </% Roo %>

To specify the text filter to use, include its "key" in the starting tag after Roo:. The filter key is a unique identifier that represents a text filter. To see a list of keys for available filters, click on the help box (?) next to the "Text Formatting" drop-down list in the entry editing window.

You may specify multiple filters to apply by listing their keys, separated with commas (no spaces). Filters are applied in order from left to right. The results of the first are passed to the second, and so on.

<% Roo:firstfilter,secondfilter,thirdfilter %> This is a special section. </% Roo %>

You may specify that the section not be filtered at all by specifying no filter keys. The colon is still required.

<% Roo: %> No filters will be applied to this section. </% Roo %>

A Roo section can contain other Roo sections. Only the filters for the inner section are used on the inner section. When the inner section ends, the outer section's filters process the rest of the outer section.


Filter Parameters

Roo tags may include parameters to be passed to filters that accept them. Parameters are specified in brackets after the filter name, using the parameter name, an equals sign (=), and the parameter value. If the parameter value contains spaces, surround it with double-quotes ("). Within double-quotes, a double-quote character may be included in the value by preceding it with a backslash (\); similarly, a backslash character may be included by using two backslashes (\\). Multiple parameters may be specified, separated by spaces. For example:

<% Roo:firstfilter[attr1=value attr2="Bob says, \"Hi!\""],secondfilter %>


Literal Text That Looks Like a Roo Tag

To have the text "<% Roo" or "</% Roo" appear in a blog entry, use the special tags <% Roo \\ %> and </% Roo \\ %>, respectively. Note that the characters are passed to text filters just as they appear; to have them display in a web page, a text filter must translate the angle brackets to HTML entities (e.g. < to &lt;).

<% Roo:verbatim %>
I enclose my Roo sections with <% Roo \\ %>:filterkey %> and </% Roo \\ %>%> tags.
</% Roo %>

(This example uses the "verbatim" filter, a sample plugin included with Builderoo that converts special characters to HTML entities. See plugins.html for more information.)


Caching Filter Results

Builderoo can remember the filtered version of a section, so it does not have to re-run the filters the next time the entry is rendered if the section hasn't changed. Special purpose filters can perform heavy-duty tasks, such as generate images or fetch data from a web service, and not slow down subsequent re-builds of pages containing the entry.

In most cases, only certain filters need to have their results cached, and they should always be cached. The text filter plugin can tell Builderoo to always cache its results using the Builderoo plugin API. (See below.)

If multiple filters are being applied to a single section, and any of the filters are to be cached, then the entire section is cached. If a cached section contains a subsection, the subsection follows its own caching rules.

To explicitly cache a Roo section, regardless of whether or not the text filter told Builderoo to cache it, use the "cache" attribute in the opening tag:

<% Roo:filterkey cache %> ... big data ... </% Roo %>

Sections to be cached will run their filters every time you preview the entry, then once more when the entry is first published. Each subsequent time the entry is published, if there are no changes to the section, the cached results will be used without running the filters.


Using RooMacros

RooMacros are predefined sections of text that are inserted into an entry when a RooMacro tag is used, before any text filters are applied. To use a RooMacro in an entry, include a RooMacro tag:

<% RooMacro:macroname %>

Or, use the abbreviated tag:

<% RooM:macroname %>

To create new RooMacros for use in your entries, select "Edit RooMacros for this weblog" from the weblog's main menu screen. (Select the weblog from the "Weblogs" dropdown at the top of the screen, then click "Go".) Alternatively, go to the weblog's settings, "Plugins" panel, Show Settings for Builderoo, then "visit the Builderoo console", then select the weblog from the list.

A RooMacro associates a macro name with a section of text. A macro name must contain only letters, numbers, and underscores (_), and must be unique for all macros for a blog. Macro definitions may contain text, Roo tags, and other RooMacros.

RooMacros may take parameters that are substituted within the macro text. To pass parameters to a macro, use brackets after the macro name, similar to Roo filter parameters:

<% RooM:macroname[value1=first value2="second value"] %>

To include a parameter substitution in macro text, use a RooVar tag. RooVar tags can only be used in macro definitions.

macroname... <% RooVar:value1 %> ...

To have the contents of the RooVar "escaped", with double-quotes (") and backslashes (\) preceded by backslashes, use the escape attribute in the RooVar tag. This is useful for a value passed from one macro to another:

macroname<% RooM:othermacro[foo="<% RooVar:foovalue escape %>"] %>

Examples

Here is an example of a macro that wraps the results of another macro in a <div> tag, allowing the "param" parameter to be passed through to the second macro:

macroname<div class="special">
<% RooMacro:second specialparam=myvalue param="<% RooVar:param %>" %>
</div>

Here is an example of a macro that inserts an image. A Roo tag with no filters is used to protect the IMG from other filters:

macroname<% Roo: %><img src="smiley.gif" alt=":)"></% Roo %>

Here is an example of a macro that opens a Roo tag for the "myfilter" filter including the "foo" parameter passed to the macro, adds some text, then leaves the Roo tag open:

macroname<% Roo:myfilter[special="value" foo="<% RooVar:foo %>"] %> Some text.

This last example might be used in an entry as follows:

<% RooM:macroname[foo="bar"] %> Some more text. </% Roo %>

The result would be equivalent to:

<% Roo:myfilter[special="value" foo="bar"] %> Some text. Some more text </% Roo %>


Literal Text That Looks Like a RooMacro/RooVar Tag

As with Roo tags, to insert the text "<% RooMacro", "<% RooM", or "<% RooVar" into an entry (or macro definition) as typed, use <% RooMacro \\ %>, <% RooM \\ %>, and <% RooVar \\ %>, respectively.


Developing Builderoo Plugins

Text formatting plugins can interface with Builderoo for extra functionality. A plugin registers itself with a call to a subroutine in Builderoo.pm.

A text filter plugin that works without Builderoo, but has optional functionality if Builderoo is installed, may register as both a regular text filter and as a Builderoo plugin. If Builderoo is used, the additional functionality will be used. Plugins that require Builderoo should register only with Builderoo, and not as a regular Movable Type text filter, so it does not appear in the list of text filters outside of Builderoo.

A text filter that is set up to cache will be passed an identifier associated with the cached section. When Builderoo notices a cached section is no longer used and removes it, Builderoo can call a routine specified by the filter. This is useful for filters that generate external resources, such as images or applets, so unused resources can be deleted. The cache identifier is passed to the clean-up routine, so the filter can manage its resources.

For details on how to develop Builderoo plugins, including information on how the caching mechanism works, see the "perldoc" documentation for Builderoo.pm, or visit the Builderoo home page.


Known Issues

The following are known issues with Builderoo v0.7, which may or may not be addressed in a future version. (In some cases, the problems are unavoidable due to inherent limitations in Movable Type 3.2.)


Change History

The following is the release history for Builderoo:

v0.7, September 12, 2005: Major rewrite!

v0.6, June 12, 2005: Re-organized the Builderoo files to take advantage of better support in Movable Type v3.16 for plugins. Users that have had problems with Builderoo not finding its libraries or templates should remove the old Builderoo files, upgrade to Movable Type v3.16 or later, and install this new version of Builderoo according to the new, simpler instructions.

v0.52, July 21, 2004: New sample plugin: RooSpell, a spelling checker. Also, a teeny bug fix to silence spurious warnings when saving an entry, and some minor documentation updates.

v0.51, July 14, 2004: A bug fix release:

v0.5, June 28, 2004: The first public release. This release was submitted to the Movable Type 3.0 Developer Contest, June 2004. Many thanks to Jim Flanagan for helping to test Builderoo prior to submission.

v0.4, June 27, 2004: A private release. Implemented filter parameters, RooMacros. Upgraded the sample plugins to take advantage of these features.

v0.3, June 15, 2004: A private release. Implemented the Builderoo plugin mechanism, plugin panel for the Console, and preview expiration.

v0.2, June 12, 2004: A private release. Implemented the caching and reaping mechanism for Builderoo in the context of a weblog entry, and the "cache" attribute for Roo tags.

v0.1, June 9, 2004: A private release. Implemented Roo tags, default filters, and the "Text Filters" portion of the Builderoo Console.


License and Distribution

Builderoo v0.7 is distributed under "The MIT License," an Open Source license. The full text of the license is as follows:

Copyright © 2004-2007 Dan Sanderson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Digest::Perl::MD5, copyright © 2000 Christian Lackas, is distributed under the Perl Artistic License. See the Digest::Perl::MD5 documentation for more information.

MTRegex, copyright © 2002 Brad Choate, is distributed under "The MIT License," an Open Source license. The full text of the copyright notice and license can be found in examples/regexfilter/lib/README.txt.

Beautufier, copyright © 2003 Mike Jewell, with modifications copyright © 2003 Sean Voisen, is distributed under the GNU Public License, Version 2, June 1991. The full text of the GNU Public License under which Beautifier is distributed can be found in examples/roobeautifier/lib/COPYING.txt, with a complete list of files in example/roobeautifier/lib/README.txt.


Please visit the Builderoo home page to download updates and additional plugins, report bugs, and submit feedback and suggestions for new features.