none
[openafs-wiki.git] / TWiki / TWikiTemplates.mdwn
index 1d9a348..bec83d1 100644 (file)
@@ -1,6 +1,6 @@
 <div>
   <ul>
-    <li><a href="#TWiki Template System"> TWiki Template System</a><ul>
+    <li><a href="#TWiki Templates"> TWiki Templates</a><ul>
         <li><a href="#Overview"> Overview</a></li>
         <li><a href="#Major changes from the previous"> Major changes from the previous template system</a></li>
         <li><a href="#Functional Specifications"> Functional Specifications</a></li>
   </ul>
 </div>
 
-# <a name="TWiki Template System"></a> TWiki Template System
+# <a name="TWiki Templates"></a> TWiki Templates
 
 _Definition of the templates used to render all HTML pages displayed in TWiki_
 
 ## <a name="Overview"></a> Overview
 
-The new modular template system 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]].
+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 [[page layout|Main/WebHome#HtmlTemplates]], and also to supply[[default content|Main/WebHome#TemplateTopics]] for new pages.
 
 ## <a name="Major changes from the previous"></a><a name="Major changes from the previous "></a> Major changes from the previous template system
 
-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:
+Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for [[TWikiSkins]]. The new system:
 
 - separates a set of common template parts into a base template that is included by all of the related templates;
-
 - defines common variables, like a standard separator (ex: "|"), in the base template;
-
 - defines variable text in the individual templates and passes it back to the base template.
 
 ## <a name="Functional Specifications"></a> Functional Specifications
@@ -57,7 +55,7 @@ The main difference is that templates are now defined using variables to include
 - Variables are live in a global name space, there is no parameter passing.
 - Two-pass processing, so that you can use a variable before declaring it or after.
 - 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.
-- **_Note:_** The template directives work only for templates, they do not get processed in topic text.
+- **_NOTE:_** The template directives work only for templates, they do not get processed in topic text.
 
 ## <a name="TWiki Master Template"></a> TWiki Master Template
 
@@ -101,6 +99,8 @@ There are two types of templates:
 - **HTML Page Templates**: Defines layout of %WIKITOOLNAME% pages
 - **Template Topics**: Defines default text when you create a new topic
 
+<a name="HtmlTemplates"></a>
+
 ### <a name="HTML Page Templates"></a> HTML Page Templates
 
 %WIKITOOLNAME% uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.
@@ -110,11 +110,13 @@ The template files are in the <code>**twiki/templates**</code> directory. As an
 1. <code>**twiki/templates/$webName/$scriptName.tmpl**</code>
 2. <code>**twiki/templates/$scriptName.tmpl**</code>
 
-**_Note:_** <code>**$webName**</code> is the name of the web ( i.e. <code>**Main**</code> ), and <code>**$scriptName**</code> is the script ( i.e. <code>**view**</code> ).
+**_Note:_** `$webName` is the name of the web (ex: `Main`), and <code>**$scriptName**</code> is the script (ex: `view`).
 
 **_Note:_** [[TWikiSkins]] can be defined to overload the standard templates.
 
-Some special variables are used in templates ( especially <code>**view**</code> ) to show meta data - see [[Meta Data Rendering|Main/TWikiDocumentation#Meta_Data_Rendering]]
+Special variables are used in templates, especially in `view`, to display [[meta data|Main/TWikiMetaData#MetaDataRendering]].
+
+<a name="TemplateTopics"></a>
 
 ### <a name="Template Topics"></a> Template Topics
 
@@ -141,7 +143,7 @@ Template topics define the default text for new topics. There are three types of
 
 All template topics are located in the TWiki web. The [[WebTopicEditTemplate]] can be overloaded. The following search order applies when you create a new topic:
 
-1. The topic name specified by the `templatetopic` parameter.
+1. The topic name specified by the `templatetopic` CGI parameter.
 2. WebTopicEditTemplate in the current web.
 3. WebTopicEditTemplate in the TWiki web.
 
@@ -151,7 +153,7 @@ Here is an example for creating new topics based on a specific template topic:
 
 <form action="http://www.dementia.org/twiki//edit/%WEB%/" name="new">
   <ul>
-    <li> New example topic: <input name="topic" size="22" type="text" value="ExampleTopic20100629" /> <input name="templatetopic" type="hidden" value="ExampleTopicTemplate" /> <input type="submit" value="Create" /> (date format is YYYYMMDD) </li>
+    <li> New example topic: <input name="topic" size="23" type="text" value="ExampleTopic2010x06x29" /> <input name="templatetopic" type="hidden" value="ExampleTopicTemplate" /> <input type="submit" value="Create" /> (date format is YYYYxMMxDD) </li>
   </ul>
 </form>
 
@@ -159,10 +161,11 @@ Above form asks for a topic name. A hidden input tag of name "templatetopic" spe
 
     <form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%WEB%/">
        * New example topic:
-         <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$year$mo$day}%" size="22">
-         <input type="hidden" name="templatetopic" value="ExampleTopicTemplate">
-         <input type="hidden" name="onlywikiname" value="on">
-         <input type="submit" value="Create"> (date format is YYYYMMDD)
+         <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
+         <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
+         <input type="hidden" name="onlywikiname" value="on" />
+         <input type="submit" value="Create" />
+         (date format is <nop>YYYYxMMxDD)
     </form>
 
 The "onlywikiname" parameter enforces [[WikiWords]] for topic names.
@@ -255,11 +258,11 @@ Each oops template basically just defines some variables and includes the base t
 
 ### <a name="Sample screen shot of oopstest.t"></a> Sample screen shot of oopstest.tmpl
 
-With URL: <code>**.../bin/oops/Test/TestTopic2?template=oopstest&amp;param1=WebHome&amp;param2=WebNotify**</code>
+With URL: <code>**.../bin/oops/Sandbox/TestTopic2?template=oopstest&amp;param1=WebHome&amp;param2=WebNotify**</code>
 
 > <table border="1" cellpadding="0" cellspacing="0">
 >   <tr>
->     <td><img alt="testscreen.gif" height="304" src="http://www.dementia.org/twiki//view/testscreen.gif" width="554" /></td>
+>     <td><img alt="testscreen.gif" height="304" src="http://www.dementia.org/twiki//view/testscreen.gif" width="589" /></td>
 >   </tr>
 > </table>