3 <li><a href="#TWiki Templates"> TWiki Templates</a><ul>
4 <li><a href="#Overview"> Overview</a></li>
5 <li><a href="#Major changes from the previous"> Major changes from the previous template system</a></li>
6 <li><a href="#How Template Variables Work"> How Template Variables Work</a></li>
7 <li><a href="#Types of Template"> Types of Template</a><ul>
8 <li><a href="#Master Templates"> Master Templates</a></li>
9 <li><a href="#HTML Page Templates"> HTML Page Templates</a></li>
10 <li><a href="#Template Topics"> Template Topics</a><ul>
11 <li><a href="#Edit Template Topics and Variabl"> Edit Template Topics and Variable Expansion</a></li>
12 <li><a href="#Template Topics in Action"> Template Topics in Action</a></li>
17 <li><a href="#Templates by Example"> Templates by Example</a><ul>
18 <li><a href="#Base template oopsbase.tmpl"> Base template oopsbase.tmpl</a></li>
19 <li><a href="#Test template oopstest.tmpl"> Test template oopstest.tmpl</a></li>
20 <li><a href="#Sample screen shot of oopstest.t"> Sample screen shot of oopstest.tmpl</a></li>
23 <li><a href="#Known Issues"> Known Issues</a></li>
29 # <a name="TWiki Templates"></a> TWiki Templates
31 _Definition of the templates used to render all HTML pages displayed in TWiki_
33 ## <a name="Overview"></a> Overview
35 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|Main/WebHome#HtmlTemplates]], and also to supply [[default content|Main/WebHome#TemplateTopics]] for new pages.
37 ## <a name="Major changes from the previous"></a><a name="Major changes from the previous "></a> Major changes from the previous template system
39 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:
41 - separates a set of common template parts into a base template that is included by all of the related templates;
42 - defines common variables, like a standard separator (ex: "|"), in the base template;
43 - defines variable text in the individual templates and passes it back to the base template.
45 <a name="TemplateVariables"></a>
47 ## <a name="How Template Variables Work"></a> How Template Variables Work
49 - Special template directives (or preprocessor commands) are embedded in normal templates.
50 - All template preprocessing is done in `&TWiki::Store::readTemplate()` so that the caller simply gets an expanded template file (the same as before).
51 - Directives are of the form <code>**%TMPL:<key>%**</code> and <code>**%TMPL:<key>\{"attr"\}%**</code>.
53 - <code>**%TMPL:INCLUDE\{"file"\}%**</code>: Includes a template file. The template directory of the current web is searched first, then the templates root (`twiki/templates`).
54 - <code>**%TMPL:DEF\{"var"\}%**</code>: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
55 - <code>**%TMPL:END%**</code>: Ends variable definition.
56 - <code>**%TMPL:P\{"var"\}%**</code>: Prints a previously defined variable.
57 - Variables live in a global name space: there is no parameter passing.
58 - Two-pass processing lets you use a variable before or after declaring it.
59 - 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.
60 - %H% Use of template directives is optional: templates work without them.
61 - %X% **NOTE:** Template directives work only for templates: they do not get processed in topic text.
63 ## <a name="Types of Template"></a> Types of Template
65 There are three types of template:
67 - **Master Template**: Stores common parts; included by other templates
68 - **HTML Page Templates**: Defines the layout of %WIKITOOLNAME% pages
69 - **Template Topics**: Defines default text when you create a new topic
71 ### <a name="Master Templates"></a> Master Templates
73 Common parts, appearing in two or more templates, can be defined in a master template and then shared by others: <code>**twiki.tmpl**</code> is the default master template.
75 > <table border="1" cellpadding="0" cellspacing="0">
77 > <th bgcolor="#99CCCC"><strong> Template variable: </strong></th>
78 > <th bgcolor="#99CCCC"><strong> Defines: </strong></th>
81 > <td> %TMPL:DEF{"sep"}% </td>
82 > <td> "|" separator </td>
85 > <td> %TMPL:DEF{"htmldoctype"}% </td>
86 > <td> Start of all HTML pages </td>
89 > <td> %TMPL:DEF{"standardheader"}% </td>
90 > <td> Standard header (ex: view, index, search) </td>
93 > <td> %TMPL:DEF{"simpleheader"}% </td>
94 > <td> Simple header with reduced links (ex: edit, attach, oops) </td>
97 > <td> %TMPL:DEF{"standardfooter"}% </td>
98 > <td> Footer, excluding revision and copyright parts </td>
101 > <td> %TMPL:DEF{"oops"}% </td>
102 > <td> Skeleton of oops dialog </td>
106 <a name="HtmlTemplates"></a>
108 ### <a name="HTML Page Templates"></a> HTML Page Templates
110 %WIKITOOLNAME% 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.
112 Templates are in the <code>**twiki/templates**</code> directory. As an example, <code>**twiki/templates/view.tmpl**</code> is the template file for the <code>**twiki/bin/view**</code> script. Templates can be overloaded by individual webs. The following search order applies:
114 1. <code>**twiki/templates/$webName/$scriptName.tmpl**</code>
115 2. <code>**twiki/templates/$scriptName.tmpl**</code>
116 - `$webName` is the name of the web (ex: `Main`)
117 - `$scriptName` is the script (ex: `view`).
119 %H% **NOTE:** [[TWikiSkins]] can be defined to overload the standard templates.
121 Special variables are used in templates, especially in `view`, to display [[meta data|Main/TWikiMetaData#MetaDataRendering]].
123 <a name="TemplateTopics"></a>
125 ### <a name="Template Topics"></a> Template Topics
127 Template topics define the default text for new topics. There are three types of template topic:
129 > <table border="1" cellpadding="0" cellspacing="0">
131 > <th bgcolor="#99CCCC"><strong> Topic Name: </strong></th>
132 > <th bgcolor="#99CCCC"><strong> What it is: </strong></th>
135 > <td>[[Main/WebTopicViewTemplate]]</td>
136 > <td> Error page shown when you try to view a nonexistent topic </td>
139 > <td>[[Main/WebTopicNonWikiTemplate]]</td>
140 > <td> Alert page shown when you try to view a nonexistent topic with a non-WikiName </td>
143 > <td>[[Main/WebTopicEditTemplate]]</td>
144 > <td> Default text shown when you create a new topic. </td>
148 All template topics are located in the TWiki web. The [[WebTopicEditTemplate]] can be overloaded. When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:
150 1. A topic name specified by the `templatetopic` CGI parameter.
151 2. WebTopicEditTemplate in the current web
152 3. WebTopicEditTemplate in the TWiki web
154 #### <a name="Edit Template Topics and Variabl"></a> Edit Template Topics and Variable Expansion
156 The following variables get expanded when a user creates a new topic based on a template topic:
158 > <table border="1" cellpadding="0" cellspacing="0">
160 > <th bgcolor="#99CCCC"><strong> Variable: </strong></th>
161 > <th bgcolor="#99CCCC"><strong> Description: </strong></th>
164 > <td><code>%DATE%</code></td>
165 > <td> Current date, e.g. <code>29 Jun 2010</code></td>
168 > <td><code>%WIKIUSERNAME%</code></td>
169 > <td> User name, e.g. <code>Main.admin</code></td>
172 > <td><code>%URLPARAM{"name"}%</code></td>
173 > <td> Value of a named URL parameter </td>
176 > <td><code>%NOP%</code></td>
177 > <td> 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 <code>%URLPARAM%NOP%{...}%</code></td>
180 > <td><code>%NOP{ ... }%</code></td>
181 > <td> 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:%BR% <code>%NOP{%BR% * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup%BR% }%</code></td>
187 - Unlike other variables, `%NOP{ ... }%` can span multiple lines.
188 - 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%% }%`.
190 All other variables are unchanged, e.g. are carried over "as is" into the new topic.
192 #### <a name="Template Topics in Action"></a> Template Topics in Action
194 Here is an example for creating new topics based on a specific template topic:
196 <form action="http://www.dementia.org/twiki//edit/%WEB%/" name="new">
198 <li> New example topic: <input name="topic" size="23" type="text" value="ExampleTopic2010x06x29" /> <input name="templatetopic" type="hidden" value="ExampleTopicTemplate" /> <input name="topicparent" type="hidden" value="%TOPIC%" /> <input name="onlywikiname" type="hidden" value="on" /> <input type="submit" value="Create" /> (date format is YYYYxMMxDD) </li>
202 The above form asks for a topic name. A hidden input tag named <code>**templatetopic**</code> specifies [[ExampleTopicTemplate]] as the template topic to use. Here is the HTML source of the form:
204 <form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
206 <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
207 <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
208 <input type="hidden" name="topicparent" value="%TOPIC%" />
209 <input type="hidden" name="onlywikiname" value="on" />
210 <input type="submit" value="Create" />
211 (date format is <nop>YYYYxMMxDD)
214 The <code>**onlywikiname**</code> parameter enforces [[WikiWords]] for topic names. The <code>**topicparent**</code> parameter sets the topic parent to the topic where the form is located.
216 %T% **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: <br /><code>**-- %WIKIUSERNAME% - %DATE%**</code>
218 ## <a name="Templates by Example"></a> Templates by Example
220 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.
222 ### <a name="Base template oopsbase.tmpl"></a> Base template oopsbase.tmpl
224 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"}%`
226 > <table bgcolor="#f5f5f5" border="1" cellpadding="1" cellspacing="0">
229 > %TMPL:DEF{"sep"}% | %TMPL:END%
232 > <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title>
233 > <base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
234 > <meta name="robots" content="noindex">
236 > <body bgcolor="#FFFFFF">
237 > <table width="100%" border="0" cellpadding="3" cellspacing="0">
239 > <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%">
240 > <a href="%WIKIHOMEURL%">
241 > <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a>
244 > <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2">
245 > <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font>
248 > <tr bgcolor="%WEBBGCOLOR%">
249 > <td colspan="2">
250 > %TMPL:P{"webaction"}%
254 > --- ++ %TMPL:P{"heading"}%
255 > %TMPL:P{"message"}%
256 > <table width="100%" border="0" cellpadding="3" cellspacing="0">
257 > <tr bgcolor="%WEBBGCOLOR%">
258 > <td valign="top">
259 > Topic <b>%TOPIC%</b> . {
260 > %TMPL:P{"topicaction"}%
270 ### <a name="Test template oopstest.tmpl"></a> Test template oopstest.tmpl
272 Each oops template basically just defines some variables and includes the base template that does the layout work.
274 > <table bgcolor="#f5f5f5" border="1" cellpadding="1" cellspacing="0">
277 > %TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
278 > %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
279 > %TMPL:DEF{"heading"}%
280 > Test heading %TMPL:END%
281 > %TMPL:DEF{"message"}%
282 > Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...
284 > * Some more blah blah blah blah blah blah blah blah blah blah...
290 > %TMPL:DEF{"topicaction"}%
291 > Test =topicaction=:
292 > [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
293 > [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
294 > %TMPL:INCLUDE{"oopsbase"}%
298 > <td> </table > </td>
302 ### <a name="Sample screen shot of oopstest.t"></a> Sample screen shot of oopstest.tmpl
304 With URL: <code>**.../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify**</code>
306 > <table border="1" cellpadding="0" cellspacing="0">
308 > <td><img alt="testscreen.gif" height="304" src="http://www.dementia.org/twiki//view/testscreen.gif" width="589" /></td>
312 ## <a name="Known Issues"></a> Known Issues
314 - 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.
316 -- [[PeterThoeny]] - 01 Feb 2003 <br /> -- [[MikeMannix]] - 14 Sep 2001 <br /> -- TWiki:Main/DavidLeBlanc - 11 Mar 2002