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