README
1NAME
2 Petal::Utils - Useful template modifiers for Petal.
3
4SYNOPSIS
5 # install the default set of Petal modifiers:
6 use Petal::Utils;
7
8 # you can also install modifiers manually:
9 Petal::Utils->install( 'some_modifier', ':some_set' );
10
11 # see below for modifiers available & template syntax
12
13DESCRIPTION
14 The Petal::Utils package contains commonly used Petal modifiers (or
15 plugins), and bundles them with an easy-to-use installation interface.
16 By default, a set of modifiers are installed into Petal when you use
17 this module. You can change which modifiers are installed by naming them
18 after the use statement:
19
20 # use the default set:
21 use Petal::Utils qw( :default );
22
23 # use the date set of modifiers:
24 use Petal::Utils qw( :date );
25
26 # use only named modifiers, plus the debug set:
27 use Petal::Utils qw( UpperCase Date :debug );
28
29 # don't install any modifiers
30 use Petal::Utils qw();
31
32 You'll find a list of plugin sets throughout this document. You can also
33 get a complete list by looking at the variable:
34
35 %Petal::Utils::PLUGIN_SET;
36
37 For details on how the plugins are installed, see the "Advanced Petal"
38 section of the Petal documentation.
39
40MODIFIERS
41 Each modifier is listed under the set it belongs to.
42
43 :text
44 lowercase:, lc: $string
45 Make the entire string lowercase.
46
47 <p tal:content="lc: $string">lower</p>
48
49 uppercase:, uc: $string
50 Make the entire string uppercase.
51
52 <p tal:content="uc: $string">upper</p>
53
54 uc_first: $string
55 Make the first letter of the string uppercase.
56
57 <p tal:content="uc_first: $string">uc_first</p>
58
59 substr: $string [offset] [length] [ellipsis]
60 Extract a substring from a string. Optionally add an ellipsis (...)
61 to the end. See also, perldoc -f substr.
62
63 <span petal:content="substr:$str">string</span> # does nothing
64 <span petal:content="substr:$str 2">string</span> # cuts the first two chars
65 <span petal:content="substr:$str 2 5">string</span> # extracts chars 2-7
66 <span petal:content="substr:$str 2 5 1">string with ellipsis</span> # same as above and adds an ellipsis
67
68 printf: format list
69 The printf modifier acts exactly like Perl's sprintf function to
70 print formatted strings.
71
72 <p petal:content="printf:'%s' 'Astro'">Astro</p>
73 <p petal:content="printf:'$%0.2f' '2.5'">$2.50</p>
74
75 :date
76 date: $date
77 Convert a time() integer to a date string using Date::Format.
78
79 <span tal:replace="date: $date">Jan 1 1970 01:00:01</span>
80
81 us_date: $date
82 Convert an international date stamp (e.g., yyyymmdd, yyyy-mm-dd,
83 yyyy/mm/dd) to US format (mm/dd/yyyy).
84
85 <p tal:content="us_date: $date">2003-09-05</p>
86
87 :logic
88 if: $expr1 then: $expr2 else: $expr3
89 Do an if/then/else test and return the value of the expression
90 executed. Truthfulness of $expr1 is according to Perl (e.g.,
91 non-zero, non-empty string).
92
93 <p tal:attributes="class if: on_a_page then: a_class else: another_class">
94 Some text here...
95 </p>
96
97 or: $expr1 $expr2
98 Do a logical or. Truthfulness is according to Perl (e.g., non-zero,
99 non-empty string).
100
101 <p tal:if="or: $first $second">
102 first or second = <span tal:replace="or: $first $second">or</span>
103 </p>
104
105 and: $expr1 $expr2
106 Do a logical and. Truthfulness is according to Perl (e.g., non-zero,
107 non-empty string).
108
109 first and second = <span tal:replace="and: $first $second">and</span>
110
111 equal:, eq: $expr1 $expr2
112 Test for equality. Numbers are compared with "==", strings with
113 "eq". Truthfulness is according to Perl (e.g., non-zero, non-empty
114 string).
115
116 first eq second = <span tal:replace="eq: $first $second">equal</span>
117
118 like: $expr $regex
119 Test for equality to a regular expression (see perlre).
120
121 name like regex = <span tal:replace="like: $name ^Will.+m">like</span>
122
123 decode, decode: expression search result [search result]... [default]
124 The decode function has the functionality of an IF-THEN-ELSE
125 statement. A case-sensitive regex comparison is performed. All text
126 strings must be enclosed in single quotes.
127
128 'expression' is the value to compare.
129 'search' is the value that is compared against expression.
130 'result' is the value returned, if expression is equal to search.
131 'default. is optional. If no matches are found, the decode will return
132 default. If default is omitted, then the decode statement will return
133 null (if no matches are found).
134
135 <p petal:content="decode:$str 'dog' 'Satchel'">100</p> # if $str = dog, returns Satchel
136 <p petal:content="decode:$str 'cat' 'Buckey' 'Satchel'">Astro</p> # if $str = cat, returns Buckey, else Satchel
137
138 :list
139 sort: $list
140 Sort the values in a list before returning it.
141
142 <ul>
143 <li tal:repeat="item sort: $array_ref">$item</li>
144 </ul>
145
146 limit: $list count
147 Limit the values in a list before returning it.
148
149 <ul>
150 <li tal:repeat="item limit: $array_ref 2">$item</li>
151 </ul>
152
153 limitr: $list count
154 Shuffle the list then limit the returned values to the specified
155 count.
156
157 <ul>
158 <li tal:repeat="item limitr: $array_ref 2">$item</li>
159 </ul>
160
161 :hash
162 keys: $hash
163 Return a list of keys for a hashref. Note: It appears that values
164 cannot be accessed with dynamic keys. If you need the keys and
165 values, use "each:".
166
167 <ul>
168 <li tal:repeat="key keys: $hash_ref"><span tal:replace="key">key</span></li>
169 </ul>
170
171 each: $hash
172 Return a list of key/value pairs for a hashref.
173
174 <ul>
175 <li tal:repeat="item each: $hash_ref">
176 <span tal:replace="item/key">key</span> => <span tal:replace="item/val">value</span>
177 </li>
178 </ul>
179
180 :uri
181 uri_escape: $expr
182 Use URI::Escape's uri_escape() to escape the return value of the
183 expression.
184
185 <a href="http://foo/get.html?item=${uri_escape: item/key}">get $item/key</a>
186
187 create_href: $url [protocol]
188 Creates an absolute uri from a url with the given protocol (e.g.,
189 http, ftp -- do not include the protocol separators). If the url
190 does not have the protocol included, it will be appended. If no
191 protocol is given, 'http' will be used.
192
193 <a petal:attr="href create_href:$url">HTTP Link</a>
194 <a petal:attr="href create_href:$url ftp">FTP Link</a>
195
196 :debug
197 dump: $expr
198 Dump the data strcture of the value given.
199
200 dump name: <span tal:replace="dump: name">dump</span>
201
202SUPERSETS
203 At the time of writing, the following supersets were available:
204
205 ':none' => [],
206 ':all' => [qw( :default :hash :debug )],
207 ':default' => [qw( :text :date :logic :list )],
208
209 See %Petal::Utils::PLUGIN_SET for an up-to-date list.
210
211CONTRIBUTING
212 Contributions to the modifiers are welcome! You can suggest new
213 modifiers to add to the suite. You will have better luck getting your
214 modifier added by providing a module (see lib/Petal/Utils/And.pm for an
215 example), a patch to Utils.pm (with a modified PLUGIN_SET and
216 documentation for your new modifier), and a test suite. All modifiers
217 are subject to the discretion of the authors.
218
219AUTHORS
220 William McKee <william@knowmad.com>, and Steve Purkis <spurkis@cpan.org>
221
222COPYRIGHT
223 Copyright (c) 2003-2004 William McKee & Steve Purkis.
224
225 This module is free software and is distributed under the same license
226 as Perl itself. Use it at your own risk.
227
228THANKS
229 Thanks to Jean-Michel Hiver for making Petal available to the Perl
230 community.
231
232SEE ALSO
233 Petal
234
235