|
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 |