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
51 functionality 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
55 application flow that dramatically reduces CGI build time in most
56 cases. It does so using as little magic as possible. See
57 CGI::Ex::App.
58 The main functionality is provided by several other modules that may be
60 used separately, or together through the CGI::Ex interface.
61 "CGI::Ex::Template"
63 A Template::Toolkit compatible processing engine. With a few
64 limitations, CGI::Ex::Template can be a drop in replacement for
65 Template::Toolkit.
66 "CGI::Ex::Fill"
68 A regular expression based form filler inner (accessed through
69 ->fill or directly via its own functions). Can be a drop in
70 replacement for HTML::FillInForm. See CGI::Ex::Fill for more
71 information.
72 "CGI::Ex::Validate"
74 A form field / cgi parameter / any parameter validator (accessed
75 through ->validate or directly via its own methods). Not quite a
76 drop in for most validators, although it has most of the
77 functionality of most of the validators but with the key additions
78 of conditional validation. Has a tightly integrated JavaScript
79 portion that allows for duplicate client side validation. See
80 CGI::Ex::Validate for more information.
81 "CGI::Ex::Conf"
83 A general use configuration, or settings, or key / value file
84 reader. Has ability for providing key fallback as well as
85 immutable key definitions. Has default support for yaml, storable,
86 perl, ini, and xml and open architecture for definition of others.
87 See CGI::Ex::Conf for more information.
88 "CGI::Ex::Auth"
90 A highly configurable web based authentication system. See
91 CGI::Ex::Auth for more information.
92
94 "->fill"
95 fill is used for filling hash or cgi object values into an existing
96 html document (it doesn't deal at all with how you got the
97 document). Arguments may be given as a hash, or a hashref or
98 positional. Some of the following arguments will only work using
99 CGI::Ex::Fill - most will work with either CGI::Ex::Fill or
100 HTML::FillInForm (assume they are available unless specified
101 otherwise). (See CGI::Ex::Fill for a full explanation of
102 functionality). The arguments to fill are as follows (and in order
103 of position):
104 "text"
106 Text should be a reference to a scalar string containing the
107 html to be modified (actually it could be any reference or
108 object reference that can be modified as a string). It will be
109 modified in place. Another named argument scalarref is
110 available if you would like to copy rather than modify.
111 "form"
113 Form may be a hashref, a cgi style object, a coderef, or an
114 array of multiple hashrefs, cgi objects, and coderefs. Hashes
115 should be key value pairs. CGI objects should be able to call
116 the method param (This can be overrided). Coderefs should
117 expect the field name as an argument and should return a value.
118 Values returned by form may be undef, scalar, arrayref, or
119 coderef (coderef values should expect an argument of field name
120 and should return a value). The code ref options are available
121 to delay or add options to the bringing in of form information
122 - without having to tie the hash. Coderefs are not available
123 in HTML::FillInForm. Also HTML::FillInForm only allows CGI
124 objects if an arrayref is used.
125 NOTE: Only one of the form, fdat, and fobject arguments are
127 allowed at a time.
128 "target"
130 The name of the form that the fields should be filled to. The
131 default value of undef, means to fill in all forms in the html.
132 "fill_passwords"
134 Boolean value defaults to 1. If set to zero - password fields
135 will not be filled.
136 "ignore_fields"
138 Specify which fields to not fill in. It takes either array ref
139 of names, or a hashref with the names as keys. The hashref
140 option is not available in CGI::Ex::Fill.
141 Other named arguments are available for compatibility with
143 HTML::FillInForm. They may only be used as named arguments.
144 "scalarref"
146 Almost the same as the argument text. If scalarref is used,
147 the filled html will be returned. If text is used the html
148 passed is filled in place.
149 "arrayref"
151 An array ref of lines of the document. Forces a returned
152 filled html document.
153 "file"
155 An filename that will be opened, filled, and returned.
156 "fdat"
158 A hashref of key value pairs.
159 "fobject"
161 A cgi style object or arrayref of cgi style objects used for
162 getting the key value pairs. Should be capable of the ->param
163 method and ->cookie method as document in CGI.
164 See CGI::Ex::Fill for more information about the filling process.
166 "->object"
168 Returns the CGI object that is currently being used by CGI::Ex. If
169 none has been set it will automatically generate an object of type
170 $PREFERRED_CGI_MODULE which defaults to CGI.
171 "->validate"
173 Validate has a wide range of options available. (See
174 CGI::Ex::Validate for a full explanation of functionality).
175 Validate has two arguments:
176 "form"
178 Can be either a hashref to be validated, or a CGI style object
179 (which has the param method).
180 "val_hash"
182 The val_hash can be one of three items. First, it can be a
183 straight perl hashref containing the validation to be done.
184 Second, it can be a YAML document string. Third, it can be the
185 path to a file containing the validation. The validation in a
186 validation file will be read in depending upon file extension.
187 "->get_form"
189 Very similar to CGI->new->Vars except that arrays are returned as
190 arrays. Not sure why CGI didn't do this anyway (well - yes -
191 legacy Perl 4 - but at some point things need to be updated).
192 my $hash = $cgix->get_form;
194 my $hash = $cgix->get_form(CGI->new);
195 my $hash = get_form();
196 my $hash = get_form(CGI->new);
197 "->set_form"
199 Allow for setting a custom form hash. Useful for testing, or other
200 purposes.
201 $cgix->set_form(\%new_form);
203 "->get_cookies"
205 Returns a hash of all cookies.
206 my $hash = $cgix->get_cookies;
208 my $hash = $cgix->get_cookies(CGI->new);
209 my $hash = get_cookies();
210 my $hash = get_cookies(CGI->new);
211 "->set_cookies"
213 Allow for setting a custom cookies hash. Useful for testing, or
214 other purposes.
215 $cgix->set_cookies(\%new_cookies);
217 "->make_form"
219 Takes a hash and returns a query_string. A second optional
220 argument may contain an arrayref of keys to use from the hash in
221 building the query_string. First argument is undef, it will use
222 the form stored in itself as the hash.
223 "->content_type"
225 Can be called multiple times during the same session. Will only
226 print content-type once. (Useful if you don't know if something
227 else already printed content-type). Calling this sends the
228 Content-type header. Trying to print ->content_type is an error.
229 For clarity, the method ->print_content_type is available.
230 $cgix->print_content_type;
232 # OR
234 $cgix->print_content_type('text/html');
235 # OR
237 $cgix->print_content_type('text/html', 'utf-8');
238 "->set_cookie"
240 Arguments are the same as those to CGI->new->cookie({}). Uses
241 CGI's cookie method to create a cookie, but then, depending on if
242 content has already been sent to the browser will either print a
243 Set-cookie header, or will add a <meta http-equiv='set-cookie'> tag
244 (this is supported on most major browsers). This is useful if you
245 don't know if something else already printed content-type.
246 "->location_bounce"
248 Depending on if content has already been sent to the browser will
249 either print a Location header, or will add a <meta
250 http-equiv='refresh'> tag (this is supported on all major
251 browsers). This is useful if you don't know if something else
252 already printed content-type. Takes single argument of a url.
253 "->last_modified"
255 Depending on if content has already been sent to the browser will
256 either print a Last-Modified header, or will add a <meta
257 http-equiv='Last-Modified'> tag (this is supported on most major
258 browsers). This is useful if you don't know if something else
259 already printed content-type. Takes an argument of either a time
260 (may be a CGI -expires style time) or a filename.
261 "->expires"
263 Depending on if content has already been sent to the browser will
264 either print a Expires header, or will add a <meta
265 http-equiv='Expires'> tag (this is supported on most major
266 browsers). This is useful if you don't know if something else
267 already printed content-type. Takes an argument of a time (may be
268 a CGI -expires style time).
269 "->send_status"
271 Send a custom status. Works in both CGI and mod_perl. Arguments
272 are a status code and the content (optional).
273 "->send_header"
275 Send a http header. Works in both CGI and mod_perl. Arguments are
276 a header name and the value for that header.
277 "->print_js"
279 Prints out a javascript file. Does everything it can to make sure
280 that the javascript will cache. Takes either a full filename, or a
281 shortened name which will be looked for in @INC. (ie
282 /full/path/to/my.js or CGI/Ex/validate.js or CGI::Ex::validate)
283 #!/usr/bin/perl
285 use CGI::Ex;
286 CGI::Ex->print_js($ENV{'PATH_INFO'});
287 "->swap_template"
289 This is intended as a simple yet strong subroutine to swap in tags
290 to a document. It is intended to be very basic for those who may
291 not want the full features of a Templating system such as
292 Template::Toolkit (even though they should investigate them because
293 they are pretty nice). The default allows for basic template
294 toolkit variable swapping. There are two arguments. First is a
295 string or a reference to a string. If a string is passed, a copy
296 of that string is swapped and returned. If a reference to a string
297 is passed, it is modified in place. The second argument is a form,
298 or a CGI object, or a cgiex object, or a coderef (if the second
299 argument is missing, the cgiex object which called the method will
300 be used). If it is a coderef, it should accept key as its only
301 argument and return the proper value.
302 my $cgix = CGI::Ex->new;
304 my $form = {foo => 'bar',
305 this => {is => {nested => ['wow', 'wee']}}
306 };
307 my $str = $cgix->swap_template("<html>[% foo %]<br>[% foo %]</html>", $form));
309 # $str eq '<html>bar<br>bar</html>'
310 $str = $cgix->swap_template("[% this.is.nested.1 %]", $form));
312 # $str eq 'wee'
313 $str = "[% this.is.nested.0 %]";
315 $cgix->swap_template(\$str, $form);
316 # $str eq 'wow'
317 # may also be called with only one argument as follows:
319 # assuming $cgix had a query string of ?foo=bar&baz=wow&this=wee
320 $str = "<html>([% foo %]) <br>
321 ([% baz %]) <br>
322 ([% this %]) </html>";
323 $cgix->swap_template(\$str);
324 #$str eq "<html>(bar) <br>
325 # (wow) <br>
326 # (wee) </html>";
327 For further examples, please see the code contained in
329 t/samples/cgi_ex_* of this distribution.
330 If at a later date, the developer upgrades to Template::Toolkit,
332 the templates that were being swapped by CGI::Ex::swap_template
333 should be compatible with Template::Toolkit.
334
336 See also CGI::Ex::App.
337 See also CGI::Ex::Auth.
339 See also CGI::Ex::Conf.
341 See also CGI::Ex::Die.
343 See also CGI::Ex::Dump.
345 See also CGI::Ex::Fill.
347 See also CGI::Ex::Template.
349 See also CGI::Ex::Validate.
351
353 This module may be distributed under the same terms as Perl itself.
354
356 Paul Seamons <perl at seamons dot com>
357perl v5.30.1 2020-01-29 CGI::Ex(3)