data/TWiki/TWikiTemplatesDotPm.txt,v
changeset 0 414e01d06fd5
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/TWikiTemplatesDotPm.txt,v	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,137 @@
     1.4 +head	1.2;
     1.5 +access;
     1.6 +symbols;
     1.7 +locks; strict;
     1.8 +comment	@# @;
     1.9 +
    1.10 +
    1.11 +1.2
    1.12 +date	2008.01.22.03.21.31;	author TWikiContributor;	state Exp;
    1.13 +branches;
    1.14 +next	1.1;
    1.15 +
    1.16 +1.1
    1.17 +date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
    1.18 +branches;
    1.19 +next	;
    1.20 +
    1.21 +
    1.22 +desc
    1.23 +@new-topic
    1.24 +@
    1.25 +
    1.26 +
    1.27 +1.2
    1.28 +log
    1.29 +@buildrelease
    1.30 +@
    1.31 +text
    1.32 +@---+ Package =TWiki::Templates=
    1.33 +
    1.34 +Support for the TWiki template language.
    1.35 +
    1.36 +
    1.37 +%TOC%
    1.38 +
    1.39 +The following tokens are supported by this language:
    1.40 +
    1.41 +| %<nop>TMPL:P% | Instantiates a previously defined template |
    1.42 +| %<nop>TMPL:DEF% | Opens a template definition |
    1.43 +| %<nop>TMPL:END% | Closes a template definition |
    1.44 +| %<nop>TMPL:INCLUDE% | Includes another file of templates |
    1.45 +
    1.46 +Note; the template cache does not get reset during initialisation, so
    1.47 +the haveTemplate test will return true if a template was loaded during
    1.48 +a previous run when used with mod_perl or speedycgi. Frustrating for
    1.49 +the template author, but they just have to switch off
    1.50 +the accelerators during development.
    1.51 +
    1.52 +This is to all intents and purposes a singleton object. It could
    1.53 +easily be coverted into a true singleton (template manager).
    1.54 +
    1.55 +
    1.56 +---++ ClassMethod *new* <tt>($session)</tt>
    1.57 +
    1.58 +Constructor. Creates a new template database object.
    1.59 +   * $session - session (TWiki) object
    1.60 +
    1.61 +
    1.62 +
    1.63 +---++ ObjectMethod *finish* <tt>()</tt>
    1.64 +Break circular references.
    1.65 +
    1.66 +
    1.67 +
    1.68 +---++ ObjectMethod *haveTemplate* <tt>($name) -> $boolean</tt>
    1.69 +
    1.70 +Return true if the template exists and is loaded into the cache
    1.71 +
    1.72 +
    1.73 +
    1.74 +---++ ObjectMethod *expandTemplate* <tt>($params) -> $string</tt>
    1.75 +
    1.76 +Expand the template specified in the parameter string using =tmplP=.
    1.77 +
    1.78 +Examples:
    1.79 +<verbatim>
    1.80 +$tmpls->expandTemplate('"blah");
    1.81 +$tmpls->expandTemplate('context="view" then="sigh" else="humph"');
    1.82 +
    1.83 +
    1.84 +
    1.85 +---++ ObjectMethod *tmplP* <tt>($attrs) -> $string</tt>
    1.86 +
    1.87 +Return value expanded text of the template, as found from looking
    1.88 +in the register of template definitions. The attrs can contain a template
    1.89 +name in _DEFAULT, and / or =context=, =then= and =else= values.
    1.90 +
    1.91 +Recursively expands any contained TMPL:P tags.
    1.92 +
    1.93 +Note that it would be trivial to add template parameters to this,
    1.94 +simply by iterating over the other parameters (other than _DEFAULT, context,
    1.95 +then and else) and doing a s/// in the template for that parameter value. This
    1.96 +would add considerably to the power of templates. There is already code
    1.97 +to do this in the MacrosPlugin.
    1.98 +
    1.99 +
   1.100 +
   1.101 +---++ ObjectMethod *readTemplate* <tt>($name,$skins,$web) -> $text</tt>
   1.102 +
   1.103 +Return value: expanded template text
   1.104 +
   1.105 +Reads a template, constructing a candidate name for the template thus
   1.106 +   0 looks for file =$name.$skin.tmpl= (for each skin)
   1.107 +      0 in =templates/$web=
   1.108 +      0 in =templates=, look for
   1.109 +   0 looks for file =$name.tmpl=
   1.110 +      0 in =templates/$web=
   1.111 +      0 in =templates=, look for
   1.112 +   0 if a template is not found, tries in this order
   1.113 +      0 parse =$name= into a web name (default to $web) and a topic name and looks for this topic
   1.114 +      0 looks for topic =${skin}Skin${name}Template= 
   1.115 +         0 in $web (for each skin)
   1.116 +         0 in =TWiki::cfg{SystemWebName}= (for each skin)
   1.117 +      0 looks for topic =${name}Template=
   1.118 +         0 in $web (for each skin)
   1.119 +         0 in =TWiki::cfg{SystemWebName}= (for each skin)
   1.120 +In the event that the read fails (template not found, access permissions fail)
   1.121 +returns the empty string ''.
   1.122 +
   1.123 +=$skin=, =$web= and =$name= are forced to an upper-case first character
   1.124 +when composing user topic names.
   1.125 +
   1.126 +If template text is found, extracts include statements and fully expands them.
   1.127 +Also extracts template definitions and adds them to the
   1.128 +list of loaded templates, overwriting any previous definition.
   1.129 +
   1.130 +
   1.131 +@
   1.132 +
   1.133 +
   1.134 +1.1
   1.135 +log
   1.136 +@buildrelease
   1.137 +@
   1.138 +text
   1.139 +@d32 5
   1.140 +@