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. There are three modifiers to variable expansion:

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). There are three variations:

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:

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 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):

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.

Page tools: View Source, Add Comment.
Search:
Login: Password:
Atom Syndication: Recent Comments.
Last modified: Tue Sep 27 16:59:21 2005
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.