Difference: TWikiTemplates (5 vs. 6)

Revision 62001-09-15 - MikeMannix

Line: 1 to 1
 
META TOPICPARENT name="WebHome"
Line: 36 to 36
 
  • Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads just the twiki.tmpl, like twiki.print.tmpl, that redefines the header and footer.
  • Note: The template directives work only for templates, they do not get processed in topic text.
Changed:
<
<

New Template System by Example

>
>

TWiki Master Template

All common parts are defined in a master template, twiki.tmpl, that all other templates use.

Template variable: Defines:
%TMPL:DEF{"sep"}% "|" separator
%TMPL:DEF{"htmldoctype"}% Start of all HTML pages
%TMPL:DEF{"standardheader"}% Standard header (ex: view, index, seach)
%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

Types of Template

There are two types of templates:

  • HTML Page Templates: Defines layout of TWiki pages
  • Template Topics: Defines default text when you create a new topic

HTML Page Templates

TWiki uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.

The template files 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 per web. The following search order applies:

  1. twiki/templates/$webName/$scriptName.tmpl
  2. twiki/templates/$scriptName.tmpl

Note: $webName is the name of the web ( i.e. Main ), and $scriptName is the script ( i.e. view ).

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

Some special variables are used in templates ( especially view ) to show meta data - see Meta Data Rendering

Template Topics

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

Topic Name: What it is:
WebTopicViewTemplate Help text shown when you view a non existing topic.
WebTopicNonWikiTemplate Help text shown when you view a non existing topic that has not a WikiName.
WebTopicEditTemplate Default text shown when you create a new topic.
All template topics are located in the TWiki web. The WebTopicEditTemplate can be overloaded. The following search order applies when you create a new topic:

  1. The topic name specified by the templatetopic 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 YYYYMMDD)

Above form asks for a topic name. A hidden input tag of name "templatetopic" specifies the ExampleTopicTemplate as the template topic. Here is the HTML source of the form:

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

The "onlywikiname" parameter enforces WikiWords for topic names.

Note: Use can use the %WIKIUSERNAME% and %DATE% variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is:
-- %WIKIUSERNAME% - %DATE%

Templates by Example

  Attached is an example of an oops base template oopsbase.tmpl and a example oops dialog oopstest.tmpl which is based on the base template. NOTE: This isn't the release version, just a quick, simple demo.
Line: 44 to 119
  The first line declares the delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%
Changed:
<
<
>
>
 
%TMPL:DEF{"sep"}% | %TMPL:END%

Line: 95 to 169
  Each oops template basically just defines some variables and includes the base template that does the layout work.
Changed:
<
<
>
>
 
%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%

Line: 126 to 200
  With URL: .../bin/oops/Test/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify
Changed:
<
<
>
>
 
testscreen.gif
Deleted:
<
<

TWiki master template

All common template parts are defined in one master template, twiki.tmpl, that all other templates include.

Template variable: Defines:
%TMPL:DEF{"sep"}% "|" separator
%TMPL:DEF{"htmldoctype"}% Start of all HTML pages
%TMPL:DEF{"standardheader"}% Standard header (ex: view, index, seach)
%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

Example: oopspreview.tmpl template
%TMPL:INCLUDE{"twiki"}%
%TMPL:DEF{"titleaction"}% (oops) %TMPL:END%
%TMPL:DEF{"webaction"}% *Attention* %TMPL:END%
%TMPL:DEF{"heading"}% Topic is not saved yet %TMPL:END%
%TMPL:DEF{"message"}% Please go back in your browser and save the topic. %TMPL:END%
%TMPL:DEF{"topicaction"}%
%TMPL:END%
%TMPL:P{"oops"}%
 

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 is a structurally complete HTML document with a .tmpl filename extension - it contains unresolved %VARIABLES%, but can still be previewed directly in a browser.
Changed:
<
<
-- PeterThoeny - 23 Jul 2001
-- MikeMannix - 30 Aug 2001
>
>
-- PeterThoeny - 23 Jul 2001
-- MikeMannix - 14 Sep 2001
 
META FILEATTACHMENT attr="h" comment="Example of oopstest.tmpl rendered" date="999598142" name="testscreen.gif" path="C:\02_TWikiDocs\testscreen.gif" size="9460" user="MikeMannix" version="1.1"
META TOPICMOVED by="MikeMannix" date="1000277381" from="TWiki.TWikiTemplateSystem" to="TWiki.TWikiTemplates"
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiTemplates