1Expr(3) User Contributed Perl Documentation Expr(3)
2
6 HTML::Template::Expr - HTML::Template extension adding expression
7 support
8
10 use HTML::Template::Expr;
11 my $template = HTML::Template::Expr->new(filename => 'foo.tmpl');
13 $template->param(banana_count => 10);
14 print $template->output();
15
17 This module provides an extension to HTML::Template which allows
18 expressions in the template syntax. This is purely an addition - all
19 the normal HTML::Template options, syntax and behaviors will still
20 work. See HTML::Template for details.
21 Expression support includes comparisons, math operations, string
23 operations and a mechanism to allow you add your own functions at
24 runtime. The basic syntax is:
25 <TMPL_IF EXPR="banana_count > 10">
27 I've got a lot of bananas.
28 </TMPL_IF>
29 This will output "I've got a lot of bananas" if you call:
31 $template->param(banana_count => 100);
33 In your script. <TMPL_VAR>s also work with expressions:
35 I'd like to have <TMPL_VAR EXPR="banana_count * 2"> bananas.
37 This will output "I'd like to have 200 bananas." with the same param()
39 call as above.
40
42 Some of you may wonder if I've been replaced by a pod person. Just for
43 the record, I still think this sort of thing should be avoided.
44 However, I realize that there are some situations where allowing the
45 template author some programatic leeway can be invaluable.
46 If you don't like it, don't use this module. Keep using plain ol'
48 HTML::Template - I know I will! However, if you find yourself needing
49 a little programming in your template, for whatever reason, then this
50 module may just save you from HTML::Mason.
51
53 Variables are unquoted alphanumeric strings with the same restrictions
54 as variable names in HTML::Template. Their values are set through
55 param(), just like normal HTML::Template variables. For example, these
56 two lines are equivalent:
57 <TMPL_VAR EXPR="foo">
59 <TMPL_VAR NAME="foo">
61 Numbers are unquoted strings of numbers and may have a single "." to
63 indicate a floating point number. For example:
64 <TMPL_VAR EXPR="10 + 20.5">
66 String constants must be enclosed in quotes, single or double. For
68 example:
69 <TMPL_VAR EXPR="sprintf('%d', foo)">
71 You can string together operators to produce complex booleans:
73 <TMPL_IF EXPR="(foo || bar || baz || (bif && bing) || (bananas > 10))">
75 I'm in a complex situation.
76 </TMPL_IF>
77 The parser is pretty simple, so you may need to use parenthesis to get
79 the desired precedence.
80
82 Here's a list of supported comparison operators:
83 · Numeric Comparisons
85 · <
87 · >
89 · ==
91 · !=
93 · >=
95 · <=
97 · <=>
99 · String Comparisons
101 · gt
103 · lt
105 · eq
107 · ne
109 · ge
111 · le
113 · cmp
115
117 The basic operators are supported:
118 · +
120 · -
122 · *
124 · /
126 · %
128 There are also some mathy functions. See the FUNCTIONS section below.
130
132 Boolean logic is available:
133 · && (synonym: and)
135 · || (synonym: or)
137
139 The following functions are available to be used in expressions. See
140 perldoc perlfunc for details.
141 · sprintf
143 · substr (2 and 3 arg versions only)
145 · lc
147 · lcfirst
149 · uc
151 · ucfirst
153 · length
155 · defined
157 · abs
159 · atan2
161 · cos
163 · exp
165 · hex
167 · int
169 · log
171 · oct
173 · rand
175 · sin
177 · sqrt
179 · srand
181 All functions must be called using full parenthesis. For example, this
183 is a syntax error:
184 <TMPL_IF expr="defined foo">
186 But this is good:
188 <TMPL_IF expr="defined(foo)">
190
192 To define a new function, pass a "functions" option to new:
193 $t = HTML::Template::Expr->new(filename => 'foo.tmpl',
195 functions =>
196 { func_name => \&func_handler });
197 Or, you can use "register_function" class method to register the
199 function globally:
200 HTML::Template::Expr->register_function(func_name => \&func_handler);
202 You provide a subroutine reference that will be called during output.
204 It will recieve as arguments the parameters specified in the template.
205 For example, here's a function that checks if a directory exists:
206 sub directory_exists {
208 my $dir_name = shift;
209 return 1 if -d $dir_name;
210 return 0;
211 }
212 If you call HTML::Template::Expr->new() with a "functions" arg:
214 $t = HTML::Template::Expr->new(filename => 'foo.tmpl',
216 functions => {
217 directory_exists => \&directory_exists
218 });
219 Then you can use it in your template:
221 <tmpl_if expr="directory_exists('/home/sam')">
223 This can be abused in ways that make my teeth hurt.
225
227 "register_function" class method can be called in mod_perl's startup.pl
228 to define widely used common functions to HTML::Template::Expr. Add
229 something like this to your startup.pl:
230 use HTML::Template::Expr;
232 HTML::Template::Expr->register_function(foozicate => sub { ... });
234 HTML::Template::Expr->register_function(barify => sub { ... });
235 HTML::Template::Expr->register_function(baznate => sub { ... });
236 You might also want to pre-compile some commonly used templates and
238 cache them. See HTML::Template's FAQ for instructions.
239
241 Currently the module forces the HTML::Template global_vars option to be
242 set. This will hopefully go away in a future version, so if you need
243 global_vars in your templates then you should set it explicitely.
244 The module won't work with HTML::Template's file_cache or shared_cache
246 modes, but normal memory caching should work. I hope to address this
247 is a future version.
248 The module is inefficient, both in parsing and evaluation. I'll be
250 working on this for future versions and patches are always welcome.
251
253 I am aware of no bugs - if you find one, join the mailing list and tell
254 us about it. You can join the HTML::Template mailing-list by visiting:
255 http://lists.sourceforge.net/lists/listinfo/html-template-users
257 Of course, you can still email me directly (sam@tregar.com) with bugs,
259 but I reserve the right to forward bug reports to the mailing list.
260 When submitting bug reports, be sure to include full details, including
262 the VERSION of the module, a test script and a test template
263 demonstrating the problem!
264
266 The following people have generously submitted bug reports, patches and
267 ideas:
268 Peter Leonard
270 Tatsuhiko Miyagawa
271 Don Brodale
272 Thanks!
274
276 Sam Tregar <sam@tregar.com>
277
279 HTML::Template::Expr : HTML::Template extension adding expression
280 support
281 Copyright (C) 2001 Sam Tregar (sam@tregar.com)
283 This module is free software; you can redistribute it and/or modify it
285 under the terms of either:
286 a) the GNU General Public License as published by the Free Software
288 Foundation; either version 1, or (at your option) any later version, or
289 b) the "Artistic License" which comes with this module.
291 This program is distributed in the hope that it will be useful, but
293 WITHOUT ANY WARRANTY; without even the implied warranty of
294 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the
295 GNU General Public License or the Artistic License for more details.
296 You should have received a copy of the Artistic License with this
298 module, in the file ARTISTIC. If not, I'll be glad to provide one.
299 You should have received a copy of the GNU General Public License along
301 with this program; if not, write to the Free Software Foundation, Inc.,
302 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
303
305 Hey! The above document had some coding errors, which are explained
306 below:
307 Around line 496:
309 =back doesn't take any parameters, but you said =back 4
310 Around line 516:
312 =back doesn't take any parameters, but you said =back 4
313 Around line 518:
315 =back doesn't take any parameters, but you said =back 4
316 Around line 536:
318 =back doesn't take any parameters, but you said =back 4
319 Around line 550:
321 =back doesn't take any parameters, but you said =back 4
322 Around line 599:
324 =back doesn't take any parameters, but you said =back 4
325perl v5.12.0 2006-04-18 Expr(3)