Sometimes the insertion of simple static content into the output will not suffice for projects of moderate complexity. A designer frequently wishes to repeat certain elements throughout the page, keeping a consistent structure and look-and-feel. BML provides this functionality by allowing you to declare blocks which take parameters, which can then be used in building the content inserted into the document.
The simplest parameter-accepting block is one you've seen already in the above examples. Unless otherwise designated, all blocks accept one parameter, which is put into a variable called DATA. This parameter can then be interpolated into the resulting output with a placeholder that looks like: %%DATA%%.
This lookup file defines two blocks, one called heading which creates level-one heading HTML, and another called subhead, which creates level-two headings.
These could be used like so:
Example 1.5. BML file using parameterized blocks
<html> <head><title>Hansel and Grendel Go to Finishing School</title> <body> <?heading Hansel and Grendel Go to Finishing School heading?> <p>Our story begins at a point in the Universe not unlike where you are now sitting, drinking your government-sanctioned stimulant, dreaming of the day when you, too, will own your own personalized luxury home on 0.3 acres of land, with a stunning view of, well, the neighbor's personalized luxury home on 0.3 acres of land. Except this point in the Universe is much more exciting, fine-smelling, and generally a better place to be than yours.</p> <?subheading No, Really, It Is Much Finer subheading?> <p>So, anyway, at this particular point in the Universe, on a day not entirely unlike today, two entirely unrelated mythological pantheons collided, resulting in a fast friendship between a Little Boy Bound to be Eaten by the Architypal Crone and a Faceless Beast That Waits for the Hero to Dispatch It. Which, as you might have guessed, was not the intention of the various storytellers involved, but that's what happens when people stop reading all the really cool stories and start checking the Financial Section every 12 minutes. There's only so much space to go around in the collective consciousness, you know...</p> </body> </html>
which would result in output like:
Example 1.6. Parameterized Output: Named Parameters
<html> <head><title>Hansel and Grendel Go to Finishing School</title> <body> <h1>Hansel and Grendel Go to Finishing School heading</h1> <p>Our story begins at a point in the Universe not unlike where you are now sitting, drinking your government-sanctioned stimulant, dreaming of the day when you, too, will own your own personalized luxury home on 0.3 acres of land, with a stunning view of, well, the neighbor's personalized luxury home on 0.3 acres of land. Except this point in the Universe is much more exciting, fine-smelling, and generally a better place to be than yours.</p> <h2>No, Really, It Is Much Finer</h2> <p>So, anyway, at this particular point in the Universe, on a day not entirely unlike today, two entirely unrelated mythological pantheons collided, resulting in a fast friendship between a Little Boy Bound to be Eaten by the Architypal Crone and a Faceless Beast That Waits for the Hero to Dispatch It. Which, as you might have guessed, was not the intention of the various storytellers involved, but that's what happens when people stop reading all the really cool stories and start checking the Financial Section every 12 minutes. There's only so much space to go around in the collective consciousness, you know...</p> </body> </html>
By this point, you might be saying, "But wait! I'd much rather type '<h1> ... </h1>' than '<?heading ... heading?>'!" If you were absolutely confident that headings would always be expressed with <h1> tags, and subheadings with <h2> tags, it might be more efficent to leave them as static HTML. If, however, someone wants all headings and subheadings to change throughout the site, having the definition of them expressed as a block makes changing them everywhere a simple matter of changing the block that defines them:
Example 1.7. Alternate Heading Block
heading=><h1 class="heading"><img src="logo.png"/> %%DATA%%</h1> subhead<= <!-- This is a subheading, which naturally requires a chicken above it --> <img src="chicken.png" /><br /> <h2 class="subheading">%%DATA%%</h2> <=subhead
Instead of a fairly complex search-and-replace session over multiple files, you instead need only change the definition of what a heading means in one place, and see it reflected throughout your site. Note that multiline blocks can also use the DATA parameter.
The examples above are admittedly contrived, and could probably be accomplished using CSS, but it should serve to demonstrate a use which is orthogonal to the role played by style systems.
Many tasks will not be able to be accomplished with blocks that have only one parameter, so BML provides another kind of block that can be passed multiple parameters. Up 'til now, we've been using blocks with an implied parameter, but we'll need to tell BML that the block we're defining is different. This is accomplished by specifying one or more flags when declaring the block. Flags are single letters that are placed inside curly braces ({}) at the beginning of the block definition. For example, the flag that corresponds to the full block type (which we'll be using for blocks that can accept multiple parameters) is designated with an {F} flag:
Example 1.8. Block Definitions with Flags
smallcaps=>{D}<span style="font-variant: small-caps">%%DATA%%</span>
topiclink=>{F}<a href="/topic.pl?name=%%name%%">%%linktext%%</a>
section<={F}
<div id="section-%%id%%" class="section">
<h3>%%heading%%</h3>
<p>%%body%%</p>
</div>
<=section
As you can see, two of the blocks declared above have an {F} flag, and one has a {D} flag. The {D} flag stands for 'data', which is the default block type we're already familiar with, so the flag part could have been omitted. There are other block types which specify other attributes and behaviors, but for now we'll focus on the {F} type.
In the above example, two {F} blocks are defined, a single-line one and a multi-line one. Both expect multiple parameters which they use to fill in parts of the HTML fragments they are responsible for creating. They also use placeholders like {D} blocks do, but they have unique names that will serve as the label given with the parameter that belongs there when calling it from a BML file.
Calling an {F} block necessarily looks a bit different than the simple references made to {D} blocks. Calls to a block which requires multiple parameters uses the same syntax as that used for declaring blocks:
Example 1.9. BML File
<?section id=>listrules heading=>Rules of the Lists body<= There are many considerations when engaging in mounted combat at a tourney, not the least of which is obeying the convoluted and sometimes confusing localized <em>Rules of the Lists</em>. <=body section?>
In the above example, the section block is being called with three parameters, two of which are single-line parameters (id and heading), and a third multi-line one (body). The output rendered by combining the above BML file with the previous lookup file would look something like:
Example 1.10. Example output
<div id="section-listrules" class="section"> <h3>Rules of the Lists</h3> <p>There are many considerations when engaging in mounted combat at a tourney, not the least of which is obeying the convoluted and sometimes confusing localized <em>Rules of the Lists</em>. </p> </div>
In addition to the named parameters introduced above, BML also supports positional parameters. Like with named parameters, a block with positional parameters is designated with the use of a flag, this time the {P} or "pipe-delimited" flag. Parameters in a {P} block are represented with %%DATA1%%, %%DATA2%%, etc. This can be useful when a routine takes a lot of parameters, or when calling the same block many times with tabular or list data.
An example of this is building a list of links, each of which is an item in a definition list:
Example 1.11. Block Definitions with Positional Parameters
LINKITEM=>{P}<dt><a href="%%data2%%">%%data1%%</a></dt> <dd>%%data3%%</dd>
LINKLIST<=
{F}
<h4>My Current Reading List</h4>
<dl>
%%items%%
</dl>
<p><small>Last updated: %%date%%</small></p>
<=LINKLIST
Example 1.12. BML File using the 'listlist' and 'linkitem' blocks
<?linklist date=>2004/10/14 items<= <?linkitem News of Brad|http://brad.livejournal.com/|Brad's daily adventure linkitem?> <?linkitem BoingBoing|http://boingboing.net/|A directory of wonderful things linkitem?> <?linkitem WPGtR|http://poignantguide.net/ruby/|Wow, this book comes with an onion! linkitem?> <=items linklist?>
Combining the two files above would render output like this:
Example 1.13. Example output
<h4>My Current Reading List</h4> <dl> <dt><a href="http://brad.livejournal.com/">News of Brad</a></dt> <dd>Brad's daily adventure</dd> <dt><a href="http://boingboing.net/">BoingBoing</a></dt> <dd>A directory of wonderful things</dd> <dt><a href="http://poignantguide.net/ruby/">WPGtR</a></dt> <dd>Wow, this book comes with an onion!</dd> </dl> <p><small>Last updated: 2004/10/14</small></p>