Builderoo Plugins

These plugins are distributed under "The MIT License." See readme.html for licensing information.

Some libraries included with RooBeautifier are distributed under the GNU Public License. See examples/roobeautifier/lib/README.txt for more information.

Visit the Builderoo home page.

Introduction

Builderoo comes with several sample plugins that demonstrate the usefulness of Builderoo's features, and are generally useful in their own right. See each section below for installation instructions.

SmartyFilter

The original SmartyPants plugin was not implemented as a text filter, presumably because an entry can only use one filter for the entire entry, and SmartyPants is most useful in conjunction with other filters. Text filters such as John's Markdown, Brad Choate's MTTextile, or Crys Clouse's QuickCode have made special provisions in their code to detect the presence of the SmartyPants plugin and use it as part of their own filter process. With Builderoo, multiple text filters can be applied by the author, so it is no longer necessary to hard-code interaction between plugins.

SmartyFilter is a text filter that replaces quote marks, dashes, and elipses with formal HTML mark-up for the equivalent typographic characters. It uses John Gruber's SmartyPants plugin to perform the transformations.

SmartyFilter can be configured to perform certain transformations by default. Transformations can also be controlled with parameters in a Roo tag.

SmartyFilter requires that the SmartyPants plugin be installed. SmartyFilter 0.2 was tested with SmartyPants 1.5.1.

To install SmartyFilter, copy the smartyfilter directory from the examples/ directory to Movable Type's plugins/ directory. To configure SmartyFilter, find it in your weblog's Settings screen, under "Plugins", and select "Show Settings".

To use SmartyFilter, use the "smartypants" filter.

When used in a Roo tag, the config parameter can override the configuration. The value of the config parameter is the SmartyPants configuration string, which consists of one or more of the following:

Here is an example using SmartyFilter and Movable Type's "Convert Line Breaks" filter for a section:

<% Roo:smartypants[config=1],__default__ %>
"Good day, Boris," said the bellboy. He took a knife--one of the big ones--from the shelf and stabbed him thrice. "I bet you didn't expect that, eh old chap?"

"Not at all," Boris replied, bleeding profusely. Then he died... or did he?
</% Roo %>

This example will appear in the blog entry as:

“Good day, Boris,” said the bellboy. He took a knife—one of the big ones—from the shelf and stabbed him thrice. “I bet you didn’t expect that, eh old chap?”

“Not at all,” Boris replied, bleeding profusely. Then he died… or did he?

RegexFilter

RegexFilter is based on Brad Choate's MTRegex plugin. MTRegex implements Movable Type template tags for defining patterns and performing substitutions on a section of a template, and a global filter for performing substitutions (earlier defined in templates) on the results of a MT template tag (such as MTEntryText). For use with entries, MTRegex can only perform replacements after the entry text has gone through its text filter, and it must perform all replacements on the entire entry text. Only substitutions defined in template tags for the current template are applied, requiring that the patterns be defined in every template that displays entry text. Because entry preview does not use user-defined templates to show what the entry looks like, replacements do not happen during entry preview.

Because RegexFilter is a Builderoo text filter, it can perform replacements before or after any other text filters, and can perform replacements just for a section of an entry using Roo tags. Roo tags can insulate a section from having RegexFilter replacements performed simply by not using the "regex" filter.

RegexFilter performs pattern replacements on a section of text, using regular expressions.

RegexFilter can have pattern replacements defined in its plugin configuration. Replacements set in configuration are applied everywhere the entry text is used, including entry preview. RegexFilter also honors MTRegex patterns defined in templates.

To install RegexFilter, copy the regexfilter directory from the examples/ directory to Movable Type's plugins/ directory.

To configure default substitution patterns for a weblog, find RegexFilter in your weblog's Settings screen, under "Plugins", and select "Show Settings". Specify one substitution per line, as a Perl substitution regular expression. A substitution may optionally be given a name by specifying the name (consisting of letters, numbers, and underscores) and an equal sign before the pattern. A substitution's name can be used to apply just that specific substitution to text when RegexFilter is invoked.

Named patterns can optionally specify that the pattern is not to be applied within HTML tags by including ":no_html" immediately after the name.

Here is an example of several patterns defined in configuration:

Pattern substitutions:s/foo/bar/gi
s{thier}{their}g
smiley = s/:-D/<img src="smiley.gif">/g
weblink:no_html = s{\b(?:http://)(\S*?)\b}{<a href="http://$1">http://$1</a>}g

To use RegexFilter within Builderoo, use the "regex" filter.

When used in a Roo tag, the "regex" filter can take the following optional parameters:

The following example uses the preset pattern configuration above, and "regex" as the base filter.

They were quite emfoorassed when thier website at http://www.gnu.org/ was hacked.

After substitutions, this would appear in the blog entry as:

They were quite embarrassed when their website at http://www.gnu.org/ was hacked.

RegexFilter includes MTRegex 1.61 in the distribution. The MTRegex template tags and global filters are disabled by default. To enable the full MTRegex plugin, rename and move regexfilter/lib/regex.pl.txt to regexfilter/regex.pl, or download and install the latest version of MTRegex.

RooBeautifier

RooBeautifier was inspired by Sean Voisen's MTCodeBeautifier plugin. Like SmartyPants, MTCodeBeautifier was not implemented as a text filter, because a text filter applies to an entire entry, which would be inappropriate for formatting sections of sample source code. Instead, it is implemented as an MT template tag, and applied to entry text using Brad Choate's MTMacro plugin, requiring the replacement text and source code to pass through the selected text filter. MTCodeBeautifier explicitly interfaces with Brad's MTTextile text filter plugin, to get around incompatibilities between some kinds of source code and MTTextile mark-up. Builderoo allows you to apply only RooBeautifier to a section of an entry, so there is no concern for incompatibilities between filters.

RooBeautifier is a Builderoo text filter that formats a section of computer source code in an entry, using syntax highlighting and indentation appropriate for the computer programming langauge used in the section.

To install RooBeautifier:

  1. Copy the roobeautifier directory from the examples/ directory to Movable Type's plugins/ directory.
  2. Set up the colors to use in your weblog's stylesheet. Select Templates for your weblog, then select the Stylesheet template (or the appropriate file for your weblog). Add styles appropriate for your weblog, such as the following (thanks Sean): 
    .linecomment { color: #FF8000; }
.blockcomment { color: #FF8000; }
.prepro { color: #0000BB; }
.select {}
.quote { color: #DD0000; }
.category1 { color: #007700; }
.category2 { color: #0000BB; }
.category3 { color: #0000BB; }

To use the plugin, include a Roo tag for the "code" filter in a blog entry.

To specify the language whose syntax rules should be used from indentation and highlighting, provide the language name as a (valueless) parameter. An "HFile" module, such as the ones in RooBeautifier's lib/ directory, must be installed for the language. The language name is the part of the HFile module name after "HFile_". For example, the HFile module for the Java language is named "HFile_java.pm", so the language name to use is "java", like so:

<% Roo:code[java] %> ... </% Roo %>

You may also specify the language via the "language" attribute (language="java"). If no language is specified in the tag, RooBeautifier uses the default specified in the weblog's settings for the plugin.

RooBeautifier will also recognize a few shortcuts for known language names. This version includes aliases for ActionScript (as, using the actionscript HFile), PHP (php, using the php3 HFile), and ColdFusion (cf, using the coldfusion HFile). These are defined near the top of RooBeautifier.pl; feel free to add your own.

RooBeautifier can automatically re-indent the source code according to the language syntax rules. A configuration setting controls whether code is re-indented by default. The indent and noindent (valueless) parameters override the default for a section. If RooBeautifier is configured not to re-indent code, the original indentation will be preserved, and only syntax highlighting will be applied.

Note that colors will not show up during preview of an entry, because the preview screen does not use the blog's stylesheet.

Here is an example of RooBeautifier in action:

This is how the plugin gets its configuration and attributes:

<% Roo:code[perl] %>
my $config = $plugin->get_config_hash('blog:'.$ctx->stash('blog')->id);
my $attrs = $ctx->stash('roo_attributes') || {};

my $myattr;
if (defined($attrs->{myattr})) {
    $myattr = $attrs->{myattr}->[0];
} else {
    # "myattr" attribute not specified, default to configuration
    $myattr = $config->{myattr_default}->[0];
}
</% Roo %>

Notice that the attribute data structure
allows for multiple values for each attribute name.  The hash
reference is followed by <code>-&gt;[0]</code> to get the
value of the first attribute with that name.

This example will appear in the blog entry as:

This is how the plugin gets its configuration and attributes:

my $config = $plugin->get_config_hash('blog:'.$ctx->stash('blog')->id);
my $attrs = $ctx->stash('roo_attributes') || {};

my $myattr;
if (defined($attrs->{myattr})) {
 $myattr = $attrs->{myattr}->[0];
} else {
 # "myattr" attribute not specified, default to configuration
 $myattr = $config->{myattr_default}->[0];
}

Notice that the attribute data structure allows for multiple values for each attribute name. The hash reference is followed by ->[0] to get the value of the first attribute with that name.

Both RooBeautifier and Voisen's MTCodeBeautifier use Mike Jewell's Beautifier engine to perform the formatting. RooBeautifier includes Jewell's Beautifier, along with some enhancements by Voisen, in the distribution. The Beautifier formatting engine is distributed under the GNU Public License. The complete text of the license is included in this distribution in the file "COPYING.txt", in RooBeautifier's lib/ directory. See "README.txt" in the same directory for the list of relevant files.

Verbatim

Verbatim is included as an example of a "building block" text filter that you might want to use for an entry in combination with other filters, or in a portion of an entry, such as text that is pasted in from another source that might contain characters that would confuse web browsers (angle brackets, ampersands).

Verbatim is a simple Movable Type text filter that translates characters into HTML entities, and converts line breaks into HTML break tags.

To install, copy the verbatim directory from the examples/ directory to Movable Type's plugins/ directory.

Verbatim's filter key is "verbatim".


RooLaTeX

RooLaTeX, RooLilypond, and RooGraphviz are examples of heavy duty text filters made possible by Builderoo. Each plugin converts text-based mark-up embedded in the entry into an image, without the need for an application on the local computer to generate an image file that is then uploaded to the web server by hand. Builderoo's caching mechanism ensures the image is only generated when the mark-up for the image changes, speeding up subsequent re-builds of the entry. Builderoo also cleans up unused image files after entries are deleted. The author can tweak the result using the entry preview until the image is perfect, and only the last copy of the image is kept.

LaTeX is a document preparation system, popular in academic publishing, especially in mathematics. LaTeX and supporting packages include a powerful mark-up language for drawing diagrams and mathematical formulae, with hundreds of other packages available for other printed material. RooLaTeX lets you include such diagrams and formulae in a blog entry using LaTeX mark-up.

RooLaTeX requires that the following software be installed on the server running Movable Type:

Installing this software on a web server is beyond the scope of this document, but it should be easy for most Unix-based systems, including Linux and Mac OS X. For Linux, most distributions include packages for these applications. For Mac OS X, all pieces are available using Fink.

RooLaTeX is expected to work on all Unix-like platforms. This version takes advantage of features of the command shell executed by Perl, and is not expected to run on Windows web servers.

To install the plugin:

  1. Copy the roolatex directory from the examples/ directory to Movable Type's plugins/ directory.
  2. Determine a directory accessible to the web server where RooLaTeX will put its images. Make a new directory if necessary. Set permissions on the directory so the web server can create files and subdirectories.
  3. Log in to Movable Type's administration panel, then select System Overview, then Plugins. Find RooLaTeX, then select "Show Settings". Configure the paths to the required applications. Save changes.
  4. Go to the weblog in the administration panel, then select Settings, then "Plugins." Find RooLaTeX, then select "Show Settings." Set the "Destination Directory" and "Destination URL", and confirm that the other settings are appropriate. Save changes.

To use the plugin, include a Roo tag for the "latex" filter in a blog entry. The tag may optionally specify the following parameters to override their corresponding settings in the configuration:

Images generated by RooLaTeX have a transparent background, and are anti-aliased for the background color specified by the "grey level" configuration setting or parameter. The text will be black. If the actual background color is not a level of grey, set the grey level to 0 to prevent anti-alias fringes from appearing.

Here is an example of RooLaTeX in action:

The RooLaTeX plugin is based on
<a href="http://www.fourmilab.ch/webtools/textogif/textogif.html">textogif</a>
by John Walker.  The textogif website includes the following example.

<% Roo:latex %>
\begin{displaymath}
\int H(x,x')\psi(x')dx' = -\frac{\hbar^2}{2m}\frac{d^2}{dx^2}
                          \psi(x)+V(x)\psi(x)
\end{displaymath}
</% Roo %>

Very pretty.  But what does it mean?

This example will appear in the blog entry as:

The RooLaTeX plugin is based on textogif by John Walker. The textogif website includes the following example.

RooLaTeX example

Very pretty. But what does it mean?

RooLilypond

GNU Lilypond generates musical score from a mark-up language. RooLilypond lets you include musical score in a blog entry using Lilypond mark-up.

RooLilypond requires that the following software be installed on the server running Movable Type:

Installing this software on a web server is beyond the scope of this document, but it should be easy for most Unix-based systems, including Linux and Mac OS X.

For Mac OS X, all pieces are available using Fink. Be sure to add "/sw/bin" to the end of the software directories list.

RooLilypond is expected to work on all Unix-like platforms. This version takes advantage of features of the command shell executed by Perl, and is not expected to run on Windows web servers.

To install the plugin:

  1. Copy the roolilypond directory from the examples/ directory to Movable Type's plugins/ directory.
  2. Determine a directory accessible to the web server where RooLilypond will put its images. Make a new directory if necessary. Set permissions on the directory so the web server can create files and subdirectories.
  3. Log in to Movable Type's administration panel, then select System Overview, then Plugins. Find RooLilypond, then select "Show Settings". Configure the paths to the required applications. Save changes.
  4. Go to the weblog in the administration panel, then select Settings, then "Plugins." Find RooLilypond, then select "Show Settings." Set the "Destination Directory" and "Destination URL", and confirm that the other settings are appropriate. Save changes.

To use the plugin, include a Roo tag for the "lilypond" filter in a blog entry. The tag may optionally specify the following parameters to override their corresponding settings in the configuration:

Images generated by RooLilypond have a transparent background, and are anti-aliased for the background color specified by the "grey level" configuration setting or parameter. The text will be black. If the actual background color is not a level of grey, set the grey level to 0 to prevent anti-alias fringes from appearing.

Here is an example of RooLilypond in action:

In his <i>Arabesque No. 1</i>, 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 %>
\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 %>

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.

RooLilypond can be made to work with a version of Lilypond older than 2.6.3, as long as it supports output directly to PostScript. You may need to adjust the Lilypond header and footer in the weblog settings to suppress page numbers. You may also need to adjust the example above.

RooGraphviz

Graphviz generates graph diagrams from a mark-up language called "dot". RooGraphviz lets you include such diagrams in a blog entry using dot mark-up. All three Graphviz modes are supported: "dot" (directed graphs), "neato" (undirected graphs, spring model), and "twopi" (undirected graphs, circular).

RooGraphviz requires that Graphviz be installed on the server running Movable Type. If available, it uses Netpbm to determine the dimensions of the image. (If Netpbm is not available, the IMG tag will be rendered without "width" and "height" values.)

To install the plugin:

  1. Copy the roographviz directory from the examples/ directory to Movable Type's plugins/ directory.
  2. Determine a directory accessible to the web server where RooGraphviz will put its images. Make a new directory if necessary. Set permissions on the directory so the web server can create files and subdirectories.
  3. Log in to Movable Type's administration panel, then select System Overview, then Plugins. Find RooGraphviz, then select "Show Settings". Configure the paths to the required applications. Save changes.
  4. Go to the weblog in the administration panel, then select Settings, then "Plugins." Find RooGraphviz, then select "Show Settings." Set the "Destination Directory" and "Destination URL", and confirm that the other settings are appropriate. Save changes.

To use the plugin, include a Roo tag for the "dot" filter in a blog entry. The default mode is specified in configuration. To select "dot", "neato" or "twopi" when it isn't the default, specify the command as a (valueless) parameter, e.g. <% Roo:dot[neato] %>, or as a value to the "cmd" parameter.

RooGraphviz also supports the following parameters to override their corresponding settings in the configuration:

Here is an example of RooGraphviz in action:

It's important to know the classification of animals.

<% Roo:dot %>
digraph hierarchy {
node [fontname=Courier]
Animals->{ Mammals Reptiles }
Mammals->{ Dogs Cats }
Reptiles->{ Iguanas }
}
</% Roo %>

As you can see, an iguana is not a mammal.

This example will appear in the blog entry as:

It's important to know the classification of animals.

RooGraphviz example

As you can see, an iguana is not a mammal.

RooSpell

RooSpell is made possible by Builderoo mainly because there is no good way for a plugin to modify the display of the entry preview page other than to be the text filter for the entry. Without Builderoo, only one text filter can be applied to the entry, so either the text filter is the spell checker, the text filter is not the spell checker, or the spell checker has to be built into another text filter. With Builderoo, multiple text filters can be applied to an entry, so RooSpell can perform the preview-only highlighting of misspelled words, while other text filters can still do their jobs. Builderoo can also shield other sections, such as computer source code or RooLaTeX mark-up, from being spell-checked during preview.

RooSpell is a spelling checker for blog entries. When you preview an entry, misspelled words are highlighted, with spelling suggestions shown when you hold the mouse pointer over a misspelled word. The highlights do not appear when the entry is published.

RooSpell requires that Ispell be properly installed on the server running Movable Type. Ispell is usually available on most Unix-based systems.

Be sure to determine which version of Ispell is on your system and adjust the RooSpell configuration accordingly. In particular: The -H flag that ignores text in HTML tags was not implemented until Ispell 3.2. If you have Ispell 3.1 or earlier, you will have to remove the -H from the default configuration. (You can make up for the lack of this feature by configuring RooSpell to ignore HTML keywords, like "img" and "alt".) To determine your version of Ispell, run ispell -v on the command line.

To install the plugin, copy the roospell directory from the examples/ directory to Movable Type's plugins/ directory. Log in to the Movable Type administrative interface, select System Overview, "Plugins", find RooSpell and select "Show Settings". Confirm that the settings are correct.

Finally, use Builderoo's base filter settings for your weblog to make the "spell" filter the last base filter. (If "spell" were not the last filter, it may insert mark-up for misspelled words that may confuse later filters. In particular, if the "Convert Line Breaks" filter comes after RooSpell, it will add extraneous HTML mark-up to RooSpell's stylesheet, and misspelled words may not be highlighted properly.)

You can add words to RooSpell's dictionary specific to each weblog using the weblog's plugin settings panel.

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