Template files are the main way to create interesting web pages in MillScript. They are written in XHTML augmented with some custom tags. It is easy to write new custom tags in MillScript (or even in Java) to capture some common design motif.
Template files are found in the inventory and are given the extension ".tp". (This extension is important because it signals to the MillScript interpreter that the special template compiler is required.) A template can be a tiny document fragment or an entire page. In either case, they are compiled into a MillScript function and assigned to a variable whose name matches that of the file. So, if you see a template file "menu.tp" you can access it in MillScript through the variable "menu". Simply referring to that variable will cause MillScript to search the inventory and autoload the relevant file.
We call the compiled function the "template function" in order to distinguish it from the "template file".
Almost always, templates require arguments. These can be passed in as
arguments to the template function. Such arguments are specified by
the arg element, or indexing the arg list.
In order to make it possible to view a template in a browser, most custom tags only look at their attributes and ignore their children. As a result, you can insert helpful text inside a custom tag so that a browser, such as navigator or explorer, will ignore the unknown tag but display the useful text.
Templates are written in XHTML augmented with some custom tags, to access template arguments and execute millscript code.
Template arguments are generally accessed by the arg
element, e.g.
<arg n="1"/>
As you have probably already guessed, the "n" attribute specifies
the argument by position. The first argument is n="1",
the second is n="2" and so on. However, since this is
a bit longwinded the first 9 arguments have the obvious shortcuts
arg1 to arg9.
These arguments are bound to a list called arg and can
be accessed as arg[1], arg[2], and so on.
This means they can be incorporated into expressions using the
features described below.
You can also refer to template arguments within comments, using the
familiar format
function syntax, e.g. the following example uses %2p to
include the value of the second argument in the comment:
<!-- This is a comment with the following variable bit: %2p -->
Templates can also use simple MillScript expressions to substitute
attributes and children. Let us suppose you wanted to make the
"bgcolor" attribute of the body element depend on a MillScript
variable color. You would write a template something
like this;
<html>
<head>
</head>
<body bgcolor="?color">
<arg1><i>The contents go here</i></arg1>
</body>
</html>
The key is the use of the initial "?". This signals to the template compiler that the attribute is not a literal string but a simple MillScript expression. (How simple? It must obey the rules of XML. That's the real constraint.)
To substitute the value of a MillScript expression in normal element content, you should use the "item" element. This has a single attribute named "val" whose value is expected to be a simple MillScript expression. e.g. To substitute the variable "mainBody" into the body of a template we would write something like this;
<html>
<head>
</head>
<body bgcolor="?color">
<item val="mainBody">
Substitute mainBody here
</item>
</body>
</html>
Note that we do not need the leading "?" this time (although if you put it in it does not matter, it is simply stripped off.) That is because "item" knows that the value of the "val" attribute is always MillScript and never a plain string.
In both of these cases(using an "item" tag, or an attribute starting with a "?") you could refer to one of the templates arguments, e.g. to refer to the second argument to the template you could use either of the following examples:
<html>
<head>
</head>
<body bgcolor="?arg[2]">
<item val="arg[2]">
Substitute the second argument here
</item>
</body>
</html>
tp file in your inventory, containing the
required XHTML, arguments and expressions, as detailed in the file format. e.g Lets assume you create a
file called simple.tp.
<html>
<head>
</head>
<body bgcolor="?color">
<arg1>The template body</arg1>
<!-- The following paragraph uses %2p as it's style -->
<p style="?arg[2]">
Some text
</p>
</body>
</html>
simple
var color = "#FEFEFE";
simple( <b>"the replacement body text"</b>, "color: red" );
simple,
would return:
<html>
<head>
</head>
<body bgcolor="#FEFEFE">
<b>"the replacement body text"</b>
<!-- The following paragraph uses color: red as it's style -->
<p style="color: red">
Some text
</p>
</body>
</html>