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 <abbrev>BML</abbrev>
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 The Alabaster Project greeting<=

Welcome to , a joint effort between the citizens of earth and Spumco, Inc.

<=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 <?project project?>

]]> Given the lookup file from the previous example, the BML file above would yield output like: Output The Alabaster Project

The Alabaster Project

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

]]> 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 <varname>DATA</varname> 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

%%DATA%%

subheading=>

%%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: BML file using parameterized blocks Hansel and Grendel Go to Finishing School ]]> ]]> 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.

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

]]> which would result in output like: Parameterized Output: Named Parameters Hansel and Grendel Go to Finishing School ]]> Hansel and Grendel Go to Finishing School heading]]> 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.

]]> No, Really, It Is Much Finer]]> 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...

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

%%DATA%%

subhead<=

%%DATA%%

<=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 {D}%%DATA%% topiclink=>{F}%%linktext%% section<={F}

%%heading%%

%%body%%

<=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 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 Rules of the Lists. <=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

Rules of the Lists

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 Rules of the Lists.

]]>
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 {P}
%%data1%%
%%data3%%
LINKLIST<= {F}

My Current Reading List

%%items%%

Last updated: %%date%%

<=LINKLIST ]]> BML File using the 'listlist' and 'linkitem' blocks 2004/10/14 items<= <=items linklist?> ]]> Combining the two files above would render output like this: Example output My Current Reading List
News of Brad
Brad's daily adventure
BoingBoing
A directory of wonderful things
WPGtR
Wow, this book comes with an onion!

Last updated: 2004/10/14

]]>
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 <literal>{S}</literal> block {S}Spumco, Inc. ]]> This defines the companyname block as static. BML File that calls the static block Welcome to ]]> Combining the two yields: Example output Welcome to Spumco, Inc. ]]>
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 <literal>{R}</literal> block Example output
A Full Example FooBar Enterprises - Page

FooBar Enterprises - Page

Headers - What good are they?

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.

Templates are for Wimps!

I'd rather have to edit all of my pages by hand when I decide to change the unified look of my site!

]]> {D}
%%DATA%%
]]> ]]>