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="#Template Topics in Action"> Template Topics in Action</a></li>
16 <li><a href="#Templates by Example"> Templates by Example</a><ul>
17 <li><a href="#Base template oopsbase.tmpl"> Base template oopsbase.tmpl</a></li>
18 <li><a href="#Test template oopstest.tmpl"> Test template oopstest.tmpl</a></li>
19 <li><a href="#Sample screen shot of oopstest.t"> Sample screen shot of oopstest.tmpl</a></li>
22 <li><a href="#Known Issues"> Known Issues</a></li>
28 # <a name="TWiki Templates"></a> TWiki Templates
30 _Definition of the templates used to render all HTML pages displayed in TWiki_
32 ## <a name="Overview"></a> Overview
34 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.
36 ## <a name="Major changes from the previous"></a><a name="Major changes from the previous "></a> Major changes from the previous template system
38 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:
40 - separates a set of common template parts into a base template that is included by all of the related templates;
41 - defines common variables, like a standard separator (ex: "|"), in the base template;
42 - defines variable text in the individual templates and passes it back to the base template.
44 <a name="TemplateVariables"></a>
46 ## <a name="How Template Variables Work"></a> How Template Variables Work
48 - Special template directives (or preprocessor commands) are embedded in normal templates.
49 - All template preprocessing is done in `&TWiki::Store::readTemplate()` so that the caller simply gets an expanded template file (the same as before).
50 - Directives are of the form <code>**%TMPL:<key>%**</code> and <code>**%TMPL:<key>\{"attr"\}%**</code>.
52 - <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`).
53 - <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.
54 - <code>**%TMPL:END%**</code>: Ends variable definition.
55 - <code>**%TMPL:P\{"var"\}%**</code>: Prints a previously defined variable.
56 - Variables live in a global name space: there is no parameter passing.
57 - Two-pass processing lets you use a variable before or after declaring it.
58 - 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.
59 - %H% Use of template directives is optional: templates work without them.
60 - %X% **NOTE:** Template directives work only for templates: they do not get processed in topic text.
62 ## <a name="Types of Template"></a> Types of Template
64 There are three types of template:
66 - **Master Template**: Stores common parts; included by other templates
67 - **HTML Page Templates**: Defines the layout of %WIKITOOLNAME% pages
68 - **Template Topics**: Defines default text when you create a new topic
70 ### <a name="Master Templates"></a> Master Templates
72 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.
74 > <table border="1" cellpadding="0" cellspacing="0">
76 > <th bgcolor="#99CCCC"><strong> Template variable: </strong></th>
77 > <th bgcolor="#99CCCC"><strong> Defines: </strong></th>
80 > <td> %TMPL:DEF{"sep"}% </td>
81 > <td> "|" separator </td>
84 > <td> %TMPL:DEF{"htmldoctype"}% </td>
85 > <td> Start of all HTML pages </td>
88 > <td> %TMPL:DEF{"standardheader"}% </td>
89 > <td> Standard header (ex: view, index, search) </td>
92 > <td> %TMPL:DEF{"simpleheader"}% </td>
93 > <td> Simple header with reduced links (ex: edit, attach, oops) </td>
96 > <td> %TMPL:DEF{"standardfooter"}% </td>
97 > <td> Footer, excluding revision and copyright parts </td>
100 > <td> %TMPL:DEF{"oops"}% </td>
101 > <td> Skeleton of oops dialog </td>
105 <a name="HtmlTemplates"></a>
107 ### <a name="HTML Page Templates"></a> HTML Page Templates
109 %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.
111 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:
113 1. <code>**twiki/templates/$webName/$scriptName.tmpl**</code>
114 2. <code>**twiki/templates/$scriptName.tmpl**</code>
115 - `$webName` is the name of the web (ex: `Main`)
116 - `$scriptName` is the script (ex: `view`).
118 %H% **NOTE:** [[TWikiSkins]] can be defined to overload the standard templates.
120 Special variables are used in templates, especially in `view`, to display [[meta data|Main/TWikiMetaData#MetaDataRendering]].
122 <a name="TemplateTopics"></a>
124 ### <a name="Template Topics"></a> Template Topics
126 Template topics define the default text for new topics. There are three types of template topic:
128 > <table border="1" cellpadding="0" cellspacing="0">
130 > <th bgcolor="#99CCCC"><strong> Topic Name: </strong></th>
131 > <th bgcolor="#99CCCC"><strong> What it is: </strong></th>
134 > <td>[[Main/WebTopicViewTemplate]]</td>
135 > <td> Error page shown when you try to view a nonexistent topic </td>
138 > <td>[[Main/WebTopicNonWikiTemplate]]</td>
139 > <td> Alert page shown when you try to view a nonexistent topic with a non-WikiName </td>
142 > <td>[[Main/WebTopicEditTemplate]]</td>
143 > <td> Default text shown when you create a new topic. </td>
147 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:
149 1. A topic name specified by the `templatetopic` CGI parameter.
150 2. WebTopicEditTemplate in the current web
151 3. WebTopicEditTemplate in the TWiki web
153 #### <a name="Template Topics in Action"></a> Template Topics in Action
155 Here is an example for creating new topics based on a specific template topic:
157 <form action="http://www.dementia.org/twiki//edit/%WEB%/" name="new">
159 <li> New example topic: <input name="topic" size="23" type="text" value="ExampleTopic2010x06x29" /> <input name="templatetopic" type="hidden" value="ExampleTopicTemplate" /> <input type="submit" value="Create" /> (date format is YYYYxMMxDD) </li>
163 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:
165 <form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
167 <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
168 <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
169 <input type="hidden" name="onlywikiname" value="on" />
170 <input type="submit" value="Create" />
171 (date format is <nop>YYYYxMMxDD)
174 The <code>**onlywikiname**</code> parameter enforces [[WikiWords]] for topic names.
176 %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>
178 ## <a name="Templates by Example"></a> Templates by Example
180 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.
182 ### <a name="Base template oopsbase.tmpl"></a> Base template oopsbase.tmpl
184 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"}%`
186 > <table bgcolor="#f5f5f5" border="1" cellpadding="1" cellspacing="0">
189 > %TMPL:DEF{"sep"}% | %TMPL:END%
192 > <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title>
193 > <base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
194 > <meta name="robots" content="noindex">
196 > <body bgcolor="#FFFFFF">
197 > <table width="100%" border="0" cellpadding="3" cellspacing="0">
199 > <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%">
200 > <a href="%WIKIHOMEURL%">
201 > <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a>
204 > <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2">
205 > <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font>
208 > <tr bgcolor="%WEBBGCOLOR%">
209 > <td colspan="2">
210 > %TMPL:P{"webaction"}%
214 > --- ++ %TMPL:P{"heading"}%
215 > %TMPL:P{"message"}%
216 > <table width="100%" border="0" cellpadding="3" cellspacing="0">
217 > <tr bgcolor="%WEBBGCOLOR%">
218 > <td valign="top">
219 > Topic <b>%TOPIC%</b> . {
220 > %TMPL:P{"topicaction"}%
230 ### <a name="Test template oopstest.tmpl"></a> Test template oopstest.tmpl
232 Each oops template basically just defines some variables and includes the base template that does the layout work.
234 > <table bgcolor="#f5f5f5" border="1" cellpadding="1" cellspacing="0">
237 > %TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
238 > %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
239 > %TMPL:DEF{"heading"}%
240 > Test heading %TMPL:END%
241 > %TMPL:DEF{"message"}%
242 > Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...
244 > * Some more blah blah blah blah blah blah blah blah blah blah...
250 > %TMPL:DEF{"topicaction"}%
251 > Test =topicaction=:
252 > [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
253 > [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
254 > %TMPL:INCLUDE{"oopsbase"}%
258 > <td> </table > </td>
262 ### <a name="Sample screen shot of oopstest.t"></a> Sample screen shot of oopstest.tmpl
264 With URL: <code>**.../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify**</code>
266 > <table border="1" cellpadding="0" cellspacing="0">
268 > <td><img alt="testscreen.gif" height="304" src="http://www.dementia.org/twiki//view/testscreen.gif" width="589" /></td>
272 ## <a name="Known Issues"></a> Known Issues
274 - 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.
276 -- [[PeterThoeny]] - 23 Jul 2001 <br /> -- [[MikeMannix]] - 14 Sep 2001 <br /> -- TWiki:Main/DavidLeBlanc - 11 Mar 2002