data/TWiki/TWikiTemplates.txt,v
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     1 head	1.28;
       
     2 access;
       
     3 symbols;
       
     4 locks; strict;
       
     5 comment	@# @;
       
     6 
       
     7 
       
     8 1.28
       
     9 date	2008.01.22.03.21.32;	author TWikiContributor;	state Exp;
       
    10 branches;
       
    11 next	1.27;
       
    12 
       
    13 1.27
       
    14 date	2007.03.03.14.51.54;	author TWikiContributor;	state Exp;
       
    15 branches;
       
    16 next	1.26;
       
    17 
       
    18 1.26
       
    19 date	2007.01.16.04.12.06;	author TWikiContributor;	state Exp;
       
    20 branches;
       
    21 next	1.25;
       
    22 
       
    23 1.25
       
    24 date	2006.04.01.05.55.16;	author TWikiContributor;	state Exp;
       
    25 branches;
       
    26 next	1.24;
       
    27 
       
    28 1.24
       
    29 date	2006.02.01.12.01.20;	author TWikiContributor;	state Exp;
       
    30 branches;
       
    31 next	1.23;
       
    32 
       
    33 1.23
       
    34 date	2004.08.15.21.22.01;	author PeterThoeny;	state Exp;
       
    35 branches;
       
    36 next	1.22;
       
    37 
       
    38 1.22
       
    39 date	2004.04.25.07.07.38;	author PeterThoeny;	state Exp;
       
    40 branches;
       
    41 next	1.21;
       
    42 
       
    43 1.21
       
    44 date	2003.12.31.07.29.57;	author PeterThoeny;	state Exp;
       
    45 branches;
       
    46 next	1.20;
       
    47 
       
    48 1.20
       
    49 date	2003.12.16.08.19.00;	author PeterThoeny;	state Exp;
       
    50 branches;
       
    51 next	1.19;
       
    52 
       
    53 1.19
       
    54 date	2003.04.02.08.24.51;	author PeterThoeny;	state Exp;
       
    55 branches;
       
    56 next	1.18;
       
    57 
       
    58 1.18
       
    59 date	2003.02.01.12.46.00;	author PeterThoeny;	state Exp;
       
    60 branches;
       
    61 next	1.17;
       
    62 
       
    63 1.17
       
    64 date	2003.01.08.07.13.12;	author PeterThoeny;	state Exp;
       
    65 branches;
       
    66 next	1.16;
       
    67 
       
    68 1.16
       
    69 date	2003.01.05.05.02.04;	author PeterThoeny;	state Exp;
       
    70 branches;
       
    71 next	1.15;
       
    72 
       
    73 1.15
       
    74 date	2003.01.05.02.53.25;	author PeterThoeny;	state Exp;
       
    75 branches;
       
    76 next	1.14;
       
    77 
       
    78 1.14
       
    79 date	2003.01.04.07.51.31;	author PeterThoeny;	state Exp;
       
    80 branches;
       
    81 next	1.13;
       
    82 
       
    83 1.13
       
    84 date	2002.12.20.09.09.08;	author PeterThoeny;	state Exp;
       
    85 branches;
       
    86 next	1.12;
       
    87 
       
    88 1.12
       
    89 date	2002.07.18.07.20.00;	author PeterThoeny;	state Exp;
       
    90 branches;
       
    91 next	1.11;
       
    92 
       
    93 1.11
       
    94 date	2001.12.04.10.21.53;	author PeterThoeny;	state Exp;
       
    95 branches;
       
    96 next	1.10;
       
    97 
       
    98 1.10
       
    99 date	2001.09.18.05.33.48;	author MikeMannix;	state Exp;
       
   100 branches;
       
   101 next	1.9;
       
   102 
       
   103 1.9
       
   104 date	2001.09.16.05.43.05;	author MikeMannix;	state Exp;
       
   105 branches;
       
   106 next	1.8;
       
   107 
       
   108 1.8
       
   109 date	2001.09.15.19.19.17;	author PeterThoeny;	state Exp;
       
   110 branches;
       
   111 next	1.7;
       
   112 
       
   113 1.7
       
   114 date	2001.09.15.09.32.57;	author MikeMannix;	state Exp;
       
   115 branches;
       
   116 next	1.6;
       
   117 
       
   118 1.6
       
   119 date	2001.09.15.05.49.30;	author MikeMannix;	state Exp;
       
   120 branches;
       
   121 next	1.5;
       
   122 
       
   123 1.5
       
   124 date	2001.09.14.08.41.49;	author PeterThoeny;	state Exp;
       
   125 branches;
       
   126 next	1.4;
       
   127 
       
   128 1.4
       
   129 date	2001.09.12.06.49.41;	author MikeMannix;	state Exp;
       
   130 branches;
       
   131 next	1.3;
       
   132 
       
   133 1.3
       
   134 date	2001.09.08.14.50.06;	author MikeMannix;	state Exp;
       
   135 branches;
       
   136 next	1.2;
       
   137 
       
   138 1.2
       
   139 date	2001.09.07.10.07.14;	author MikeMannix;	state Exp;
       
   140 branches;
       
   141 next	1.1;
       
   142 
       
   143 1.1
       
   144 date	2001.09.04.10.07.11;	author MikeMannix;	state Exp;
       
   145 branches;
       
   146 next	;
       
   147 
       
   148 
       
   149 desc
       
   150 @none
       
   151 @
       
   152 
       
   153 
       
   154 1.28
       
   155 log
       
   156 @buildrelease
       
   157 @
       
   158 text
       
   159 @%META:TOPICINFO{author="TWikiContributor" date="1196874068" format="1.1" version="28"}%
       
   160 %STARTINCLUDE%
       
   161 ---+ TWiki Templates
       
   162 
       
   163 _Definition of the templates used to render all HTML pages displayed in TWiki_ 
       
   164 
       
   165 %TOC%
       
   166 
       
   167 ---++ Overview
       
   168 
       
   169 _Templates_ are plain text with embedded _template directives_ that tell TWiki how to compose blocks of text together, to create something new.
       
   170 
       
   171 There are two types of template:
       
   172    * *Master Templates*: Define the HTML used to display TWiki pages.
       
   173    * *Template Topics*: Define default text when you create a new topic
       
   174 
       
   175 __%T% Tip:__ TWiki:TWiki.TWikiTemplatesSupplement on TWiki.org has supplemental documentation on TWiki templates.
       
   176 
       
   177 #HtmlTemplates
       
   178 ---++ Master Templates
       
   179 TWiki uses master templates when composing the output from 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.
       
   180 
       
   181 Master templates are also used in the definition of TWikiSkins.
       
   182 
       
   183 Master templates are stored as text files with the extension =.tmpl=. They are usually HTML with embedded _template directives_. The directives are expanded when TWiki wants to generate a user interface screen.
       
   184 
       
   185 #TemplateVariables
       
   186 ---+++ How Template Directives Work
       
   187    * Directives are of the form ==%<nop>TMPL:&lt;key&gt;%== and ==%<nop>TMPL:&lt;key&gt;{"attr"}%==.
       
   188    * Directives:
       
   189       * ==%<nop>TMPL:INCLUDE{"file"}%==: Includes a template file. The file is found as described [[#FindingTemplates][below]].
       
   190       * ==%<nop>TMPL:DEF{"block"}%==: Define a block. *All* text between this and the next =%<nop>TMPL:END%= directive is removed and saved for later use with =%<nop>TMPL:P=.
       
   191       * ==%<nop>TMPL:END%==: Ends a block definition.
       
   192       * ==%<nop>TMPL:P{"var"}%==: Includes a previously defined block.
       
   193       * ==%<nop>{...}%==: is a comment.
       
   194    * Two-pass processing lets you use a variable before or after declaring it.
       
   195    * 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.
       
   196    * %H% Use of template directives is optional: templates work without them.
       
   197    * %X% *NOTE:* Template directives work only for templates: they do not get processed in normal topic text.
       
   198 
       
   199 TMPL:P also supports simple parameters. For example, given the definition
       
   200 =%<nop>TMPL:DEF{"x"}% x%<nop>P%z%<nop>TMPL:END%= then =%<nop>TMPL:P{"x" P="y"}%= will expand to =xyz=.
       
   201 
       
   202 Note that parameters can simply be ignored; for example, =%<nop>TMPL:P{"x"}%= will expand to x%<nop>P%z.
       
   203 
       
   204 Any alphanumeric characters can be used in parameter names. You are highly recommended to use parameter names that cannot be confused with TWikiVariables.
       
   205 
       
   206 Note that three parameter names, =context=, =then= and =else= are *reserved*. They are used to support a limited form of "if" condition that you can use to select which of two templates to use, based on a _context identifier_:
       
   207 <verbatim>
       
   208 %TMPL:DEF{"link_inactive"}%<input type="button" disabled value="Link>%TMPL:END%
       
   209 %TMPL:DEF{"link_active"}%<input type="button" onclick="link()" value="Link" />%TMPL:END%
       
   210 %TMPL:P{context="inactive" then="inactive_link" else="active_link"}% for %CONTEXT%
       
   211 </verbatim>
       
   212 When the "inactive" context is set, then this will expand the "link_inactive" template; otherwise it will expand the "link_active" template.
       
   213 See IfStatements for details of supported context identifiers.
       
   214 
       
   215 ---+++ Finding Templates
       
   216 
       
   217 The master templates shipped with a twiki release are stored in the twiki/templates directory. As an example, ==twiki/templates/view.tmpl== is the default template file for the ==twiki/bin/view== script. 
       
   218 
       
   219 You can save templates in other directories as long as they are listed in the ={TemplatePath}= configuration setting. The ={TemplatePath}= is defined in the Miscellaneous section of the [[%SCRIPTURLPATH{configure}%][configure]] page.
       
   220 
       
   221 You can also save templates in user topics. The ={TemplatePath}= configuration setting defines which topics will be accepted as templates.
       
   222 
       
   223 Templates that are included with an explicit ='.tmpl'= extension  are looked for only in the =templates/= directory. For instance =%TMPL:INCLUDE{"example.tmpl"}%= will only return =templates/example.tmpl=, regardless of ={TemplatePath}= and SKIN settings.
       
   224 
       
   225 The out-of-the-box setting of ={TemplatePath}= supports the following search order to determine which template file or topic to use for a particular script or =%TMPL:INCLUDE{"script"}%= statement. The _skin path_ is set as described in TWikiSkins.
       
   226 
       
   227    1 templates/%RED%web%ENDCOLOR%/%RED%script%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl for each %RED%skin%ENDCOLOR% on the skin path
       
   228       * %X% this usage is supported *for compatibility only* and is *deprecated*. Store web-specific templates in TWiki topics instead.
       
   229    1 templates/%RED%script%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl for each %RED%skin%ENDCOLOR% on the skin path
       
   230    1 templates/%RED%web%ENDCOLOR%/%RED%script%ENDCOLOR%.tmpl
       
   231       * %X% this usage is supported *for compatibility only* and is *deprecated*. Store web-specific templates in TWiki topics instead.
       
   232    1 templates/%RED%script%ENDCOLOR%.tmpl
       
   233    1 The TWiki topic aweb.atopic if the template name can be parsed into aweb.atopic
       
   234    1 The TWiki topic %RED%web%ENDCOLOR%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
       
   235    1 The TWiki topic %RED%web%ENDCOLOR%.%RED%Script%ENDCOLOR%Template
       
   236    1 The TWiki topic %<nop>SYSTEMWEB%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
       
   237    1 The TWiki topic %<nop>SYSTEMWEB%.%RED%Script%ENDCOLOR%Template
       
   238 *Legend:*
       
   239    * %RED%script%ENDCOLOR% refers to the script name, e.g =view=, =edit=
       
   240    * %RED%Script%ENDCOLOR% refers to the same, but with the first character capitalized, e.g =View=
       
   241    * %RED%skin%ENDCOLOR% refers to a skin name, e.g =dragon=, =pattern=. All skins are checked at each stage, in the order they appear in the skin path.
       
   242    * %RED%Skin%ENDCOLOR% refers to the same, but with the first character capitalized, e.g =Dragon=
       
   243    * %RED%web%ENDCOLOR% refers to the current web
       
   244 
       
   245 For example, the =example= template file will be searched for in the following places, when the current web is =Thisweb= and the skin path is =print,pattern=:
       
   246 
       
   247    I. =templates/Thisweb/example.print.tmpl= _deprecated; don't rely on it_
       
   248    I. =templates/Thisweb/example.pattern.tmpl= _deprecated; don't rely on it_
       
   249    I. =templates/example.print.tmpl=
       
   250    I. =templates/example.pattern.tmpl=
       
   251    I. =templates/Thisweb/example.tmpl= _deprecated; don't rely on it_
       
   252    I. =templates/example.tmpl=
       
   253    I. =Thisweb.PrintSkinExampleTemplate=
       
   254    I. =Thisweb.PatternSkinExampleTemplate=
       
   255    I. =Thisweb.ExampleTemplate=
       
   256    I. =%SYSTEMWEB%.PrintSkinExampleTemplate=
       
   257    I. =%SYSTEMWEB%.PatternSkinExampleTemplate=
       
   258    I. =%SYSTEMWEB%.ExampleTemplate=
       
   259 
       
   260 Template names are usually derived from the name of the currently executing script; however it is also possible to override these settings in the =view= and =edit= scripts, for example when a topic-specific template is required. Two preference variables can be used to override the templates used:
       
   261    * =VIEW_TEMPLATE= sets the template to be used for viewing a topic
       
   262    * =EDIT_TEMPLATE= sets the template for editing a topic.
       
   263 If these preferences are set locally (using _Local_ instead of _Set_) for a topic, in WebPreferences, in [[%LOCALSITEPREFS%]], or [[%SYSTEMWEB%.TWikiPreferences]] (using _Set_), the indicated templates will be chosen for =view= and =edit= respectively. The template search order is as specified above.
       
   264 
       
   265 ---+++ TMPL:INCLUDE recursion for piecewise customisation, or mixing in new features
       
   266 
       
   267 If there is recursion in the TMPL:INCLUDE chain (eg twiki.classic.tmpl contains =%<nop>TMPL:INCLUDE{"twiki"}%=, the templating system will include the next twiki.SKIN in the skin path. 
       
   268 For example, to create a customisation of pattern skin, where you _only_ want to over-ride the breadcrumbs for the view script, you can create only a view.yourlocal.tmpl:
       
   269 <verbatim>
       
   270 %TMPL:INCLUDE{"view"}%
       
   271 %TMPL:DEF{"breadcrumb"}% We don't want any crumbs %TMPL:END%
       
   272 </verbatim>
       
   273 and then set SKIN=yourlocal,pattern
       
   274 
       
   275 The default ={TemplatePath}= will not give you the desired result if you put these statements in the topic =Thisweb.YourlocalSkinViewTemplate=. The default ={TemplatePath}= will resolve the request to the =template/view.pattern.tmpl=, before it gets to the =Thisweb.YourlocalSkinViewTemplate= resolution. You can make it work by prefixing the ={TemplatePath}= with: =$web.YourlocalSkin$nameTemplate=. 
       
   276 
       
   277 ---+++ Default master template
       
   278 
       
   279 ==twiki.tmpl== is the default master template. It defines the following sections.
       
   280 
       
   281 | *Template variable:* | *Defines:* |
       
   282 | =%<nop>TMPL:DEF{"sep"}%= | "&#124;" separator |
       
   283 | =%<nop>TMPL:DEF{"htmldoctype"}%= | Start of all HTML pages |
       
   284 | =%<nop>TMPL:DEF{"standardheader"}%= | Standard header (ex: view, index, search)  |
       
   285 | =%<nop>TMPL:DEF{"simpleheader"}%= | Simple header with reduced links (ex: edit, attach, oops) |
       
   286 | =%<nop>TMPL:DEF{"standardfooter"}%= | Footer, excluding revision and copyright parts |
       
   287 
       
   288 #TemplateTopics
       
   289 ---++ Template Topics
       
   290 
       
   291 The second type of template in TWiki are template topics. Template topics define the default text for new topics. There are three types of template topic:
       
   292 
       
   293 | *Topic Name:* | *What it is:* |
       
   294 | WebTopicViewTemplate | Alert page shown when you try to view a nonexistent topic. This page is usually used as a prompt to help you create a new topic. |
       
   295 | WebTopicNonWikiTemplate | Alert page shown when you try to view a nonexistent topic with a non-WikiName. Again, this page is used as a prompt to help you create the new topic. |
       
   296 | WebTopicEditTemplate | Default text used in a new topic. |
       
   297 
       
   298 When you create a new topic using the =edit= script, TWiki locates a topic to use as a content template according to the following search order:
       
   299    1 A topic name specified by the =templatetopic= CGI parameter
       
   300       * if no web is specified, the current web is searched first and then the %SYSTEMWEB% web
       
   301    1 <nop>WebTopicEditTemplate in the current web
       
   302    1 <nop>WebTopicEditTemplate in the %SYSTEMWEB% web
       
   303 
       
   304 #TemplateTopicsVars
       
   305 ---+++ Variable Expansion
       
   306 
       
   307 When the following variables are used in a template topic, they automatically get expanded when new topic is created based on it:
       
   308 
       
   309 | *Variable:* | *Description:* |
       
   310 | =%<nop>DATE%= | Signature format date. See VarDATE |
       
   311 | =%<nop>GMTIME%= | Date/time. See VarGMTIME |
       
   312 | =%<nop>GMTIME{...}%= | Formatted date/time. See VarGMTIME2 |
       
   313 | =%<nop>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, such as =%<nop>URLPA%<nop>NOP%RAM{...}%= escaping URLPARAM |
       
   314 | =%<nop>STARTSECTION{type="templateonly"}%%BR%...%BR%%<nop>ENDSECTION{type="templateonly"}%= | Text that gets removed when a new topic based on the template is created. See notes below. |
       
   315 | =%<nop>SERVERTIME%= | Date/time. See VarSERVERTIME |
       
   316 | =%<nop>SERVERTIME{...}%= | Formatted date/time. See VarSERVERTIME2 |
       
   317 | =%<nop>USERNAME%= | Login name of user who is instantiating the new topic, e.g. %USERNAME% |
       
   318 | =%<nop>URLPARAM{"name"}%= | Value of a named URL parameter |
       
   319 | =%<nop>WIKINAME%= | WikiName of user who is instantiating the new topic, e.g. <nop>%WIKINAME% |
       
   320 | =%<nop>WIKIUSERNAME%= | User name of user who is instantiating the new tpoic, e.g. <nop>%WIKIUSERNAME% |
       
   321 
       
   322 =%<nop>STARTSECTION{type="templateonly"}%%BR%...%BR%%<nop>ENDSECTION{type="templateonly"}%= markers are used to embed text that you _do not_ want expanded when a new topic based on the template topic is created. For example, you might want to write in the template topic:
       
   323 <pre>
       
   324 %<nop>STARTSECTION{type="templateonly"}%
       
   325 This template can only be changed by:
       
   326    * Set <nop>ALLOWTOPICCHANGE = <nop>%USERSWEB%.TWikiAdminGroup
       
   327 %<nop>ENDSECTION{type="templateonly"}%
       
   328 </pre>
       
   329 This will restrict who can edit the template topic, but will get removed when a new topic based on that template topic is created.
       
   330 
       
   331 =%<nop>NOP%= can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation e.g.i escape =%<nop>SERVERTIME%= with =%<nop>SER%<nop>NOP%VERTIME%=.
       
   332 
       
   333 All other variables are unchanged, e.g. are carried over "as is" into the new topic.
       
   334 
       
   335 ---+++ Specifying a Form
       
   336 When you create a new topic based on a template, you often want the new topic to have a form attached to it. You can attach a form to the template topic, in which case it will be copied into the new topic.
       
   337 
       
   338 Sometimes this isn't quite what you want, as it copies all the existing data from the template topic into the new topic. To avoid this and use the default values specified in the form definition instead, you can use the =formtemplate= CGI parameter to the =edit= script to specify the name of a form to attach.
       
   339 
       
   340 See TWikiScripts for information about all the other parameters to =edit=.
       
   341 
       
   342 #AutomaticallyGeneratedTopicname
       
   343 ---+++ Automatically Generated Topic Names
       
   344 
       
   345 For TWiki applications it is useful to be able to automatically generate unique topicnames, such as !BugID0001, !BugID0002, etc. You can add =AUTOINC&lt;n&gt;= to the topic name in the edit and save scripts, and it will be replaced with an auto-incremented number on topic save. =&lt;n&gt;= is a number starting from 0, and may include leading zeros. Leading zeros are used to zero-pad numbers so that auto-incremented topic names can sort properly. Deleted topics are not re-used to ensure uniqueness of topic names. That is, the auto-incremented number is always higher than the existing ones, even if there are gaps in the number sequence.
       
   346 
       
   347 *Examples:*
       
   348    * =BugAUTOINC0= - creates topic names =Bug0=, =Bug1=, =Bug2=, ... (does not sort properly)
       
   349    * =ItemAUTOINC0000= - creates topic names =Item0000=, =Item0001=, =Item0002=, ... (sorts properly up to 9999)
       
   350    * =DocIDAUTOINC10001= - start with =DocID10001=, =DocID10002=, ... (sorts properly up to 99999; auto-links)
       
   351 
       
   352 Example link to create a new topic:%BR%
       
   353 <verbatim>
       
   354 [[%SCRIPTURLPATH{edit}%/%WEB%/BugIDAUTOINC00001?templatetopic=BugTemplate;topicparent=%TOPIC%;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]
       
   355 </verbatim>
       
   356 
       
   357 ---+++ Template Topics in Action
       
   358 
       
   359 Here is an example for creating new topics (in the Sandbox web) based on a specific template topic and form:
       
   360 
       
   361 <form name="new" action="%SCRIPTURLPATH{edit}%/Sandbox/">
       
   362    * New example topic: 
       
   363      <input type="text" name="topic" value="ExampleTopicAUTOINC0001" size="30" />&nbsp;<input type="submit" class="twikiSubmit" value="Create" />
       
   364      <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
       
   365      <input type="hidden" name="topicparent" value="%TOPIC%" />
       
   366      <input type="hidden" name="onlywikiname" value="on" />
       
   367      <input type="hidden" name="onlynewtopic" value="on" />
       
   368 </form>
       
   369 
       
   370 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:
       
   371 
       
   372 <pre>
       
   373 &lt;form name="new" action="%<nop>SCRIPTURLPATH{edit}%/Sandbox/"&gt;
       
   374    * New example topic: 
       
   375      &lt;input type="text" name="topic" value="ExampleTopicAUTOINC0001" size="30" /&gt;
       
   376      &lt;input type="hidden" name="templatetopic" value="ExampleTopicTemplate" /&gt;
       
   377      &lt;input type="hidden" name="topicparent" value="%<nop>TOPIC%" /&gt;
       
   378      &lt;input type="hidden" name="onlywikiname" value="on" /&gt;
       
   379      &lt;input type="hidden" name="onlynewtopic" value="on" /&gt;
       
   380      &lt;input type="submit" class="twikiSubmit" value="Create" /&gt;
       
   381 &lt;/form&gt;
       
   382 </pre>
       
   383 
       
   384 See TWikiScripts#edit for details of the parameters that the =edit= script understands.
       
   385 
       
   386 %T% *TIP:* You can use the =%<nop>WIKIUSERNAME%= and =%<nop>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 />
       
   387 ==-- %<nop>WIKIUSERNAME% - %<nop>DATE%==
       
   388 
       
   389 ---+++ Using Absolute vs Relative URLs in Templates
       
   390 
       
   391 When you use TWikiVariables such as %<nop>PUBURL% and %<nop>PUBURLPATH% in templates you should be aware that using %<nop>PUBURL% instead of %<nop>PUBURLPATH% puts absolute URLs in the produced HTML. This means that when a user saves a TWiki page in HTML and emails the file to someone outside a company firewall, the receiver has a severe problem viewing it. It is therefore recommended always to use the %<nop>PUBURLPATH% to refer to images, CSS, Javascript files etc so links become relative. This way browsers just give up right away and show a usable html file.
       
   392 
       
   393 __Related Topics:__ TWikiSkins, DeveloperDocumentationCategory, AdminDocumentationCategory
       
   394 
       
   395 %STOPINCLUDE%
       
   396 -- __Contributors:__ TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.DavidLeBlanc, TWiki:Main.CrawfordCurrie
       
   397 @
       
   398 
       
   399 
       
   400 1.27
       
   401 log
       
   402 @buildrelease
       
   403 @
       
   404 text
       
   405 @d1 1
       
   406 a1 2
       
   407 %META:TOPICINFO{author="TWikiContributor" date="1171585604" format="1.1" version="27"}%
       
   408 %TOC%
       
   409 d3 1
       
   410 a3 1
       
   411 ---# TWiki Templates
       
   412 d7 2
       
   413 d11 4
       
   414 a14 3
       
   415 There are three types of template:
       
   416    * *Master Templates*: Define blocks of text for use in other templates
       
   417    * *HTML Page Templates*: Define the layout of <nop>%WIKITOOLNAME% pages
       
   418 d17 1
       
   419 a17 1
       
   420 All three types of template use the TWiki template system.
       
   421 d19 3
       
   422 a21 1
       
   423 __%T% Tip:__ TWiki:TWiki.TWikiTemplatesSupplement on TWiki.org has supplemental documentation on TWiki templates.
       
   424 d23 1
       
   425 a23 1
       
   426 ---++ The TWiki Template System
       
   427 d25 1
       
   428 a25 1
       
   429 _Templates_ are plain text with embedded _template directives_ that tell TWiki how to compose blocks of text together to create something new.
       
   430 a28 1
       
   431    * Template directives are embedded in templates.
       
   432 d44 1
       
   433 a44 1
       
   434 Note that parameters can simply be ignored; for example=%<nop>TMPL:P{"x"}%= will expand to x%<nop>P%z.
       
   435 d59 3
       
   436 a61 1
       
   437 Templates are stored either in the ==twiki/templates== directory, or can also be read from user topics. As an example, ==twiki/templates/view.tmpl== is the default template file for the ==twiki/bin/view== script.
       
   438 d63 1
       
   439 a63 1
       
   440 Templates that are included using =%TMPL:INCLUDE%= are also found using the same search algorithm, unless you explicitly put ='.tmpl'= at the end of the template name. In this case, the string is assumed to be the full name of a template in the =templates= directory, and the algorithm isn't used.
       
   441 d65 3
       
   442 a67 1
       
   443 TWiki uses the following search order to determine which template file or topic to use for a particular script. The _skin path_ is set as described in TWikiSkins.
       
   444 a68 1
       
   445 <blockquote>
       
   446 d78 2
       
   447 a79 2
       
   448    1 The TWiki topic %<nop>TWIKIWEB%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
       
   449    1 The TWiki topic %<nop>TWIKIWEB%.%RED%Script%ENDCOLOR%Template
       
   450 d86 1
       
   451 a86 1
       
   452 </blockquote>
       
   453 d88 1
       
   454 d98 3
       
   455 a100 3
       
   456    I. =%TWIKIWEB%.PrintSkinExampleTemplate=
       
   457    I. =%TWIKIWEB%.PatternSkinExampleTemplate=
       
   458    I. =%TWIKIWEB%.ExampleTemplate=
       
   459 d102 1
       
   460 a102 1
       
   461 Template names are usually derived from the name of the currently executing script; however it is also possible to override these settings in the =view= and =edit= scripts, for example when a topic-specific template is required. Two preference variables can be user to override the templates used:
       
   462 d105 1
       
   463 a105 1
       
   464 If these preferences are set locally (using _Local_ instead of _Set_) for a topic, in WebPreferences, in [[%LOCALSITEPREFS%]], or [[%TWIKIWEB%.TWikiPreferences]] (using _Set_), the indicated templates will be chosen for =view= and =edit= respectively. The template search order is as specified above.
       
   465 d107 1
       
   466 a107 1
       
   467 ---+++ TMPL:INCLUDE recusion for piecewise customisation, or mixing in new features
       
   468 d109 1
       
   469 a109 1
       
   470 If there is recusion in the TMPL:INCLUDE chain (eg twiki.classic.tmpl contains =%<nop>TMPL:INCLUDE{"twiki"}%=, the templating system will include the next twiki.SKIN in the skin path. 
       
   471 d117 6
       
   472 a122 3
       
   473 ---++ Master Templates
       
   474 Master templates use the block definition directives (=%<nop>TMPL:DEF= and =%<nop>TMPL:END%=) to define common sections that appear in two or more other templates. ==twiki.tmpl== is the default master template.
       
   475 <blockquote>
       
   476 a128 11
       
   477 | =%<nop>TMPL:DEF{"oops"}%= | Skeleton of oops dialog |
       
   478 </blockquote>
       
   479 
       
   480 #HtmlTemplates
       
   481 ---++ HTML Page Templates
       
   482 
       
   483 HTML page templates are files of HTML mixed with template directives that tell TWiki how to build up an HTML page. As described above, the template system supports the use of 'include' directives that let you re-use the same sections of HTML - such as headers and footers - in several different places.
       
   484 
       
   485 TWiki uses HTML page templates when composing the output from 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.
       
   486 
       
   487 HTML page templates are also used in the definition of TWikiSkins.
       
   488 d133 2
       
   489 a134 2
       
   490 Template topics define the default text for new topics. There are three types of template topic:
       
   491 <blockquote>
       
   492 d136 9
       
   493 a144 10
       
   494 | WebTopicViewTemplate | Error page shown when you try to view a nonexistent topic |
       
   495 | WebTopicNonWikiTemplate | Alert page shown when you try to view a nonexistent topic with a non-WikiName |
       
   496 | WebTopicEditTemplate | Default text shown when you create a new topic. |
       
   497 </blockquote>
       
   498 When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:
       
   499 
       
   500    1. A topic name specified by the =templatetopic= CGI parameter
       
   501       * if no web is specified, the current web is searched first and then the %TWIKIWEB% web
       
   502    1. <nop>WebTopicEditTemplate in the current web
       
   503    1. <nop>WebTopicEditTemplate in the %TWIKIWEB% web
       
   504 d147 1
       
   505 a147 1
       
   506 ---+++ Edit Template Topics and Variable Expansion
       
   507 d149 1
       
   508 a149 1
       
   509 The following variables get expanded when a user creates a new topic based on a template topic:
       
   510 a150 1
       
   511 <blockquote>
       
   512 a162 1
       
   513 </blockquote>
       
   514 d165 2
       
   515 a166 2
       
   516 <verbatim>
       
   517 %STARTSECTION{type="templateonly"}%
       
   518 d168 3
       
   519 a170 3
       
   520    * Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroup
       
   521 %ENDSECTION{type="templateonly"}%
       
   522 </verbatim>
       
   523 d173 1
       
   524 a173 1
       
   525 =%<nop>NOP%= can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation e.g.i escape =%nop>SERVERTIME%= with =%<nop>SER%<nop>NOP%VERTIME%=.
       
   526 d177 22
       
   527 d201 1
       
   528 a201 1
       
   529 Here is an example for creating new topics based on a specific template topic:
       
   530 d203 1
       
   531 a203 1
       
   532 <form name="new" action="%SCRIPTURLPATH{edit}%/%WEB%/">
       
   533 d205 1
       
   534 a205 1
       
   535      <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="26" />&nbsp;<input type="submit" class="twikiSubmit" value="Create" />
       
   536 a209 1
       
   537      (date format is <nop>YYYYxMMxDD)
       
   538 d215 1
       
   539 a215 1
       
   540 &lt;form name="new" action="%<nop>SCRIPTURLPATH{edit}%/%<nop>WEB%/"&gt;
       
   541 d217 1
       
   542 a217 1
       
   543      &lt;input type="text" name="topic" value="ExampleTopic%<nop>SERVERTIME{$yearx$mox$day}%" size="26" /&gt;
       
   544 a222 1
       
   545      (date format is &lt;nop&gt;YYYYxMMxDD)
       
   546 d231 1
       
   547 a231 4
       
   548 #AutomaticallyGeneratedTopicname
       
   549 ---+++ Automatically Generated Topicname
       
   550 
       
   551 For TWiki application it is useful to automatically generate unique topicnames, such as !BugID0001, !BugID0002, etc. You can add =AUTOINC&lt;n&gt;= to the topic name in the edit and save scripts, it gets replaced with an auto-incremented number on topic save. =&lt;n&gt;= is a number starting from 0, and may include leading zeros. Leading zeros are used to zero-pad numbers so that auto-incremented topic names can sort properly. Deleted topics are not re-used to ensure uniqueness of topic names. That is, the auto-incremented number is always higher than the existing ones, even if there are gaps in the number sequence.
       
   552 d233 1
       
   553 a233 92
       
   554 *Examples:*
       
   555    * =BugAUTOINC0= - creates topic names =Bug0=, =Bug1=, =Bug2=, ... (does not sort properly)
       
   556    * =ItemAUTOINC0000= - creates topic names =Item0000=, =Item0001=, =Item0002=, ... (sorts properly up to 9999)
       
   557    * =DocIDAUTOINC10001= - start with =DocID10001=, =DocID10002=, ... (sorts properly up to 99999; auto-links)
       
   558 
       
   559 Example link to create a new topic:%BR%
       
   560 <verbatim>
       
   561 [[%SCRIPTURLPATH{"edit"}%/%WEB%/BugIDAUTOINC00000?templatetopic=BugTemplate&amp;topicparent=%TOPIC%&amp;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]=
       
   562 </verbatim>
       
   563 
       
   564 ---++ Master Templates by Example
       
   565 
       
   566 Attached is an example of an oops based template =oopsbase.tmpl= and an example oops dialog =oopstest.tmpl= based on the base template. %T% *NOTE:* This isn't the release version, just a quick, simple demo.
       
   567 
       
   568 ---+++ Base template oopsbase.tmpl
       
   569 
       
   570 The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing =%<nop>TMPL:P{"sep"}%=
       
   571 
       
   572 <blockquote>
       
   573 <pre>
       
   574 %<nop>TMPL:DEF{"sep"}% | %<nop>TMPL:END%
       
   575 &lt;html&gt;
       
   576 &lt;head&gt;
       
   577   &lt;title&gt; %<nop>WIKITOOLNAME% . %<nop>WEB% . %<nop>TOPIC% %.TMPL:P{"titleaction"}%&lt;/title&gt;
       
   578   &lt;base href<nop>="%<nop>SCRIPTURLPATH{"view"}%/%<nop>WEB%/%<nop>TOPIC%"&gt;
       
   579   &lt;meta name="robots" content="noindex"&gt;
       
   580 &lt;/head&gt;
       
   581 &lt;body bgcolor="#FFFFFF"&gt;
       
   582 &lt;table width="100%" border="0" cellpadding="3" cellspacing="0"&gt;
       
   583   &lt;tr&gt;
       
   584     &lt;td bgcolor="%<nop>WEBBGCOLOR%" rowspan="2" valign="top" width="1%"&gt;
       
   585       &lt;a href<nop>="%<nop>WIKIHOMEURL%"&gt;
       
   586       &lt;img src="%<nop>PUBURLPATH%/wikiHome.gif" border="0"&gt;&lt;/a&gt;
       
   587     &lt;/td&gt;
       
   588     &lt;td&gt;
       
   589       &lt;b&gt;%<nop>WIKITOOLNAME% . %<nop>WEB% . &lt;/b&gt;&lt;font size="+2"&gt;
       
   590       &lt;B&gt;%<nop>TOPIC%&lt;/b&gt; %<nop>TMPL:P{"titleaction"}%&lt;/font&gt;
       
   591     &lt;/td&gt;
       
   592   &lt;/tr&gt;
       
   593   &lt;tr bgcolor="%<nop>WEBBGCOLOR%"&gt;
       
   594     &lt;td colspan="2"&gt;
       
   595       %<nop>TMPL:P{"webaction"}%
       
   596     &lt;/td&gt;
       
   597   &lt;/tr&gt;
       
   598 &lt;/table&gt;
       
   599 --- ++ %<nop>TMPL:P{"heading"}%
       
   600 %<nop>TMPL:P{"message"}%
       
   601 &lt;table width="100%" border="0" cellpadding="3" cellspacing="0"&gt;
       
   602   &lt;tr bgcolor="%<nop>WEBBGCOLOR%"&gt;
       
   603     &lt;td valign="top"&gt;
       
   604       Topic &lt;b&gt;%<nop>TOPIC%&lt;/b&gt; . {
       
   605         %<nop>TMPL:P{"topicaction"}%
       
   606       }
       
   607     &lt;/td&gt;
       
   608   &lt;/tr&gt;
       
   609 &lt;/table&gt;
       
   610 &lt;/body&gt;
       
   611 </pre>
       
   612 </blockquote>
       
   613 
       
   614 ---+++ Test template oopstest.tmpl
       
   615 
       
   616 Each oops template basically just defines some variables and includes the base template that does the layout work.
       
   617 
       
   618 <blockquote>
       
   619 <pre>
       
   620 %<nop>TMPL:DEF{"titleaction"}% (test =titleaction=) %<nop>TMPL:END%
       
   621 %<nop>TMPL:DEF{"webaction"}% test =webaction= %<nop>TMPL:END%
       
   622 %<nop>TMPL:DEF{"heading"}%
       
   623 Test heading %<nop>TMPL:END%
       
   624 %<nop>TMPL:DEF{"message"}%
       
   625 Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...
       
   626 
       
   627    * Some more blah blah blah blah blah blah blah blah blah blah...
       
   628    * Param1: %<nop>PARAM1%
       
   629    * Param2: %<nop>PARAM2%
       
   630    * Param3: %<nop>PARAM3%
       
   631    * Param4: %<nop>PARAM4%
       
   632 %<nop>TMPL:END%
       
   633 %<nop>TMPL:DEF{"topicaction"}%
       
   634 Test =topicaction=:
       
   635 [<nop>[%<nop>WEB%.%<nop>TOPIC%][OK]] %<nop>TMPL:P{"sep"}%
       
   636 [<nop>[%<nop>TWIKIWEB%.TWikiRegistration][Register]] %<nop>TMPL:END%
       
   637 %<nop>TMPL:INCLUDE{"oopsbase"}%
       
   638 </pre>
       
   639 </blockquote>
       
   640 
       
   641 ---+++ Sample screen shot of oopstest.tmpl
       
   642 
       
   643 With URL: ==.../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify==
       
   644 
       
   645 <img style="border:1px solid #ddd;" src="%ATTACHURLPATH%/testscreen.gif" width="589" height="304" alt="testscreen.gif">
       
   646 d237 2
       
   647 a238 3
       
   648 -- __Contributors:__ TWiki:Main.CrawfordCurrie, TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.DavidLeBlanc
       
   649 
       
   650 %META:FILEATTACHMENT{name="testscreen.gif" attr="h" comment="Example of oopstest.tmpl rendered" date="1026977240" path="C:\Data\Temp\testscreen.gif" size="9566" user="TWikiContributor" version="1.2"}%
       
   651 @
       
   652 
       
   653 
       
   654 1.26
       
   655 log
       
   656 @buildrelease
       
   657 @
       
   658 text
       
   659 @d1 1
       
   660 a1 1
       
   661 %META:TOPICINFO{author="TWikiContributor" date="1164676388" format="1.1" version="26"}%
       
   662 d114 6
       
   663 a119 6
       
   664 | %<nop>TMPL:DEF{"sep"}% | "&#124;" separator |
       
   665 | %<nop>TMPL:DEF{"htmldoctype"}% | Start of all HTML pages |
       
   666 | %<nop>TMPL:DEF{"standardheader"}% | Standard header (ex: view, index, search)  |
       
   667 | %<nop>TMPL:DEF{"simpleheader"}% | Simple header with reduced links (ex: edit, attach, oops) |
       
   668 | %<nop>TMPL:DEF{"standardfooter"}% | Footer, excluding revision and copyright parts |
       
   669 | %<nop>TMPL:DEF{"oops"}% | Skeleton of oops dialog |
       
   670 d210 1
       
   671 a210 1
       
   672 See TWikiScripts for details of the parameters that the =edit= script understands.
       
   673 d315 2
       
   674 @
       
   675 
       
   676 
       
   677 1.25
       
   678 log
       
   679 @buildrelease
       
   680 @
       
   681 text
       
   682 @d1 1
       
   683 a1 1
       
   684 %META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="25"}%
       
   685 d17 2
       
   686 d29 1
       
   687 a29 1
       
   688       * ==%<nop>TMPL:DEF{"block"}%==: Define a block. Text between this and the =%<nop>TMPL:END%= directive is not used in-place, but is saved for later use with =%<nop>TMPL:P=. Leading and trailing whitespace is ignored.
       
   689 d69 1
       
   690 a69 1
       
   691    1 The TWiki topic %RED%web%ENDCOLOR%.%RED%topic%ENDCOLOR% if the template name can be parsed into %RED%web%ENDCOLOR%.%RED%topic%ENDCOLOR%
       
   692 d72 2
       
   693 a73 2
       
   694    1 The TWiki topic %TWIKIWEB%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
       
   695    1 The TWiki topic %TWIKIWEB%.%RED%Script%ENDCOLOR%Template
       
   696 d100 10
       
   697 d158 1
       
   698 a158 1
       
   699 | =%<nop>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 =%<nop>URLPARAM%<nop>NOP%{...}%= |
       
   700 d218 6
       
   701 a223 1
       
   702 If you want to make a TWiki application where you need automatically generated unique topicnames, you can use 10 X's in the edit / save URL, and they will be replaced on topic save with a count value. For example, !BugIDXXXXXXXXXX will result in topics named !BugID0, !BugID1, !BugID2 etc. 
       
   703 d227 1
       
   704 a227 1
       
   705 [[%SCRIPTURLPATH{"edit"}%/%WEB%/BugIDXXXXXXXXXX?templatetopic=BugTemplate&amp;topicparent=%TOPIC%&amp;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]=
       
   706 a238 2
       
   707 <table border="1" cellspacing="0" cellpadding="1" bgcolor="#f5f5f5">
       
   708 <tr><td>
       
   709 a277 2
       
   710 </td></tr>
       
   711 </table>
       
   712 a284 2
       
   713 <table border="1" cellspacing="0" cellpadding="1" bgcolor="#f5f5f5">
       
   714 <tr><td>
       
   715 a304 2
       
   716 </td></tr>
       
   717 </table>
       
   718 d311 1
       
   719 a311 3
       
   720 <blockquote>
       
   721 | <img src="%ATTACHURLPATH%/testscreen.gif" width="589" height="304" alt="testscreen.gif"> |
       
   722 </blockquote>
       
   723 a315 1
       
   724 
       
   725 @
       
   726 
       
   727 
       
   728 1.24
       
   729 log
       
   730 @buildrelease
       
   731 @
       
   732 text
       
   733 @d1 1
       
   734 a1 1
       
   735 %META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="24"}%
       
   736 d11 3
       
   737 a13 3
       
   738 	* *Master Templates*: Define blocks of text for use in other templates
       
   739 	* *HTML Page Templates*: Define the layout of <nop>%WIKITOOLNAME% pages
       
   740 	* *Template Topics*: Define default text when you create a new topic
       
   741 d23 12
       
   742 a34 12
       
   743 	* Template directives are embedded in templates.
       
   744 	* Directives are of the form ==%<nop>TMPL:&lt;key&gt;%== and ==%<nop>TMPL:&lt;key&gt;{"attr"}%==.
       
   745 	* Directives:
       
   746 		* ==%<nop>TMPL:INCLUDE{"file"}%==: Includes a template file. The file is found as described [[#FindingTemplates][below]].
       
   747 		* ==%<nop>TMPL:DEF{"block"}%==: Define a block. Text between this and the =%<nop>TMPL:END%= directive is not used in-place, but is saved for later use with =%<nop>TMPL:P=. Leading and trailing whitespace is ignored.
       
   748 		* ==%<nop>TMPL:END%==: Ends a block definition.
       
   749 		* ==%<nop>TMPL:P{"var"}%==: Includes a previously defined block.
       
   750 		* ==%<nop>{...}%==: is a comment.
       
   751 	* Two-pass processing lets you use a variable before or after declaring it.
       
   752 	* 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.
       
   753 	* %H% Use of template directives is optional: templates work without them.
       
   754 	* %X% *NOTE:* Template directives work only for templates: they do not get processed in normal topic text.
       
   755 d61 11
       
   756 a71 11
       
   757 	1 templates/%RED%web%ENDCOLOR%/%RED%script%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl for each %RED%skin%ENDCOLOR% on the skin path
       
   758 		* %X% this usage is supported *for compatibility only* and is *deprecated*. Store web-specific templates in TWiki topics instead.
       
   759 	1 templates/%RED%script%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl for each %RED%skin%ENDCOLOR% on the skin path
       
   760 	1 templates/%RED%web%ENDCOLOR%/%RED%script%ENDCOLOR%.tmpl
       
   761 		* %X% this usage is supported *for compatibility only* and is *deprecated*. Store web-specific templates in TWiki topics instead.
       
   762 	1 templates/%RED%script%ENDCOLOR%.tmpl
       
   763 	1 The TWiki topic %RED%web%ENDCOLOR%.%RED%topic%ENDCOLOR% if the template name can be parsed into %RED%web%ENDCOLOR%.%RED%topic%ENDCOLOR%
       
   764 	1 The TWiki topic %RED%web%ENDCOLOR%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
       
   765 	1 The TWiki topic %RED%web%ENDCOLOR%.%RED%Script%ENDCOLOR%Template
       
   766 	1 The TWiki topic %TWIKIWEB%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
       
   767 	1 The TWiki topic %TWIKIWEB%.%RED%Script%ENDCOLOR%Template
       
   768 d73 5
       
   769 a77 5
       
   770 	* %RED%script%ENDCOLOR% refers to the script name, e.g =view=, =edit=
       
   771 	* %RED%Script%ENDCOLOR% refers to the same, but with the first character capitalized, e.g =View=
       
   772 	* %RED%skin%ENDCOLOR% refers to a skin name, e.g =dragon=, =pattern=. All skins are checked at each stage, in the order they appear in the skin path.
       
   773 	* %RED%Skin%ENDCOLOR% refers to the same, but with the first character capitalized, e.g =Dragon=
       
   774 	* %RED%web%ENDCOLOR% refers to the current web
       
   775 d80 12
       
   776 a91 12
       
   777 	I. =templates/Thisweb/example.print.tmpl= _deprecated; don't rely on it_
       
   778 	I. =templates/Thisweb/example.pattern.tmpl= _deprecated; don't rely on it_
       
   779 	I. =templates/example.print.tmpl=
       
   780 	I. =templates/example.pattern.tmpl=
       
   781 	I. =templates/Thisweb/example.tmpl= _deprecated; don't rely on it_
       
   782 	I. =templates/example.tmpl=
       
   783 	I. =Thisweb.PrintSkinExampleTemplate=
       
   784 	I. =Thisweb.PatternSkinExampleTemplate=
       
   785 	I. =Thisweb.ExampleTemplate=
       
   786 	I. =%TWIKIWEB%.PrintSkinExampleTemplate=
       
   787 	I. =%TWIKIWEB%.PatternSkinExampleTemplate=
       
   788 	I. =%TWIKIWEB%.ExampleTemplate=
       
   789 d94 2
       
   790 a95 2
       
   791 	* =VIEW_TEMPLATE= sets the template to be used for viewing a topic
       
   792 	* =EDIT_TEMPLATE= sets the template for editing a topic.
       
   793 d131 4
       
   794 a134 4
       
   795 	1. A topic name specified by the =templatetopic= CGI parameter
       
   796 		* if no web is specified, the current web is searched first and then the %TWIKIWEB% web
       
   797 	1. <nop>WebTopicEditTemplate in the current web
       
   798 	1. <nop>WebTopicEditTemplate in the %TWIKIWEB% web
       
   799 d143 3
       
   800 a145 3
       
   801 | =%<nop>DATE%= | Signature format date. See TWikiVariables#VarDATE |
       
   802 | =%<nop>GMTIME%= | Date/time. See TWikiVariables#VarGMTIME |
       
   803 | =%<nop>GMTIME{...}%= | Formatted date/time. See TWikiVariables#VarGMTIME2 |
       
   804 d148 2
       
   805 a149 2
       
   806 | =%<nop>SERVERTIME%= | Date/time. See TWikiVariables#VarSERVERTIME |
       
   807 | =%<nop>SERVERTIME{...}%= | Formatted date/time. See TWikiVariables#VarSERVERTIME2 |
       
   808 d160 1
       
   809 a160 1
       
   810 	* Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroup
       
   811 d174 7
       
   812 a180 7
       
   813 	* New example topic: 
       
   814 	  <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="26" />&nbsp;<input type="submit" class="twikiSubmit" value="Create" />
       
   815 	  <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
       
   816 	  <input type="hidden" name="topicparent" value="%TOPIC%" />
       
   817 	  <input type="hidden" name="onlywikiname" value="on" />
       
   818 	  <input type="hidden" name="onlynewtopic" value="on" />
       
   819 	  (date format is <nop>YYYYxMMxDD)
       
   820 d187 8
       
   821 a194 8
       
   822 	* New example topic: 
       
   823 	  &lt;input type="text" name="topic" value="ExampleTopic%<nop>SERVERTIME{$yearx$mox$day}%" size="26" /&gt;
       
   824 	  &lt;input type="hidden" name="templatetopic" value="ExampleTopicTemplate" /&gt;
       
   825 	  &lt;input type="hidden" name="topicparent" value="%<nop>TOPIC%" /&gt;
       
   826 	  &lt;input type="hidden" name="onlywikiname" value="on" /&gt;
       
   827 	  &lt;input type="hidden" name="onlynewtopic" value="on" /&gt;
       
   828 	  &lt;input type="submit" class="twikiSubmit" value="Create" /&gt;
       
   829 	  (date format is &lt;nop&gt;YYYYxMMxDD)
       
   830 d235 8
       
   831 a242 8
       
   832 	 &lt;td bgcolor="%<nop>WEBBGCOLOR%" rowspan="2" valign="top" width="1%"&gt;
       
   833 		&lt;a href<nop>="%<nop>WIKIHOMEURL%"&gt;
       
   834 		&lt;img src="%<nop>PUBURLPATH%/wikiHome.gif" border="0"&gt;&lt;/a&gt;
       
   835 	 &lt;/td&gt;
       
   836 	 &lt;td&gt;
       
   837 		&lt;b&gt;%<nop>WIKITOOLNAME% . %<nop>WEB% . &lt;/b&gt;&lt;font size="+2"&gt;
       
   838 		&lt;B&gt;%<nop>TOPIC%&lt;/b&gt; %<nop>TMPL:P{"titleaction"}%&lt;/font&gt;
       
   839 	 &lt;/td&gt;
       
   840 d245 3
       
   841 a247 3
       
   842 	 &lt;td colspan="2"&gt;
       
   843 		%<nop>TMPL:P{"webaction"}%
       
   844 	 &lt;/td&gt;
       
   845 d254 5
       
   846 a258 5
       
   847 	 &lt;td valign="top"&gt;
       
   848 		Topic &lt;b&gt;%<nop>TOPIC%&lt;/b&gt; . {
       
   849 		  %<nop>TMPL:P{"topicaction"}%
       
   850 		}
       
   851 	 &lt;/td&gt;
       
   852 d282 5
       
   853 a286 5
       
   854 	* Some more blah blah blah blah blah blah blah blah blah blah...
       
   855 	* Param1: %<nop>PARAM1%
       
   856 	* Param2: %<nop>PARAM2%
       
   857 	* Param3: %<nop>PARAM3%
       
   858 	* Param4: %<nop>PARAM4%
       
   859 @
       
   860 
       
   861 
       
   862 1.23
       
   863 log
       
   864 @none
       
   865 @
       
   866 text
       
   867 @d1 1
       
   868 a1 2
       
   869 %META:TOPICINFO{author="PeterThoeny" date="1092604921" format="1.0" version="1.23"}%
       
   870 %META:TOPICPARENT{name="WebHome"}%
       
   871 d10 4
       
   872 a13 1
       
   873 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 [[#HtmlTemplates][page layout]], and also to supply [[#TemplateTopics][default content]] for new pages.
       
   874 d15 1
       
   875 a15 1
       
   876 ---++ Major changes from the previous template system
       
   877 d17 1
       
   878 a17 1
       
   879 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:
       
   880 d19 1
       
   881 a19 3
       
   882 	* separates a set of common template parts into a base template that is included by all of the related templates;  
       
   883 	* defines common variables, like a standard separator (ex: "|"), in the base template; 
       
   884 	* defines variable text in the individual templates and passes it back to the base template.
       
   885 d22 2
       
   886 a23 4
       
   887 ---++ How Template Variables Work
       
   888 
       
   889 	* Special template directives (or preprocessor commands) are embedded in normal templates.
       
   890 	* All template preprocessing is done in =&TWiki::Store::readTemplate()= so that the caller simply gets an expanded template file (the same as before).
       
   891 d26 5
       
   892 a30 5
       
   893 		* ==%<nop>TMPL:INCLUDE{"file"}%==: Includes a template file. The template directory of the current web is searched first, then the templates root (=twiki/templates=).
       
   894 		* ==%<nop>TMPL:DEF{"var"}%==: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
       
   895 		* ==%<nop>TMPL:END%==: Ends variable definition.
       
   896 		* ==%<nop>TMPL:P{"var"}%==: Prints a previously defined variable.
       
   897 	* Variables live in a global name space: there is no parameter passing.
       
   898 d34 6
       
   899 a39 1
       
   900 	* %X% *NOTE:* Template directives work only for templates: they do not get processed in topic text.
       
   901 d41 1
       
   902 a41 1
       
   903 ---++ Types of Template
       
   904 d43 12
       
   905 a54 1
       
   906 There are three types of template:
       
   907 d56 1
       
   908 a56 3
       
   909 	* *Master Template*: Stores common parts; included by other templates
       
   910 	* *HTML Page Templates*: Defines the layout of %WIKITOOLNAME% pages
       
   911 	* *Template Topics*: Defines default text when you create a new topic
       
   912 d58 1
       
   913 a58 1
       
   914 ---+++ Master Templates
       
   915 d60 40
       
   916 a99 1
       
   917 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.
       
   918 d111 1
       
   919 a111 11
       
   920 ---+++ HTML Page Templates
       
   921 
       
   922 TWiki 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.
       
   923 
       
   924 Templates are stored either in the ==twiki/templates== directory or in user topics. As an example, ==twiki/templates/view.tmpl== is the template file for the ==twiki/bin/view== script.
       
   925 
       
   926 %H% Templates can be overloaded by individual webs.
       
   927 
       
   928 %H% TWikiSkins can overload the standard templates.
       
   929 
       
   930 TWiki uses the following search order to determine which template to use:
       
   931 d113 1
       
   932 a113 8
       
   933 <blockquote>
       
   934 | *If a skin is specified* | *If no skin is specified* |
       
   935 | =templates/%<nop>WEB%/%RED%script</b>.%RED%skin%ENDCOLOR%.tmpl= | =templates/%<nop>WEB%/%RED%script%ENDCOLOR%.tmpl= |
       
   936 | =templates/%RED%script%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl= | =templates/%RED%script%ENDCOLOR%.tmpl= |
       
   937 | =data/%<nop>WEB%/%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template.txt= | =data/%<nop>WEB%/%RED%Script%ENDCOLOR%Template.txt= |
       
   938 | =data/%TWIKIWEB%/%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template.txt= | =data/%TWIKIWEB%/%RED%Script%ENDCOLOR%Template.txt= |
       
   939 | *Legend:* %BB% %RED%script%ENDCOLOR% refers to the script name, e.g =view=, =edit= %BB% %RED%Script%ENDCOLOR% refers to the same, but with the first character capitalized, e.g =View= %BB% %RED%skin%ENDCOLOR% refers to the skin name, e.g =dragon=, =pattern= %BB% %RED%Skin%ENDCOLOR% refers to the same, but with the first character capitalized, e.g =Dragon= %BB% =%<nop>WEB%= refers to the current web ||
       
   940 </blockquote>
       
   941 d115 1
       
   942 a115 8
       
   943 Additionally (and primarily for use in =%TMPL<nop>:INCLUDE{}%=) the template name may be a wiki topic name, specified as =%RED%Web%ENDCOLOR%.%RED%Topic%ENDCOLOR%=, in which case the search is:
       
   944 <blockquote>
       
   945 | *If a skin is specified* | *If no skin is specified* |
       
   946 | =templates/%RED%web%ENDCOLOR%/%RED%Web%ENDCOLOR%.%RED%Topic%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl= | =templates/%RED%web%ENDCOLOR%/%RED%Web%ENDCOLOR%.%RED%Topic%ENDCOLOR%.tmpl= |
       
   947 | =templates/%RED%Web%ENDCOLOR%.%RED%Topic%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl= | =templates/%RED%Web%ENDCOLOR%.%RED%Topic%ENDCOLOR%.tmpl= |
       
   948 |  =data/%RED%Web%ENDCOLOR%/%RED%Topic%ENDCOLOR%.txt=  ||
       
   949 </blockquote>
       
   950 If %RED%Web%ENDCOLOR% is not specified in the INCLUDE, it defaults to %TWIKIWEB%, and the search to the first type.
       
   951 d117 1
       
   952 a117 1
       
   953 Special variables are used in templates, especially in =view=, to display [[TWikiMetaData#MetaDataRendering][meta data]].
       
   954 d120 1
       
   955 a120 1
       
   956 ---+++ Template Topics
       
   957 d129 1
       
   958 a129 1
       
   959 All template topics are located in the %TWIKIWEB% 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:
       
   960 d131 2
       
   961 a132 1
       
   962 	1. A topic name specified by the =templatetopic= CGI parameter.
       
   963 d136 2
       
   964 a137 1
       
   965 ---++++ Edit Template Topics and Variable Expansion
       
   966 d143 8
       
   967 a150 4
       
   968 | =%<nop>DATE%= | Current date, e.g. =%DATE%= |
       
   969 | =%<nop>USERNAME%= | Login name, e.g. =jsmith= |
       
   970 | =%<nop>WIKINAME%= | WikiName of user, e.g. =JohnSmith= |
       
   971 | =%<nop>WIKIUSERNAME%= | User name, e.g. =Main.JohnSmith= |
       
   972 d152 2
       
   973 a153 2
       
   974 | =%<nop>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 =%<nop>URLPARAM%<nop>NOP%{...}%= |
       
   975 | =%<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>NOP{%BR%&nbsp; &nbsp;* Set&nbsp;ALLOWTOPICCHANGE = <nop>Main.TWikiAdminGroup%BR% }%= |
       
   976 d156 10
       
   977 a165 3
       
   978 __Notes:__
       
   979 	* Unlike other variables, =%<nop>NOP{ ... }%= can span multiple lines. 
       
   980 	* 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>NOP{ ... }%=: Insert a =%<nop>NOP%= between =}= and =%=. Silly example: =%<nop>NOP{ %<nop>GMTIME{"$year"}%<nop>NOP%% }%=.
       
   981 d169 1
       
   982 a169 1
       
   983 ---++++ Template Topics in Action
       
   984 d173 1
       
   985 a173 1
       
   986 <form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
       
   987 d175 1
       
   988 a175 1
       
   989 	  <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
       
   990 a179 1
       
   991 	  <input type="submit" value="Create" />
       
   992 d186 1
       
   993 a186 1
       
   994 &lt;form name="new" action="%<nop>SCRIPTURLPATH%/edit%<nop>SCRIPTSUFFIX%/%<nop>INTURLENCODE{"%<nop>WEB%"}%/"&gt;
       
   995 d188 1
       
   996 a188 1
       
   997 	  &lt;input type="text" name="topic" value="ExampleTopic%<nop>SERVERTIME{$yearx$mox$day}%" size="23" /&gt;
       
   998 d193 1
       
   999 a193 1
       
  1000 	  &lt;input type="submit" value="Create" /&gt;
       
  1001 d198 1
       
  1002 a198 13
       
  1003 The =edit= scipt understands the following parameters, typically supplied by HTML input fields:
       
  1004 
       
  1005 <blockquote>
       
  1006 | *Parameter:* | *Description:* |
       
  1007 | =topic= | Name of topic to create. Can be set in a text field, or is set programmatically (e.g. with a sequential number) |
       
  1008 | =onlywikiname= | If set, TWiki will complain if the topic name is not a WikiWord |
       
  1009 | =onlynewtopic= | If set, TWiki will complain if a topic of the same name already exists |
       
  1010 | =templatetopic= | The name of the template topic, e.g. topic used to copy the initial content |
       
  1011 | =topicparent= | Sets the parent topic |
       
  1012 | =TopicClassification= | Assuming the template topic has a form with a field called "TopicClassification", it will set the value of the field |
       
  1013 | =contenttype= | Optional parameter that defines the application type to write into the CGI header. Defaults to =text/html=. May be used to invoke alternative client applications |
       
  1014 | =anyname= | Any parameter can passed to the new topic; if the template topic contains =%<nop>URLPARAM{"anyname"}%=, it will be replaced by its value |
       
  1015 </blockquote>
       
  1016 d203 9
       
  1017 a211 1
       
  1018 ---++ Templates by Example
       
  1019 d213 3
       
  1020 a215 1
       
  1021 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.
       
  1022 d229 1
       
  1023 a229 1
       
  1024   &lt;base href<nop>="%<nop>SCRIPTURL%/view%<nop>SCRIPTSUFFIX%/%<nop>WEB%/%<nop>TOPIC%"&gt;
       
  1025 d295 1
       
  1026 a295 1
       
  1027 </table >
       
  1028 d306 1
       
  1029 a306 3
       
  1030 ---++ Known Issues
       
  1031 
       
  1032 	* 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.
       
  1033 d308 1
       
  1034 a308 4
       
  1035 -- TWiki:Main.CrawfordCurrie - 30 Jun 2004 %BR%
       
  1036 -- TWiki:Main.PeterThoeny - 15 Aug 2004 %BR%
       
  1037 -- TWiki:Main.MikeMannix - 14 Sep 2001 %BR%
       
  1038 -- TWiki:Main.DavidLeBlanc - 11 Mar 2002
       
  1039 a309 2
       
  1040 %META:FILEATTACHMENT{name="testscreen.gif" attr="h" comment="Example of oopstest.tmpl rendered" date="1026977240" path="C:\Data\Temp\testscreen.gif" size="9566" user="PeterThoeny" version="1.2"}%
       
  1041 %META:TOPICMOVED{by="MikeMannix" date="1000277381" from="TWiki.TWikiTemplateSystem" to="TWiki.TWikiTemplates"}%
       
  1042 @
       
  1043 
       
  1044 
       
  1045 1.22
       
  1046 log
       
  1047 @none
       
  1048 @
       
  1049 text
       
  1050 @d1 1
       
  1051 a1 1
       
  1052 %META:TOPICINFO{author="PeterThoeny" date="1082876858" format="1.0" version="1.22"}%
       
  1053 d62 1
       
  1054 a62 1
       
  1055 %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.
       
  1056 d64 1
       
  1057 a64 1
       
  1058 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:
       
  1059 d66 1
       
  1060 a66 4
       
  1061 	1. ==twiki/templates/$webName/$scriptName.tmpl==
       
  1062 	2. ==twiki/templates/$scriptName.tmpl==
       
  1063 		* =$webName= is the name of the web (ex: =Main=)
       
  1064 		* =$scriptName= is the script (ex: =view=).
       
  1065 d68 21
       
  1066 a88 1
       
  1067 %H% *NOTE:* TWikiSkins can be defined to overload the standard templates.
       
  1068 d169 1
       
  1069 d273 2
       
  1070 a274 1
       
  1071 -- TWiki:Main.PeterThoeny - 25 Apr 2004 %BR%
       
  1072 @
       
  1073 
       
  1074 
       
  1075 1.21
       
  1076 log
       
  1077 @none
       
  1078 @
       
  1079 text
       
  1080 @d1 1
       
  1081 a1 1
       
  1082 %META:TOPICINFO{author="PeterThoeny" date="1072855797" format="1.0" version="1.21"}%
       
  1083 d3 256
       
  1084 a258 253
       
  1085 %TOC%
       
  1086 %STARTINCLUDE%
       
  1087 ---# TWiki Templates
       
  1088 
       
  1089 _Definition of the templates used to render all HTML pages displayed in TWiki_ 
       
  1090 
       
  1091 ---++ Overview
       
  1092 
       
  1093 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 [[#HtmlTemplates][page layout]], and also to supply [[#TemplateTopics][default content]] for new pages.
       
  1094 
       
  1095 ---++ Major changes from the previous template system
       
  1096 
       
  1097 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:
       
  1098 
       
  1099 	* separates a set of common template parts into a base template that is included by all of the related templates;  
       
  1100 	* defines common variables, like a standard separator (ex: "|"), in the base template; 
       
  1101 	* defines variable text in the individual templates and passes it back to the base template.
       
  1102 
       
  1103 #TemplateVariables
       
  1104 ---++ How Template Variables Work
       
  1105 
       
  1106 	* Special template directives (or preprocessor commands) are embedded in normal templates.
       
  1107 	* All template preprocessing is done in =&TWiki::Store::readTemplate()= so that the caller simply gets an expanded template file (the same as before).
       
  1108 	* Directives are of the form ==%<nop>TMPL:&lt;key&gt;%== and ==%<nop>TMPL:&lt;key&gt;{"attr"}%==.
       
  1109 	* Directives:
       
  1110 		* ==%<nop>TMPL:INCLUDE{"file"}%==: Includes a template file. The template directory of the current web is searched first, then the templates root (=twiki/templates=).
       
  1111 		* ==%<nop>TMPL:DEF{"var"}%==: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
       
  1112 		* ==%<nop>TMPL:END%==: Ends variable definition.
       
  1113 		* ==%<nop>TMPL:P{"var"}%==: Prints a previously defined variable.
       
  1114 	* Variables live in a global name space: there is no parameter passing.
       
  1115 	* Two-pass processing lets you use a variable before or after declaring it.
       
  1116 	* 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.
       
  1117 	* %H% Use of template directives is optional: templates work without them.
       
  1118 	* %X% *NOTE:* Template directives work only for templates: they do not get processed in topic text.
       
  1119 
       
  1120 ---++ Types of Template
       
  1121 
       
  1122 There are three types of template:
       
  1123 
       
  1124 	* *Master Template*: Stores common parts; included by other templates
       
  1125 	* *HTML Page Templates*: Defines the layout of %WIKITOOLNAME% pages
       
  1126 	* *Template Topics*: Defines default text when you create a new topic
       
  1127 
       
  1128 ---+++ Master Templates
       
  1129 
       
  1130 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.
       
  1131 <blockquote>
       
  1132 | *Template variable:* | *Defines:* |
       
  1133 | %<nop>TMPL:DEF{"sep"}% | "&#124;" separator |
       
  1134 | %<nop>TMPL:DEF{"htmldoctype"}% | Start of all HTML pages |
       
  1135 | %<nop>TMPL:DEF{"standardheader"}% | Standard header (ex: view, index, search)  |
       
  1136 | %<nop>TMPL:DEF{"simpleheader"}% | Simple header with reduced links (ex: edit, attach, oops) |
       
  1137 | %<nop>TMPL:DEF{"standardfooter"}% | Footer, excluding revision and copyright parts |
       
  1138 | %<nop>TMPL:DEF{"oops"}% | Skeleton of oops dialog |
       
  1139 </blockquote>
       
  1140 
       
  1141 #HtmlTemplates
       
  1142 ---+++ HTML Page Templates
       
  1143 
       
  1144 %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.
       
  1145 
       
  1146 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:
       
  1147 
       
  1148 	1. ==twiki/templates/$webName/$scriptName.tmpl==
       
  1149 	2. ==twiki/templates/$scriptName.tmpl==
       
  1150 		* =$webName= is the name of the web (ex: =Main=)
       
  1151 		* =$scriptName= is the script (ex: =view=).
       
  1152 
       
  1153 %H% *NOTE:* TWikiSkins can be defined to overload the standard templates.
       
  1154 
       
  1155 Special variables are used in templates, especially in =view=, to display [[TWikiMetaData#MetaDataRendering][meta data]].
       
  1156 
       
  1157 #TemplateTopics
       
  1158 ---+++ Template Topics
       
  1159 
       
  1160 Template topics define the default text for new topics. There are three types of template topic:
       
  1161 <blockquote>
       
  1162 | *Topic Name:* | *What it is:* |
       
  1163 | WebTopicViewTemplate | Error page shown when you try to view a nonexistent topic |
       
  1164 | WebTopicNonWikiTemplate | Alert page shown when you try to view a nonexistent topic with a non-WikiName |
       
  1165 | WebTopicEditTemplate | Default text shown when you create a new topic. |
       
  1166 </blockquote>
       
  1167 All template topics are located in the %TWIKIWEB% 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:
       
  1168 
       
  1169 	1. A topic name specified by the =templatetopic= CGI parameter.
       
  1170 	1. <nop>WebTopicEditTemplate in the current web
       
  1171 	1. <nop>WebTopicEditTemplate in the %TWIKIWEB% web
       
  1172 
       
  1173 ---++++ Edit Template Topics and Variable Expansion
       
  1174 
       
  1175 The following variables get expanded when a user creates a new topic based on a template topic:
       
  1176 
       
  1177 <blockquote>
       
  1178 | *Variable:* | *Description:* |
       
  1179 | =%<nop>DATE%= | Current date, e.g. =%DATE%= |
       
  1180 | =%<nop>WIKIUSERNAME%= | User name, e.g. =%WIKIUSERNAME%= |
       
  1181 | =%<nop>URLPARAM{"name"}%= | Value of a named URL parameter |
       
  1182 | =%<nop>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 =%<nop>URLPARAM%<nop>NOP%{...}%= |
       
  1183 | =%<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>NOP{%BR%&nbsp; &nbsp;* Set&nbsp;ALLOWTOPICCHANGE = <nop>Main.TWikiAdminGroup%BR% }%= |
       
  1184 </blockquote>
       
  1185 
       
  1186 __Notes:__
       
  1187 	* Unlike other variables, =%<nop>NOP{ ... }%= can span multiple lines. 
       
  1188 	* 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>NOP{ ... }%=: Insert a =%<nop>NOP%= between =}= and =%=. Silly example: =%<nop>NOP{ %<nop>GMTIME{"$year"}%<nop>NOP%% }%=.
       
  1189 
       
  1190 All other variables are unchanged, e.g. are carried over "as is" into the new topic.
       
  1191 
       
  1192 ---++++ Template Topics in Action
       
  1193 
       
  1194 Here is an example for creating new topics based on a specific template topic:
       
  1195 
       
  1196 <form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
       
  1197 	* New example topic: 
       
  1198 	  <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
       
  1199 	  <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
       
  1200 	  <input type="hidden" name="topicparent" value="%TOPIC%" />
       
  1201 	  <input type="hidden" name="onlywikiname" value="on" />
       
  1202 	  <input type="hidden" name="onlynewtopic" value="on" />
       
  1203 	  <input type="submit" value="Create" />
       
  1204 	  (date format is <nop>YYYYxMMxDD)
       
  1205 </form>
       
  1206 
       
  1207 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:
       
  1208 
       
  1209 <pre>
       
  1210 &lt;form name="new" action="%<nop>SCRIPTURLPATH%/edit%<nop>SCRIPTSUFFIX%/%<nop>INTURLENCODE{"%<nop>WEB%"}%/"&gt;
       
  1211 	* New example topic: 
       
  1212 	  &lt;input type="text" name="topic" value="ExampleTopic%<nop>SERVERTIME{$yearx$mox$day}%" size="23" /&gt;
       
  1213 	  &lt;input type="hidden" name="templatetopic" value="ExampleTopicTemplate" /&gt;
       
  1214 	  &lt;input type="hidden" name="topicparent" value="%<nop>TOPIC%" /&gt;
       
  1215 	  &lt;input type="hidden" name="onlywikiname" value="on" /&gt;
       
  1216 	  &lt;input type="hidden" name="onlynewtopic" value="on" /&gt;
       
  1217 	  &lt;input type="submit" value="Create" /&gt;
       
  1218 	  (date format is &lt;nop&gt;YYYYxMMxDD)
       
  1219 &lt;/form&gt;
       
  1220 </pre>
       
  1221 
       
  1222 The =edit= scipt understands the following parameters, typically supplied by HTML input fields:
       
  1223 
       
  1224 <blockquote>
       
  1225 | *Parameter:* | *Description:* |
       
  1226 | =topic= | Name of topic to create. Can be set in a text field, or is set programmatically (e.g. with a sequential number) |
       
  1227 | =onlywikiname= | If set, TWiki will complain if the topic name is not a WikiWord |
       
  1228 | =onlynewtopic= | If set, TWiki will complain if a topic of the same name already exists |
       
  1229 | =templatetopic= | The name of the template topic, e.g. topic used to copy the initial content |
       
  1230 | =topicparent= | Sets the parent topic |
       
  1231 | =TopicClassification= | Assuming the template topic has a form with a field called "TopicClassification", it will set the value of the field |
       
  1232 | =anyname= | Any parameter can passed to the new topic; if the template topic contains =%<nop>URLPARAM{"anyname"}%=, it will be replaced by its value |
       
  1233 </blockquote>
       
  1234 
       
  1235 %T% *TIP:* You can use the =%<nop>WIKIUSERNAME%= and =%<nop>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 />
       
  1236 ==-- %<nop>WIKIUSERNAME% - %<nop>DATE%==
       
  1237 
       
  1238 ---++ Templates by Example
       
  1239 
       
  1240 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.
       
  1241 
       
  1242 ---+++ Base template oopsbase.tmpl
       
  1243 
       
  1244 The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing =%<nop>TMPL:P{"sep"}%=
       
  1245 
       
  1246 <blockquote>
       
  1247 <table border="1" cellspacing="0" cellpadding="1" bgcolor="#f5f5f5">
       
  1248 <tr><td>
       
  1249 <pre>
       
  1250 %<nop>TMPL:DEF{"sep"}% | %<nop>TMPL:END%
       
  1251 &lt;html&gt;
       
  1252 &lt;head&gt;
       
  1253   &lt;title&gt; %<nop>WIKITOOLNAME% . %<nop>WEB% . %<nop>TOPIC% %.TMPL:P{"titleaction"}%&lt;/title&gt;
       
  1254   &lt;base href<nop>="%<nop>SCRIPTURL%/view%<nop>SCRIPTSUFFIX%/%<nop>WEB%/%<nop>TOPIC%"&gt;
       
  1255   &lt;meta name="robots" content="noindex"&gt;
       
  1256 &lt;/head&gt;
       
  1257 &lt;body bgcolor="#FFFFFF"&gt;
       
  1258 &lt;table width="100%" border="0" cellpadding="3" cellspacing="0"&gt;
       
  1259   &lt;tr&gt;
       
  1260 	 &lt;td bgcolor="%<nop>WEBBGCOLOR%" rowspan="2" valign="top" width="1%"&gt;
       
  1261 		&lt;a href<nop>="%<nop>WIKIHOMEURL%"&gt;
       
  1262 		&lt;img src="%<nop>PUBURLPATH%/wikiHome.gif" border="0"&gt;&lt;/a&gt;
       
  1263 	 &lt;/td&gt;
       
  1264 	 &lt;td&gt;
       
  1265 		&lt;b&gt;%<nop>WIKITOOLNAME% . %<nop>WEB% . &lt;/b&gt;&lt;font size="+2"&gt;
       
  1266 		&lt;B&gt;%<nop>TOPIC%&lt;/b&gt; %<nop>TMPL:P{"titleaction"}%&lt;/font&gt;
       
  1267 	 &lt;/td&gt;
       
  1268   &lt;/tr&gt;
       
  1269   &lt;tr bgcolor="%<nop>WEBBGCOLOR%"&gt;
       
  1270 	 &lt;td colspan="2"&gt;
       
  1271 		%<nop>TMPL:P{"webaction"}%
       
  1272 	 &lt;/td&gt;
       
  1273   &lt;/tr&gt;
       
  1274 &lt;/table&gt;
       
  1275 --- ++ %<nop>TMPL:P{"heading"}%
       
  1276 %<nop>TMPL:P{"message"}%
       
  1277 &lt;table width="100%" border="0" cellpadding="3" cellspacing="0"&gt;
       
  1278   &lt;tr bgcolor="%<nop>WEBBGCOLOR%"&gt;
       
  1279 	 &lt;td valign="top"&gt;
       
  1280 		Topic &lt;b&gt;%<nop>TOPIC%&lt;/b&gt; . {
       
  1281 		  %<nop>TMPL:P{"topicaction"}%
       
  1282 		}
       
  1283 	 &lt;/td&gt;
       
  1284   &lt;/tr&gt;
       
  1285 &lt;/table&gt;
       
  1286 &lt;/body&gt;
       
  1287 </pre>
       
  1288 </td></tr>
       
  1289 </table>
       
  1290 </blockquote>
       
  1291 
       
  1292 ---+++ Test template oopstest.tmpl
       
  1293 
       
  1294 Each oops template basically just defines some variables and includes the base template that does the layout work.
       
  1295 
       
  1296 <blockquote>
       
  1297 <table border="1" cellspacing="0" cellpadding="1" bgcolor="#f5f5f5">
       
  1298 <tr><td>
       
  1299 <pre>
       
  1300 %<nop>TMPL:DEF{"titleaction"}% (test =titleaction=) %<nop>TMPL:END%
       
  1301 %<nop>TMPL:DEF{"webaction"}% test =webaction= %<nop>TMPL:END%
       
  1302 %<nop>TMPL:DEF{"heading"}%
       
  1303 Test heading %<nop>TMPL:END%
       
  1304 %<nop>TMPL:DEF{"message"}%
       
  1305 Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...
       
  1306 
       
  1307 	* Some more blah blah blah blah blah blah blah blah blah blah...
       
  1308 	* Param1: %<nop>PARAM1%
       
  1309 	* Param2: %<nop>PARAM2%
       
  1310 	* Param3: %<nop>PARAM3%
       
  1311 	* Param4: %<nop>PARAM4%
       
  1312 %<nop>TMPL:END%
       
  1313 %<nop>TMPL:DEF{"topicaction"}%
       
  1314 Test =topicaction=:
       
  1315 [<nop>[%<nop>WEB%.%<nop>TOPIC%][OK]] %<nop>TMPL:P{"sep"}%
       
  1316 [<nop>[%<nop>TWIKIWEB%.TWikiRegistration][Register]] %<nop>TMPL:END%
       
  1317 %<nop>TMPL:INCLUDE{"oopsbase"}%
       
  1318 </pre>
       
  1319 </td></tr>
       
  1320 </table >
       
  1321 </blockquote>
       
  1322 
       
  1323 ---+++ Sample screen shot of oopstest.tmpl
       
  1324 
       
  1325 With URL: ==.../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify==
       
  1326 
       
  1327 <blockquote>
       
  1328 | <img src="%ATTACHURLPATH%/testscreen.gif" width="589" height="304" alt="testscreen.gif"> |
       
  1329 </blockquote>
       
  1330 
       
  1331 ---++ Known Issues
       
  1332 
       
  1333 	* 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.
       
  1334 
       
  1335 -- TWiki:Main.PeterThoeny - 30 Dec 2004 %BR%
       
  1336 -- TWiki:Main.MikeMannix - 14 Sep 2001 %BR%
       
  1337 -- TWiki:Main.DavidLeBlanc - 11 Mar 2002
       
  1338 @
       
  1339 
       
  1340 
       
  1341 1.20
       
  1342 log
       
  1343 @none
       
  1344 @
       
  1345 text
       
  1346 @d1 1
       
  1347 a1 1
       
  1348 %META:TOPICINFO{author="PeterThoeny" date="1071562740" format="1.0" version="1.20"}%
       
  1349 d120 1
       
  1350 d134 1
       
  1351 d146 1
       
  1352 d253 1
       
  1353 a253 1
       
  1354 -- TWiki:Main.PeterThoeny - 16 Dec 2003 %BR%
       
  1355 @
       
  1356 
       
  1357 
       
  1358 1.19
       
  1359 log
       
  1360 @none
       
  1361 @
       
  1362 text
       
  1363 @d1 1
       
  1364 a1 1
       
  1365 %META:TOPICINFO{author="PeterThoeny" date="1049271891" format="1.0" version="1.19"}%
       
  1366 d138 11
       
  1367 a148 1
       
  1368 The ==onlywikiname== parameter enforces WikiWords for topic names. The ==topicparent== parameter sets the topic parent to the topic where the form is located.
       
  1369 d250 3
       
  1370 a252 3
       
  1371 -- PeterThoeny - 01 Feb 2003 <br />
       
  1372 -- MikeMannix - 14 Sep 2001 <br />
       
  1373 -- TWiki:Main/DavidLeBlanc - 11 Mar 2002
       
  1374 @
       
  1375 
       
  1376 
       
  1377 1.18
       
  1378 log
       
  1379 @none
       
  1380 @
       
  1381 text
       
  1382 @d1 1
       
  1383 a1 1
       
  1384 %META:TOPICINFO{author="PeterThoeny" date="1044103560" format="1.0" version="1.18"}%
       
  1385 d118 2
       
  1386 d131 1
       
  1387 d138 1
       
  1388 a138 1
       
  1389 The ==onlywikiname== parameter enforces WikiWords for topic names.
       
  1390 @
       
  1391 
       
  1392 
       
  1393 1.17
       
  1394 log
       
  1395 @none
       
  1396 @
       
  1397 text
       
  1398 @d1 1
       
  1399 a1 1
       
  1400 %META:TOPICINFO{author="PeterThoeny" date="1042009992" format="1.0" version="1.17"}%
       
  1401 d91 19
       
  1402 d237 1
       
  1403 a237 1
       
  1404 -- PeterThoeny - 23 Jul 2001 <br />
       
  1405 @
       
  1406 
       
  1407 
       
  1408 1.16
       
  1409 log
       
  1410 @none
       
  1411 @
       
  1412 text
       
  1413 @d1 1
       
  1414 a1 1
       
  1415 %META:TOPICINFO{author="PeterThoeny" date="1041742924" format="1.0" version="1.16"}%
       
  1416 d95 1
       
  1417 a95 1
       
  1418 <form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%URLENCODE{"%WEB%"}%/">
       
  1419 d106 1
       
  1420 a106 1
       
  1421 &lt;form name="new" action="%<nop>SCRIPTURLPATH%/edit%<nop>SCRIPTSUFFIX%/%<nop>URLENCODE{"%<nop>WEB%"}%/"&gt;
       
  1422 @
       
  1423 
       
  1424 
       
  1425 1.15
       
  1426 log
       
  1427 @none
       
  1428 @
       
  1429 text
       
  1430 @d1 1
       
  1431 a1 1
       
  1432 %META:TOPICINFO{author="PeterThoeny" date="1041735205" format="1.0" version="1.15"}%
       
  1433 d95 1
       
  1434 a95 1
       
  1435 <form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%WEBURLENCODED%/">
       
  1436 d106 1
       
  1437 a106 1
       
  1438 &lt;form name="new" action="%<nop>SCRIPTURLPATH%/edit%<nop>SCRIPTSUFFIX%/%<nop>WEBURLENCODED%/"&gt;
       
  1439 @
       
  1440 
       
  1441 
       
  1442 1.14
       
  1443 log
       
  1444 @none
       
  1445 @
       
  1446 text
       
  1447 @d1 1
       
  1448 a1 1
       
  1449 %META:TOPICINFO{author="PeterThoeny" date="1041666691" format="1.0" version="1.14"}%
       
  1450 d95 1
       
  1451 a95 1
       
  1452 <form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%WEB%/">
       
  1453 d106 1
       
  1454 a106 1
       
  1455 &lt;form name="new" action="%<nop>SCRIPTURLPATH%/edit%<nop>SCRIPTSUFFIX%/%<nop>WEB%/"&gt;
       
  1456 @
       
  1457 
       
  1458 
       
  1459 1.13
       
  1460 log
       
  1461 @none
       
  1462 @
       
  1463 text
       
  1464 @d1 1
       
  1465 a1 1
       
  1466 %META:TOPICINFO{author="PeterThoeny" date="1040375348" format="1.0" version="1.13"}%
       
  1467 d21 1
       
  1468 @
       
  1469 
       
  1470 
       
  1471 1.12
       
  1472 log
       
  1473 @none
       
  1474 @
       
  1475 text
       
  1476 @d1 1
       
  1477 a1 1
       
  1478 %META:TOPICINFO{author="PeterThoeny" date="1026976800" format="1.0" version="1.12"}%
       
  1479 d11 1
       
  1480 a11 1
       
  1481 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 mark-up for template-specific content. Templates are used to define [[#HtmlTemplates][page layout]], and also to supply[[#TemplateTopics][default content]] for new pages.
       
  1482 d21 1
       
  1483 a21 1
       
  1484 ---++ Functional Specifications
       
  1485 a23 1
       
  1486 	* Use of template directives is optional, templates work without them.
       
  1487 d25 1
       
  1488 a25 1
       
  1489 	* Directives are of the form =%<nop>TMPL:&lt;key&gt;%= and =%<nop>TMPL:&lt;key&gt;{"attr"}%=.
       
  1490 d27 9
       
  1491 a35 8
       
  1492 		* =%<nop>TMPL:INCLUDE{"file"}%=: Includes a template file. The template directory of the current web is searched first, then the templates root (=twiki/templates=).
       
  1493 		* =%<nop>TMPL:DEF{"var"}%=: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
       
  1494 		* =%<nop>TMPL:END%=: Ends variable definition.
       
  1495 		* =%<nop>TMPL:P{"var"}%=: Prints a previously defined variable.
       
  1496 	* Variables are live in a global name space, there is no parameter passing.
       
  1497 	* Two-pass processing, so that you can use a variable before declaring it or after.
       
  1498 	* 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.
       
  1499 	* __NOTE:__ The template directives work only for templates, they do not get processed in topic text.
       
  1500 d37 9
       
  1501 a45 1
       
  1502 ---++ TWiki Master Template
       
  1503 d47 1
       
  1504 a47 1
       
  1505 All common parts are defined in a master template, ==twiki.tmpl==, that all other templates use.
       
  1506 d52 1
       
  1507 a52 1
       
  1508 | %<nop>TMPL:DEF{"standardheader"}% | Standard header (ex: view, index, seach)  |
       
  1509 a57 7
       
  1510 ---++ Types of Template
       
  1511 
       
  1512 There are two types of templates:
       
  1513 
       
  1514 	* *HTML Page Templates*: Defines layout of %WIKITOOLNAME% pages
       
  1515 	* *Template Topics*: Defines default text when you create a new topic
       
  1516 
       
  1517 d61 1
       
  1518 a61 1
       
  1519 %WIKITOOLNAME% 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.
       
  1520 d63 1
       
  1521 a63 1
       
  1522 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:
       
  1523 d67 2
       
  1524 d70 1
       
  1525 a70 3
       
  1526 __Note:__ =$webName= is the name of the web (ex: =Main=), and ==$scriptName== is the script (ex: =view=).
       
  1527 
       
  1528 __Note:__ TWikiSkins can be defined to overload the standard templates.
       
  1529 d77 1
       
  1530 a77 1
       
  1531 Template topics define the default text for new topics. There are three types of template topics:
       
  1532 d80 2
       
  1533 a81 2
       
  1534 | WebTopicViewTemplate | Help text shown when you view a non existing topic. |
       
  1535 | WebTopicNonWikiTemplate | Help text shown when you view a non existing topic that has not a WikiName. |
       
  1536 d84 1
       
  1537 a84 1
       
  1538 All template topics are located in the %TWIKIWEB% web. The WebTopicEditTemplate can be overloaded. The following search order applies when you create a new topic:
       
  1539 d86 3
       
  1540 a88 3
       
  1541 	1. The topic name specified by the =templatetopic= CGI parameter.
       
  1542 	1. <nop>WebTopicEditTemplate in the current web.
       
  1543 	1. <nop>WebTopicEditTemplate in the %TWIKIWEB% web.
       
  1544 d102 1
       
  1545 a102 1
       
  1546 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:
       
  1547 d115 1
       
  1548 a115 1
       
  1549 The "onlywikiname" parameter enforces WikiWords for topic names.
       
  1550 d117 2
       
  1551 a118 1
       
  1552 __Note:__ Use can use the =%<nop>WIKIUSERNAME%= and =%<nop>DATE%= variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is: <br> =-- %<nop>WIKIUSERNAME% - %<nop>DATE%=
       
  1553 d122 1
       
  1554 a122 1
       
  1555 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.
       
  1556 d126 1
       
  1557 a126 1
       
  1558 The first line declares the delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing =%<nop>TMPL:P{"sep"}%=
       
  1559 d210 1
       
  1560 a210 1
       
  1561 | <img src="%ATTACHURL%/testscreen.gif" width="589" height="304" alt="testscreen.gif"> |
       
  1562 d215 1
       
  1563 a215 1
       
  1564 	* 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.
       
  1565 d218 2
       
  1566 a219 1
       
  1567 -- MikeMannix - 14 Sep 2001 <br />	
       
  1568 @
       
  1569 
       
  1570 
       
  1571 1.11
       
  1572 log
       
  1573 @none
       
  1574 @
       
  1575 text
       
  1576 @d1 1
       
  1577 a1 1
       
  1578 %META:TOPICINFO{author="PeterThoeny" date="1007461313" format="1.0" version="1.11"}%
       
  1579 d205 1
       
  1580 a205 1
       
  1581 With URL: ==.../bin/oops/Test/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify==
       
  1582 d208 1
       
  1583 a208 1
       
  1584 | <img src="%ATTACHURL%/testscreen.gif" width="554" height="304" alt="testscreen.gif"> |
       
  1585 d217 1
       
  1586 a217 1
       
  1587 %META:FILEATTACHMENT{name="testscreen.gif" attr="h" comment="Example of oopstest.tmpl rendered" date="999598142" path="C:\02_TWikiDocs\testscreen.gif" size="9460" user="MikeMannix" version="1.1"}%
       
  1588 @
       
  1589 
       
  1590 
       
  1591 1.10
       
  1592 log
       
  1593 @none
       
  1594 @
       
  1595 text
       
  1596 @d1 1
       
  1597 a1 1
       
  1598 %META:TOPICINFO{author="MikeMannix" date="1000791228" format="1.0" version="1.10"}%
       
  1599 d208 1
       
  1600 a208 1
       
  1601 | <img src="%ATTACHURLPATH%/testscreen.gif" width="554" height="304" alt="testscreen.gif"> |
       
  1602 @
       
  1603 
       
  1604 
       
  1605 1.9
       
  1606 log
       
  1607 @none
       
  1608 @
       
  1609 text
       
  1610 @d1 1
       
  1611 a1 1
       
  1612 %META:TOPICINFO{author="MikeMannix" date="1000619326" format="1.0" version="1.9"}%
       
  1613 d11 1
       
  1614 a11 1
       
  1615 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 mark-up for template-specific content.
       
  1616 d57 1
       
  1617 d73 1
       
  1618 @
       
  1619 
       
  1620 
       
  1621 1.8
       
  1622 log
       
  1623 @none
       
  1624 @
       
  1625 text
       
  1626 @d1 1
       
  1627 a1 1
       
  1628 %META:TOPICINFO{author="PeterThoeny" date="1000581557" format="1.0" version="1.8"}%
       
  1629 d5 1
       
  1630 a5 1
       
  1631 ---# TWiki Template System
       
  1632 d11 1
       
  1633 a11 1
       
  1634 The new modular template system is more flexible, efficient, and easily updated than the old set-up, where each template is a complete HTML file. The new master template approach places common templates parts, like headers and footers, in one shared file. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for TWikiSkins.
       
  1635 d15 1
       
  1636 a15 1
       
  1637 The main difference is that templates are now defined using variables to include template parts. You change one stored instance of a common element to update all occurrences. The new system:
       
  1638 d17 2
       
  1639 a18 4
       
  1640 	* separates a set of common template parts into a base template that is included by all of the related templates;
       
  1641 	
       
  1642 	* defines common variables, like a standard separator (ex: "|"), in the base template;
       
  1643 	
       
  1644 d35 1
       
  1645 a35 1
       
  1646 	* __Note:__ The template directives work only for templates, they do not get processed in topic text.
       
  1647 @
       
  1648 
       
  1649 
       
  1650 1.7
       
  1651 log
       
  1652 @none
       
  1653 @
       
  1654 text
       
  1655 @d1 1
       
  1656 a1 1
       
  1657 %META:TOPICINFO{author="MikeMannix" date="1000546377" format="1.0" version="1.7"}%
       
  1658 d51 1
       
  1659 d53 1
       
  1660 d85 1
       
  1661 a85 1
       
  1662 	1. The topic name specified by the =templatetopic= parameter.
       
  1663 d95 4
       
  1664 a98 3
       
  1665 	  <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$year$mo$day}%" size="22">
       
  1666 	  <input type="hidden" name="templatetopic" value="ExampleTopicTemplate">
       
  1667 	  <input type="submit" value="Create"> (date format is YYYYMMDD)
       
  1668 d106 5
       
  1669 a110 4
       
  1670 	  &lt;input type="text" name="topic" value="ExampleTopic%<nop>SERVERTIME{$year$mo$day}%" size="22"&gt;
       
  1671 	  &lt;input type="hidden" name="templatetopic" value="ExampleTopicTemplate"&gt;
       
  1672 	  &lt;input type="hidden" name="onlywikiname" value="on"&gt;
       
  1673 	  &lt;input type="submit" value="Create"&gt; (date format is YYYYMMDD)
       
  1674 @
       
  1675 
       
  1676 
       
  1677 1.6
       
  1678 log
       
  1679 @none
       
  1680 @
       
  1681 text
       
  1682 @d1 1
       
  1683 a1 1
       
  1684 %META:TOPICINFO{author="MikeMannix" date="1000534076" format="1.0" version="1.6"}%
       
  1685 d66 1
       
  1686 a66 1
       
  1687 __Note:__ ==$webName== is the name of the web ( i.e. ==Main== ), and ==$scriptName== is the script ( i.e. ==view== ).
       
  1688 d70 1
       
  1689 a70 1
       
  1690 Some special variables are used in templates ( especially ==view== ) to show meta data - see [[TWikiDocumentation#Meta_Data_Rendering][Meta Data Rendering]]
       
  1691 @
       
  1692 
       
  1693 
       
  1694 1.5
       
  1695 log
       
  1696 @none
       
  1697 @
       
  1698 text
       
  1699 @d1 1
       
  1700 a1 1
       
  1701 %META:TOPICINFO{author="PeterThoeny" date="1000456909" format="1.0" version="1.5"}%
       
  1702 d39 76
       
  1703 a114 1
       
  1704 ---++ New Template System by Example
       
  1705 d122 2
       
  1706 a123 2
       
  1707 <blockquote style="background-color:#f0f0f0">
       
  1708 <table border="1" cellspacing="0" cellpadding="1">
       
  1709 a167 1
       
  1710 
       
  1711 d172 2
       
  1712 a173 2
       
  1713 <blockquote style="background-color:#f0f0f0">
       
  1714 <table border="1" cellspacing="0" cellpadding="1">
       
  1715 d203 1
       
  1716 a203 1
       
  1717 <blockquote style="background-color:#f0f0f0">
       
  1718 a206 26
       
  1719 ---++ TWiki master template
       
  1720 
       
  1721 All common template parts are defined in one master template, =twiki.tmpl=, that all other templates include.
       
  1722 
       
  1723 | *Template variable:* | *Defines:* |
       
  1724 | %<nop>TMPL:DEF{"sep"}% | "&#124;" separator |
       
  1725 | %<nop>TMPL:DEF{"htmldoctype"}% | Start of all HTML pages |
       
  1726 | %<nop>TMPL:DEF{"standardheader"}% | Standard header (ex: view, index, seach)  |
       
  1727 | %<nop>TMPL:DEF{"simpleheader"}% | Simple header with reduced links (ex: edit, attach, oops) |
       
  1728 | %<nop>TMPL:DEF{"standardfooter"}% | Footer, excluding revision and copyright parts |
       
  1729 | %<nop>TMPL:DEF{"oops"}% | Skeleton of oops dialog |
       
  1730 
       
  1731 <blockquote style="background-color:#f0f0f0">
       
  1732 *Example: =oopspreview.tmpl= template*
       
  1733 <pre>
       
  1734 %<nop>TMPL:INCLUDE{"twiki"}%
       
  1735 %<nop>TMPL:DEF{"titleaction"}% (oops) %<nop>TMPL:END%
       
  1736 %<nop>TMPL:DEF{"webaction"}% *Attention* %<nop>TMPL:END%
       
  1737 %<nop>TMPL:DEF{"heading"}% Topic is not saved yet %<nop>TMPL:END%
       
  1738 %<nop>TMPL:DEF{"message"}% Please go back in your browser and save the topic. %<nop>TMPL:END%
       
  1739 %<nop>TMPL:DEF{"topicaction"}%
       
  1740 %<nop>TMPL:END%
       
  1741 %<nop>TMPL:P{"oops"}%
       
  1742 </pre>
       
  1743 </blockquote>
       
  1744 
       
  1745 d211 2
       
  1746 a212 2
       
  1747 -- PeterThoeny - 23 Jul 2001 <br>
       
  1748 -- MikeMannix - 30 Aug 2001 
       
  1749 @
       
  1750 
       
  1751 
       
  1752 1.4
       
  1753 log
       
  1754 @none
       
  1755 @
       
  1756 text
       
  1757 @d1 1
       
  1758 a1 1
       
  1759 %META:TOPICINFO{author="MikeMannix" date="1000277381" format="1.0" version="1.4"}%
       
  1760 d11 1
       
  1761 a11 1
       
  1762 The new modular template system is more flexible, efficient, and easily updated than the old set-up, where each template is a complete HTML file. The new master template approach places common templates parts, like headers and footers, in one shared file. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for [[TWikiDocumentation#TWiki_Skins][skins]].
       
  1763 d29 2
       
  1764 a30 2
       
  1765 	* Initial set of directives:
       
  1766 		* =%<nop>TMPL:INCLUDE{"file"}%=: Includes a template file. The usual search path is applied.
       
  1767 a33 1
       
  1768 	* New directives can be added over time when needed, ex: IF-THEN-ELSE.
       
  1769 d36 1
       
  1770 a36 1
       
  1771 	* Templates and [[TWikiDocumentation#TWiki_Skins][skins]] 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.
       
  1772 a46 2
       
  1773 __NOTE:__ Added a dot to escape rendering of variables, i.e. read ==%.WEB%== as ==%<nop>WEB%==.
       
  1774 
       
  1775 d48 2
       
  1776 d51 1
       
  1777 a51 4
       
  1778 &lt;table border="1" cellspacing="0" cellpadding="1"&gt;
       
  1779 &lt;tr&gt;&lt;td&gt;
       
  1780 &lt;verbatim&gt;
       
  1781 %.TMPL:DEF{"sep"}% | %.TMPL:END%
       
  1782 d54 2
       
  1783 a55 2
       
  1784   &lt;title&gt; %.WIKITOOLNAME% . %.WEB% . %.TOPIC% %.TMPL:P{"titleaction"}%&lt;/title&gt;
       
  1785   &lt;base href="%.SCRIPTURL%/view%.SCRIPTSUFFIX%/%.WEB%/%.TOPIC%"&gt;
       
  1786 d61 3
       
  1787 a63 3
       
  1788 	 &lt;td bgcolor="%.WEBBGCOLOR%" rowspan="2" valign="top" width="1%"&gt;
       
  1789 		&lt;a href="%.WIKIHOMEURL%"&gt;
       
  1790 		&lt;img src="%.PUBURLPATH%/wikiHome.gif" border="0"&gt;&lt;/a&gt;
       
  1791 d66 2
       
  1792 a67 2
       
  1793 		&lt;b&gt;%.WIKITOOLNAME% . %.WEB% . &lt;/b&gt;&lt;font size="+2"&gt;
       
  1794 		&lt;B&gt;%.TOPIC%&lt;/b&gt; %.TMPL:P{"titleaction"}%&lt;/font&gt;
       
  1795 d70 1
       
  1796 a70 1
       
  1797   &lt;tr bgcolor="%.WEBBGCOLOR%"&gt;
       
  1798 d72 1
       
  1799 a72 1
       
  1800 		%.TMPL:P{"webaction"}%
       
  1801 d76 2
       
  1802 a77 2
       
  1803 --- ++ %.TMPL:P{"heading"}%
       
  1804 %.TMPL:P{"message"}%
       
  1805 d79 1
       
  1806 a79 1
       
  1807   &lt;tr bgcolor="%.WEBBGCOLOR%"&gt;
       
  1808 d81 2
       
  1809 a82 2
       
  1810 		Topic &lt;b&gt;%TOPIC%&lt;/b&gt; . {
       
  1811 		  %.TMPL:P{"topicaction"}%
       
  1812 a87 3
       
  1813 &lt;/verbatim&gt;
       
  1814 &lt;/td&gt;&lt;/tr&gt;
       
  1815 &lt;/table &gt;
       
  1816 d89 2
       
  1817 d101 6
       
  1818 a106 6
       
  1819 <verbatim>
       
  1820 %.TMPL:DEF{"titleaction"}% (test =titleaction=) %.TMPL:END%
       
  1821 %.TMPL:DEF{"webaction"}% test =webaction= %.TMPL:END%
       
  1822 %.TMPL:DEF{"heading"}%
       
  1823 Test heading %.TMPL:END%
       
  1824 %.TMPL:DEF{"message"}%
       
  1825 d110 6
       
  1826 a115 6
       
  1827 	* Param1: %PARAM1%
       
  1828 	* Param2: %PARAM2%
       
  1829 	* Param3: %PARAM3%
       
  1830 	* Param4: %PARAM4%
       
  1831 %.TMPL:END%
       
  1832 %.TMPL:DEF{"topicaction"}%
       
  1833 d117 4
       
  1834 a120 4
       
  1835 [[%.WEB%.%TOPIC%][OK]] %.TMPL:P{"sep"}%
       
  1836 [[%.TWIKIWEB%.TWikiRegistration][Register]] %.TMPL:END%
       
  1837 %.TMPL:INCLUDE{"oopsbase"}%
       
  1838 </verbatim>
       
  1839 d133 2
       
  1840 d146 1
       
  1841 a146 1
       
  1842 *Example: =preview.tmpl= template*
       
  1843 d161 1
       
  1844 a161 1
       
  1845 	* 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.
       
  1846 d163 1
       
  1847 a163 1
       
  1848 -- Main.PeterThoeny - 23 Jul 2001 <br>
       
  1849 @
       
  1850 
       
  1851 
       
  1852 1.3
       
  1853 log
       
  1854 @none
       
  1855 @
       
  1856 text
       
  1857 @d1 1
       
  1858 a1 1
       
  1859 %META:TOPICINFO{author="MikeMannix" date="999960753" format="1.0" version="1.3"}%
       
  1860 d169 1
       
  1861 @
       
  1862 
       
  1863 
       
  1864 1.2
       
  1865 log
       
  1866 @none
       
  1867 @
       
  1868 text
       
  1869 @d1 1
       
  1870 a1 1
       
  1871 %META:TOPICINFO{author="MikeMannix" date="999857234" format="1.0" version="1.2"}%
       
  1872 a2 5
       
  1873 ---+ new topic for the final doc
       
  1874 
       
  1875 Slightly edited down, but waiting for new docs, hopefully.
       
  1876 
       
  1877 see also for ref: orig TWikiTemplatingSystem
       
  1878 a3 1
       
  1879 
       
  1880 d7 1
       
  1881 a7 1
       
  1882 _Define the templates used to render all HTML pages displayed in TWiki_ 
       
  1883 d9 1
       
  1884 a9 1
       
  1885 ---+ Overview
       
  1886 d11 1
       
  1887 a11 1
       
  1888 We have a need for more advanced template handling. As Main.JohnTalintyre pointed out in CommonHeaderFooterTemplate it makes sense to separate the header and footer into one file so that it can be easily altered (or even overloaded by a skin). Also the oops dialog messages are all identical except for a few variables like heading, and so on.
       
  1889 d13 1
       
  1890 a13 1
       
  1891 Using external modules like the TemplateToolkit would be one way to go, but this will add a lot of baggage to TWiki.
       
  1892 d15 1
       
  1893 a15 1
       
  1894 ---++ Needs of the TWiki templating system
       
  1895 d17 5
       
  1896 a21 3
       
  1897 	* Separate common parts into one (or more) base template file(s) and include that from other template files like =view.tmpl=.
       
  1898 	* Define common variables like a "|" separator in the base template and use them in other template files
       
  1899 	* Define variable text in templates (i.e. =view.tmpl=) and pass them to the base template
       
  1900 d23 1
       
  1901 a23 3
       
  1902 ---++ Functional Spec
       
  1903 
       
  1904 I tried to define a simple but powerful solution that can be extended over time. Here we go:
       
  1905 d27 2
       
  1906 a28 2
       
  1907 	* All template preprocessing is done in =&TWiki::Store::readTemplate()= so that the caller simply gets an expanded template file (the same as before)
       
  1908 	* Directives are of form =%<nop>TMPL:&lt;key&gt;%= and =%<nop>TMPL:&lt;key&gt;{"attr"}%=.
       
  1909 d34 5
       
  1910 a38 6
       
  1911 	* New directives can be added over time when needed, i.e. IF-THEN-ELSE.
       
  1912 	* Variables live in a global name space, there is no parameter passing.
       
  1913 	* Two pass processing, so that you can use a variable before declaring it or after.
       
  1914 	* Templates and skins work transparently and interchangeably. You could for example define a new skin just for the header & footer and keep the other template files unchanged.
       
  1915 	* __Note:__ The template directive work only for templates, they do not get processed in topic text.
       
  1916 
       
  1917 d40 1
       
  1918 a40 1
       
  1919 ---++ Examples
       
  1920 d42 1
       
  1921 a42 1
       
  1922 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. This is not the version that will go into the release, it is just a quick hack.
       
  1923 d44 1
       
  1924 a44 1
       
  1925 ---++++ Base template oopsbase.tmpl
       
  1926 d48 1
       
  1927 a48 1
       
  1928 __Note:__ Added a dot to escape rendering of variables, i.e. read ==%.WEB%== as ==%<nop>WEB%==.
       
  1929 d50 1
       
  1930 d96 1
       
  1931 d99 1
       
  1932 a99 1
       
  1933 ---++++ Test template oopstest.tmpl
       
  1934 d103 1
       
  1935 d128 1
       
  1936 d130 1
       
  1937 a130 1
       
  1938 ---++++ Sample screen shot of oopstest.tmpl
       
  1939 d134 1
       
  1940 d136 1
       
  1941 d138 1
       
  1942 a138 17
       
  1943 ---++ Comments and feedback
       
  1944 
       
  1945 	* The itching factor to put this into the upcoming release is to easy the pending converstion of the templates into XHTML format and to have a more flexible solution for templates and skins.
       
  1946 	* Is the terminology OK?
       
  1947 	* Is the spec OK?
       
  1948 	* Are there any other directives that are needed urgently?
       
  1949 	* One drawback by using the directives is that you can only test a template from within TWiki. This is because you don't have a text that has a linear flow when you use TMPL:DEF, TMPL:P and TMPL:INCLUDE.
       
  1950 
       
  1951 -- Main.PeterThoeny - 21 Jul 2001 <br>
       
  1952 
       
  1953 	* It's probably more readable to enforce variables being defined before use, which would avoid need for slower two-pass processing.
       
  1954 		* [ Main.PeterThoeny ] You need two-pass processing because you need to define the "|" separator in the included template onone side, and on the other side define variables for the included template. The processing happens as regex in memory, so there is no mesurable speed penalty.
       
  1955 	* It would be nice to simplify the syntax a bit, e.g. not using "" around variable names (they don't really need it, unlike filenames), and not using braces - however, this is not a big deal and there is some merit in keeping consistent with the current TWiki syntax.
       
  1956 		* [ Main.PeterThoeny ] The templating system uses the standard internal TWiki function to parse variable attributes. The "" can be skipped (is possible but is not documented).
       
  1957 
       
  1958 
       
  1959 Please have a look at the latest templates in the TWikiAlphaRelease. There is now one master template called =twiki.tmpl= that all other templates include (well, will include when all done). The idea is to define all common parts of the templates in =twiki.tmpl= and simply use that from all other templates.
       
  1960 d141 1
       
  1961 a141 1
       
  1962 | %<nop>TMPL:DEF{"sep"}% | %TMPL:END% | "&#124;" separator |
       
  1963 d143 3
       
  1964 a145 3
       
  1965 | %<nop>TMPL:DEF{"standardheader"}% | Standard header (for view, rdiff, ... |
       
  1966 | %<nop>TMPL:DEF{"simpleheader"}% | Simple header with reduced links (for edit, attach, oops,...) |
       
  1967 | %<nop>TMPL:DEF{"standardfooter"}% | Footer, excluding revision part and copyright part |
       
  1968 d148 2
       
  1969 a149 1
       
  1970 I.e. the =preview.tmpl= template is now simply:
       
  1971 d155 3
       
  1972 a157 3
       
  1973 %<nop>TMPL:DEF{"message"}%
       
  1974   Please go back in your browser and save the topic. %<nop>TMPL:END%
       
  1975 %<nop>TMPL:DEF{"topicaction"}% %<nop>TMPL:END%
       
  1976 d160 3
       
  1977 d164 1
       
  1978 a164 1
       
  1979 With this it should be possible to create a skin that overloads just the =twiki.tmpl=, i.e. a =twiki.print.tmpl= that redefines the header and footer.
       
  1980 a167 1
       
  1981 
       
  1982 @
       
  1983 
       
  1984 
       
  1985 1.1
       
  1986 log
       
  1987 @none
       
  1988 @
       
  1989 text
       
  1990 @d1 1
       
  1991 a1 1
       
  1992 %META:TOPICINFO{author="MikeMannix" date="999598350" format="1.0" version="1.1"}%
       
  1993 d11 1
       
  1994 a11 1
       
  1995 ---## TWiki Template System
       
  1996 d15 1
       
  1997 a15 1
       
  1998 ---+++ Overview
       
  1999 d21 1
       
  2000 a21 1
       
  2001 ---+++ Needs of the TWiki templating system
       
  2002 d27 1
       
  2003 a27 1
       
  2004 ---+++ Functional Spec
       
  2005 d47 1
       
  2006 a47 1
       
  2007 ---+++ Examples
       
  2008 d51 1
       
  2009 a51 1
       
  2010 ---+++++ Base template oopsbase.tmpl
       
  2011 d104 1
       
  2012 a104 1
       
  2013 ---+++++ Test template oopstest.tmpl
       
  2014 d133 1
       
  2015 a133 1
       
  2016 ---+++++ Sample screen shot of oopstest.tmpl
       
  2017 d139 1
       
  2018 a139 1
       
  2019 ---+++ Comments and feedback
       
  2020 @