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

VERSION

10       version 2.54
11

CGI::Ex SYNOPSIS

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

DESCRIPTION

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
62       The main functionality is provided by several other modules that may be
63       used separately, or together through the CGI::Ex interface.
64
65       "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
70       "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
76       "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
85       "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
92       "CGI::Ex::Auth"
93           A highly configurable web based authentication system.  See
94           CGI::Ex::Auth for more information.
95

CGI::Ex METHODS

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
108           "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
115           "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
129               NOTE: Only one of the form, fdat, and fobject arguments are
130               allowed at a time.
131
132           "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
136           "fill_passwords"
137               Boolean value defaults to 1.  If set to zero - password fields
138               will not be filled.
139
140           "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
145           Other named arguments are available for compatibility with
146           HTML::FillInForm.  They may only be used as named arguments.
147
148           "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
153           "arrayref"
154               An array ref of lines of the document.  Forces a returned
155               filled html document.
156
157           "file"
158               An filename that will be opened, filled, and returned.
159
160           "fdat"
161               A hashref of key value pairs.
162
163           "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
168           See CGI::Ex::Fill for more information about the filling process.
169
170       "->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
175       "->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
180           "form"
181               Can be either a hashref to be validated, or a CGI style object
182               (which has the param method).
183
184           "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
191       "->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
196               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
201       "->set_form"
202           Allow for setting a custom form hash.  Useful for testing, or other
203           purposes.
204
205               $cgix->set_form(\%new_form);
206
207       "->get_cookies"
208           Returns a hash of all cookies.
209
210               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
215       "->set_cookies"
216           Allow for setting a custom cookies hash.  Useful for testing, or
217           other purposes.
218
219               $cgix->set_cookies(\%new_cookies);
220
221       "->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
227       "->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
234               $cgix->print_content_type;
235
236               # OR
237               $cgix->print_content_type('text/html');
238
239               # OR
240               $cgix->print_content_type('text/html', 'utf-8');
241
242       "->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
250       "->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
257       "->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
265       "->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
273       "->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
277       "->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
281       "->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
287               #!/usr/bin/perl
288               use CGI::Ex;
289               CGI::Ex->print_js($ENV{'PATH_INFO'});
290
291       "->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
306             my $cgix = CGI::Ex->new;
307             my $form = {foo  => 'bar',
308                         this => {is => {nested => ['wow', 'wee']}}
309                        };
310
311             my $str =  $cgix->swap_template("<html>[% foo %]<br>[% foo %]</html>", $form));
312             # $str eq '<html>bar<br>bar</html>'
313
314             $str = $cgix->swap_template("[% this.is.nested.1 %]", $form));
315             # $str eq 'wee'
316
317             $str = "[% this.is.nested.0 %]";
318             $cgix->swap_template(\$str, $form);
319             # $str eq 'wow'
320
321             # 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
331           For further examples, please see the code contained in
332           t/samples/cgi_ex_* of this distribution.
333
334           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

MODULES

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

LICENSE

356       This module may be distributed under the same terms as Perl itself.
357

AUTHOR

359       Paul Seamons <perl at seamons dot com>
360
361
362
363perl v5.38.0                      2023-07-20                        CGI::Ex(3)
Impressum