1CGI::Ex(3)            User Contributed Perl Documentation           CGI::Ex(3)
2
3
4

NAME

6       CGI::Ex - CGI utility suite - makes powerful application writing fun
7       and easy
8

CGI::Ex SYNOPSIS

10           ### You probably don't want to use CGI::Ex directly
11           ### You probably should use CGI::Ex::App instead.
12
13           my $cgix = CGI::Ex->new;
14
15           $cgix->print_content_type;
16
17           my $hash = $cgix->form;
18
19           if ($hash->{'bounce'}) {
20
21               $cgix->set_cookie({
22                   name  => ...,
23                   value => ...,
24               });
25
26               $cgix->location_bounce($new_url_location);
27               exit;
28           }
29
30           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

DESCRIPTION

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
59       The main functionality is provided by several other modules that may be
60       used separately, or together through the CGI::Ex interface.
61
62       "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
67       "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
73       "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
82       "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
89       "CGI::Ex::Auth"
90           A highly configurable web based authentication system.  See
91           CGI::Ex::Auth for more information.
92

CGI::Ex METHODS

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
105           "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
112           "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
126               NOTE: Only one of the form, fdat, and fobject arguments are
127               allowed at a time.
128
129           "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
133           "fill_passwords"
134               Boolean value defaults to 1.  If set to zero - password fields
135               will not be filled.
136
137           "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
142           Other named arguments are available for compatibility with
143           HTML::FillInForm.  They may only be used as named arguments.
144
145           "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
150           "arrayref"
151               An array ref of lines of the document.  Forces a returned
152               filled html document.
153
154           "file"
155               An filename that will be opened, filled, and returned.
156
157           "fdat"
158               A hashref of key value pairs.
159
160           "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
165           See CGI::Ex::Fill for more information about the filling process.
166
167       "->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
172       "->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
177           "form"
178               Can be either a hashref to be validated, or a CGI style object
179               (which has the param method).
180
181           "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
188       "->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
193               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
198       "->set_form"
199           Allow for setting a custom form hash.  Useful for testing, or other
200           purposes.
201
202               $cgix->set_form(\%new_form);
203
204       "->get_cookies"
205           Returns a hash of all cookies.
206
207               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
212       "->set_cookies"
213           Allow for setting a custom cookies hash.  Useful for testing, or
214           other purposes.
215
216               $cgix->set_cookies(\%new_cookies);
217
218       "->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
224       "->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
231               $cgix->print_content_type;
232
233               # OR
234               $cgix->print_content_type('text/html');
235
236               # OR
237               $cgix->print_content_type('text/html', 'utf-8');
238
239       "->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
247       "->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
254       "->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
262       "->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
270       "->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
274       "->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
278       "->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
284               #!/usr/bin/perl
285               use CGI::Ex;
286               CGI::Ex->print_js($ENV{'PATH_INFO'});
287
288       "->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
303             my $cgix = CGI::Ex->new;
304             my $form = {foo  => 'bar',
305                         this => {is => {nested => ['wow', 'wee']}}
306                        };
307
308             my $str =  $cgix->swap_template("<html>[% foo %]<br>[% foo %]</html>", $form));
309             # $str eq '<html>bar<br>bar</html>'
310
311             $str = $cgix->swap_template("[% this.is.nested.1 %]", $form));
312             # $str eq 'wee'
313
314             $str = "[% this.is.nested.0 %]";
315             $cgix->swap_template(\$str, $form);
316             # $str eq 'wow'
317
318             # 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
328           For further examples, please see the code contained in
329           t/samples/cgi_ex_* of this distribution.
330
331           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

MODULES

336       See also CGI::Ex::App.
337
338       See also CGI::Ex::Auth.
339
340       See also CGI::Ex::Conf.
341
342       See also CGI::Ex::Die.
343
344       See also CGI::Ex::Dump.
345
346       See also CGI::Ex::Fill.
347
348       See also CGI::Ex::Template.
349
350       See also CGI::Ex::Validate.
351

LICENSE

353       This module may be distributed under the same terms as Perl itself.
354

AUTHOR

356       Paul Seamons <perl at seamons dot com>
357
358
359
360perl v5.30.1                      2020-01-29                        CGI::Ex(3)
Impressum