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

Overview

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
Legend:
  • 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:INCLUDE{"view"}%
%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
%STARTSECTION{type="templateonly"}%
...
%ENDSECTION{type="templateonly"}%
Text that gets removed when a new topic based on the template is created. See notes below.
%SERVERTIME% Date/time. See VarSERVERTIME
%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" }% 

Example:

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.

%EOTC__SEARCH{"."
 topic="%URLPARAM{prefix}%*"
 nonoise="on"
 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.

Examples:

  • 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.

Example:

  • 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="/cgi-bin/edit/Sandbox/WebHome">
   * New example topic: 
     <input type="text" name="topic" value="ExampleTopicAUTOINC0001" size="30" />
     <input type="hidden" name="templatetopic" value="TWiki06x00.ExampleTopicTemplate" />
     <input type="hidden" name="topicparent" value="WebHome" />
     <input type="hidden" name="onlywikiname" value="on" />
     <input type="hidden" name="onlynewtopic" value="on" />
     <input type="submit" class="twikiSubmit" value="Create" />
</form>

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="/cgi-bin/save/Sandbox/" method="post">
    ...
</form>

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

Hi,

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

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: r81 < r80 < r79 < r78 < r77 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r81 - 2016-12-09 - AmyHuang
 
  • 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-2016 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.