**%TMPL:<key>%**
and **%TMPL:<key>\{"attr"\}%**
.
- Directives:
- **%TMPL:INCLUDE\{"file"\}%**
: Includes a template file. The file is found as described [[below|Main/WebHome#FindingTemplates]].
- **%TMPL:DEF\{"block"\}%**
: Define a block. Text between this and the `%TMPL:END%` directive is not used in-place, but is saved for later use with `%TMPL:P`. Leading and trailing whitespace is ignored.
- **%TMPL:END%**
: Ends a block definition.
- **%TMPL:P\{"var"\}%**
: Includes a previously defined block.
- **%\{...\}%**
: is a comment.
- Two-pass processing lets you use a variable before or after declaring it.
- Templates and [[TWikiSkins]] work transparently and interchangeably. For example, you can create a skin that overloads only the `twiki.tmpl` master template, like `twiki.print.tmpl`, that redefines the header and footer.
- %H% Use of template directives is optional: templates work without them.
- %X% **NOTE:** Template directives work only for templates: they do not get processed in normal topic text.
TMPL:P also supports simple parameters. For example, given the definition `%TMPL:DEF{"x"}% x%P%z%TMPL:END%` then `%TMPL:P{"x" P="y"}%` will expand to `xyz`.
Note that parameters can simply be ignored; for example=%TMPL:P\{"x"\}%= will expand to x%P%z.
Any alphanumeric characters can be used in parameter names. You are highly recommended to use parameter names that cannot be confused with [[TWikiVariables]].
Note that three parameter names, `context`, `then` and `else` are **reserved**. They are used to support a limited form of "if" condition that you can use to select which of two templates to use, based on a _context identifier_:
%TMPL:DEF{"link_inactive"}%%TMPL:END%
%TMPL:P{context="inactive" then="inactive_link" else="active_link"}% for %CONTEXT%
When the "inactive" context is set, then this will expand the "link\_inactive" template; otherwise it will expand the "link\_active" template. See [[IfStatements]] for details of supported context identifiers.
### Finding Templates
Templates are stored either in the **twiki/templates**
directory, or can also be read from user topics. As an example, **twiki/templates/view.tmpl**
is the default template file for the **twiki/bin/view**
script.
Templates that are included using `%TMPL:INCLUDE%` are also found using the same search algorithm, unless you explicitly put `'.tmpl'` at the end of the template name. In this case, the string is assumed to be the full name of a template in the `templates` directory, and the algorithm isn't used.
TWiki uses the following search order to determine which template file or topic to use for a particular script. The _skin path_ is set as described in [[TWikiSkins]].
> 1. templates/%RED%web%ENDCOLOR%/%RED%script%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl for each %RED%skin%ENDCOLOR% on the skin path
> - %X% this usage is supported **for compatibility only** and is **deprecated**. Store web-specific templates in TWiki topics instead.
> 2. templates/%RED%script%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl for each %RED%skin%ENDCOLOR% on the skin path
> 3. templates/%RED%web%ENDCOLOR%/%RED%script%ENDCOLOR%.tmpl
> - %X% this usage is supported **for compatibility only** and is **deprecated**. Store web-specific templates in TWiki topics instead.
> 4. templates/%RED%script%ENDCOLOR%.tmpl
> 5. The TWiki topic %RED%web%ENDCOLOR%.%RED%topic%ENDCOLOR% if the template name can be parsed into %RED%web%ENDCOLOR%.%RED%topic%ENDCOLOR%
> 6. The TWiki topic %RED%web%ENDCOLOR%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
> 7. The TWiki topic %RED%web%ENDCOLOR%.%RED%Script%ENDCOLOR%Template
> 8. The TWiki topic TWiki.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
> 9. The TWiki topic TWiki.%RED%Script%ENDCOLOR%Template
>
> **Legend:**
>
> - %RED%script%ENDCOLOR% refers to the script name, e.g `view`, `edit`
> - %RED%Script%ENDCOLOR% refers to the same, but with the first character capitalized, e.g `View`
> - %RED%skin%ENDCOLOR% refers to a skin name, e.g `dragon`, `pattern`. All skins are checked at each stage, in the order they appear in the skin path.
> - %RED%Skin%ENDCOLOR% refers to the same, but with the first character capitalized, e.g `Dragon`
> - %RED%web%ENDCOLOR% refers to the current web
For example, the `example` template file will be searched for in the following places, when the current web is `Thisweb` and the skin path is `print,pattern`:
1. `templates/Thisweb/example.print.tmpl` _deprecated; don't rely on it_
2. `templates/Thisweb/example.pattern.tmpl` _deprecated; don't rely on it_
3. `templates/example.print.tmpl`
4. `templates/example.pattern.tmpl`
5. `templates/Thisweb/example.tmpl` _deprecated; don't rely on it_
6. `templates/example.tmpl`
7. `Thisweb.PrintSkinExampleTemplate`
8. `Thisweb.PatternSkinExampleTemplate`
9. `Thisweb.ExampleTemplate`
10. `TWiki.PrintSkinExampleTemplate`
11. `TWiki.PatternSkinExampleTemplate`
12. `TWiki.ExampleTemplate`
Template names are usually derived from the name of the currently executing script; however it is also possible to override these settings in the `view` and `edit` scripts, for example when a topic-specific template is required. Two preference variables can be user to override the templates used:
- `VIEW_TEMPLATE` sets the template to be used for viewing a topic
- `EDIT_TEMPLATE` sets the template for editing a topic.
If these preferences are set locally (using _Local_ instead of _Set_) for a topic, in [[WebPreferences]], in [[Main.TWikiPreferences|Main/TWikiPreferences]], or [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] (using _Set_), the indicated templates will be chosen for `view` and `edit` respectively. The template search order is as specified above.
## Master Templates
Master templates use the block definition directives (`%TMPL:DEF` and `%TMPL:END%`) to define common sections that appear in two or more other templates. **twiki.tmpl**
is the default master template.
> Template variable: | >Defines: | >
---|---|
%TMPL:DEF{"sep"}% | >"|" separator | >
%TMPL:DEF{"htmldoctype"}% | >Start of all HTML pages | >
%TMPL:DEF{"standardheader"}% | >Standard header (ex: view, index, search) | >
%TMPL:DEF{"simpleheader"}% | >Simple header with reduced links (ex: edit, attach, oops) | >
%TMPL:DEF{"standardfooter"}% | >Footer, excluding revision and copyright parts | >
%TMPL:DEF{"oops"}% | >Skeleton of oops dialog | >
Topic Name: | >What it is: | >
---|---|
[[Main/WebTopicViewTemplate]] | >Error page shown when you try to view a nonexistent topic | >
[[Main/WebTopicNonWikiTemplate]] | >Alert page shown when you try to view a nonexistent topic with a non-WikiName | >
[[Main/WebTopicEditTemplate]] | >Default text shown when you create a new topic. | >
Variable: | >Description: | >
---|---|
%DATE% |
> Signature format date. See [[Main/VarDATE]] | >
%GMTIME% |
> Date/time. See [[Main/VarGMTIME]] | >
%GMTIME{...}% |
> Formatted date/time. See [[Main/VarGMTIME2]] | >
%NOP% |
> A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable like %URLPARAM%NOP%{...}% |
>
%STARTSECTION{type="templateonly"}%%BR%...%BR%%ENDSECTION{type="templateonly"}% |
> Text that gets removed when a new topic based on the template is created. See notes below. | >
%SERVERTIME% |
> Date/time. See [[Main/VarSERVERTIME]] | >
%SERVERTIME{...}% |
> Formatted date/time. See [[Main/VarSERVERTIME2]] | >
%USERNAME% |
> Login name of user who is instantiating the new topic, e.g. admin | >
%URLPARAM{"name"}% |
> Value of a named URL parameter | >
%WIKINAME% |
> [[Main/WikiName]] of user who is instantiating the new topic, e.g. admin | >
%WIKIUSERNAME% |
> User name of user who is instantiating the new tpoic, e.g. Main.admin | >
**templatetopic**
specifies [[ExampleTopicTemplate]] as the template topic to use. Here is the HTML source of the form:
See [[TWikiScripts]] for details of the parameters that the `edit` script understands.
%T% **TIP:** You can use the `%WIKIUSERNAME%` and `%DATE%` variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is: **-- %WIKIUSERNAME% - %DATE%**
### Automatically Generated Topicname
If you want to make a TWiki application where you need automatically generated unique topicnames, you can use 10 X's in the edit / save URL, and they will be replaced on topic save with a count value. For example, BugIDXXXXXXXXXX will result in topics named BugID0, BugID1, BugID2 etc.
Example link to create a new topic:%BR%
[[%SCRIPTURLPATH{"edit"}%/%WEB%/BugIDXXXXXXXXXX?templatetopic=BugTemplate&topicparent=%TOPIC%&t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]=
## Master Templates by Example
Attached is an example of an oops based template `oopsbase.tmpl` and an example oops dialog `oopstest.tmpl` based on the base template. %T% **NOTE:** This isn't the release version, just a quick, simple demo.
### Base template oopsbase.tmpl
The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing `%TMPL:P{"sep"}%`
> > %TMPL:DEF{"sep"}% | %TMPL:END% > <html> > <head> > <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> > <base href="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%"> > <meta name="robots" content="noindex"> > </head> > <body bgcolor="#FFFFFF"> > <table width="100%" border="0" cellpadding="3" cellspacing="0"> > <tr> > <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> > <a href="%WIKIHOMEURL%"> > <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> > </td> > <td> > <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> > <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> > </td> > </tr> > <tr bgcolor="%WEBBGCOLOR%"> > <td colspan="2"> > %TMPL:P{"webaction"}% > </td> > </tr> > </table> > --- ++ %TMPL:P{"heading"}% > %TMPL:P{"message"}% > <table width="100%" border="0" cellpadding="3" cellspacing="0"> > <tr bgcolor="%WEBBGCOLOR%"> > <td valign="top"> > Topic <b>%TOPIC%</b> . { > %TMPL:P{"topicaction"}% > } > </td> > </tr> > </table> > </body> > |
>
> %TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% > %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% > %TMPL:DEF{"heading"}% > Test heading %TMPL:END% > %TMPL:DEF{"message"}% > Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... > > * Some more blah blah blah blah blah blah blah blah blah blah... > * Param1: %PARAM1% > * Param2: %PARAM2% > * Param3: %PARAM3% > * Param4: %PARAM4% > %TMPL:END% > %TMPL:DEF{"topicaction"}% > Test =topicaction=: > [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% > [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% > %TMPL:INCLUDE{"oopsbase"}% > |
>
**.../bin/oops/Sandbox/TestTopic2?template=oopstest¶m1=WebHome¶m2=WebNotify**
> > |