**%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. **All** text between this and the next `%TMPL:END%` directive is removed and saved for later use with `%TMPL:P`.
- **%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 aweb.atopic if the template name can be parsed into aweb.atopic
> 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 %TWIKIWEB%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
> 9. The TWiki topic %TWIKIWEB%.%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.
### TMPL:INCLUDE recusion for piecewise customisation, or mixing in new features
If there is recusion in the TMPL:INCLUDE chain (eg twiki.classic.tmpl contains `%TMPL:INCLUDE{"twiki"}%`, the templating system will include the next twiki.SKIN in the skin path. For example, to create a customisation of pattern skin, where you _only_ want to over-ride the breadcrumbs for the view script, you can create only a view.yourlocal.tmpl:
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"breadcrumb"}% We don't want any crumbs %TMPL:END%
and then set SKIN=yourlocal,pattern
## 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, such as %URLPA%NOP%RAM{...}% escaping URLPARAM |
>
%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#edit]] 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
For TWiki application it is useful to automatically generate unique topicnames, such as BugID0001, BugID0002, etc. You can add `AUTOINC> > > | >> %WIKITOOLNAME% . %WEB% . > %TOPIC% %TMPL:P{"titleaction"}% > | >
> %TMPL:P{"webaction"}% > | >
> Topic %TOPIC% . { > %TMPL:P{"topicaction"}% > } > | >
**.../bin/oops/Sandbox/TestTopic2?template=oopstest¶m1=WebHome¶m2=WebNotify**
**_Related Topics:_** [[TWikiSkins]], [[DeveloperDocumentationCategory]], [[AdminDocumentationCategory]]
-- **_Contributors:_** TWiki:Main.CrawfordCurrie, TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.DavidLeBlanc