= What Templates Can Contain

Templates are literal text except for four magic template expansions
(call them substitutions or macros if you want): _${...}_, _#{...}_,
_@{...}_, and _%{...}_.

Generally, it is a fatal error for any of the expansions not to work:
undefined variables, missing templates, no renderer by the name you
listed in the template, etc.

_${...}_ inserts the value of the named
[[global variable GlobalVariables]]. There are three modifiers to
variable expansion:
* _${|var1|var2|...}_ is *alternatives*: it inserts the value of the
  first of var1, var2, etc that are defined.
* _${?...}_ is *error-free* expansion: it makes it not an error for
  the rest of the expansion to use undefined variables; instead
  an empty result is inserted. _${?|...|..}_ works.
* _${!...}_ is *cancelling* expansion: if the variable or variable sequence
  isn't defined, the whole template produces nothing.
A _?_ or _!_ modifier must come before a _|_ modifier.

Variable expansion always produces valid HTML-quoted results.

_@{...}_ invokes the named renderer and inserts its output. That's it;
renderers take no arguments (or guff).

_%{...}_ invokes the named renderer and inserts its output, *except*
that if the renderer produces no output the entire template will
produce no output. Thus a template consisting of
>  Last modified: %{lastmodified} <br/>
is entirely empty if the _lastmodified_ renderer produces nothing,
instead of being 'Last modified:' and a line break (which would look
ugly).

_#{...}_ is template inclusion: the named template is recursively
expanded. Template names are just file names for files under the
template root directory (set in DWiki's
[[configuration file ConfigurationFile]]).
There are three variations:
* _#{|t1|t2|...}_ is *alternative* expansion: it inserts the first of
  t1, t2, etc that expanded to something non-blank.
* _#{?t1|t2|...}_ is *conditional* expansion: it only expands the
  additional templates if t1 expanded to something.
* _#{<t1[|t2|...]}_ and _#{!t1[|t2|...]}_ are *first found* expansion,
  and requires a longer explanation.

== First Found Expansion

First found expansion is a way of testing a number of possibly
existing templates and using the first one that actually exists.
With the _#{!...}_ form it is a fatal error for no template to be
found; with the _#{<...}_ form it is not, and the whole expansion is
just empty.

Each of the t1, t2, etc alternatives are paths, augmented with
*expansion operators*. There are two:
* _$(~~<varname>~~)_ expands a [[global variable]], like _${...}_ at the
  template level. (Unlike _${...}_, the variable expansion is not
  HTML-quoted.)
* _...~~<rest>~~_ first tries the full path _<rest>_, and then tries
  backing up to each of _<rest>_'s parent directories until they run out.
  (That's a literal three dots at the start.)

An example may help. With a _$(pagename)_ of ((dwiki/TemplateSyntax))
and a _$(view-format)_ of _normal_, 
the template inclusion
>  #{<Overrides/...$(pagename)/magic.tmpl|default/$(view-format).tmpl}
would first try Overrides/dwiki/TemplateSyntax/magic.tmpl, then
Overrides/dwiki/magic.tmpl, then Overrides/magic.tmpl, and finally
default/normal.tmpl.

== An example:
This DWiki uses %{..} and #{|t1|t2} expansion to produce a nice
message about a directory being entirely empty of pages if it is,
instead of 'The following pages are available in this directory:'
followed by nothing at all. (You can see this at Tests/SubTestDir.)

A simplified version of the template for directories is:
>  #{structure/header.tmpl}
>  <h1> Directory ${pagename} </h1>
>  #{|dir/dirconts.tmpl|dir/dirempty.tmpl}
>  #{structure/footer.tmpl}

The _dir/dirconts.tmpl_ template is:
>  <p>The following pages are available in this directory: %{listdir}</p>
while the the _dir/dirempty.tmpl_ template is:
>  <p> This directory is empty. </p>

The _%{listdir}_ in dirconts.tmpl makes the entire template empty if
the _listdir_ renderer returns nothing (ie, the directory is
empty). Then the _#{|..|..}_ sees that the first template is empty and
goes on to use diremtpy.tmpl. If there are files in the directory, the
dirconts.tmpl template has content and dirempty.tmpl does not get
used.

== Available renders

For convenience (mostly [[People/ChrisSiebenmann]]'s), here is the
canonical list of all available renderers. This is generated by the
code itself, so is is guaranteed to be 100% accurate (at least for
names; your mileage may vary for documentation):

{{DocAll:renderers}}

For quite a lot of these, the best real documentation is to see how
they are used in the default DWiki template set. (Which is
unfortunately a bit of a dark twisted maze at the moment.)

Renderers normally produce things about or from the current page,
although some of them (for use in peculiar context) operate on other
things.  Unless otherwise specified, all renderers are silent if they
can't produce something appropriate, which is handy for use in
_%{....}_ or just in general.