skin3Add my vote for this tag template_system3Add my vote for this tag create new tag
, view all tags
ALERT! NOTE: This is a DistributionDocument. Please help maintain high quality documentation: This is a wiki, please fix the documentation if you find errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below. Use the Support web for problems you are having using TWiki.

TWiki Templates

Definition of the templates used to render all HTML pages displayed in TWiki


Templates are plain text with embedded template directives that tell TWiki how to compose blocks of text together, to create something new.

There are two types of template:

  • Master Templates: Define the HTML used to display TWiki pages.
  • Template Topics: Define default text when you create a new topic

TIP Tip: TWiki:TWiki.TWikiTemplatesSupplement on TWiki.org has supplemental documentation on TWiki templates.

Master Templates

TWiki uses master templates when composing the output from all actions, like topic view, edit, and preview. This allows you to change the look and feel of all pages by editing just a few template files.

Master templates are also used in the definition of TWikiSkins.

Master templates are stored as text files with the extension .tmpl. They are usually HTML with embedded template directives. The directives are expanded when TWiki wants to generate a user interface screen.

How Template Directives Work

  • Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
  • Directives:
    • %TMPL:INCLUDE{"file"}%: Includes a template file. The file is found as described below.
    • %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.
  • HELP Use of template directives is optional: templates work without them.
  • ALERT! 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"}%<input type="button" disabled value="Link>%TMPL:END%
%TMPL:DEF{"link_active"}%<input type="button" onclick="link()" value="Link" />%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

The master templates shipped with a twiki release are stored in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the default template file for the twiki/bin/view script.

You can save templates in other directories as long as they are listed in the {TemplatePath} configuration setting. The {TemplatePath} is defined in the Miscellaneous section of the configure page.

You can also save templates in user topics (IF there is no possible template match in the templates directory). The {TemplatePath} configuration setting defines which topics will be accepted as templates.

Templates that are included with an explicit '.tmpl' extension are looked for only in the templates/ directory. For instance %TMPL:INCLUDE{"example.tmpl"}% will only return templates/example.tmpl, regardless of {TemplatePath} and SKIN settings.

The out-of-the-box setting of {TemplatePath} supports the following search order to determine which template file or topic to use for a particular script or %TMPL:INCLUDE{"script"}% statement. The skin path is set as described in TWikiSkins.

  1. templates/web/script.skin.tmpl for each skin on the skin path
    • ALERT! this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
  2. templates/script.skin.tmpl for each skin on the skin path
  3. templates/web/script.tmpl
    • ALERT! this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
  4. templates/script.tmpl
  5. The TWiki topic aweb.atopic if the template name can be parsed into aweb.atopic
  6. The TWiki topic web.SkinSkinScriptTemplate for each skin on the skin path
  7. The TWiki topic web.ScriptTemplate
  8. The TWiki topic %SYSTEMWEB%.SkinSkinScriptTemplate for each skin on the skin path
  9. The TWiki topic %SYSTEMWEB%.ScriptTemplate
  • script refers to the script name, e.g view, edit
  • Script refers to the same, but with the first character capitalized, e.g View
  • skin 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.
  • Skin refers to the same, but with the first character capitalized, e.g Dragon
  • web 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. TWiki06x00.PrintSkinExampleTemplate
  11. TWiki06x00.PatternSkinExampleTemplate
  12. TWiki06x00.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 used 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, or TWiki06x00.TWikiPreferences (using Set), the indicated templates will be chosen for view and edit respectively. The template search order is as specified above.

TIP Tip: If you want to override existing templates, without having to worry that your changes will get overwritten by the next TWiki update, change the {TemplatePath} so that another directory, such as the %USERSWEB% appears at the front. You can then put your own templates into that directory or web and these will override the standard templates. (Note that such will increase the lookup time for templates by searching your directory first.)

TMPL:INCLUDE recursion for piecewise customization, or mixing in new features

If there is recursion 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 customization 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:DEF{"breadcrumb"}% We don't want any crumbs %TMPL:END%
and then set SKIN=yourlocal,pattern

The default {TemplatePath} will not give you the desired result if you put these statements in the topic Thisweb.YourlocalSkinViewTemplate. The default {TemplatePath} will resolve the request to the template/view.pattern.tmpl, before it gets to the Thisweb.YourlocalSkinViewTemplate resolution. You can make it work by prefixing the {TemplatePath} with: $web.YourlocalSkin$nameTemplate.

Default master template

twiki.tmpl is the default master template. It defines the following sections.

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

Template Topics

The second type of template in TWiki are template topics. Template topics define the default text for new topics. There are four types of template topic:

Topic Name: What it is:
WebTopicViewTemplate Alert page shown when you try to view a nonexistent topic. This page is usually used as a prompt to help you create a new topic.
WebTopicNonWikiTemplate Alert page shown when you try to view a nonexistent topic with a non-WikiName. Again, this page is used as a prompt to help you create the new topic.
WebTopicEditTemplate Default text used in a new topic.
<MyCustomNamed>Template Whenever you create a topic ending in the word "Template", it is automatically added to the list of available templates in the "Use Template" drop down field on the WebCreateNewTopic page.

When you create a new topic using the edit script, TWiki locates a topic to use as a content template according to the following search order:

  1. A topic name specified by the templatetopic CGI parameter
    • if no web is specified, the current web is searched first and then the TWiki06x00 web
  2. WebTopicEditTemplate in the current web
  3. WebTopicEditTemplate in the Main web
  4. WebTopicEditTemplate in the TWiki06x00 web

Variable Expansion

TWikiVariables located in template topics get expanded as follows when a new topic is created.

1. Default variable expansion

The following variables used in a template topic automatically get expanded when new topic is created based on it:

Variable: Description:
%DATE% Signature format date. See VarDATE
%GMTIME% Date/time. See VarGMTIME
%GMTIME{...}% Formatted date/time. See 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
Text that gets removed when a new topic based on the template is created. See notes below.
%SERVERTIME{...}% Formatted date/time. See VarSERVERTIME2
%USERNAME% Login name of user who is instantiating the new topic, e.g. guest
%URLPARAM{"name"}% Value of a named URL parameter. See VarURLPARAM.
%WIKINAME% WikiName of user who is instantiating the new topic, e.g. TWikiGuest
%WIKIUSERNAME% User name of user who is instantiating the new tpoic, e.g. Main.TWikiGuest

2. Preventing variable expansion

In a template topic, embed text that you do not want expanded inside a %STARTSECTION{type="templateonly"}% ... %ENDSECTION{type="templateonly"}% section. For example, you might want to write this in the template topic:

This template can only be changed by:
   * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
This will restrict who can edit the template topic, but will be removed when a new topic based on that template topic is created.

%NOP% can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation. For example, escape %SERVERTIME% with %SER%NOP%VERTIME%.

3. Causing variable expansion in a section

You can forcefully expand TWikiVariables by placing them inside a type="expandvariables" section in the template topic, such as:

%STARTSECTION{ type="expandvariables" }% ... %ENDSECTION{ type="expandvariables" }% 


If you have the following content in a template topic:

%STARTSECTION{ type="expandvariables" }%
   * %SYSTEMWEB%.ATasteOfTWiki - view a short introductory presentation on TWiki for beginners
   * %SYSTEMWEB%.WelcomeGuest - starting points on TWiki
   * %SYSTEMWEB%.TWikiUsersGuide - complete TWiki documentation
   * Sandbox.%HOMETOPIC% - try out TWiki on your own
   * Sandbox.%TOPIC%Sandbox - just for me
%ENDSECTION{ type="expandvariables" }%

you will get this raw text in new topics based on that template topic:

   * TWiki06x00.ATasteOfTWiki - view a short introductory presentation on TWiki for beginners
   * TWiki06x00.WelcomeGuest - starting points on TWiki
   * TWiki06x00.TWikiUsersGuide - complete TWiki documentation
   * Sandbox.WebHome - try out TWiki on your own
   * Sandbox.JimmyNeutronSandbox - just for me

4. Specifying variables to be expanded individually

You may want to mix variables to be expanded and variables not to be. By prepending a variable name with EOTC__ (EOTC followed by two underscores; EOTC stands for Expand On Topic Creation), you can have the variable expanded.

Here's an example.

 format="$percntINCLUDE{$topic}$percnt" separator="$n"
This yields a series of %INCLUDE{...}%s, which are not expanded. This is not achievable by an expandvariables section.

Specifying a Form

When you create a new topic based on a template, you often want the new topic to have a form attached to it. You can attach a form to the template topic, in which case it will be copied into the new topic.

Sometimes this isn't quite what you want, as it copies all the existing data from the template topic into the new topic. To avoid this and use the default values specified in the form definition instead, you can use the formtemplate CGI parameter to the edit script to specify the name of a form to attach.

See TWikiScripts for information about all the other parameters to edit.

Automatically Generated Topic Names

For TWiki applications it is useful to be able to automatically generate unique topic names, such as BugID0001, BugID0002, etc. You can add AUTOINC<n> to the topic name in the edit and save scripts, and it will be replaced with an auto-incremented number on topic save. <n> is a number starting from 0, and may include leading zeros. Leading zeros are used to zero-pad numbers so that auto-incremented topic names can sort properly. Deleted topics are not re-used to ensure uniqueness of topic names. That is, the auto-incremented number is always higher than the existing ones, even if there are gaps in the number sequence.


  • BugAUTOINC0 - creates topic names Bug0, Bug1, Bug2, ... (does not sort properly)
  • ItemAUTOINC0000 - creates topic names Item0000, Item0001, Item0002, ... (sorts properly up to 9999)
  • DocIDAUTOINC10001 - start with DocID10001, DocID10002, ... (sorts properly up to 99999; auto-links)

Characters after AUTOINC<n> are preserved, but are not taken into account when calculating the next increment. Use this to create topic names that have a unique identifier (serial number) and a descriptive text.


  • BlogAUTOINC0001-my-first-blog - creates topic name Blog0001-my-first-blog
  • BlogAUTOINC0001-my-crazy-cats - creates topic name Blog0002-my-crazy-cats
  • BlogAUTOINC0001-fondue-recipe - creates topic name Blog0003-fondue-recipe

Example link to create a new topic:

[[%SCRIPTURLPATH{edit}%/%WEB%/BugIDAUTOINC00001?templatetopic=BugTemplate;topicparent=%TOPIC%;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]

Template Topics in Action

Here is an example for creating new topics (in the Sandbox web) based on a specific template topic and form:

  • New example topic:

The above form asks for a topic name. A hidden input tag named templatetopic specifies ExampleTopicTemplate as the template topic to use. Here is the raw text of the form:

%EDITFORMFIELD{ "new" type="start" action="edit" topic="Sandbox.%TOPIC%" }%
   * New example topic: 
     %EDITFORMFIELD{ "topic" type="text" value="ExampleTopicAUTOINC0001" size="30" }%
     %EDITFORMFIELD{ "templatetopic" type="hidden" value="%SYSTEMWEB%.ExampleTopicTemplate" }%
     %EDITFORMFIELD{ "topicparent" type="hidden" value="%HOMETOPIC%" }%
     %EDITFORMFIELD{ "onlywikiname" type="hidden" value="on" }%
     %EDITFORMFIELD{ "onlynewtopic" type="hidden" value="on" }%
     %EDITFORMFIELD{ "form" type="submit" value="Create" }%
%EDITFORMFIELD{ "form" type="end" }%

Here is the equivalent form using a hand-crafted HTML form:

<form name="new" action="%SCRIPTURLPATH{edit}%/Sandbox/%HOMETOPIC%">
   * New example topic: 
     <input type="text" name="topic" value="ExampleTopicAUTOINC0001" size="30" />
     <input type="hidden" name="templatetopic" value="%SYSTEMWEB%.ExampleTopicTemplate" />
     <input type="hidden" name="topicparent" value="%HOMETOPIC%" />
     <input type="hidden" name="onlywikiname" value="on" />
     <input type="hidden" name="onlynewtopic" value="on" />
     <input type="submit" class="twikiSubmit" value="Create" />

ALERT! Note: You can create a topic in one step, without going through the edit screen. To do that, specify the save script instead of the edit script in the form action. When you specify the save script in an HTML form tag you have to use the "post" method. This is done automatically when using the EDITFORMFIELD variable. Example when using the HTML form tag:

<form name="new" action="%SCRIPTURLPATH{save}%/Sandbox/" method="post">

HELP The edit and save scripts understand many more parameters, see TWikiScripts#edit and TWikiScripts#save for details.

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

Using Absolute vs Relative URLs in Templates

When you use TWikiVariables such as %PUBURL% and %PUBURLPATH% in templates you should be aware that using %PUBURL% instead of %PUBURLPATH% puts absolute URLs in the produced HTML. This means that when a user saves a TWiki page in HTML and emails the file to someone outside a company firewall, the receiver has a severe problem viewing it. It is therefore recommended always to use the %PUBURLPATH% to refer to images, CSS, Javascript files etc so links become relative. This way browsers just give up right away and show a usable html file.

Related Topics: TWikiSkins, TWikiForms, TWikiScripts, DeveloperDocumentationCategory, AdminDocumentationCategory

-- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.DavidLeBlanc, TWiki:Main.CrawfordCurrie, TWiki:Main.SopanShewale

Comments & Questions about this Distribution Document Topic

I created a set of custom HTML templates for WikiLearn for the (IIRC) Feb/Mar 2001 Beta release (they are currently used only on my private (behind a firewall) TWiki). Can I use those as is in the current version of TWiki, or must I convert to the new approach?

While I'm asking questions, should I add WikiLearn on twiki.org and my private TWiki to the new list of TWiki installations?

BTW, this page is much clearer than any previous documentation I can recall on the new template system -- good work! (Or maybe I know / understand more than I did the last time I looked at this page? wink )

-- RandyKramer - 12 Oct 2002

You should be able to use older templates and skins with the latest TWiki version. (Better to ask non-doc related questions in the Support web.)

I would not add the Wikilearn web on TWiki.org since it is not an installation. You could add own installation if you want.

-- PeterThoeny - 14 Oct 2002

It might be worth mentioning at the start of the page that these 'templates' are not the same as a 'form templates', it took me a bit to figure out that when TWikiForms refers to 'form templates', it doesn't refer to one of these.

When I sneak under the covers and look at the templates/*.tmpl files, there are some interesting-looking bits that aren't documented here, such as %REPEAT% and %SPLIT%. It would be nice if they could be documented.

-- AlanBurlison - 28 Jan 2003

I've used the form described in Template Topics in Action to automatically create a new topic based on a template (over on CFK TWiki:CFK.EventSchedule).

It works, but I'd prefer to change it so the user has to enter three separate fields, one each for Year, Month, and Day of the scheduled event, then presses Create, and a new topic named EVT2003m05d10CoreTraining (or similar) is created. I think that will be easier for the users to understand and see (because of the small size type in the text entry box). Is it possible without patching TWiki? Hints?

I've looked a little bit at trying to setup three custom variables (%SYEAR%, %SMONTH%, %SDAY%) using the TWiki 3 space * Set SYEAR = and then putting a form there to display a text entry box and accept the value and set the variable, but I'm really just shooting in the dark. (I'm starting to read up on HTML and forms, but hints would be greatly appreciated.)

Incidentally, %INTURLENCODE{"TWiki"}% did not work on the CFK TWiki — apparently %INTURLENCODE% is not recognized, maybe because the CFK TWiki uses the Athens release of TWiki. I solved that problem by simply using %WEB% instead.

-- RandyKramer - 03 May 2003

INTURLENCODE is in fact working on TWiki.org since TWiki is on a post-Beijing release - %INTURLENCODE{"Gratinée"}% gives Gratinée. This only affects accented characters, i.e. those with the 8th bit set. So your first incantation was correct and is preferred to let your new-topic code handle I18N now, and in the future when the need for the encoding hack may go away (for more info, see InternationalisationEnhancements and InternationalisingYourSkin.)

If you still have problem, please log a bug under Codev.WebHome and link it to InternationalisationIssues if possible.

-- RichardDonkin - 06 May 2003

Richard, Thanks!

Unfortunately, my last statement was misleading — the problem with INTURLENCODE was on the other TWiki (which uses Athens), not at twiki.org. But, at least I now know that INTURLENCODE is the function to deal with internationalization of URLs. wink

I've changed some wording in my last comment to make it read more correctly.

Re my desire to have the user enter year, month, and day separately, I started doing some reading on (HTML) forms (collecting notes on Wikilearn.HtmlForms), and I'm beginning to see how I could probably do that, at the cost of having to write a CGI handler. I might attempt that someday as a learning exercise, but for now I have something that works.

-- RandyKramer - 06 May 2003

I added useful (for me at least) example from WhereISTheMagicOfTheTWikiURLDocumented -- PeterMasiar - 14 Jul 2003

Template Topic Overwriting Existing Topic: I've used the form shown in Template Topics in Action to create new topics based on a template. To my surprise I noticed, that existing topics are overwritten without warning, when create is used with an existing topic name. An example can be found at HHsSandbox#Topic_Creation_using_HHsTemplate. Is anybody aware of a patch or workaround?

-- HansruediHaenni - 02 Sep 2003

There's a useful overview of all the TWiki templates at Codev.TemplatesDocumentation.

-- RichardDonkin - 28 Dec 2003

The phrase "All template topics are located in the TWiki web." leads one to believe that even custom topics used by setting "templatetopic" should be in the TWiki web. It wouild be better to clarify - "All of these template topics are located in the TWiki web. For overloaded and custom topics, the template should reside in the same web where the topic is created.

-- BenWebb - 17 Jan 2005

I think there is a bug (either in the code or the docs, but rather in the code) in the way the search for the right topic is done. This documentations states that the order is the following :

If a skin is specified :

  1. templates/%WEB%/script.skin.tmpl
  2. templates/script.skin.tmpl
  3. data/%WEB%/SkinSkinScriptTemplate.txt
  4. data/TWiki/SkinSkinScriptTemplate.txt
But instead, if I add a SkinSkinScriptTemplate topic to the Web, what I noticed is that the following order applies :
  1. templates/%WEB%/script.skin.tmpl
  2. templates/script.skin.tmpl
  3. templates/script.tmpl
  4. data/%WEB%/SkinSkinScriptTemplate.txt
  5. data/TWiki/SkinSkinScriptTemplate.txt
I think the default case (loading script.tmpl, third case) should be done in the end in TWiki::Store::_readTemplateFile ... I will try to provide a clean patch as soon as this is confirmed to be a bug... in the mean-time, I filed this bug : Codev.UserTopicTemplateNotFoundComparedToDocsSearchOrder

-- OlivierBerger - 01 Jul 2005

Using %URLPARAM%NOP%{...}% doesn't work, instead, use: %URLPA%NOP%RAM{...}%, e.g., to include tags in an edit template:

%TAGME{  tpaction="%URLPA%NOP%RAM{tpaction}%" tag="%URLPA%NOP%RAM{tag}%" }% 

-- JoaoChrist - 10 Jul 2006

Thanks for the alert, I updated the doc. (And fixed your example that got corrupted.)

-- PeterThoeny - 10 Jul 2006

This topic needs to be extended to include discussion of the new features of Dakar, e.g., conditionalization,...

-- ThomasWeigert - 22 Sep 2006


how can I put variables in a template, that should not be expanded? I am working on a template for the comments plugin and would like to add a line under each comment, that will contain the answer of the page author. That line should start with a red arrow (just an example) and the variable for that icon is %M%.

What do I have to do, that the variable is going as is into the wiki page?

-- AndreasEbbertKarroum - 05 Dec 2006

Please ask support questions in the Support web, this thread here is about the documentation of templates.

-- PeterThoeny - 05 Dec 2006

It would appear that the problem posted above by OlivierBerger 18 months ago is still a problem. 4.0.5 appears to still display the same behaviour. Couldn't work it out until I found his note. Is there some reason why either the doco or the bug hasn't been sorted out? Or am I missing something?

-- MarcusLeonard - 22 Dec 2006

I believe the docs have been updated for the upcoming TWikiRelease04x01x00: TWiki04x01.TWikiTemplates

-- PeterThoeny - 23 Dec 2006

I had the same problem. Eventually I read the code of Templates.pm and worked it out. I think there should be a reference on this page to the TemplatePath configuration variable. Here are my notes. See also my support question in TemplateDoesNotWorkInTopic.

Here are my notes:

The use of templates is incompletely described in the documentation.

There are two views. 1. The view of the twiki user, who can use skins and covers 2. The view of the programmer, who can use loadTemplate to obtain the content of a template file.

The twiki user needs to be aware of

  • the configuration setting of the TemplatePath configuration variable and
  • the SKIN and COVER variable setting.
The TemplatePath configuration variable determines the locations where TWiki will look for templates. It take the form of TemplatePath=<filenam>,<filenam>,<filenam> where <filenam> is a pattern that can either form
  • a pathname for a file in the filesystem, or
  • a topicname in a web.
The TemplatePath shipped with the installation of 4.1.2 is
  • /home/httpd/twiki412/templates/$web/$name.$skin.tmpl
  • /home/httpd/twiki412/templates/$name.$skin.tmpl
  • /home/httpd/twiki412/templates/$web/$name.tmpl
  • /home/httpd/twiki412/templates/$name.tmpl
  • $web.$skinSkin$nameTemplate
  • TWiki.$skinSkin$nameTemplate
  • $web.$nameTemplate
  • TWiki.$nameTemplate
A user looking at the topic WebHome in the Main web with the SKIN=pattern will look for the template at the following location in order

  1. /home/httpd/twiki412/templates/Main/view.pattern.tmpl
  2. /home/httpd/twiki412/templates/view.pattern.tmpl
  3. /home/httpd/twiki412/templates/Main/view.tmpl
  4. /home/httpd/twiki412/templates/view.tmpl
  5. Main.PatternSkinViewTemplate
  6. TWiki.PatternSkinViewTemplate
  7. Main.ViewTemplate
  8. TWiki.ViewTemplate

Note: this explains why the problem TemplateDoesNotWorkInTopic reported on 10 November 2007 occurred. My request is satisfied with number 4 rather than the expected number 5. It also shows how to fix it. I changed the TemplatePath to look for all the skinned templates before the non skinned ones. And since my covers are in twiki topics and the skins in files, I check the topics first. My TemplatePath is now:

  • $web.$skinSkin$nameTemplate
  • TWiki.$skinSkin$nameTemplate
  • /home/httpd/twiki412/templates/$web/$name.$skin.tmpl
  • /home/httpd/twiki412/templates/$name.$skin.tmpl
  • $web.$nameTemplate
  • TWiki.$nameTemplate
  • /home/httpd/twiki412/templates/$web/$name.tmpl
  • /home/httpd/twiki412/templates/$name.tmpl
And that indeed solved the problem!

Had the skin been SKIN=cover,pattern then the loop over the skins is inside the loop over the filenames in the TemplatePath:

  1. Main.CoverSkinViewTemplate
  2. Main.PatternSkinViewTemplate
  3. TWiki.CoverSkinViewTemplate
  4. TWiki.PatternSkinViewTemplate
  5. /home/httpd/twiki412/templates/Main/view.cover.tmpl
  6. /home/httpd/twiki412/templates/Main/view.pattern.tmpl
  7. /home/httpd/twiki412/templates/view.cover.tmpl
  8. /home/httpd/twiki412/templates/view.pattern.tmpl
  9. /home/httpd/twiki412/templates/Main/view.tmpl
  10. /home/httpd/twiki412/templates/view.tmpl
  11. Main.ViewTemplate
  12. TWiki.ViewTemplate
I.e. there is a double loop, outer over TemplatePath, inner over the SKIN path. The first existing resolution found is used.

The programmer has more options loadTemplate('web', 'pattern,current', 'Main") will look for a template in the same sequence as in the example above.

But it will also handle two special cases: loadTemplate('somename.tmpl') will try to retrieve templates/somename.tmpl. If that file does not exist it will fail to return a template

loadTemplate('Main.ViewTemplate') will try to retrieve the text of ViewTemplate topic. If that topic does not exist it will try to find the topic on the skinpath if it is defined.

In that case the call loadTemplate('Main.ViewTemplate','pattern,current') . is as if the programmer had asked for:

loadTemplate('view', 'pattern,curent', 'Main')

There are probably more subtle considerations to setting up the TemplatePath. But I have not explored any further. My problem is solved.

-- BramVanOosterhout - 04 Dec 2007

Thanks Bram; this is tracked in TWikibug:Item5077. Feel free to update the docs here. They are up to date with the latest version in SVN.

-- PeterThoeny - 04 Dec 2007


Added text in Finding templates and TMPL:INCLUDE recursion....

Also removed the first %TOC% from this page.

-- BramVanOosterhout - 05 Dec 2007

Thanks Bram. I did some more fixes.

-- PeterThoeny - 05 Dec 2007

Confusing ! Please confirm that and we should change the docs
When looking at the TemplatePath, you see variables like $name and $skin but never $script. This is the case because $name is will be replaced by the curretn script, and thats what %script% means here, what is quite confusing.In addition when you use VIEW_TEMPLATE, then $name is replaced by %VIEW_TEMPLATE% and NO script-name is used at all!.
So setting

   * Set VIEW_TEMPLATE=HideForm

would match on the topic : $web.HideFormTemplate,TWiki.HideFormTemplate, TWiki.$skinSkinHideFormTemplate, $web.$skinSkinHideFormTemplate
and would not match to : $web.HideForm*View*Template ... if our script would be view
This is correct if you use the TemplatePath definitions out of 4.1.2 TWiki.spec! And Watch out, TemplateDir is the one defining the system-path to the templates, TemplatePath is a kind of aggregated possible matches to filenames / topicnames mainly relative to TemplateDir. USE BETTER NAMES!

-- MayerEugen - 25 Jan 2008

I think the Template Topics section on this page should discuss how to create topic templates beyond the Web defaults. There is no mention of how to add other topic templates to the "Use Templates" drop down on the WebCreateNewTopic page. I looked around the TWiki web, searched the Support web a bit, and eventually discovered by accident on my own that it's simply a matter of placing the word Template at the end of your topic name. Is this covered somewhere else in the documentation and I've just completely missed it?

-- GarySprague - 15 May 2008

Mayer and Gary: Please feel free to update the docs directly. Yes, it should be documented how to create a new template topic.

-- PeterThoeny - 15 May 2008

Explained how to override system templates in a way that does not cause the custom templates to be wiped out by the next TWiki upgrade.

-- ThomasWeigert - 2010-09-19

Thank you Thomas! I took this into SVN trunk and 5.0 branch.

Argh, the WYSIWYG editor messed up the page. You meant to add one paragraph but changed 35 paragraphs. I restored topic content with SVN updated content.

-- PeterThoeny - 2010-09-20


Not having any luck with AUTOINC in creating new pages with numbered topic names. When I use the example provided, I get a link that creates the page "PageNameAUTOINC00001" and always wants to use that exact name. I was expecting "PageName00001" and the next time I clicked the link, "PageName00002." Isn't that the behavior described?

Thanks, Joe M.

-- JoeMontibello - 2011-07-20

Please ask support questions in the Support forum. This section is about the documentation of this topic.

-- PeterThoeny - 2011-07-20

Thanks TreyFore for adding a missing anchor. I updated this topic in Subversion accordingly.

-- PeterThoeny - 2012-03-11

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.
Edit | Attach | Watch | Print version | History: r80 < r79 < r78 < r77 < r76 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r80 - 2014-12-16 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2015 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.