The template system facilitates the separation of HTML from c;
that is to say, the presentation of data from the generation
of that data. It accomplishes this through the use
of macros and dynamic blocks in the template file.
The term parse as used here really has more the meaning
of expand. The reason is historical.
A macro is identified by any sequence of the form
{name},
where name
consists entirely of alphanumeric characters or underscores,
and is used to
identify the macro within the program.
A macro can acquire a value, a string, by one of three ways:
In the latter case the value of the macro becomes text of the template,
with all internal macros and dynamic blocks expanded.
A dynamic block is identified by a sequence
of the form,
<!-- BEGIN DYNAMIC BLOCK: name --> HTML code
<!-- END DYNAMIC BLOCK: name -->
where name
consists entirely of alphanumeric characters or underscores,
and is used to
identify the block within the program.
The 'BEGIN' and 'END' tags must be on lines by themselves.
They cannot be mixed with other text on the same line.
Each time a dynamic block is parsed,
the resulting text, including all
macros or nested dynamic blocks, are added to the value of the enclosing
template.
WebTemplate allows an abbreviation of the block identifier. So
the above pattern could look like this:
<!-- BDB: name --> HTML code
<!-- EDB: name -->
The BDB and EDB still have to be by themselves on the line, however.
The library allows comments in template files.
Comments are identified by caller-defined markers in the
template text.
int WebTemplate_parse_dynamic(WebTemplateW, char*block_name)
Arguments:
W:
A WebTemplate
block_name:
Identifier of the block to be parsed
Return:
0 if OK; 1 if template not found.
Errors:
Notes:
Evaluates all macros and nested blocks
and adds the resultant text to this block's parent template.
The block's identifier is a dotted concatenation of the template's
name, the names of any enclosing blocks, and this block's name.
For example, the identifier of a block named "item", within
a block named "list", in the template "page", would
be "page.list.item".
It allows persistant cgi programs to setup for
a new page.
Form and cookie API
The template package includes some convenience routines
for managing cookies and parsing form data.
Parameters, whether from a form or the QUERY_STRING, consist
of name and value pairs. Both the names and values are strings.
A name may appear without a value.
A name may appear more than once
and thus acquire multiple values. No distinction is made
between parameters acquired from forms or from QUERY_STRING arguments,
except that the form values are processed first.
Cookies, received and sent with headers, are also name and
value pairs.
In addition, the template system stores the REMOTE_USER
environment variable, set by the web server on authenticated
requests, in the global variable remote_user.
NOTE
Comments in this file are delimited by 'NOTE' and 'ENDNOTE'
ENDNOTE
<html>
<head>
<title>{TITLE}</title>
</head>
<body>
{BODY}
</body>
</html>
list.tpl
# comments in this file are identified by leading '#'
<h1>{TITLE}</h1>
<p>
<table colsep=3>
<tr><td align=right>n</td><td align=right>n!</td></tr>
<!-- BEGIN DYNAMIC BLOCK: num -->
<tr><td align=right>{N}</td><td align=right>{NFACT}</td></tr>
<!-- END DYNAMIC BLOCK: num -->
</table>
This program
/* Show factorials */
main()
{
WebTemplate W;
int n;
int f = 1;
char txt[12];
/* Initialize */
W = newWebTemplate();
/* Write the headers */
WebTemplate_header(W);
/* Load the two templates */
WebTemplate_set_comments(W, "NOTE", "ENDNOTE");
WebTemplate_get_by_name(W, "page", "page.tpl");
WebTemplate_set_comments(W, "#", NULL);
WebTemplate_get_by_name(W, "list", "list.tpl");
/* Set the title */
WebTemplate_assign(W, "TITLE", "10 factorials");
/* Make a line for each number */
for (n=1;n<11;n++) {
f = n * f;
sprintf(txt,"%d",n);
WebTemplate_assign(W, "N", txt);
sprintf(txt,"%d",f);
WebTemplate_assign(W, "NFACT", txt);
WebTemplate_parse_dynamic(W, "list.num");
}
/* Make the body of the page */
WebTemplate_parse(W, "BODY", "list");
/* Make the page */
WebTemplate_parse(W, "PAGE", "page");
/* Write the page */
WebTemplate_write(W, "PAGE");
exit (0);
}