# 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|Main/WebHome#HtmlTemplates]], and also to supply [[default content|Main/WebHome#TemplateTopics]] 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. - %H% Use of template directives is optional: templates work without them. - %X% **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 %WIKITOOLNAME% 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 %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. 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`). %H% **NOTE:** [[TWikiSkins]] can be defined to overload the standard templates. Special variables are used in templates, especially in `view`, to display [[meta data|Main/TWikiMetaData#MetaDataRendering]]. ### Template Topics Template topics define the default text for new topics. There are three types of template topic: > > > > > > > > > > > > > > > > > >
Topic Name: What it is:
[[Main/WebTopicViewTemplate]] Error page shown when you try to view a nonexistent topic
[[Main/WebTopicNonWikiTemplate]] Alert page shown when you try to view a nonexistent topic with a non-WikiName
[[Main/WebTopicEditTemplate]] Default text shown when you create a new topic.
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: 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. 29 Jun 2010
%WIKIUSERNAME% User name, e.g. Main.admin
%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:%BR% %NOP{%BR%   * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup%BR% }%
**_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:
* New example topic: (date format is YYYYxMMxDD) 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 [[Main/WikiWord]]
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
anyname Any parameter can passed to the new topic; if the template topic contains %URLPARAM{"anyname"}%, it will be replaced by its value
%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:
**-- %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. > > > > > > > >
> %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:DEF{"topicaction"}%
> Test =topicaction=:
> [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
> [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
> %TMPL:INCLUDE{"oopsbase"}%
</table >
### Sample screen shot of oopstest.tmpl With URL: **.../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify** > > > > >
## 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:Main.PeterThoeny - 16 Dec 2003 %BR% -- TWiki:Main.MikeMannix - 14 Sep 2001 %BR% -- TWiki:Main.DavidLeBlanc - 11 Mar 2002