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