1 |
dpavlin |
1 |
Text::CPPTemplate(3) gedafe Text::CPPTemplate(3) |
2 |
|
|
|
3 |
|
|
|
4 |
|
|
|
5 |
|
|
NAME |
6 |
|
|
Text::CPPTemplate - CPP-Style Templates |
7 |
|
|
|
8 |
|
|
SYNOPSIS |
9 |
|
|
use Text::CPPTemplate; |
10 |
|
|
|
11 |
|
|
my $templ = new Text::CPPTemplate('/var/web/templates','.html'); |
12 |
|
|
|
13 |
|
|
print $templ->template({ |
14 |
|
|
PAGE => 'index', |
15 |
|
|
ELEMENT => 'header', |
16 |
|
|
TITLE => 'Test' |
17 |
|
|
}); |
18 |
|
|
|
19 |
|
|
DESCRIPTION |
20 |
|
|
CPPTemplate is a templating system using a CPP-style (C |
21 |
|
|
Pre-Processor) syntax. CPPTemplate is quite fast so that |
22 |
|
|
it can be used in online Applications such as CGI scripts |
23 |
|
|
to separate program the code from the HTML. CPPTemplate is |
24 |
|
|
not HTML specific, so it can be used for other applica- |
25 |
|
|
tions. For performance reasons, the files containing the |
26 |
|
|
templates are read only once and are cached for further |
27 |
|
|
use. This is especially handy when working with long run- |
28 |
|
|
ning scripts which use the same template over and over |
29 |
|
|
again. Apache mod_perl is such an environment. |
30 |
|
|
|
31 |
|
|
An application can use a large number of templates. They |
32 |
|
|
could for example represent different parts of output gen- |
33 |
|
|
erated by the aplication. Each template can contain vari- |
34 |
|
|
ables and CPP style if-then-else structures. When the |
35 |
|
|
template gets activated, all the variables will get sub- |
36 |
|
|
stituted and the if-then-else structures will get pro- |
37 |
|
|
cessed. |
38 |
|
|
|
39 |
|
|
FILE NAMES |
40 |
|
|
When you activate a template, you do not specify a |
41 |
|
|
file-name, but only variables. Based on the contents of |
42 |
|
|
some special variables, CPPTemplate will try to load an |
43 |
|
|
apropriate template file from disk. It tries to do this |
44 |
|
|
using a number of different file-names. The first one to |
45 |
|
|
exist will be used. A directory where the templates |
46 |
|
|
reside and a suffix have to be specified with the "new" |
47 |
|
|
method. The following list shows which variables cause |
48 |
|
|
CPPTemplate to look for which files: |
49 |
|
|
|
50 |
|
|
o PAGE_ELEMENT (PAGE and ELEMENT are variables) |
51 |
|
|
|
52 |
|
|
o ELEMENT |
53 |
|
|
|
54 |
|
|
o PAGE |
55 |
|
|
|
56 |
|
|
o "default" (as is, not a variable) |
57 |
|
|
|
58 |
|
|
In addition, if THEME is specified, the template will be |
59 |
|
|
first searched in the subdirectory specified by that vari- |
60 |
|
|
able of the templates directory. |
61 |
|
|
|
62 |
|
|
In the example given in SYNOPSIS, the following files will |
63 |
|
|
be opened in turn until one is found to exist (in the |
64 |
|
|
directory /var/web/templates): index_header.html, |
65 |
|
|
header.html, index.html and default.html. |
66 |
|
|
|
67 |
|
|
VARIABLE SUBSTITUTION |
68 |
|
|
Variables are marked "##var##" in the templates. If no |
69 |
|
|
variable is found with that specified name, the ##var## |
70 |
|
|
text remains unchanged. |
71 |
|
|
|
72 |
|
|
CPP-STYLE DIRECTIVES |
73 |
|
|
"MiniCPP" directives permit the selection of parts of the |
74 |
|
|
template based on some condition. The language is very |
75 |
|
|
very basic, it seems to be good-enough for most applica- |
76 |
|
|
tions. The following directives are supported: |
77 |
|
|
|
78 |
|
|
"// comment" |
79 |
|
|
The whole line is removed from the output |
80 |
|
|
|
81 |
|
|
"#ifdef VAR" |
82 |
|
|
If variable VAR is defined, the following text will be |
83 |
|
|
selected. |
84 |
|
|
|
85 |
|
|
"#if expr" |
86 |
|
|
If the expression "expr" evaluates to true (see |
87 |
|
|
"EXPRESSIONS"), the following text will be selected. |
88 |
|
|
You can use substitutions in the expression with the |
89 |
|
|
syntax '##VAR##'. |
90 |
|
|
|
91 |
|
|
"#elif expr" |
92 |
|
|
If the previous "#if" (or "#elif") expression was |
93 |
|
|
false, evaluate this "expr" and if true select the |
94 |
|
|
following text. |
95 |
|
|
|
96 |
|
|
"#else" |
97 |
|
|
If the previous "#if" (or "#elif") expression was |
98 |
|
|
false, select the following text. |
99 |
|
|
|
100 |
|
|
"#endif" |
101 |
|
|
Ends an "#ifdef" or an "#if". |
102 |
|
|
|
103 |
|
|
Note that these elements can be nested. |
104 |
|
|
|
105 |
|
|
The newlines will be removed unless two consecutive lines |
106 |
|
|
without MiniCPP directives are found. Spaces and tabs will |
107 |
|
|
be removed from the beginning and the end of each line. |
108 |
|
|
Use '\ ' (backslash space) to insert spaces at the begin- |
109 |
|
|
ning or the end of the line. |
110 |
|
|
|
111 |
|
|
EXPRESSIONS |
112 |
|
|
At the moment only the following expressions are supported |
113 |
|
|
(don't laugh :-)) |
114 |
|
|
|
115 |
|
|
A = B |
116 |
|
|
If A is equal to B (the text), then the expression is |
117 |
|
|
true. |
118 |
|
|
|
119 |
|
|
A ~ B |
120 |
|
|
Match A against the regular expression (perl) B. True |
121 |
|
|
if it does match, false otherwise. |
122 |
|
|
|
123 |
|
|
EXAMPLE |
124 |
|
|
|
125 |
|
|
|
126 |
|
|
|
127 |
|
|
|
128 |
|
|
|
129 |
|
|
|
130 |
|
|
|
131 |
|
|
|
132 |
|
|
|
133 |
|
|
#if ##ELEMENT## = ruler |
134 |
|
|
<HR> |
135 |
|
|
#elif ##ELEMENT## = buttons |
136 |
|
|
#ifdef ADD_URL |
137 |
|
|
<A href="##ADD_URL##">Add</A> |
138 |
|
|
#endif |
139 |
|
|
#ifdef PREV_URL |
140 |
|
|
<A href="##PREV_URL##">Prev</A> |
141 |
|
|
#endif |
142 |
|
|
#ifdef NEXT_URL |
143 |
|
|
<A href="##NEXT_URL##">Next</A> |
144 |
|
|
#endif |
145 |
|
|
</P> |
146 |
|
|
#endif |
147 |
|
|
|
148 |
|
|
PER-METHOD DOCUMENTATION |
149 |
|
|
"new($templates_dir, $suffix)" |
150 |
|
|
Create a new CPPTemplate object. $templates_dir is the |
151 |
|
|
directory where the templates are stored and $suffix |
152 |
|
|
is a text to append to the file-names. |
153 |
|
|
|
154 |
|
|
"template(\%vars)" |
155 |
|
|
Return a processed template. "\%vars" is a hashref |
156 |
|
|
containing the variables used for building the |
157 |
|
|
file-name, for the substitutions and the CPP-style |
158 |
|
|
directives. |
159 |
|
|
|
160 |
|
|
SEE ALSO |
161 |
|
|
Text::TagTemplate(3) |
162 |
|
|
|
163 |
|
|
COPYRIGHT |
164 |
|
|
Copyright (c) 2000 ETH Zurich, All rights reserved. |
165 |
|
|
|
166 |
|
|
LICENSE |
167 |
|
|
This program is free software; you can redistribute it |
168 |
|
|
and/or modify it under the terms of the GNU General Public |
169 |
|
|
License as published by the Free Software Foundation; |
170 |
|
|
either version 2 of the License, or (at your option) any |
171 |
|
|
later version. |
172 |
|
|
|
173 |
|
|
This program is distributed in the hope that it will be |
174 |
|
|
useful, but WITHOUT ANY WARRANTY; without even the implied |
175 |
|
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR |
176 |
|
|
PURPOSE. See the GNU General Public License for more |
177 |
|
|
details. |
178 |
|
|
|
179 |
|
|
You should have received a copy of the GNU General Public |
180 |
|
|
License along with this program; if not, write to the Free |
181 |
|
|
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA |
182 |
|
|
02139, USA. This library is free software; you can redis- |
183 |
|
|
tribute it and/or modify it under the terms of the GNU |
184 |
|
|
Lesser General Public License as published by the Free |
185 |
|
|
Software Foundation; either version 2.1 of the License, or |
186 |
|
|
(at your option) any later version. |
187 |
|
|
|
188 |
|
|
AUTHOR |
189 |
|
|
David Schweikert <dws@ee.ethz.ch>, Tobi Oetiker |
190 |
|
|
<oetiker@ee.ethz.ch> |
191 |
|
|
|
192 |
|
|
|
193 |
|
|
|
194 |
|
|
0.3 2000-10-22 Text::CPPTemplate(3) |