BML Home : BML Tutorial |

# BML Tutorial

In this section I will attempt to walk you through the basics of creating a very simple BML document and hopefully give you a glimpse of BML's power and flexibility. The goal of this all is for you to learn how to become lazier and have your website become cooler at the same time. Stick with me and re-read sections if they're hard to understand because I've written them terribly. `:)`

Here we go... First off, any HTML document is a valid BML document. Once you have BML installed on your webserver, you could potentially rename all your documents to BML and leave it at that, but you wouldn't be harnessing any of BML's usefulness. However, that's what you should do to start off.

Let's pretend you already have a pretty well designed site and the look of it all is pretty much consistent throughout. However, you want to make a change to something---color, structure, layout, whatever. Do you want to go and modify every single page? Not really. This is where BML gets really useful. However, first we must define our document in terms of BML blocks, not gobs of HTML tags. Here's our document to start with...

    <HTML>
    <HEAD><TITLE>Iguana Recipes</TITLE></HEAD>
    <BODY BGCOLOR=#DDDDFF TEXT=#000000 LINK=#009900 VLINK=#FFC000>

    <P ALIGN=CENTER>
    <FONT SIZE=+3 FACE="Arial" COLOR=#FF0000>Iguana Recipes</FONT>
    </P><HR>

    <P><FONT SIZE=+1><B>Intro</B></FONT>
    <BR>Do you like iguanas?  If so, you should consider the
    following recipes on how to cook iguanas into a tasty meal...

    <P><FONT SIZE=+1><B>Appetizers</B></FONT>
    <BR>Iguana legs, iguana eyeballs, it's food a whole family
    can enjoy!

    </BODY>
    </HTML>

This sample document appears to be a fairly simple page, entitled "Iguana Recipes". To begin, there is some large centered text with the title of the page (which also appears in the TITLE in the HEAD section). After that there are two headings, Intro and Appetizers, both with text under them.

One of the main ideas of BML is to cut down on repetition by shoving commonly used stuff into templates, called blocks. The block definitions get stored in one or more .look files. Simple sites, and new sites using BML will only use the global.look file.

The first thing we need to do to begin simplifying the HTML document above is to identify parts which are repitious and define BML blocks for them. The first thing I notice is that the heading code, for "Intro" and "Appetizers", is used twice. Let's define a block for that named, say, H1. Note that this name has nothing to do with the HTML tag H1, I just use the name often for its shortness and because there are often different levels of headings and numbering them is much easier than having a bunch of different heading names to remember.

Anyway, here's the beginning of our global.look file:

    H1=>{D}<P><FONT SIZE=+1><B>%%DATA%%</B></FONT>

Let's look at this piece by piece. First off, the `H1` is the name of our block. The `=>` mark means that this block definition is just a single-line definition and ends at the end of the line. The `{D}` identifies what type of block this is. There are different types of blocks that are commonly used which will be discussed as we use them. The 'D' block is a simple block in which there is only one property being passed into the block, named DATA. This type of block is the default; I could've left it unspecified for this introductory purpose, but it's good practice to always tack it on. Everything after the block identifier is the template information, with the double percent signs around variable names. The %%DATA%% will later become whatever heading text we pass it.

Now, back to our BML document, which I've changed to now utilize our newly formed BML block H1:

    <HTML>
    <HEAD><TITLE>Iguana Recipes</TITLE></HEAD>
    <BODY BGCOLOR=#DDDDFF TEXT=#000000 LINK=#009900 VLINK=#FFC000>

    <P ALIGN=CENTER>
    <FONT SIZE=+3 FACE="Arial" COLOR=#FF0000>Iguana Recipes</FONT>
    </P><HR>

    (=H1 Intro H1=)
    <BR>Do you like iguanas?  If so, you should consider the
    following recipes on how to cook iguanas into a tasty meal...

    (=H1 Appetizers H1=)
    <BR>Iguana legs, iguana eyeballs, it's food a whole family
    can enjoy!

    </BODY>
    </HTML>

You'll see that where there used to be an ugly mess of HTML is now the clean BML blocks. The `(=H1` begins the H1 block and the `H1=)` ends the H1 block. Because this is block of type {D}, everything in between the starting and ending marks is passed to the template as a single variable, named DATA.

Now let's get into something a wee bit more complicated... full blocks. Full blocks, of type {F} can have different variables passed into the template. The most common use of a full block is to make your PAGE definition. Most people use a PAGE block to avoid doing the structure of their whole page. If you think about it, the only two really necessary variables that change between pages and should be a part of the PAGE block are the title and the body. The title for our sample page would be "Iguana Recipes" and the body would be everything from the "Intro" heading to the end of the "Appetizers" section. Again, my referring to BODY as a BML block variable has nothing to do with an HTML BODY tag. Actually, we're going to hide the whole HTML BODY inside our block definition. Let's also include the large centered text into our BODY block, since it's always going to be the same, just with the page's title inserted, which we're already going to pass.

Instead of a single-line block definition like our H1 block, we're going to have to use a multi-line definition for this block. Again, we return to our global.look file and add the following...

    PAGE<=
    {F}<HTML>
    <HEAD><TITLE>%%TITLE%%</TITLE></HEAD>
    <BODY BGCOLOR=#DDDDFF TEXT=#000000 LINK=#009900 VLINK=#FFC000>

    <P ALIGN=CENTER>
    <FONT SIZE=+3 FACE="Arial" COLOR=#FF0000>%%TITLE%%</FONT>
    </P><HR>

    %%BODY%%

    </BODY>
    </HTML>
    <=PAGE

Only a few different things to note from our last block definition: the `PAGE<=` line starts a multi-line definition and the `<=PAGE` ends it. The {F} identifier means there will be multiple variables passed into this block. Note that the {F} goes at the very beginning of the first line of the definition, not right after the `<=` mark.

Now, let's confuse you some more and show you what the new BML document will look like....

    (=PAGE
    TITLE=>Iguana Recipes
    BODY<=

    (=H1 Intro H1=)
    <BR>Do you like iguanas?  If so, you should consider the
    following recipes on how to cook iguanas into a tasty meal...

    (=H1 Appetizers H1=)
    <BR>Iguana legs, iguana eyeballs, it's food a whole family
    can enjoy!

    <=BODY
    PAGE=)

What?!! It looks like a BML document and a block definition .look file! Well, yes, it kinda does. The method of specifying single-line and multi-line elements is the same, to make it a little easier to get a grasp of. What is happening here is that we really just have one block, the PAGE block. Inside that block are two variables, the single-line TITLE variable and the multi-line BODY variable.

From here, you're basically done. You could create a paragraph block named `P` to be a wrapper around your paragraphs, but that's not absolutely necessary. Remember, BML is all about being lazy. If you think a block will help you be lazy in the long run, make it. If you think it will cause unwanted complications, who cares.

This tutorial is only the start, there is a lot of stuff you can do with BML. Read the other sections for information on other features and a more detailed look at the stuff you've already learned. Just have fun with it.

Return to BML Home.