[openafs-wiki.git] / TWiki / TWikiTemplates.mdwn

<div>
  <ul>
    <li><a href="#TWiki Templates"> TWiki Templates</a><ul>
        <li><a href="#Overview"> Overview</a></li>
        <li><a href="#Major changes from the previous"> Major changes from the previous template system</a></li>
        <li><a href="#How Template Variables Work"> How Template Variables Work</a></li>
        <li><a href="#Types of Template"> Types of Template</a><ul>
            <li><a href="#Master Templates"> Master Templates</a></li>
            <li><a href="#HTML Page Templates"> HTML Page Templates</a></li>
            <li><a href="#Template Topics"> Template Topics</a><ul>
                <li><a href="#Template Topics in Action"> Template Topics in Action</a></li>
              </ul>
            </li>
          </ul>
        </li>
        <li><a href="#Templates by Example"> Templates by Example</a><ul>
            <li><a href="#Base template oopsbase.tmpl"> Base template oopsbase.tmpl</a></li>
            <li><a href="#Test template oopstest.tmpl"> Test template oopstest.tmpl</a></li>
            <li><a href="#Sample screen shot of oopstest.t"> Sample screen shot of oopstest.tmpl</a></li>
          </ul>
        </li>
        <li><a href="#Known Issues"> Known Issues</a></li>
      </ul>
    </li>
  </ul>
</div>

# <a name="TWiki Templates"></a> TWiki Templates

_Definition of the templates used to render all HTML pages displayed in TWiki_

## <a name="Overview"></a> 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.

## <a name="Major changes from the previous"></a><a name="Major changes from the previous "></a> 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.

## <a name="How Template Variables Work"></a> 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 <code>**%TMPL:&lt;key&gt;%**</code> and <code>**%TMPL:&lt;key&gt;\{"attr"\}%**</code>.
- Directives:
  - <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`).
  - <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.
  - <code>**%TMPL:END%**</code>: Ends variable definition.
  - <code>**%TMPL:P\{"var"\}%**</code>: 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.

## <a name="Types of Template"></a> 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

### <a name="Master Templates"></a> Master Templates

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.

> <table border="1" cellpadding="0" cellspacing="0">
>   <tr>
>     <th bgcolor="#99CCCC"><strong> Template variable: </strong></th>
>     <th bgcolor="#99CCCC"><strong> Defines: </strong></th>
>   </tr>
>   <tr>
>     <td> %TMPL:DEF{"sep"}% </td>
>     <td> "|" separator </td>
>   </tr>
>   <tr>
>     <td> %TMPL:DEF{"htmldoctype"}% </td>
>     <td> Start of all HTML pages </td>
>   </tr>
>   <tr>
>     <td> %TMPL:DEF{"standardheader"}% </td>
>     <td> Standard header (ex: view, index, search) </td>
>   </tr>
>   <tr>
>     <td> %TMPL:DEF{"simpleheader"}% </td>
>     <td> Simple header with reduced links (ex: edit, attach, oops) </td>
>   </tr>
>   <tr>
>     <td> %TMPL:DEF{"standardfooter"}% </td>
>     <td> Footer, excluding revision and copyright parts </td>
>   </tr>
>   <tr>
>     <td> %TMPL:DEF{"oops"}% </td>
>     <td> Skeleton of oops dialog </td>
>   </tr>
> </table>

<a name="HtmlTemplates"></a>

### <a name="HTML Page Templates"></a> 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 <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:

1. <code>**twiki/templates/$webName/$scriptName.tmpl**</code>
2. <code>**twiki/templates/$scriptName.tmpl**</code>
  - `$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]].

<a name="TemplateTopics"></a>

### <a name="Template Topics"></a> Template Topics

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

> <table border="1" cellpadding="0" cellspacing="0">
>   <tr>
>     <th bgcolor="#99CCCC"><strong> Topic Name: </strong></th>
>     <th bgcolor="#99CCCC"><strong> What it is: </strong></th>
>   </tr>
>   <tr>
>     <td>[[Main/WebTopicViewTemplate]]</td>
>     <td> Error page shown when you try to view a nonexistent topic </td>
>   </tr>
>   <tr>
>     <td>[[Main/WebTopicNonWikiTemplate]]</td>
>     <td> Alert page shown when you try to view a nonexistent topic with a non-WikiName </td>
>   </tr>
>   <tr>
>     <td>[[Main/WebTopicEditTemplate]]</td>
>     <td> Default text shown when you create a new topic. </td>
>   </tr>
> </table>

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

#### <a name="Template Topics in Action"></a> Template Topics in Action

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

<form action="http://www.dementia.org/twiki//edit/%WEB%/" name="new">
  <ul>
    <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>
  </ul>
</form>

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:

    <form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%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 <code>**onlywikiname**</code> parameter enforces [[WikiWords]] for topic names.

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

## <a name="Templates by Example"></a> 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.

### <a name="Base template oopsbase.tmpl"></a> 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"}%`

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

### <a name="Test template oopstest.tmpl"></a> Test template oopstest.tmpl

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

> <table bgcolor="#f5f5f5" border="1" cellpadding="1" cellspacing="0">
>   <tr>
>     <td><pre>
> %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"}%
> </pre></td>
>   </tr>
>   <tr>
>     <td> &lt;/table &gt; </td>
>   </tr>
> </table>

### <a name="Sample screen shot of oopstest.t"></a> Sample screen shot of oopstest.tmpl

With URL: <code>**.../bin/oops/Sandbox/TestTopic2?template=oopstest&amp;param1=WebHome&amp;param2=WebNotify**</code>

> <table border="1" cellpadding="0" cellspacing="0">
>   <tr>
>     <td><img alt="testscreen.gif" height="304" src="http://www.dementia.org/twiki//view/testscreen.gif" width="589" /></td>
>   </tr>
> </table>

## <a name="Known Issues"></a> 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 <br /> -- [[MikeMannix]] - 14 Sep 2001 <br /> -- TWiki:Main/DavidLeBlanc - 11 Mar 2002