[mypage::header "HTML/Tcl Templates"]
<p>
A Tcl template works by mixing Tcl code into normal HTML pages.
The server uses the Tcl subst command to replace the Tcl code and
variable references with their results and values.
Here are a few examples:

 Tcl fragment Result
[html::foreach {code} {
  {[Httpd_Version]}
  {[clock format [clock seconds]]}
  {$Doc(root)}
  {[expr 7 * 826]}
} {
   $code [subst $code]
}]

<p>
There are two template systems provided by the Doc module:
tml and subst templates.  They both work
in a similar way to replace in-line Tcl,
but they differ in the setup done before a page is processed.

Simple "subst" Templates

If you have a file
that ends with ".subst",
then it is processed every time the page is fetched.
There is relatively little setup done before processing the page.

tml Templates
The ".tml" template system is similar to the ".subst" system,
but it provides caching and additional
setup before pages are processed.

Caching Template Results
<p>
The ".tml" template system provides caching of template results
in static ".html" files.  This saves the cost of re-processing the
template each time you access the file.
By default, the file page.html contains the cached results
of processing the file page.tml.  If the page.tml
page is modified, the cached copy is regenerated.  To get the
cache, you have to ask for the page.html file.  The server
automatically checks to see if there is a corresponding page.tml
file, processes the template, caches the result in page.html,
and returns the result.
<p>
However, you don't want
to cache if the page must be processed on each access.
If you don't want your templates cached, put a call to

\[Doc_Dynamic\]
into your page.  That surpresses the caching of the template results.

Per-directory .tml files
<p>
Before processing a page.tml page, the server loads
any file named ".tml" (no prefix) in the same directory.
This allows you to put procedure and variable definitions in
the ".tml" file that are shared among the pages in that directory.
<p>
The server looks up the directory hierarchy to the document root
for additional ".tml" files.  These are all loaded in order from the
root down towards the directory containing the template file page.tml.
If you look at the sample htdocs tree that comes with the server,
you can see how these .tml files are used.

More Examples

- A self modifying page lets you try out
a few things yourself.

- FAQ Generator example that illustrates
how to use
the faq module in the sample custom directory.

- Templates with Form Data
If you want to process query data, it is available via the ncgi
interface, and indirectly via the html interface used
to create form elements.

[mypage::footer]
