# BML Schemes

Changing your site's layout

BML is the language used to serve pages to users that they don't manage themselves. To get an idea of what BMLis, the following is a quote from the BML manual:

> The Better Markup Language

> BML is a server-side markup language that lets you define your own BML blocks and use them as templates within your BML pages. Your templates don't even have to be static. Because BML pages are converted to HTML on the server when users request them, this also enables you to embed live code within your BML pages, just like a CGI script.

With LiveJournal, we used BML because it makes it easier for us to write the layouts that comprise LiveJournal, without requiring frequent changes or rewrites on our part to come up with a customized look and feel. In the next section you will read how to make the necessary additions to the LiveJournal schemes to tailor your LiveJournal installation to your exact needs.

For more information on BML, please refer to .

## Writing a BML Scheme

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

For LiveJournal, the most common templates are defined in the file ``$LJHOME`/cgi-bin/bml/scheme/global.look`; all other schemes either replace all of the templates, or inherit whichever is not replaced.

To write your own scheme, all you have to do is write your own BML lookup file that use the same templates as ``$LJHOME`/cgi-bin/bml/global.look`. Then, implementing a new scheme becomes pretty painless:

### Creating a new BML scheme: foo:

1. Create a new file under ``$LJHOME`/cgi-bin/bml/scheme`, labelled after the scheme name (foo). For example: ``$LJHOME`/cgi-bin/bml/scheme/foo.look`. This file should contain all of the BML directives you've written for your unique layout. The first line in this file should be

       _parent=>global.look

   .

2. If you don't have a local BML configuration file (`_config-local.bml`) in your ``$LJHOME`/htdocs/` directory, you should create one now. The contents of that file should look like:

   ### Sample `_config-local.bml`

       DefaultScheme foo

3. Manually restart the apache process.

After you've written your scheme, consider adding it to the array in , so that your users can use their preferred scheme.

## BML Template Reference

For reference, here are the most commonly used BML templates in the LiveJournal repository:

### Pre-configured

The following are BML templates that are set from configuration options in ``$LJHOME`/cgi-bin/ljconfig.pl`. All templates here are defined as S (static).

- DOMAIN
- IMGPREFIX
- STATPREFIX
- SITEROOT
- SITENAME
- ADMIN_EMAIL
- SUPPORT_EMAIL

The following BML templates are defined in ``$LJHOME`/cgi-bin/bml/scheme/global.look` and are available in every scheme.

### Global

SECURITYPRIVATE

  HTML image sourcing from `/img/icon_private.gif`

SECURITYPROTECTED

  HTML image sourcing from `/img/icon_protected.gif`

LJUSER

  Given a username, it creates a properly formated LiveJournal username reference

LJCOMM

  Given a community username, it creates a properly formatted LiveJournal community username reference

LJUSERF

  Same as LJUSER, except that the link to the userinfo page includes the additional user information

HELP

  Given a URL, this provides a small link with the caption help

INERR

  Displays an error message in an easily identifiable manner (bold red text)

NEEDLOGIN

  A small blurb that's included on pages where the user is not logged in and is required to be

BADINPUT

  An error message that displays when there is an encoding problem with the user's browser

REQUIREPOST

  An error message explaining that certain user actions require POSTing information through an HTML form, rather than manually GETting the page

LOAD_PAGE_INFO

  Initializes and populates a perl array that is used to create a sidebar of links along a page layout

H1

  Top level header on a page

H2

  Sub level header on a page

P

  Generic HTML paragraph wrapper

STANDOUT

  Given a block of text, this template tries grab the user's attention by using different text and background colors

BADCONTENT

  An error message that displays when a problem (that the user can fix) has occurred during a request

DE

  A template that de-emphasizes text

EMCOLOR
EMCOLORLITE
HOTCOLOR

  Various emphasis colors

SCREENEDBARCOLOR

  A color that is used to highlight screened comments in comment threads

CHOICE

  Given 3 arguments (a URL, a title, and an explanatory blurb), this template fashions an item to be used in a CHOICES list

CHOICES

  Given 2 arguments, this template tries to construct a side by side list of options and appropriate links

PAGE

  This template is the BML template that governs the look of the entire scheme, and takes 4 arguments:

  title

    The page title

  head

    Page-specific elements that belong in a HTML head

  bodyopts

    Additional attributes for the HTML body element

  body

    The main content of the page