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