TWiki Templates

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

Overview

There are three types of template:

• Master Templates: Define blocks of text for use in other templates
• HTML Page Templates: Define the layout of KoreaCmsWiki pages
• Template Topics: Define default text when you create a new topic

All three types of template use the TWiki template system.

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

The TWiki Template System

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

How Template Directives Work

• Template directives are embedded in templates.
• 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.
• Use of template directives is optional: templates work without them.
• 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%

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/web/script.skin.tmpl for each skin on the skin path
   • 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
   • 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 %TWIKIWEB%.SkinSkinScriptTemplate for each skin on the skin path
9. The TWiki topic %TWIKIWEB%.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

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.

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%

Master Templates

Template variable:	Defines:

HTML Page Templates

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.

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.

HTML page templates are also used in the definition of TWikiSkins.

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
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.

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
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

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

%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"}%

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

Template Topics in Action

Here is an example for creating new topics based on a specific template 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 HTML source of the form:

<form name="new" action="%SCRIPTURLPATH{edit}%/%WEB%/">
   * New example topic: 
     <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" />
     <input type="submit" class="twikiSubmit" value="Create" />
     (date format is <nop>YYYYxMMxDD)
</form>

Automatically Generated Topicname

For TWiki application it is useful to automatically generate unique topicnames, such as BugID0001, BugID0002, etc. You can add AUTOINC<n> to the topic name in the edit and save scripts, it gets 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)

Example link to create a new topic:

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

Master Templates by Example

Attached is an example of an oops based template oopsbase.tmpl and an example oops dialog oopstest.tmpl based on the base template. NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END%
<html>
<head>
  <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title>
  <base href="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%">
  <meta name="robots" content="noindex">
</head>
<body bgcolor="#FFFFFF">
<table width="100%" border="0" cellpadding="3" cellspacing="0">
  <tr>
    <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%">
      <a href="%WIKIHOMEURL%">
      <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a>
    </td>
    <td>
      <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2">
      <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font>
    </td>
  </tr>
  <tr bgcolor="%WEBBGCOLOR%">
    <td colspan="2">
      %TMPL:P{"webaction"}%
    </td>
  </tr>
</table>
--- ++ %TMPL:P{"heading"}%
%TMPL:P{"message"}%
<table width="100%" border="0" cellpadding="3" cellspacing="0">
  <tr bgcolor="%WEBBGCOLOR%">
    <td valign="top">
      Topic <b>%TOPIC%</b> . {
        %TMPL:P{"topicaction"}%
      }
    </td>
  </tr>
</table>
</body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
%TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
%TMPL:DEF{"heading"}%
Test heading %TMPL:END%
%TMPL:DEF{"message"}%
Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...

   * Some more blah blah blah blah blah blah blah blah blah blah...
   * Param1: %PARAM1%
   * Param2: %PARAM2%
   * Param3: %PARAM3%
   * Param4: %PARAM4%
%TMPL:END%
%TMPL:DEF{"topicaction"}%
Test =topicaction=:
[[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
[[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
%TMPL:INCLUDE{"oopsbase"}%

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

Related Topics: TWikiSkins, DeveloperDocumentationCategory, AdminDocumentationCategory

TWiki Templates

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

Overview

There are three types of template:

• Master Templates: Define blocks of text for use in other templates
• HTML Page Templates: Define the layout of KoreaCmsWiki pages
• Template Topics: Define default text when you create a new topic

All three types of template use the TWiki template system.

The TWiki Template System

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

How Template Directives Work

• Template directives are embedded in templates.
• 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: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.
• Use of template directives is optional: templates work without them.
• 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%

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/web/script.skin.tmpl for each skin on the skin path
   • 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
   • this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
4. templates/script.tmpl

1. The TWiki topic web.SkinSkinScriptTemplate for each skin on the skin path
2. The TWiki topic web.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

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.

Master Templates

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

HTML Page Templates

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.

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.

HTML page templates are also used in the definition of TWikiSkins.

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
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.

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
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

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:
%DATE%	Signature format date. See VarDATE
%GMTIME%	Date/time. See VarGMTIME
%GMTIME{...}%	Formatted date/time. See VarGMTIME2

%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"}%

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

Template Topics in Action

Here is an example for creating new topics based on a specific template 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 HTML source of the form:

<form name="new" action="%SCRIPTURLPATH{edit}%/%WEB%/">
   * New example topic: 
     <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" />
     <input type="submit" class="twikiSubmit" value="Create" />
     (date format is <nop>YYYYxMMxDD)
</form>

See TWikiScripts for details of the parameters that the edit script understands.

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

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. NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END%
<html>
<head>
  <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title>
  <base href="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%">
  <meta name="robots" content="noindex">
</head>
<body bgcolor="#FFFFFF">
<table width="100%" border="0" cellpadding="3" cellspacing="0">
  <tr>
    <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%">
      <a href="%WIKIHOMEURL%">
      <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a>
    </td>
    <td>
      <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2">
      <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font>
    </td>
  </tr>
  <tr bgcolor="%WEBBGCOLOR%">
    <td colspan="2">
      %TMPL:P{"webaction"}%
    </td>
  </tr>
</table>
--- ++ %TMPL:P{"heading"}%
%TMPL:P{"message"}%
<table width="100%" border="0" cellpadding="3" cellspacing="0">
  <tr bgcolor="%WEBBGCOLOR%">
    <td valign="top">
      Topic <b>%TOPIC%</b> . {
        %TMPL:P{"topicaction"}%
      }
    </td>
  </tr>
</table>
</body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
%TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
%TMPL:DEF{"heading"}%
Test heading %TMPL:END%
%TMPL:DEF{"message"}%
Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...

   * Some more blah blah blah blah blah blah blah blah blah blah...
   * Param1: %PARAM1%
   * Param2: %PARAM2%
   * Param3: %PARAM3%
   * Param4: %PARAM4%
%TMPL:END%
%TMPL:DEF{"topicaction"}%
Test =topicaction=:
[[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
[[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
%TMPL:INCLUDE{"oopsbase"}%

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

TWiki Templates

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

Overview

There are three types of template:

The TWiki Template System

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

How Template Directives Work

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%

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.

Master Templates

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

HTML Page Templates

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.

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.

HTML page templates are also used in the definition of TWikiSkins.

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
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.

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:

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

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

Template Topics in Action

Here is an example for creating new topics based on a specific template 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 HTML source of the form:

<form name="new" action="%SCRIPTURLPATH{edit}%/%WEB%/">

See TWikiScripts for details of the parameters that the edit script understands.

TIP: You can use the %WIKIUSERNAME% and %DATE% variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is:
-- %WIKIUSERNAME% - %DATE%

Automatically Generated Topicname

If you want to make a TWiki application where you need automatically generated unique topicnames, you can use 10 X's in the edit / save URL, and they will be replaced on topic save with a count value. For example, BugIDXXXXXXXXXX will result in topics named BugID0, BugID1, BugID2 etc.

Example link to create a new topic:

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

Master Templates by Example

Attached is an example of an oops based template oopsbase.tmpl and an example oops dialog oopstest.tmpl based on the base template. NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr>

TWiki Templates

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

Overview

• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:

• 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.
• Use of template directives is optional: templates work without them.

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
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.

1. WebTopicEditTemplate in the current web
2. WebTopicEditTemplate in the TWiki web

Variable:	Description:

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

• New example topic:

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title>

TWiki Templates

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

Overview

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.

Major changes from the previous template system

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:

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

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).
• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %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.
• 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.
• Use of template directives is optional: templates work without them.
• NOTE: Template directives work only for templates: they do not get processed in topic text.

Types of Template

There are three types of template:

• Master Template: Stores common parts; included by other templates
• HTML Page Templates: Defines the layout of KoreaCmsWiki? pages
• Template Topics: Defines default text when you create a new topic

Master Templates

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.

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

HTML Page Templates

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
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.

1. A topic name specified by the templatetopic CGI parameter.
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

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:
%DATE%	Current date, e.g. 2022-05-21
%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
%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%{...}%
%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 }%

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%% }%.

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

Template Topics in Action

Here is an example for creating new topics based on a specific template 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 HTML source of the form:

<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
	* New example topic: 
	  <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
	  <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" />
	  <input type="submit" value="Create" />
	  (date format is <nop>YYYYxMMxDD)
</form>

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

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%

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. %A% NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> <a href="%WIKIHOMEURL%"> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> </td> <td> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> </td> </tr> <tr bgcolor="%WEBBGCOLOR%"> <td colspan="2"> %TMPL:P{"webaction"}% </td> </tr> </table> --- ++ %TMPL:P{"heading"}% %TMPL:P{"message"}% <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr bgcolor="%WEBBGCOLOR%"> <td valign="top"> Topic <b>%TOPIC%</b> . { %TMPL:P{"topicaction"}% } </td> </tr> </table> </body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

</table >

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% %TMPL:DEF{"heading"}% Test heading %TMPL:END% %TMPL:DEF{"message"}% Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... * Some more blah blah blah blah blah blah blah blah blah blah... * Param1: %PARAM1% * Param2: %PARAM2% * Param3: %PARAM3% * Param4: %PARAM4% %TMPL:END% %TMPL:DEF{"topicaction"}% Test =topicaction=: [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% %TMPL:INCLUDE{"oopsbase"}%

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.

TWiki Templates

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

Overview

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.

Major changes from the previous template system

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:

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

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).
• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %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.
• 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.
• Use of template directives is optional: templates work without them.
• NOTE: Template directives work only for templates: they do not get processed in topic text.

Types of Template

There are three types of template:

• Master Template: Stores common parts; included by other templates
• HTML Page Templates: Defines the layout of KoreaCmsWiki? pages
• Template Topics: Defines default text when you create a new topic

Master Templates

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.

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

HTML Page Templates

KoreaCmsWiki? 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 in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded by individual webs. The following search order applies:

1. twiki/templates/$webName/$scriptName.tmpl
2. twiki/templates/$scriptName.tmpl
   • $webName is the name of the web (ex: Main)
   • $scriptName is the script (ex: view).

NOTE: TWikiSkins can be defined to overload the standard templates.

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

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
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.

1. A topic name specified by the templatetopic CGI parameter.
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

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:
%DATE%	Current date, e.g. 2022-05-21
%WIKIUSERNAME%	User name, e.g. Main.TWikiGuest
%URLPARAM{"name"}%	Value of a named URL parameter
%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%{...}%
%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 }%

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%% }%.

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

Template Topics in Action

Here is an example for creating new topics based on a specific template 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 HTML source of the form:

<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
	* New example topic: 
	  <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
	  <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
	  <input type="hidden" name="topicparent" value="%TOPIC%" />
	  <input type="hidden" name="onlywikiname" value="on" />

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

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%

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. %A% NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> <a href="%WIKIHOMEURL%"> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> </td> <td> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> </td> </tr> <tr bgcolor="%WEBBGCOLOR%"> <td colspan="2"> %TMPL:P{"webaction"}% </td> </tr> </table> --- ++ %TMPL:P{"heading"}% %TMPL:P{"message"}% <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr bgcolor="%WEBBGCOLOR%"> <td valign="top"> Topic <b>%TOPIC%</b> . { %TMPL:P{"topicaction"}% } </td> </tr> </table> </body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

</table >

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% %TMPL:DEF{"heading"}% Test heading %TMPL:END% %TMPL:DEF{"message"}% Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... * Some more blah blah blah blah blah blah blah blah blah blah... * Param1: %PARAM1% * Param2: %PARAM2% * Param3: %PARAM3% * Param4: %PARAM4% %TMPL:END% %TMPL:DEF{"topicaction"}% Test =topicaction=: [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% %TMPL:INCLUDE{"oopsbase"}%

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.

TWiki Templates

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

Overview

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.

Major changes from the previous template system

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:

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

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).
• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %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.
• 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.
• Use of template directives is optional: templates work without them.
• NOTE: Template directives work only for templates: they do not get processed in topic text.

Types of Template

There are three types of template:

• Master Template: Stores common parts; included by other templates
• HTML Page Templates: Defines the layout of KoreaCmsWiki? pages
• Template Topics: Defines default text when you create a new topic

Master Templates

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.

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

HTML Page Templates

KoreaCmsWiki? 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 in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded by individual webs. The following search order applies:

1. twiki/templates/$webName/$scriptName.tmpl
2. twiki/templates/$scriptName.tmpl
   • $webName is the name of the web (ex: Main)
   • $scriptName is the script (ex: view).

NOTE: TWikiSkins can be defined to overload the standard templates.

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

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
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.

1. A topic name specified by the templatetopic CGI parameter.
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

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:
%DATE%	Current date, e.g. 2022-05-21
%WIKIUSERNAME%	User name, e.g. Main.TWikiGuest
%URLPARAM{"name"}%	Value of a named URL parameter
%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%{...}%
%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 }%

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%% }%.

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

Template Topics in Action

Here is an example for creating new topics based on a specific template 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 HTML source of the form:

<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
	* New example topic: 
	  <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
	  <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
	  <input type="hidden" name="topicparent" value="%TOPIC%" />
	  <input type="hidden" name="onlywikiname" value="on" />
	  <input type="submit" value="Create" />
	  (date format is <nop>YYYYxMMxDD)
</form>

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. %A% NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> <a href="%WIKIHOMEURL%"> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> </td> <td> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> </td> </tr> <tr bgcolor="%WEBBGCOLOR%"> <td colspan="2"> %TMPL:P{"webaction"}% </td> </tr> </table> --- ++ %TMPL:P{"heading"}% %TMPL:P{"message"}% <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr bgcolor="%WEBBGCOLOR%"> <td valign="top"> Topic <b>%TOPIC%</b> . { %TMPL:P{"topicaction"}% } </td> </tr> </table> </body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

</table >

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% %TMPL:DEF{"heading"}% Test heading %TMPL:END% %TMPL:DEF{"message"}% Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... * Some more blah blah blah blah blah blah blah blah blah blah... * Param1: %PARAM1% * Param2: %PARAM2% * Param3: %PARAM3% * Param4: %PARAM4% %TMPL:END% %TMPL:DEF{"topicaction"}% Test =topicaction=: [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% %TMPL:INCLUDE{"oopsbase"}%

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.

TWiki Templates

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

Overview

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.

Major changes from the previous template system

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:

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

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).
• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %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.
• 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.
• Use of template directives is optional: templates work without them.
• NOTE: Template directives work only for templates: they do not get processed in topic text.

Types of Template

There are three types of template:

• Master Template: Stores common parts; included by other templates
• HTML Page Templates: Defines the layout of KoreaCmsWiki? pages
• Template Topics: Defines default text when you create a new topic

Master Templates

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.

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

HTML Page Templates

KoreaCmsWiki? 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 in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded by individual webs. The following search order applies:

1. twiki/templates/$webName/$scriptName.tmpl
2. twiki/templates/$scriptName.tmpl
   • $webName is the name of the web (ex: Main)
   • $scriptName is the script (ex: view).

NOTE: TWikiSkins can be defined to overload the standard templates.

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

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
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.

1. A topic name specified by the templatetopic CGI parameter.
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

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:
%DATE%	Current date, e.g. 2022-05-21
%WIKIUSERNAME%	User name, e.g. Main.TWikiGuest
%URLPARAM{"name"}%	Value of a named URL parameter
%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%{...}%
%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 }%

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%% }%.

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

Template Topics in Action

Here is an example for creating new topics based on a specific template 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 HTML source of the form:

<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
	* New example topic: 
	  <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
	  <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />

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. %A% NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> <a href="%WIKIHOMEURL%"> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> </td> <td> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> </td> </tr> <tr bgcolor="%WEBBGCOLOR%"> <td colspan="2"> %TMPL:P{"webaction"}% </td> </tr> </table> --- ++ %TMPL:P{"heading"}% %TMPL:P{"message"}% <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr bgcolor="%WEBBGCOLOR%"> <td valign="top"> Topic <b>%TOPIC%</b> . { %TMPL:P{"topicaction"}% } </td> </tr> </table> </body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

</table >

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% %TMPL:DEF{"heading"}% Test heading %TMPL:END% %TMPL:DEF{"message"}% Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... * Some more blah blah blah blah blah blah blah blah blah blah... * Param1: %PARAM1% * Param2: %PARAM2% * Param3: %PARAM3% * Param4: %PARAM4% %TMPL:END% %TMPL:DEF{"topicaction"}% Test =topicaction=: [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% %TMPL:INCLUDE{"oopsbase"}%

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.

-- PeterThoeny - 01 Feb 2003
-- MikeMannix? - 14 Sep 2001
-- TWiki:Main/DavidLeBlanc - 11 Mar 2002

TWiki Templates

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

Overview

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.

Major changes from the previous template system

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:

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

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).
• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %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.
• 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.
• Use of template directives is optional: templates work without them.
• NOTE: Template directives work only for templates: they do not get processed in topic text.

Types of Template

There are three types of template:

• Master Template: Stores common parts; included by other templates
• HTML Page Templates: Defines the layout of KoreaCmsWiki? pages
• Template Topics: Defines default text when you create a new topic

Master Templates

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.

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

HTML Page Templates

KoreaCmsWiki? 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 in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded by individual webs. The following search order applies:

1. twiki/templates/$webName/$scriptName.tmpl
2. twiki/templates/$scriptName.tmpl
   • $webName is the name of the web (ex: Main)
   • $scriptName is the script (ex: view).

NOTE: TWikiSkins can be defined to overload the standard templates.

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

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
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.

1. A topic name specified by the templatetopic CGI parameter.
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

Template Topics in Action

Here is an example for creating new topics based on a specific template 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 HTML source of the form:

<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
	* New example topic: 
	  <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
	  <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
	  <input type="hidden" name="onlywikiname" value="on" />
	  <input type="submit" value="Create" />
	  (date format is <nop>YYYYxMMxDD)
</form>

The onlywikiname parameter enforces WikiWords for topic names.

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%

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. %A% NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> <a href="%WIKIHOMEURL%"> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> </td> <td> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> </td> </tr> <tr bgcolor="%WEBBGCOLOR%"> <td colspan="2"> %TMPL:P{"webaction"}% </td> </tr> </table> --- ++ %TMPL:P{"heading"}% %TMPL:P{"message"}% <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr bgcolor="%WEBBGCOLOR%"> <td valign="top"> Topic <b>%TOPIC%</b> . { %TMPL:P{"topicaction"}% } </td> </tr> </table> </body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

</table >

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% %TMPL:DEF{"heading"}% Test heading %TMPL:END% %TMPL:DEF{"message"}% Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... * Some more blah blah blah blah blah blah blah blah blah blah... * Param1: %PARAM1% * Param2: %PARAM2% * Param3: %PARAM3% * Param4: %PARAM4% %TMPL:END% %TMPL:DEF{"topicaction"}% Test =topicaction=: [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% %TMPL:INCLUDE{"oopsbase"}%

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.

TWiki Templates

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

Overview

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.

Major changes from the previous template system

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:

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

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).
• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %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.
• 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.
• Use of template directives is optional: templates work without them.
• NOTE: Template directives work only for templates: they do not get processed in topic text.

Types of Template

There are three types of template:

• Master Template: Stores common parts; included by other templates
• HTML Page Templates: Defines the layout of KoreaCmsWiki? pages
• Template Topics: Defines default text when you create a new topic

Master Templates

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.

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

HTML Page Templates

KoreaCmsWiki? 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 in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded by individual webs. The following search order applies:

1. twiki/templates/$webName/$scriptName.tmpl
2. twiki/templates/$scriptName.tmpl
   • $webName is the name of the web (ex: Main)
   • $scriptName is the script (ex: view).

NOTE: TWikiSkins can be defined to overload the standard templates.

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

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
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.

1. A topic name specified by the templatetopic CGI parameter.
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

Template Topics in Action

Here is an example for creating new topics based on a specific template topic:

• New example topic: (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:

• New example topic: <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" /> <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" /> <input type="hidden" name="onlywikiname" value="on" /> <input type="submit" value="Create" /> (date format is <nop>YYYYxMMxDD)

The onlywikiname parameter enforces WikiWords for topic names.

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%

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. %A% NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> <a href="%WIKIHOMEURL%"> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> </td> <td> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> </td> </tr> <tr bgcolor="%WEBBGCOLOR%"> <td colspan="2"> %TMPL:P{"webaction"}% </td> </tr> </table> --- ++ %TMPL:P{"heading"}% %TMPL:P{"message"}% <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr bgcolor="%WEBBGCOLOR%"> <td valign="top"> Topic <b>%TOPIC%</b> . { %TMPL:P{"topicaction"}% } </td> </tr> </table> </body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

</table >

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% %TMPL:DEF{"heading"}% Test heading %TMPL:END% %TMPL:DEF{"message"}% Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... * Some more blah blah blah blah blah blah blah blah blah blah... * Param1: %PARAM1% * Param2: %PARAM2% * Param3: %PARAM3% * Param4: %PARAM4% %TMPL:END% %TMPL:DEF{"topicaction"}% Test =topicaction=: [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% %TMPL:INCLUDE{"oopsbase"}%

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.

-- PeterThoeny - 23 Jul 2001
-- MikeMannix? - 14 Sep 2001
-- TWiki:Main/DavidLeBlanc - 11 Mar 2002

TWiki Templates

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

Overview

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.

Major changes from the previous template system

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:

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

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).
• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %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.
• 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.
• Use of template directives is optional: templates work without them.
• NOTE: Template directives work only for templates: they do not get processed in topic text.

Types of Template

There are three types of template:

• Master Template: Stores common parts; included by other templates
• HTML Page Templates: Defines the layout of KoreaCmsWiki? pages
• Template Topics: Defines default text when you create a new topic

Master Templates

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.

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

HTML Page Templates

KoreaCmsWiki? 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 in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded by individual webs. The following search order applies:

1. twiki/templates/$webName/$scriptName.tmpl
2. twiki/templates/$scriptName.tmpl
   • $webName is the name of the web (ex: Main)
   • $scriptName is the script (ex: view).

NOTE: TWikiSkins can be defined to overload the standard templates.

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

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
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.

1. A topic name specified by the templatetopic CGI parameter.
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

Template Topics in Action

Here is an example for creating new topics based on a specific template topic:

• New example topic: (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:

• New example topic: <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" /> <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" /> <input type="hidden" name="onlywikiname" value="on" /> <input type="submit" value="Create" /> (date format is <nop>YYYYxMMxDD)

The onlywikiname parameter enforces WikiWords for topic names.

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%

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. %A% NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> <a href="%WIKIHOMEURL%"> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> </td> <td> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> </td> </tr> <tr bgcolor="%WEBBGCOLOR%"> <td colspan="2"> %TMPL:P{"webaction"}% </td> </tr> </table> --- ++ %TMPL:P{"heading"}% %TMPL:P{"message"}% <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr bgcolor="%WEBBGCOLOR%"> <td valign="top"> Topic <b>%TOPIC%</b> . { %TMPL:P{"topicaction"}% } </td> </tr> </table> </body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

</table >

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% %TMPL:DEF{"heading"}% Test heading %TMPL:END% %TMPL:DEF{"message"}% Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... * Some more blah blah blah blah blah blah blah blah blah blah... * Param1: %PARAM1% * Param2: %PARAM2% * Param3: %PARAM3% * Param4: %PARAM4% %TMPL:END% %TMPL:DEF{"topicaction"}% Test =topicaction=: [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% %TMPL:INCLUDE{"oopsbase"}%

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.

-- PeterThoeny - 23 Jul 2001
-- MikeMannix? - 14 Sep 2001
-- TWiki:Main/DavidLeBlanc - 11 Mar 2002

TWiki Templates

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

Overview

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.

Major changes from the previous template system

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:

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

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).
• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %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.
• 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.
• Use of template directives is optional: templates work without them.
• NOTE: Template directives work only for templates: they do not get processed in topic text.

Types of Template

There are three types of template:

• Master Template: Stores common parts; included by other templates
• HTML Page Templates: Defines the layout of KoreaCmsWiki? pages
• Template Topics: Defines default text when you create a new topic

Master Templates

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.

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