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