[TclHttpd] uses [subst] to generate web pages from .tml files, optionally caching the results.

1. a global page() array is populated with useful values from the environment

''Used in a template, the following outputs the template path:''

 $page(template)

2. a CGI environment is set up in env() (nb. this is a hangover from cgi and is relatively inefficient.  It can be turned off by setting Template(env) to 0)

''Used in a template, the following outputs the client browser string:''

 $env(HTTP_USER_AGENT)

3. Query data is read from the connection, and stored in page(query)

4. all .tml files back to the document root are sourced into the template interpreter (which may be the global interprester, or another interpreter dedicated to template expansion)

5. the ${template}.tml file is [subst]ed

6. errors from the [subst] are handled

7. cookies (if any) are saved

8. unless [[Template_Dynamic]] was called to inhibit the behavior, or the template was requested explicitly, the [subst] result is cached in the file with the name the user requested. ''What is the difference between this and [[Doc_Dynamic]]?''

9. the generated content is returned to the client

----
'''Extended Templates - Aggregation'''

In a recent modification/hack, a ${template}.tml is permitted to be a directory.  In that case, a file ${template}.tml/index.tml is evaluated, and its result returned to the client (after potentially being cached.)

This means that a template can, conceptually, be a collection of other files, and provides a kind of file context for processing.  An example of use might be to provide a summary or assembled page from these components.

Since [TclHttpd] will default to caching the result of evaluating ${template}.tml/index.tml as ${template}.html, and will compare the cached version against the last modification time of the whole ${template}.tml/ directory, this provides an efficient mechanism for aggregation.

Note that any directory's index.html file will now be compared by modification time to that of the whole directory, when considering generation from index.tml, thus any directory can be considered as a collection and aggregated, but since changes to a subdirectory do not propagate to its parent directory, index.tml aggregation doesn't propagate.

Use of index.tml, in combination with ${template}.tml/ generation, you can control the propagation of changes from a sub-collection to collections in which they are contained.

----

'''Hints and Tricks'''

'''Access to per-socket data''': A lot of tclhttpd context is stored in a global array called Httpd$sock where socket is the file descriptor of the current connection.  To access this data, you can use ''upvar #0 Httpd[[Httpd_CurrentSocket]] data'' and reference the array as data.

'''Working Directory''': to discover the directory containing the current template file use ''file dirname $page(filename)''.  [TclHttpd] doesn't itself presume anything about the current working directory.

'''Redirection''':

''Example:''

 [Doc_Redirect http://www.tcl.tk/]