TWiki/TWikiTemplatesDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Templates="></a> Package =TWiki::Templates
   2
   3 Support for the TWiki template language.
   4
   5 <div>
   6   <ul>
   7     <li><a href="#Package =TWiki::Templates="> Package TWiki::Templates</a><ul>
   8         <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
   9         <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
  10         <li><a href="#ObjectMethod <strong>haveTemplate</strong> ($na"> ObjectMethod haveTemplate <tt>($name) -&gt; $boolean</tt></a></li>
  11         <li><a href="#ObjectMethod <strong>expandTemplate</strong> ($"> ObjectMethod expandTemplate <tt>($params) -&gt; $string</tt></a></li>
  12       </ul>
  13     </li>
  14   </ul>
  15 </div>
  16
  17 The following tokens are supported by this language:
  18
  19 <table border="1" cellpadding="0" cellspacing="0">
  20   <tr>
  21     <td> %TMPL:P% </td>
  22     <td> Instantiates a previously defined template </td>
  23   </tr>
  24   <tr>
  25     <td> %TMPL:DEF% </td>
  26     <td> Opens a template definition </td>
  27   </tr>
  28   <tr>
  29     <td> %TMPL:END% </td>
  30     <td> Closes a template definition </td>
  31   </tr>
  32   <tr>
  33     <td> %TMPL:INCLUDE% </td>
  34     <td> Includes another file of templates </td>
  35   </tr>
  36 </table>
  37
  38 Note; the template cache does not get reset during initialisation, so the haveTemplate test will return true if a template was loaded during a previous run when used with mod\_perl or speedycgi. Frustrating for the template author, but they just have to switch off the accelerators during development.
  39
  40 This is to all intents and purposes a singleton object. It could easily be coverted into a true singleton (template manager).
  41
  42 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session)"></a> [[ClassMethod]] **new** `($session)`
  43
  44 Constructor. Creates a new template database object.
  45
  46 - $session - session (TWiki) object
  47
  48 ## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
  49
  50 Break circular references.
  51
  52 ## <a name="ObjectMethod &lt;strong&gt;haveTemplate&lt;/strong&gt; ($na"></a> [[ObjectMethod]] **haveTemplate** `($name) -> $boolean`
  53
  54 Return true if the template exists and is loaded into the cache
  55
  56 ## <a name="ObjectMethod &lt;strong&gt;expandTemplate&lt;/strong&gt; ($"></a> [[ObjectMethod]] **expandTemplate** `($params) -> $string`
  57
  58 Expand the template specified in the parameter string using `tmplP`.
  59
  60 Examples:
  61
  62     $tmpls->expandTemplate('"blah");
  63     $tmpls->expandTemplate('context="view" then="sigh" else="humph"');
  64
  65     ---++ ObjectMethod *tmplP* <tt>($attrs) -> $string</tt>
  66
  67     Return value expanded text of the template, as found from looking
  68     in the register of template definitions. The attrs can contain a template
  69     name in _DEFAULT, and / or =context=, =then= and =else= values.
  70
  71     Recursively expands any contained TMPL:P tags.
  72
  73     Note that it would be trivial to add template parameters to this,
  74     simply by iterating over the other parameters (other than _DEFAULT, context,
  75     then and else) and doing a s/// in the template for that parameter value. This
  76     would add considerably to the power of templates. There is already code
  77     to do this in the MacrosPlugin.
  78
  79     ---++ ObjectMethod *readTemplate* <tt>($name,$skins,$web) -> $text</tt>
  80
  81     Return value: expanded template text
  82
  83     Reads a template, constructing a candidate name for the template thus
  84        0 looks for file =$name.$skin.tmpl= (for each skin)
  85           0 in =templates/$web=
  86           0 in =templates=, look for
  87        0 looks for file =$name.tmpl=
  88           0 in =templates/$web=
  89           0 in =templates=, look for
  90        0 if a template is not found, tries in this order
  91           0 parse =$name= into a web name (default to $web) and a topic name and looks for this topic
  92           0 looks for topic =${skin}Skin${name}Template=
  93              0 in $web (for each skin)
  94              0 in =TWiki::cfg{SystemWebName}= (for each skin)
  95           0 looks for topic =${name}Template=
  96              0 in $web (for each skin)
  97              0 in =TWiki::cfg{SystemWebName}= (for each skin)
  98     In the event that the read fails (template not found, access permissions fail)
  99     returns the empty string ''.
 100
 101     =$skin=, =$web= and =$name= are forced to an upper-case first character
 102     when composing user topic names.
 103
 104     If template text is found, extracts include statements and fully expands them.
 105     Also extracts template definitions and adds them to the
 106     list of loaded templates, overwriting any previous definition.