# A Brief Tutorial

# A Brief Tutorial

The goal of using BML is to become a smarter, lazier webmaster. The qualities that define a BML author should be the same as a good Perl programmer: laziness, impatience, and hubris.

## Introducing BML

### Blocks

BML is essentially a simple macro language. Macros are called blocks in BML. Blocks are defined in look files and are invoked in BML files. Blocks accept parameters and are divided into several types according to how parameters are transmitted and how the definition of the block is able to make use of them. Definitions of blocks are essentially chunks of HTML with potentially more recursive BML block invocations inside them.

#### BML lookup file

    project=>The Alabaster Project

    greeting<=
    <p>Welcome to <?project project?>, a joint effort between the citizens of earth
    and Spumco, Inc.</p>
    <=greeting

The "project" and "greeting" constructs in the above example lookup file are blocks, and can be used to insert their respective content into HTML output. The "project" block is a single-line block that consists of everything immediately following the name of the block and the `=>` up to the end of the line. The "greeting" block is a multiline block, and contains all the lines immediately following the `greeting<=` line and preceding the `<=greeting` one.

### BML Files

A BML file is simply an HTML file with some BML block invocations in it. Each such invocation specifies the name of the block and the parameters, if any, to pass to it. The ultimate result of a block's invocation at runtime is HTML which is put in the outgoing stream exactly at the place where the block's invocation resided in the BML file.

#### BML file

    <html>
      <head><title><?project project?></title>
      <body>
    	<h1><?project project?></h1>

    	<?greeting greeting?>
      </body>
    </html>

Given the lookup file from the previous example, the BML file above would yield output like:

#### Output

    <html>
      <head><title>The Alabaster Project</title>
      <body>
            <h1>The Alabaster Project</h1>

            <p>Welcome to The Alabaster Project, a joint effort between the citizens of earth
    and Spumco, Inc.</p>

      </body>
    </html>

The block invocations in the BML lookup file example above do not contain parameters, but even so are still a powerful way of building a document out of aggregate parts. Adding parameters, of course, increases this usefulness.

## Block Parameters

### 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 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%%`.

#### 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, and another called `subhead`, which creates level-two headings.

These could be used like so:

#### 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:

#### 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:

#### 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.

### Block Flags and Passing Multiple Parameters

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:

#### 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:

#### 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 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>

### Parameterized Output: Positional Parameters

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:

#### 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

#### 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 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>

## Static Blocks

Sometimes the re-expansion of embedded BMl might not be what you want. In that case, you can designate a block with a flag which will cause it to stop or limit the re-expansion of embedded calls.

### Fully-Static Blocks

If you add the `{S}` flag to the block you're defining, the contents of it will not be re-evaluated afterward. This is mostly useful when you have blocks that you are sure will never contain BML to be expanded or properties to fill in, and you want to save the overhead of trying to re-evaluate them.

#### Look file with `{S}` block

    companyname=>{S}Spumco, Inc.

This defines the `companyname` block as static.

#### BML File that calls the static block

    <h1>Welcome to <?companyname companyname?></h1>

Combining the two yields:

#### Example output

    <h1>Welcome to Spumco, Inc.</h1>

### Semi-static Blocks

Sometimes you want a block which fits somewhere between the fully-dynamic `{D}` blocks and the completely-static behavior of `{S}` blocks. Enter the `{R}` block flag, which expands pRoperties like those passed to a `{D}`, `{F}`, or `{P}` block, but doesn't expand BML that might be inserted by one of those.

#### Look file with `{R}` block

####

#### Example output

## A Full Example

    		<html>
    		<head>
    		<title>FooBar Enterprises - Page</title>
    	  </head>
    		<body>
    		<h1 class="header">FooBar Enterprises - Page</h1>
    		<hr />
    		<div class="header"><strong>Headers - What good are they?</strong></div>
    		<p class="para" style="text-align: justify">
    		This is just an introductory text. The normal way to include text like this
    		is to write it in Latin, but since I don't know Latin, you'll have to settle
    		with this little paragraph.
    	  </p>
    		<div class="header"><strong>Templates are for Wimps!</strong></div>
    		<p class="para">
    		I'd rather have to edit all of my pages by hand when I decide to change the
    		unified look of my site!
    	  </p>
    	  </body>
    	  </html>

    		header=>{D}<div class="header"><strong>%%DATA%%</strong></div>

    		<?header Headers - What good are they? header?>