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