1CGI::Ex(3) User Contributed Perl Documentation CGI::Ex(3)
2
6 CGI::Ex - CGI utility suite - makes powerful application writing fun
7 and easy
8
10 ### You probably don't want to use CGI::Ex directly
11 ### You probably should use CGI::Ex::App instead.
12 my $cgix = CGI::Ex->new;
14 $cgix->print_content_type;
16 my $hash = $cgix->form;
18 if ($hash->{'bounce'}) {
20 $cgix->set_cookie({
22 name => ...,
23 value => ...,
24 });
25 $cgix->location_bounce($new_url_location);
27 exit;
28 }
29 if (scalar keys %$form) {
31 my $val_hash = $cgix->conf_read($pathtovalidation);
32 my $err_obj = $cgix->validate($hash, $val_hash);
33 if ($err_obj) {
34 my $errors = $err_obj->as_hash;
35 my $input = "Some content";
36 my $content = "";
37 $cgix->swap_template(\$input, $errors, $content);
38 $cgix->fill({text => \$content, form => $hashref});
39 print $content;
40 exit;
41 } else {
42 print "Success";
43 }
44 } else {
45 print "Main page";
46 }
47
49 CGI::Ex provides a suite of utilities to make writing CGI scripts more
50 enjoyable. Although they can all be used separately, the main func‐
51 tionality of each of the modules is best represented in the
52 CGI::Ex::App module. CGI::Ex::App takes CGI application building to
53 the next step. CGI::Ex::App is not quite a framework (which normally
54 includes pre-built html) instead CGI::Ex::App is an extended applica‐
55 tion flow that dramatically reduces CGI build time in most cases. It
56 does so using as little magic as possible. See CGI::Ex::App.
57 The main functionality is provided by several other modules that may be
59 used separately, or together through the CGI::Ex interface.
60 "CGI::Ex::Template"
62 A Template::Toolkit compatible processing engine. With a few limi‐
63 tations, CGI::Ex::Template can be a drop in replacement for Tem‐
64 plate::Toolkit.
65 "CGI::Ex::Fill"
67 A regular expression based form filler inner (accessed through
68 ->fill or directly via its own functions). Can be a drop in
69 replacement for HTML::FillInForm. See CGI::Ex::Fill for more
70 information.
71 "CGI::Ex::Validate"
73 A form field / cgi parameter / any parameter validator (accessed
74 through ->validate or directly via its own methods). Not quite a
75 drop in for most validators, although it has most of the function‐
76 ality of most of the validators but with the key additions of con‐
77 ditional validation. Has a tightly integrated JavaScript portion
78 that allows for duplicate client side validation. See
79 CGI::Ex::Validate for more information.
80 "CGI::Ex::Conf"
82 A general use configuration, or settings, or key / value file
83 reader. Has ability for providing key fallback as well as
84 immutable key definitions. Has default support for yaml, storable,
85 perl, ini, and xml and open architecture for definition of others.
86 See CGI::Ex::Conf for more information.
87 "CGI::Ex::Auth"
89 A highly configurable web based authentication system. See
90 CGI::Ex::Auth for more information.
91
93 "->fill"
94 fill is used for filling hash or cgi object values into an existing
95 html document (it doesn't deal at all with how you got the docu‐
96 ment). Arguments may be given as a hash, or a hashref or posi‐
97 tional. Some of the following arguments will only work using
98 CGI::Ex::Fill - most will work with either CGI::Ex::Fill or
99 HTML::FillInForm (assume they are available unless specified other‐
100 wise). (See CGI::Ex::Fill for a full explanation of functional‐
101 ity). The arguments to fill are as follows (and in order of posi‐
102 tion):
103 "text"
105 Text should be a reference to a scalar string containing the
106 html to be modified (actually it could be any reference or
107 object reference that can be modified as a string). It will be
108 modified in place. Another named argument scalarref is avail‐
109 able if you would like to copy rather than modify.
110 "form"
112 Form may be a hashref, a cgi style object, a coderef, or an
113 array of multiple hashrefs, cgi objects, and coderefs. Hashes
114 should be key value pairs. CGI objects should be able to call
115 the method param (This can be overrided). Coderefs should
116 expect the field name as an argument and should return a value.
117 Values returned by form may be undef, scalar, arrayref, or
118 coderef (coderef values should expect an argument of field name
119 and should return a value). The code ref options are available
120 to delay or add options to the bringing in of form information
121 - without having to tie the hash. Coderefs are not available
122 in HTML::FillInForm. Also HTML::FillInForm only allows CGI
123 objects if an arrayref is used.
124 NOTE: Only one of the form, fdat, and fobject arguments are
126 allowed at a time.
127 "target"
129 The name of the form that the fields should be filled to. The
130 default value of undef, means to fill in all forms in the html.
131 "fill_passwords"
133 Boolean value defaults to 1. If set to zero - password fields
134 will not be filled.
135 "ignore_fields"
137 Specify which fields to not fill in. It takes either array ref
138 of names, or a hashref with the names as keys. The hashref
139 option is not available in CGI::Ex::Fill.
140 Other named arguments are available for compatibility with
142 HTML::FillInForm. They may only be used as named arguments.
143 "scalarref"
145 Almost the same as the argument text. If scalarref is used,
146 the filled html will be returned. If text is used the html
147 passed is filled in place.
148 "arrayref"
150 An array ref of lines of the document. Forces a returned
151 filled html document.
152 "file"
154 An filename that will be opened, filled, and returned.
155 "fdat"
157 A hashref of key value pairs.
158 "fobject"
160 A cgi style object or arrayref of cgi style objects used for
161 getting the key value pairs. Should be capable of the ->param
162 method and ->cookie method as document in CGI.
163 See CGI::Ex::Fill for more information about the filling process.
165 "->object"
167 Returns the CGI object that is currently being used by CGI::Ex. If
168 none has been set it will automatically generate an object of type
169 $PREFERRED_CGI_MODULE which defaults to CGI.
170 "->validate"
172 Validate has a wide range of options available. (See CGI::Ex::Vali‐
173 date for a full explanation of functionality). Validate has two
174 arguments:
175 "form"
177 Can be either a hashref to be validated, or a CGI style object
178 (which has the param method).
179 "val_hash"
181 The val_hash can be one of three items. First, it can be a
182 straight perl hashref containing the validation to be done.
183 Second, it can be a YAML document string. Third, it can be the
184 path to a file containing the validation. The validation in a
185 validation file will be read in depending upon file extension.
186 "->get_form"
188 Very similar to CGI->new->Vars except that arrays are returned as
189 arrays. Not sure why CGI didn't do this anyway (well - yes -
190 legacy Perl 4 - but at some point things need to be updated).
191 my $hash = $cgix->get_form;
193 my $hash = $cgix->get_form(CGI->new);
194 my $hash = get_form();
195 my $hash = get_form(CGI->new);
196 "->set_form"
198 Allow for setting a custom form hash. Useful for testing, or other
199 purposes.
200 $cgix->set_form(\%new_form);
202 "->get_cookies"
204 Returns a hash of all cookies.
205 my $hash = $cgix->get_cookies;
207 my $hash = $cgix->get_cookies(CGI->new);
208 my $hash = get_cookies();
209 my $hash = get_cookies(CGI->new);
210 "->set_cookies"
212 Allow for setting a custom cookies hash. Useful for testing, or
213 other purposes.
214 $cgix->set_cookies(\%new_cookies);
216 "->make_form"
218 Takes a hash and returns a query_string. A second optional argu‐
219 ment may contain an arrayref of keys to use from the hash in build‐
220 ing the query_string. First argument is undef, it will use the
221 form stored in itself as the hash.
222 "->content_type"
224 Can be called multiple times during the same session. Will only
225 print content-type once. (Useful if you don't know if something
226 else already printed content-type). Calling this sends the Con‐
227 tent-type header. Trying to print ->content_type is an error. For
228 clarity, the method ->print_content_type is available.
229 $cgix->print_content_type;
231 # OR
233 $cgix->print_content_type('text/html');
234 # OR
236 $cgix->print_content_type('text/html', 'utf-8');
237 "->set_cookie"
239 Arguments are the same as those to CGI->new->cookie({}). Uses
240 CGI's cookie method to create a cookie, but then, depending on if
241 content has already been sent to the browser will either print a
242 Set-cookie header, or will add a <meta http-equiv='set-cookie'> tag
243 (this is supported on most major browsers). This is useful if you
244 don't know if something else already printed content-type.
245 "->location_bounce"
247 Depending on if content has already been sent to the browser will
248 either print a Location header, or will add a <meta
249 http-equiv='refresh'> tag (this is supported on all major
250 browsers). This is useful if you don't know if something else
251 already printed content-type. Takes single argument of a url.
252 "->last_modified"
254 Depending on if content has already been sent to the browser will
255 either print a Last-Modified header, or will add a <meta
256 http-equiv='Last-Modified'> tag (this is supported on most major
257 browsers). This is useful if you don't know if something else
258 already printed content-type. Takes an argument of either a time
259 (may be a CGI -expires style time) or a filename.
260 "->expires"
262 Depending on if content has already been sent to the browser will
263 either print a Expires header, or will add a <meta
264 http-equiv='Expires'> tag (this is supported on most major
265 browsers). This is useful if you don't know if something else
266 already printed content-type. Takes an argument of a time (may be
267 a CGI -expires style time).
268 "->send_status"
270 Send a custom status. Works in both CGI and mod_perl. Arguments
271 are a status code and the content (optional).
272 "->send_header"
274 Send a http header. Works in both CGI and mod_perl. Arguments are
275 a header name and the value for that header.
276 "->print_js"
278 Prints out a javascript file. Does everything it can to make sure
279 that the javascript will cache. Takes either a full filename, or a
280 shortened name which will be looked for in @INC. (ie
281 /full/path/to/my.js or CGI/Ex/validate.js or CGI::Ex::validate)
282 "->swap_template"
284 This is intended as a simple yet strong subroutine to swap in tags
285 to a document. It is intended to be very basic for those who may
286 not want the full features of a Templating system such as Tem‐
287 plate::Toolkit (even though they should investigate them because
288 they are pretty nice). The default allows for basic template tool‐
289 kit variable swapping. There are two arguments. First is a string
290 or a reference to a string. If a string is passed, a copy of that
291 string is swapped and returned. If a reference to a string is
292 passed, it is modified in place. The second argument is a form, or
293 a CGI object, or a cgiex object, or a coderef (if the second argu‐
294 ment is missing, the cgiex object which called the method will be
295 used). If it is a coderef, it should accept key as its only argu‐
296 ment and return the proper value.
297 my $cgix = CGI::Ex->new;
299 my $form = {foo => 'bar',
300 this => {is => {nested => ['wow', 'wee']}}
301 };
302 my $str = $cgix->swap_template("<html>[% foo %]<br>[% foo %]</html>", $form));
304 # $str eq '<html>bar<br>bar</html>'
305 $str = $cgix->swap_template("[% this.is.nested.1 %]", $form));
307 # $str eq 'wee'
308 $str = "[% this.is.nested.0 %]";
310 $cgix->swap_template(\$str, $form);
311 # $str eq 'wow'
312 # may also be called with only one argument as follows:
314 # assuming $cgix had a query string of ?foo=bar&baz=wow&this=wee
315 $str = "<html>([% foo %]) <br>
316 ([% baz %]) <br>
317 ([% this %]) </html>";
318 $cgix->swap_template(\$str);
319 #$str eq "<html>(bar) <br>
320 # (wow) <br>
321 # (wee) </html>";
322 For further examples, please see the code contained in t/sam‐
324 ples/cgi_ex_* of this distribution.
325 If at a later date, the developer upgrades to Template::Toolkit,
327 the templates that were being swapped by CGI::Ex::swap_template
328 should be compatible with Template::Toolkit.
329
331 See also CGI::Ex::App.
332 See also CGI::Ex::Auth.
334 See also CGI::Ex::Conf.
336 See also CGI::Ex::Die.
338 See also CGI::Ex::Dump.
340 See also CGI::Ex::Fill.
342 See also CGI::Ex::Template.
344 See also CGI::Ex::Validate.
346
348 This module may be distributed under the same terms as Perl itself.
349
351 Paul Seamons <perl at seamons dot com>
352perl v5.8.8 2007-10-18 CGI::Ex(3)