If you've just run through the installation section, you should now have MML working on your server, although it won't be doing anything particularly impressive, because you've yet to set up your default style. (If you've not run through the installation section, please do so before proceeding here.)
By default, MML files on your site will have the default style applied to them. MML style definitions come in three files: a template, custom tags list and some style variables.
The template file contains the actual HTML used in the template, along with the variables which are subsituted in (but we'll come onto those later). The default template file is called default.mmt and should be placed in your mml configuration directory which you set up in the Initial Configuration part of Installation.
Here is a simple MML template file, so you can see how they are structured:
<html> <head> <title>%%SYS:TITLE%%</title> <link rel="Stylesheet" href="style.css" type="text/css"> </head> <body> <h1>%%SYS:TITLE%%</h1> <div id="navbar"> <a href="index.mml">Home</a> - <a href="mailto:mart.atkins@bigfoot.com">EMail</a> - <a href="aboutme.mml">About Me</a> - <a href="mysites.mml">My Sites</a> - <a href="stuff.mml">Stuff</a> </div> <div id="mainbody"> %%SYS:BODY%% </div> <address>This site is © Martin Atkins 2000</address> </body> </html>
You will notice that this is mostly just HTML. The parts enclosed in double-percentage signs, such as %%SYS:BODY%%, are variables. The SYS: prefix indicates that they are internal variables that are set by the MML engine, not by the user.
The two internal variables you see here, SYS:TITLE and SYS:BODY represent the title and body text of the mml document respectively.
Once you have created your default.mmt, based on the one above, you are ready to create your first mml document. MML's syntax is very similar to HTML, especially since the two main tags you use are HTML tags. The following is an example mml document:
<title>About Me</title> <body> <p>I'm a 17 year old student from London in England. Hy hobbies include programming and stuff, and I listen to a lot of music, some of my all-time favourites being <em>Little Fluffy Clouds</em> by The Orb, and <em>Host</em> by The Crocketts.</p> </body>
The <title> and <body> tags above are MML tags. The contents of these are whatever is valid inside their HTML counterparts, so <body> can contain any HTML markup you like.
If you were to save the above file in some directory that the server has been configured to use MML in, as example.mml, and then access that file in your web browser from the server (using an http: url, not a file: one) you should find you get a page built from the contents of the mml file merged into the template we created previously. This is the basis of how MML works: The content is stored in a separate file to the template and the template is automatically applied before the page is delivered to the user in HTML format.
Please note: While the closing </body> tag can be safely ommitted in HTML, this is not so in MML. Ommitting MML closing tags will cause MML to not be able to locate the tag contents correctly.
The thought has probably occured to you by now that you might want certain parts of your site to look different. There are actually two different ways to do this, and this is the one you'd pick if you want to use a different style for just one page.
Other styles are created by making another template file, with the filename stylename.mmt, where stylename is the name of the style you want to create.
In order to change to this style on a particular page, you need to add another tag to the start of the document, as follows:
<mml style="blah">
This will specify that this page uses the style 'blah'. In this case, the file blah.mmt would be used as a template rather than default.mmt.
The above method for changing style is good if the style change is only for a one-off page, but if you have a site with different sections that are styled in different ways, this method will appeal to you more.
The way this works is to define certain directories of the site which will use different styles. This is all set up in the mml.conf file using path_ sections. The syntax is:
[path_/path] style=stylename
Where path is the directory you wish to affect, relative to the server's root, and stylename is the name of the style you wish to apply. For example:
[path_/~mart/] style=mart [path_/fubar/] style=coolness
In this example, the /~mart/ directory (which, on Apache, is the site of the user 'mart') will use the 'mart' style, and the directory /fubar/ will use the 'coolness' style.
One point to note is this:
[path_/fubar/blahness/] style=funky [path_/fubar/] style=coolness
You might expect with this configuration that /fubar/blahness/ will use 'funky' while /fubar/ will use 'coolness'. If you try this you will see that 'coolness' is applied to both. Why is this? It's because later settings within matching path_ sections override previous ones, so the solution is to swap over the configurations so that /fubar/ is defined first, and then /fubar/blahness/ is overridden by the other directive.
There are other settings that can be used within path_ sections. See the configuration file reference for details.
In previous sections, you've seen certain variables mentioned but I didn't go into any kind of detail about their use.
So what exactly is a variable? Variables are temporary storage areas to which you can assign values which you can use later in your MML documents and templates.
Variables come in several types: Internal Variables, which are set by the MML processor, and then three different types of user variables: Global, Style and Page.
Global variables are set in the globvar.conf file. Style variables are set in a particular style and only apply when that style is in use. Page variables are set in the MML document itself, and only apply for that document.
While style templates are set in .mmt files, style variables are set in .mmc files of the same name. blah.mmc variables only apply when the style 'blah' is in use, unless they are overridden in the mml document. Page variables are set in the <variables> section of the mml document, and override all variables of the same name defined previously.
This is an example of setting some variables:
SITENAME=Mart's Magical Site SITEOWNER=Martin Atkins SITEOWNEREMAIL=mart.atkins@bigfoot.com EMAILLINK=<a href="%%SITEOWNEREMAIL%%">%%SITEOWNER%%</a>
These particular variables would be best set in the default style, but they could be set in any of the three variable-setting areas with the same syntax.
The last line of the example deserves a special mention: as you might have guessed, the variables will be inserted into this variable when it is assigned. There are a few things to be careful of when doing this: the value that is substitited in will be the current value of the variable, as the variables are set in order from top to bottom, so make sure you assign values to the variables you want to substitute in before you actually substitute them.
I briefly mentioned internal variables in the last section. These also come in three types. Each of these types has its own prefix to differentiate it from normal variables and other special variables.
System variables are slightly oddly named, admittedly. I called
them this off the top of my head while trying to think of a prefix to use for them.
System variables use the SYS: prefix. If you've been reading
these docs from the start you should already have met SYS:TITLE
and SYS:BODY, two of the system variables supported in this
version. In addition to this, there is SYS:HEAD, which
includes content from an optional <head> section of the MML document.
Please note that the <title> section does not go
within the <head> section in an MML document.
Environment variables, using the ENV: prefix, are simply environment variables available to the script. CGI uses environment variables to give information to CGI programs. Thus, you can use these to output information about the current connection. You can find a list of some of the more oft-used environment variables in the reference section.
Time variables return different parts of the current server date and time. This allows you to include the current date and time in almost any format you require. These too are listed in the reference section, but here's a little example anyway:
The time is %%TIME:HH%%:%%TIME:NN%%:%%TIME:SS%%, on %%TIME:DOW-LONG%% %%TIME:D%%%%TIME:D-ORD%% %%TIME:M-WORDLONG%%, %%TIME:YYYY%%.
This outputs something like:
The time is 21:38:22, on Tuesday 26th June, 2001.
The MML custom tags system allows you to override certain HTML tags with alternative tags or text within the body section of an MML document. This allows you to remove the style still more from the content, by using entirely meaningful HTML markup such as headings and paragraphs in the source document and then providing alternative markup for these in the style.
Custom tags are defined in a stylename.mmz file, which should look something this...
h1=><font color="#cccc00" size="+2"> /h1=></font> standout<= <center><table cellpadding=5 bgcolor="#a7c7e8" width="%%ATTR:WIDTH%%%"> <tr><td> <=standout /standout<= </td></tr> </table></center> <=/standout
This redefines h1 to be a presentational font tag, and creates a new tag which will form a coloured box of specified width containing the contents of the tag. I don't really condone replacing meaningful markup with presentational HTML (that's what CSS is for) but you can do it if you want to. Creating new shorthand tags can be very useful, though, especially when it comes to changing the site design later and you want to change the colour of the box...
The standout tag has a multi-line replacement, as indicated by the inverted arrow on its first definition line. MML will read in all lines until it reaches a matching end marker (<=standout) and use all of the lines between to replace the tag.
You would use these tags in code as follows:
<h1>Some Heading Text</h1> <standout width="70%"> <p>This is some text in a standout box. Blah, blah blah blah, blah blah blah blah. Blah.</p> </standout>
This would create a nice red heading and a blue standout box with the settings indicated above. At a later time, those settings could be changed and this presentation altered completely.
One final use for custom tags is to limit the usage of already-existing HTML tags. Consider the following examples:
font=><font size="%%ATTR:SIZE%%"> applet=><!--applet%%ATTR:!%%--> /applet=><!--/applet%%ATTR:!%%--> param=><!--param%%ATTR:!%%-->
The first line only permits the use of the size attribute on font tags. This can be useful when maintaining a particular image and one of your content writers gets a burst of creativity and decides to render a document in bright-pink Comic Sans.
The second bunch of settings completely removes all applets and
their associated parameters. I threw in some extra stuff to demonstrate
the special %%ATTR:!%% variable, which will be replaced
with all of the attributes and their values as specified
in the original tag.
MML allows you to embed blocks of perl code into your MML documents and templates for increased flexibility and also to allow you to create web-based applications within the MML engine.
Code blocks are inclosed in <?perl ?> tags, as follows:
<?perl print "<span style="font-size: 3em;">Hello, World!</span>\n"; ?>
In the final HTML document, the code block will be replaced by whatever it printed to its standard output, or an HTML comment containing an error message if there was a problem executing the code.
Some convenience variables and functions are provided to make it easier to write these code blocks, which you can read about in the Code Blocks section of the reference.
A point to note is that perl variables will not persist between code blocks. If you'd like to make a variable, sub or module available to code blocks you must set these up within a global initialisation script or within a page initscript.
A global initscript can be set up in the [codeblock] section of the configuration file, setting initscript=filename, where filename is the name of a file within your mml configuration directory containing only perl code.
A page initscript can be included in the <initscript> section
of an MML document, as follows:
<title>Demo of initscript</title> <body><?perl print $variable; ?></body> <initscript> $variable="I was set in the initscript."; </initscript>
There are two important caveats with initscripts. Firstly, you must not
print anything from them. If you do, you'll break
the script output and cause an Internal Server Error. There is one
exception to this: If, during the script, something is found
to be wrong that would make it bad to continue rendering, you can
ask MML to halt the request by giving a return value of 2. However,
if you do this you must provide a valid CGI response, including headers,
within the initscript.
Secondly, if there is a compile error with your initscript, MML will output an internal server error containing those errors and stop. Make sure your initscripts are correct.
All MML convenience variables and functions are available in
initscripts, with the addition of MML::addheader() which
can be used to add HTTP headers to the final MML response to set
cookies etc. You can also set the value of $MML::PageStyle and
$MML::PageTitle to programmatically set the MML style
and title used, respectively.