2. Block Parameters

2.1. The DATA Block Parameter

Sometimes the insertion of simple static content into the output will not suffice for projects of moderate complexity. A designer frequently wishes to repeat elements throughout the page, keeping a consistent look and structure. BML provides this functionality by allowing you to declare blocks which take parameters, that can then be used in building the content inserted into the document.

The simplest parameter-accepting block is the one you saw in the examples earlier. 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%%.

Example 1.4. Lookup file with DATA blocks

heading=><h1>%%DATA%%</h1>
subheading=><h2>%%DATA%%</h2>

This lookup file defines two blocks; one called heading which creates level-one heading HTML markup, and another called subhead, which creates level-two headings.

You could use these like this:

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 Archetypal 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 Archetypal 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 headings would always be expressed with <h1> tags, and subheadings with <h2> tags, it might be more efficient to leave them as static HTML. If 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 only need to change the definition of what a heading means in one place, to 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. Nonetheless, they demonstrate a use which parallels the role played by style systems.

2.2. Block Flags and Passing Multiple Parameters

Many tasks cannot be accomplished with blocks that have only one parameter, so BML provides another kind of block that can be passed multiple parameters. Until now we've used blocks with an implied parameter, so we'll need to tell BML that the block we are defining is different. We do this by specifying one or more flags when declaring the block. Flags are single letters 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 blocks declared above have an {F} flag, while 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 different from the simple references made to {D} blocks. Calls to a block that requires multiple parameters uses the same syntax you use 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 are single-line parameters (id and heading), while a third is a multi-line one (body). The output rendered after 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>

2.3. Parameterized Output: Positional Parameters

In addition to named parameters, BML supports positional parameters. As with named parameters, you designate a block with positional parameters with a flag. This time it is 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 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=>2007/11/02
items<=
<?linkitem News of Brad|http://brad.livejournal.com/|Brad's daily adventures 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 adventures</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: 2007/11/02</small></p>