1Expr(3) User Contributed Perl Documentation Expr(3)
2
6 HTML::Template::Expr - HTML::Template extension adding expression sup‐
7 port
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 opera‐
23 tions and a mechanism to allow you add your own functions at runtime.
24 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. How‐
44 ever, I realize that there are some situations where allowing the tem‐
45 plate 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 * <
86 * >
87 * ==
88 * !=
89 * >=
90 * <=
91 * <=>
92 * String Comparisons
93 * gt
94 * lt
95 * eq
96 * ne
97 * ge
98 * le
99 * cmp
100
102 The basic operators are supported:
103 * +
105 * -
106 * *
107 * /
108 * %
109 There are also some mathy functions. See the FUNCTIONS section below.
111
113 Boolean logic is available:
114 * && (synonym: and)
116 * ⎪⎪ (synonym: or)
117
119 The following functions are available to be used in expressions. See
120 perldoc perlfunc for details.
121 * sprintf
123 * substr (2 and 3 arg versions only)
124 * lc
125 * lcfirst
126 * uc
127 * ucfirst
128 * length
129 * defined
130 * abs
131 * atan2
132 * cos
133 * exp
134 * hex
135 * int
136 * log
137 * oct
138 * rand
139 * sin
140 * sqrt
141 * srand
142 All functions must be called using full parenthesis. For example, this
144 is a syntax error:
145 <TMPL_IF expr="defined foo">
147 But this is good:
149 <TMPL_IF expr="defined(foo)">
151
153 To define a new function, pass a "functions" option to new:
154 $t = HTML::Template::Expr->new(filename => 'foo.tmpl',
156 functions =>
157 { func_name => \&func_handler });
158 Or, you can use "register_function" class method to register the func‐
160 tion globally:
161 HTML::Template::Expr->register_function(func_name => \&func_handler);
163 You provide a subroutine reference that will be called during output.
165 It will recieve as arguments the parameters specified in the template.
166 For example, here's a function that checks if a directory exists:
167 sub directory_exists {
169 my $dir_name = shift;
170 return 1 if -d $dir_name;
171 return 0;
172 }
173 If you call HTML::Template::Expr->new() with a "functions" arg:
175 $t = HTML::Template::Expr->new(filename => 'foo.tmpl',
177 functions => {
178 directory_exists => \&directory_exists
179 });
180 Then you can use it in your template:
182 <tmpl_if expr="directory_exists('/home/sam')">
184 This can be abused in ways that make my teeth hurt.
186
188 "register_function" class method can be called in mod_perl's startup.pl
189 to define widely used common functions to HTML::Template::Expr. Add
190 something like this to your startup.pl:
191 use HTML::Template::Expr;
193 HTML::Template::Expr->register_function(foozicate => sub { ... });
195 HTML::Template::Expr->register_function(barify => sub { ... });
196 HTML::Template::Expr->register_function(baznate => sub { ... });
197 You might also want to pre-compile some commonly used templates and
199 cache them. See HTML::Template's FAQ for instructions.
200
202 Currently the module forces the HTML::Template global_vars option to be
203 set. This will hopefully go away in a future version, so if you need
204 global_vars in your templates then you should set it explicitely.
205 The module won't work with HTML::Template's file_cache or shared_cache
207 modes, but normal memory caching should work. I hope to address this
208 is a future version.
209 The module is inefficient, both in parsing and evaluation. I'll be
211 working on this for future versions and patches are always welcome.
212
214 I am aware of no bugs - if you find one, join the mailing list and tell
215 us about it. You can join the HTML::Template mailing-list by visiting:
216 http://lists.sourceforge.net/lists/listinfo/html-template-users
218 Of course, you can still email me directly (sam@tregar.com) with bugs,
220 but I reserve the right to forward bug reports to the mailing list.
221 When submitting bug reports, be sure to include full details, including
223 the VERSION of the module, a test script and a test template demon‐
224 strating the problem!
225
227 The following people have generously submitted bug reports, patches and
228 ideas:
229 Peter Leonard
231 Tatsuhiko Miyagawa
232 Don Brodale
233 Thanks!
235
237 Sam Tregar <sam@tregar.com>
238
240 HTML::Template::Expr : HTML::Template extension adding expression sup‐
241 port
242 Copyright (C) 2001 Sam Tregar (sam@tregar.com)
244 This module is free software; you can redistribute it and/or modify it
246 under the terms of either:
247 a) the GNU General Public License as published by the Free Software
249 Foundation; either version 1, or (at your option) any later version, or
250 b) the "Artistic License" which comes with this module.
252 This program is distributed in the hope that it will be useful, but
254 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
255 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU
256 General Public License or the Artistic License for more details.
257 You should have received a copy of the Artistic License with this mod‐
259 ule, in the file ARTISTIC. If not, I'll be glad to provide one.
260 You should have received a copy of the GNU General Public License along
262 with this program; if not, write to the Free Software Foundation, Inc.,
263 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
264perl v5.8.8 2006-04-18 Expr(3)