1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "Template::Plugin::URL 3"
132 .TH Template::Plugin::URL 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
134 Template::Plugin::URL \- Plugin to construct complex URLs
136 .IX Header "SYNOPSIS"
138 \& [% USE url('/cgi\-bin/foo.pl') %]
142 \& [% url(debug = 1, id = 123) %]
143 \& # ==> /cgi/bin/foo.pl?debug=1&id=123
147 \& [% USE mycgi = url('/cgi\-bin/bar.pl', mode='browse', debug=1) %]
152 \& # ==> /cgi/bin/bar.pl?mode=browse&debug=1
156 \& [% mycgi(mode='submit') %]
157 \& # ==> /cgi/bin/bar.pl?mode=submit&debug=1
161 \& [% mycgi(debug='d2 p0', id='D4\-2k[4]') %]
162 \& # ==> /cgi\-bin/bar.pl?mode=browse&debug=d2%20p0&id=D4\-2k%5B4%5D
165 .IX Header "DESCRIPTION"
166 The \f(CW\*(C`URL\*(C'\fR plugin can be used to construct complex URLs from a base stem
167 and a hash array of additional query parameters.
169 The constructor should be passed a base \s-1URL\s0 and optionally, a hash array
170 reference of default parameters and values. Used from with a template,
171 it would look something like the following:
174 \& [% USE url('http://www.somewhere.com/cgi\-bin/foo.pl') %]
175 \& [% USE url('/cgi\-bin/bar.pl', mode='browse') %]
176 \& [% USE url('/cgi\-bin/baz.pl', mode='browse', debug=1) %]
179 When the plugin is then called without any arguments, the default base
180 and parameters are returned as a formatted query string.
186 For the above three examples, these will produce the following outputs:
189 \& http://www.somewhere.com/cgi\-bin/foo.pl
190 \& /cgi\-bin/bar.pl?mode=browse
191 \& /cgi\-bin/baz.pl?mode=browse&debug=1
194 Note that additional parameters are separated by '\f(CW\*(C`&\*(C'\fR' rather than
195 simply '\f(CW\*(C`&\*(C'\fR'. This is the correct behaviour for \s-1HTML\s0 pages but is,
196 unfortunately, incorrect when creating URLs that do not need to be
197 encoded safely for \s-1HTML\s0. This is likely to be corrected in a future
198 version of the plugin (most probably with \s-1TT3\s0). In the mean time, you
199 can set \f(CW$Template::Plugin::URL::JOINT\fR to \f(CW\*(C`&\*(C'\fR to get the correct
202 Additional parameters may be also be specified to the \s-1URL:\s0
205 \& [% url(mode='submit', id='wiz') %]
208 Which, for the same three examples, produces:
211 \& http://www.somewhere.com/cgi\-bin/foo.pl?mode=submit&id=wiz
212 \& /cgi\-bin/bar.pl?mode=browse&id=wiz
213 \& /cgi\-bin/baz.pl?mode=browse&debug=1&id=wiz
216 A new base \s-1URL\s0 may also be specified as the first option:
219 \& [% url('/cgi\-bin/waz.pl', test=1) %]
225 \& /cgi\-bin/waz.pl?test=1
226 \& /cgi\-bin/waz.pl?mode=browse&test=1
227 \& /cgi\-bin/waz.pl?mode=browse&debug=1&test=1
230 The ordering of the parameters is non-deterministic due to fact that
231 Perl's hashes themselves are unordered. This isn't a problem as the
232 ordering of \s-1CGI\s0 parameters is insignificant (to the best of my knowledge).
233 All values will be properly escaped thanks to some code borrowed from
234 Lincoln Stein's \f(CW\*(C`CGI\*(C'\fR module. e.g.
237 \& [% USE url('/cgi\-bin/woz.pl') %]
238 \& [% url(name="Elrich von Benjy d'Weiro") %]
241 Here the spaces and "\f(CW\*(C`'\*(C'\fR" character are escaped in the output:
244 \& /cgi\-bin/woz.pl?name=Elrich%20von%20Benjy%20d%27Weiro
247 An alternate name may be provided for the plugin at construction time
248 as per regular Template Toolkit syntax.
251 \& [% USE mycgi = url('cgi\-bin/min.pl') %]
252 \& [% mycgi(debug=1) %]
256 Andy Wardley <abw@wardley.org> <http://wardley.org/>
258 .IX Header "COPYRIGHT"
259 Copyright (C) 1996\-2007 Andy Wardley. All Rights Reserved.
261 This module is free software; you can redistribute it and/or
262 modify it under the same terms as Perl itself.
264 .IX Header "SEE ALSO"