207 lines
11 KiB
XML
207 lines
11 KiB
XML
|
<chapter id="lj.customize.layout">
|
||
|
|
<title><abbrev>BML</abbrev> Schemes</title>
|
||
|
|
<subtitle>Changing your site's layout</subtitle>
|
||
|
|
<para>
|
||
|
|
<abbrev>BML</abbrev> is the language used to serve pages to users that they don't manage
|
||
|
|
themselves. To get an idea of what <abbrev>BML</abbrev>is, the following is a quote from the
|
||
|
|
<abbrev>BML</abbrev> manual:
|
||
|
|
<blockquote>
|
||
|
|
<attribution><citetitle pubwork="book">The Better Markup Language</citetitle></attribution>
|
||
|
|
<simpara>
|
||
|
|
<abbrev>BML</abbrev> is a server-side markup language that lets you define your own
|
||
|
|
<abbrev>BML</abbrev> blocks and use them as templates within your <abbrev>BML</abbrev>
|
||
|
|
pages. Your templates don't even have to be static. Because <abbrev>BML</abbrev> pages are
|
||
|
|
converted to <abbrev>HTML</abbrev> on the server when users request them, this also enables
|
||
|
|
you to embed live code within your <abbrev>BML</abbrev> pages, just like a
|
||
|
|
<abbrev>CGI</abbrev> script.
|
||
|
|
</simpara>
|
||
|
|
</blockquote>
|
||
|
|
</para><para>
|
||
|
|
With LiveJournal, we used <abbrev>BML</abbrev> 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.
|
||
|
|
</para>
|
||
|
|
<para>For more information on <abbrev>BML</abbrev>, please refer to <xref linkend="bml.index" />.</para>
|
||
|
|
<section id="lj.customize.layout.new">
|
||
|
|
<title>Writing a <abbrev>BML</abbrev> Scheme</title>
|
||
|
|
<para>
|
||
|
|
<abbrev>BML</abbrev> is essentially a simple macro language. Macros are called
|
||
|
|
<wordasword>templates</wordasword> in <abbrev>BML</abbrev>. Templates are defined in
|
||
|
|
<wordasword>lookup</wordasword> files and are <wordasword>invoked</wordasword> in
|
||
|
|
<abbrev>BML</abbrev> 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 <abbrev>HTML</abbrev> with
|
||
|
|
potentially more recursive <abbrev>BML</abbrev> template invocations inside them.
|
||
|
|
</para><para>
|
||
|
|
For LiveJournal, the most common templates are defined in the file
|
||
|
|
<filename><envar>$LJHOME</envar>/cgi-bin/bml/scheme/global.look</filename>; all other
|
||
|
|
<wordasword>schemes</wordasword> either replace all of the templates, or inherit whichever
|
||
|
|
is not replaced.
|
||
|
|
</para><para>
|
||
|
|
To write your own scheme, all you have to do is write your own <abbrev>BML</abbrev>
|
||
|
|
lookup file that use the same templates as <filename><envar>$LJHOME</envar>/cgi-bin/bml/global.look</filename>.
|
||
|
|
Then, implementing a new scheme becomes pretty painless:
|
||
|
|
<procedure><title>Creating a new <abbrev>BML</abbrev> scheme: <replaceable>foo</replaceable>:</title>
|
||
|
|
<step><simpara>
|
||
|
|
Create a new file under <filename><envar>$LJHOME</envar>/cgi-bin/bml/scheme</filename>, labelled
|
||
|
|
after the scheme name (<replaceable>foo</replaceable>). For example:
|
||
|
|
<filename><envar>$LJHOME</envar>/cgi-bin/bml/scheme/<replaceable>foo</replaceable>.look</filename>.
|
||
|
|
This file should contain all of the <abbrev>BML</abbrev> directives you've written for your unique layout.
|
||
|
|
The first line in this file should be <programlisting>_parent=>global.look</programlisting>.
|
||
|
|
</simpara></step>
|
||
|
|
<step><para>
|
||
|
|
If you don't have a local <abbrev>BML</abbrev> configuration file (<filename>_config-local.bml</filename>)
|
||
|
|
in your <filename><envar>$LJHOME</envar>/htdocs/</filename> directory, you should create one now.
|
||
|
|
The contents of that file should look like:
|
||
|
|
<example>
|
||
|
|
<title>Sample <filename>_config-local.bml</filename></title>
|
||
|
|
<programlisting>DefaultScheme <replaceable>foo</replaceable></programlisting>
|
||
|
|
</example>
|
||
|
|
</para></step>
|
||
|
|
<step><simpara>
|
||
|
|
Manually restart the apache process.
|
||
|
|
</simpara></step>
|
||
|
|
</procedure>
|
||
|
|
</para><para>
|
||
|
|
After you've written your scheme, consider adding it to the array in <xref linkend="ljconfig.schemes" />, so that
|
||
|
|
your users can use their preferred scheme.
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
<section id="lj.customize.layout.ref">
|
||
|
|
<title><abbrev>BML</abbrev> Template Reference</title>
|
||
|
|
<para>For reference, here are the most commonly used BML templates in the LiveJournal repository:</para>
|
||
|
|
<itemizedlist>
|
||
|
|
<title>Pre-configured</title>
|
||
|
|
<para>The following are BML templates that are set from configuration options in <filename><envar>$LJHOME</envar>/cgi-bin/ljconfig.pl</filename>.
|
||
|
|
All templates here are defined as <quote>S</quote> (static).</para>
|
||
|
|
<listitem><link linkend="ljconfig.domain">DOMAIN</link></listitem>
|
||
|
|
<listitem><link linkend="ljconfig.imgprefix">IMGPREFIX</link></listitem>
|
||
|
|
<listitem><link linkend="ljconfig.statprefix">STATPREFIX</link></listitem>
|
||
|
|
<listitem><link linkend="ljconfig.siteroot">SITEROOT</link></listitem>
|
||
|
|
<listitem><link linkend="ljconfig.sitename">SITENAME</link></listitem>
|
||
|
|
<listitem><link linkend="ljconfig.admin_email">ADMIN_EMAIL</link></listitem>
|
||
|
|
<listitem><link linkend="ljconfig.support_email">SUPPORT_EMAIL</link></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
<para>The following BML templates are defined in <filename><envar>$LJHOME</envar>/cgi-bin/bml/scheme/global.look</filename>
|
||
|
|
and are available in every scheme.</para>
|
||
|
|
<variablelist>
|
||
|
|
<title>Global</title>
|
||
|
|
<varlistentry>
|
||
|
|
<term>SECURITYPRIVATE</term>
|
||
|
|
<listitem><simpara>HTML image sourcing from <filename>/img/icon_private.gif</filename></simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>SECURITYPROTECTED</term>
|
||
|
|
<listitem><simpara>HTML image sourcing from <filename>/img/icon_protected.gif</filename></simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>LJUSER</term>
|
||
|
|
<listitem><simpara>Given a username, it creates a properly formated LiveJournal username reference</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>LJCOMM</term>
|
||
|
|
<listitem><simpara>Given a community username, it creates a properly formatted LiveJournal community username reference</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>LJUSERF</term>
|
||
|
|
<listitem><simpara>Same as LJUSER, except that the link to the userinfo page includes the additional user information</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>HELP</term>
|
||
|
|
<listitem><simpara>Given a URL, this provides a small link with the caption <quote>help</quote></simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>INERR</term>
|
||
|
|
<listitem><simpara>Displays an error message in an easily identifiable manner (bold red text)</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>NEEDLOGIN</term>
|
||
|
|
<listitem><simpara>A small blurb that's included on pages where the user is not logged in and is required to be</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>BADINPUT</term>
|
||
|
|
<listitem><simpara>An error message that displays when there is an encoding problem with the user's browser</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>REQUIREPOST</term>
|
||
|
|
<listitem><simpara>An error message explaining that certain user actions require POSTing information through an HTML form, rather than manually GETting the page</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>LOAD_PAGE_INFO</term>
|
||
|
|
<listitem><simpara>Initializes and populates a perl array that is used to create a sidebar of links along a page layout</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>H1</term>
|
||
|
|
<listitem><simpara>Top level header on a page</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>H2</term>
|
||
|
|
<listitem><simpara>Sub level header on a page</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>P</term>
|
||
|
|
<listitem><simpara>Generic HTML paragraph wrapper</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>STANDOUT</term>
|
||
|
|
<listitem><simpara>Given a block of text, this template tries grab the user's attention by using different text and background colors</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>BADCONTENT</term>
|
||
|
|
<listitem><simpara>An error message that displays when a problem (that the user can fix) has occurred during a request</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>DE</term>
|
||
|
|
<listitem><simpara>A template that de-emphasizes text</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>EMCOLOR</term><term>EMCOLORLITE</term><term>HOTCOLOR</term>
|
||
|
|
<listitem><simpara>Various emphasis colors</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>SCREENEDBARCOLOR</term>
|
||
|
|
<listitem><simpara>A color that is used to highlight screened comments in comment threads</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>CHOICE</term>
|
||
|
|
<listitem><simpara>Given 3 arguments (a URL, a title, and an explanatory blurb), this template fashions an item to be used in a CHOICES list</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>CHOICES</term>
|
||
|
|
<listitem><simpara>Given 2 arguments, this template tries to construct a side by side list of options and appropriate links</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>PAGE</term>
|
||
|
|
<listitem><simpara>This template is the BML template that governs the look of the entire scheme, and takes 4 arguments:
|
||
|
|
<variablelist>
|
||
|
|
<varlistentry>
|
||
|
|
<term>title</term>
|
||
|
|
<listitem><simpara>The page title</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>head</term>
|
||
|
|
<listitem><simpara>Page-specific elements that belong in a HTML head</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>bodyopts</term>
|
||
|
|
<listitem><simpara>Additional attributes for the HTML body element</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term>body</term>
|
||
|
|
<listitem><simpara>The main content of the page</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
</variablelist>
|
||
|
|
</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
</variablelist>
|
||
|
|
</section>
|
||
|
|
</chapter>
|
||
|
|
<!--
|
||
|
|
Local Variables:
|
||
|
|
mode:sgml
|
||
|
|
sgml-parent-document: ("index.xml" "part" "chapter")
|
||
|
|
End:
|
||
|
|
-->
|