HTML + Tcl Templates 251
• Each .html file has a corresponding .tml template file. This feature is
enabled with the
Doc_CheckTemplates command in the server’s configura-
tion file. Normally, the server returns the
.html file unless the correspond-
ing
.tml file has been modified more recently. In this case, the server
processes the template, caches the result in the
.html file, and returns the
result.
• A dynamic template (e.g., a form handler) must be processed each time it is
requested. If you put the
Doc_Dynamic command into your page, it turns off
the caching of the result in the
.html page. The server responds to a request
for a
.html page by processing the .tml page. Or you can just reference the
.tml file directly. If you do this, the server always processes the template.
• The server creates a
page global Tcl variable that has context about the
page being processed. Table 18–7 lists the elements of the page array.
• The server initializes the
env global Tcl variable with similar information,
but in the standard way for CGI scripts. Table 18–8 lists the elements of the
env array that are set by Cgi_SetEnv in cgi.tcl.
• The server supports per-directory "
.tml" files that contain Tcl source code.
These files are designed to contain procedure definitions and variable set-
tings that are shared among pages. The name of the file is simply "
.tml",
with nothing before the period. This is a standard way to hide files in
UNIX, but it can be confusing to talk about the per-directory "
.tml" files
and the
file.tml templates that correspond to file.html pages. The
server will source the "
.tml" files in all directories leading down to the
directory containing the template file. The server compares the modify time
of these files against the template file and will process the template if these
"
.tml" files are newer than the cached .html file. So, by modifying the
"
.tml" file in the root of your URL hierarchy, you invalidate all the cached
.html files.
• The server supports a script library for the procedures called from tem-
plates. The
Doc_TemplateLibrary procedure registers this directory. The
server adds the directory to its
auto_path, which assumes you have a
tclIndex or pkgIndex.tcl file in the directory so that the procedures are
loaded when needed.
Where to put your Tcl Code
There are three places you can put the code of your application: directly in
your template pages, in the per-directory "
.tml" files, or in the library directory.
The advantage of putting procedure definitions in the library is that they
are defined one time but executed many times. This works well with the Tcl byte-
code compiler. The disadvantage is that if you modify procedures in these files,
you have to explicitly source them into the server for these changes to take effect.
The
/debug/source URL described on page 264 is handy for this chore.
The advantage of putting code into the per-directory "
.tml" files is that
changes are picked up immediately with no effort on your part. The server auto-