Difference: TWikiTemplates (23 vs. 24)

Revision 242005-03-27 - TWikiContributor

Line: 1 to 1
Deleted:
<
<
META TOPICPARENT name="WebHome"
 

TWiki Templates

Line: 8 to 7
 

Overview

Changed:
<
<
The new modular template system offers flexible, easy control over the layout of all TWiki pages. The master template approach groups parts that are shared by several templates - like headers and footers - in a common file. Special variables allow individual layouts to include parts from a master template - variables are mixed with regular HTML markup for template-specific content. Templates are used to define page layout, and also to supply default content for new pages.
>
>
There are three types of template:
  • Master Templates: Define blocks of text for use in other templates
  • HTML Page Templates: Define the layout of TWiki pages
  • Template Topics: Define default text when you create a new topic
 
Changed:
<
<

Major changes from the previous template system

>
>
All three types of template use the TWiki template system.
 
Changed:
<
<
Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for TWikiSkins. The new system:
>
>

The TWiki Template System

 
Changed:
<
<
  • separates a set of common template parts into a base template that is included by all of the related templates;
  • defines common variables, like a standard separator (ex: "|"), in the base template;
  • defines variable text in the individual templates and passes it back to the base template.
>
>
Templates are plain text with embedded template directives that tell TWiki how to compose blocks of text together to create something new.
 
Changed:
<
<

How Template Variables Work

  • Special template directives (or preprocessor commands) are embedded in normal templates.
  • All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
>
>

How Template Directives Work

  • Template directives are embedded in templates.
 
  • Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
  • Directives:
Changed:
<
<
    • %TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
    • %TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
    • %TMPL:END%: Ends variable definition.
    • %TMPL:P{"var"}%: Prints a previously defined variable.
  • Variables live in a global name space: there is no parameter passing.
>
>
    • %TMPL:INCLUDE{"file"}%: Includes a template file. The file is found as described below.
    • %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.
  • HELP Use of template directives is optional: templates work without them.
Changed:
<
<
  • ALERT! NOTE: Template directives work only for templates: they do not get processed in topic text.
>
>
  • ALERT! NOTE: Template directives work only for templates: they do not get processed in normal topic text.
 
Changed:
<
<

Types of Template

>
>
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.
 
Changed:
<
<
There are three types of template:
>
>
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.

 
Changed:
<
<
  • Master Template: Stores common parts; included by other templates
  • HTML Page Templates: Defines the layout of TWiki pages
  • Template Topics: Defines default text when you create a new topic
>
>
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.
 
Changed:
<
<

Master Templates

>
>

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.

 
Changed:
<
<
Common parts, appearing in two or more templates, can be defined in a master template and then shared by others: twiki.tmpl is the default master template.
>
>
  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 web.topic if the template name can be parsed into web.topic
  6. The TWiki topic web.SkinSkinScriptTemplate for each skin on the skin path
  7. The TWiki topic web.ScriptTemplate
  8. The TWiki topic TWiki.SkinSkinScriptTemplate for each skin on the skin path
  9. The TWiki topic TWiki.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. 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, or 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:
<-- -->
Sorted descending
%TMPL:DEF{"sep"}% "|" separator
Line: 57 to 108
 

Changed:
<
<

HTML Page Templates

TWiki uses HTML template files for 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.

Templates are stored either in the twiki/templates directory or in user topics. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script.

>
>

HTML Page Templates

 
Changed:
<
<
HELP Templates can be overloaded by individual webs.
>
>
HTML page templates are files of HTML mixed with template directives that tell TWiki how to build up an HTML page. As described above, the template system supports the use of 'include' directives that let you re-use the same sections of HTML - such as headers and footers - in several different places.
 
Changed:
<
<
HELP TWikiSkins can overload the standard templates.
>
>
TWiki uses HTML page 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.
 
Changed:
<
<
TWiki uses the following search order to determine which template to use:

If a skin is specified If no skin is specified
templates/%WEB%/script.skin.tmpl templates/%WEB%/script.tmpl
templates/script.skin.tmpl templates/script.tmpl
data/%WEB%/SkinSkinScriptTemplate.txt data/%WEB%/ScriptTemplate.txt
data/TWiki/SkinSkinScriptTemplate.txt data/TWiki/ScriptTemplate.txt
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 the skin name, e.g dragon, pattern
Skin refers to the same, but with the first character capitalized, e.g Dragon
%WEB% refers to the current web

Additionally (and primarily for use in %TMPL:INCLUDE{}%) the template name may be a wiki topic name, specified as Web.Topic, in which case the search is:

If a skin is specified If no skin is specified
templates/web/Web.Topic.skin.tmpl templates/web/Web.Topic.tmpl
templates/Web.Topic.skin.tmpl templates/Web.Topic.tmpl
data/Web/Topic.txt
If Web is not specified in the INCLUDE, it defaults to TWiki, and the search to the first type.

Special variables are used in templates, especially in view, to display meta data.

>
>
HTML page templates are also used in the definition of TWikiSkins.
 
Changed:
<
<

Template Topics

>
>

Template Topics

  Template topics define the default text for new topics. There are three types of template topic:
Line: 99 to 126
 
WebTopicNonWikiTemplate Alert page shown when you try to view a nonexistent topic with a non-WikiName
WebTopicEditTemplate Default text shown when you create a new topic.
Changed:
<
<
All template topics are located in the TWiki web. The WebTopicEditTemplate can be overloaded. When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:
>
>
When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:
 
Changed:
<
<
  1. A topic name specified by the templatetopic CGI parameter.
>
>
  1. A topic name specified by the templatetopic CGI parameter
    • if no web is specified, the current web is searched first and then the TWiki web
 
  1. WebTopicEditTemplate in the current web
  2. WebTopicEditTemplate in the TWiki web
Changed:
<
<

Edit Template Topics and Variable Expansion

>
>

Edit Template Topics and Variable Expansion

  The following variables get expanded when a user creates a new topic based on a template topic:

Variable: Description:
Changed:
<
<
%DATE% Current date, e.g. 2024-03-28
%USERNAME% Login name, e.g. jsmith
%WIKINAME% WikiName of user, e.g. JohnSmith
%WIKIUSERNAME% User name, e.g. Main.JohnSmith
%URLPARAM{"name"}% Value of a named URL parameter
>
>
%DATE% Signature format date. See TWikiVariables#VarDATE
%GMTIME% Date/time. See TWikiVariables#VarGMTIME
%GMTIME{...}% Formatted date/time. See TWikiVariables#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%{...}%
Changed:
<
<
%NOP{ ... }% A no-operation text that gets removed. Useful to write-protect an edit template topic, but not the topics based this template topic. See notes below. Example:
%NOP{
   * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
  }%
>
>
%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 TWikiVariables#VarSERVERTIME
%SERVERTIME{...}% Formatted date/time. See TWikiVariables#VarSERVERTIME2
%USERNAME% Login name of user who is instantiating the new topic, e.g. guest
%URLPARAM{"name"}% Value of a named URL parameter
%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
 
Changed:
<
<
Notes:
  • Unlike other variables, %NOP{ ... }% can span multiple lines.
  • The scan for the closing }% pattern is "non-greedy", that is, it stops at the first occurance. That means, you need to escape variables with parameters located inside %NOP{ ... }%: Insert a %NOP% between } and %. Silly example: %NOP{ %GMTIME{"$year"}%NOP%% }%.
>
>
%STARTSECTION{type="templateonly"}%
...
%ENDSECTION{type="templateonly"}%
markers are used to embed text that you do not want expanded when a new topic based on the template topic is created. For example, you might want to write in the template topic:
%STARTSECTION{type="templateonly"}%
This template can only be changed by:
   * Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroup
%ENDSECTION{type="templateonly"}%
This will restrict who can edit the template topic, but will get 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 e.g.i escape %nop>SERVERTIME% with %SER%NOP%VERTIME%.

  All other variables are unchanged, e.g. are carried over "as is" into the new topic.
Changed:
<
<

Template Topics in Action

>
>

Template Topics in Action

  Here is an example for creating new topics based on a specific template topic:
Changed:
<
<
>
>
 
  • New example topic:
Changed:
<
<
>
>
 
 
Deleted:
<
<
  (date format is YYYYxMMxDD)

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 HTML source of the form:


Changed:
<
<
<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
>
>
<form name="new" action="%SCRIPTURLPATH{edit}%/%WEB%/">
 
  • New example topic:
Changed:
<
<
<input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
>
>
<input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="26" />
  <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" /> <input type="hidden" name="topicparent" value="%TOPIC%" /> <input type="hidden" name="onlywikiname" value="on" /> <input type="hidden" name="onlynewtopic" value="on" />
Changed:
<
<
<input type="submit" value="Create" />
>
>
<input type="submit" class="twikiSubmit" value="Create" />
  (date format is <nop>YYYYxMMxDD) </form>
Changed:
<
<
The edit scipt understands the following parameters, typically supplied by HTML input fields:

Parameter: Description:
topic Name of topic to create. Can be set in a text field, or is set programmatically (e.g. with a sequential number)
onlywikiname If set, TWiki will complain if the topic name is not a WikiWord
onlynewtopic If set, TWiki will complain if a topic of the same name already exists
templatetopic The name of the template topic, e.g. topic used to copy the initial content
topicparent Sets the parent topic
TopicClassification Assuming the template topic has a form with a field called "TopicClassification", it will set the value of the field
contenttype Optional parameter that defines the application type to write into the CGI header. Defaults to text/html. May be used to invoke alternative client applications
anyname Any parameter can passed to the new topic; if the template topic contains %URLPARAM{"anyname"}%, it will be replaced by its value
>
>
See TWikiScripts for details of the parameters that the edit script understands.
  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:
-- %WIKIUSERNAME% - %DATE%
Changed:
<
<

Templates by Example

>
>

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.

 
Changed:
<
<
Attached is an example of an oops based template oopsbase.tmpl and an example oops dialog oopstest.tmpl based on the base template. %A% NOTE: This isn't the release version, just a quick, simple demo.
>
>
Example link to create a new topic:
[[%SCRIPTURLPATH{"edit"}%/%WEB%/BugIDXXXXXXXXXX?templatetopic=BugTemplate&amp;topicparent=%TOPIC%&amp;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. TIP NOTE: This isn't the release version, just a quick, simple demo.

 

Base template oopsbase.tmpl

Line: 189 to 226
 <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title>
Changed:
<
<
<base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
>
>
<base href="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%">
  <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF">
Line: 266 to 303
 
testscreen.gif
Changed:
<
<

Known Issues

  • A drawback of referring to a master template is that you can only test a template from within TWiki, where the include variables are resolved. In the previous system, each template was a structurally complete HTML document with a .tmpl filename extension - it contained unresolved %VARIABLES%, but could still be previewed directly in a browser.
>
>
Related Topics: TWikiSkins, DeveloperDocumentationCategory, AdminDocumentationCategory
 
Changed:
<
<
-- TWiki:Main.CrawfordCurrie - 30 Jun 2004
-- TWiki:Main.PeterThoeny - 15 Aug 2004
-- TWiki:Main.MikeMannix - 14 Sep 2001
-- TWiki:Main.DavidLeBlanc - 11 Mar 2002
>
>
META FILEATTACHMENT attr="h" comment="Example of oopstest.tmpl rendered" date="1026977240" name="testscreen.gif" path="C:\Data\Temp\testscreen.gif" size="9566" user="TWikiContributor" version="1.2"
 
Deleted:
<
<
META FILEATTACHMENT attr="h" comment="Example of oopstest.tmpl rendered" date="1026977240" name="testscreen.gif" path="C:\Data\Temp\testscreen.gif" size="9566" user="PeterThoeny" version="1.2"
META TOPICMOVED by="MikeMannix" date="1000277381" from="TWiki.TWikiTemplateSystem" to="TWiki.TWikiTemplates"
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiTemplates.