2 CGI::Ex - CGI utility suite (form getter/filler/validator/app builder)
5 ### CGI Module Extensions
7 my $cgix = CGI::Ex->new;
8 my $hashref = $cgix->get_form; # uses CGI by default
10 ### send the Content-type header - whether or not we are mod_perl
11 $cgix->print_content_type;
13 my $val_hash = $cgix->conf_read($pathtovalidation);
15 my $err_obj = $cgix->validate($hashref, $val_hash);
17 my $errors = $err_obj->as_hash;
18 my $input = "Some content";
20 SomeTemplateObject->process($input, $errors, $content);
21 $cgix->fill({text => \$content, form => $hashref});
28 ### Filling functionality
30 $cgix->fill({text => \$text, form => \%hash});
31 $cgix->fill({text => \$text, fdat => \%hash});
32 $cgix->fill({text => \$text, fobject => $cgiobject});
33 $cgix->fill({text => \$text, form => [\%hash1, $cgiobject]});
34 $cgix->fill({text => \$text); # uses $self->object as the form
35 $cgix->fill({text => \$text,
39 ignore_fields => ['one','two']});
40 $cgix->fill(\$text); # uses $self->object as the form
41 $cgix->fill(\$text, \%hash, 'formname', 0, ['one','two']);
42 my $copy = $cgix->fill({scalarref => \$text, fdat => \%hash});
43 my $copy = $cgix->fill({arrayref => \@lines, fdat => \%hash});
44 my $copy = $cgix->fill({file => $filename, fdat => \%hash});
46 ### Validation functionality
48 my $err_obj = $cgix->validate($form, $val_hash);
49 my $err_obj = $cgix->validate($form, $path_to_validation);
50 my $err_obj = $cgix->validate($form, $yaml_string);
52 ### get errors separated by key name
53 ### useful for inline errors
54 my $hash = $err_obj->as_hash;
55 my %hash = $err_obj->as_hash;
57 ### get aggregate list of errors
58 ### useful for central error description
59 my $array = $err_obj->as_array;
60 my @array = $err_obj->as_array;
63 ### useful for central error description
64 my $string = $err_obj->as_string;
65 my $string = "$err_obj";
67 $cgix->{raise_error} = 1;
68 $cgix->validate($form, $val_hash);
70 my $err_obj = $cgix->validate($form, $val_hash);
71 die $err_obj if $err_obj;
73 ### Settings functionality
75 ### read file via yaml
76 my $ref = $cgix->conf_read('/full/path/to/conf.yaml');
78 ### merge all found settings.pl files together
79 @CGI::Ex::Conf::DEFAULT_PATHS = qw(/tmp /my/data/dir /home/foo);
80 @CGI::Ex::Conf::DIRECTIVE = 'MERGE';
81 @CGI::Ex::Conf::DEFAULT_EXT = 'pl';
82 my $ref = $cgix->conf_read('settings');
85 CGI::Ex provides a suite of utilities to make writing CGI scripts more
86 enjoyable. Although they can all be used separately, the main
87 functionality of each of the modules is best represented in the
88 CGI::Ex::App module. CGI::Ex::App takes CGI application building to the
89 next step. CGI::Ex::App is not a framework (which normally includes
90 prebuilt html) instead CGI::Ex::App is an extended application flow that
91 normally dramatically reduces CGI build time. See CGI::Ex::App.
93 CGI::Ex is another form filler / validator / conf reader / template
94 interface. Its goal is to take the wide scope of validators and other
95 useful CGI application modules out there and merge them into one utility
96 that has all of the necessary features of them all, as well as several
97 extended methods that I have found useful in working on the web.
99 The main functionality is provided by several other modules that may be
100 used separately, or together through the CGI::Ex interface.
103 A regular expression based form filler inner (accessed through
104 ->fill or directly via its own functions). Can be a drop in
105 replacement for HTML::FillInForm. See CGI::Ex::Fill for more
109 A form field / cgi parameter / any parameter validator (accessed
110 through ->validate or directly via its own methods). Not quite a
111 drop in for most validators, although it has most of the
112 functionality of most of the validators but with the key additions
113 of conditional validation. Has a tightly integrated JavaScript
114 portion that allows for duplicate client side validation. See
115 CGI::Ex::Validate for more information.
118 A general use configuration, or settings, or key / value file
119 reader. Has ability for providing key fallback as well as immutable
120 key definitions. Has default support for yaml, storable, perl, ini,
121 and xml and open architecture for definition of others. See
122 CGI::Ex::Conf for more information.
126 fill is used for filling hash or cgi object values into an existing
127 html document (it doesn't deal at all with how you got the
128 document). Arguments may be given as a hash, or a hashref or
129 positional. Some of the following arguments will only work using
130 CGI::Ex::Fill - most will work with either CGI::Ex::Fill or
131 HTML::FillInForm (assume they are available unless specified
132 otherwise). (See CGI::Ex::Fill for a full explanation of
133 functionality). The arguments to fill are as follows (and in order
137 Text should be a reference to a scalar string containing the
138 html to be modified (actually it could be any reference or
139 object reference that can be modfied as a string). It will be
140 modified in place. Another named argument scalarref is available
141 if you would like to copy rather than modify.
144 Form may be a hashref, a cgi style object, a coderef, or an
145 array of multiple hashrefs, cgi objects, and coderefs. Hashes
146 should be key value pairs. CGI objects should be able to call
147 the method param (This can be overrided). Coderefs should expect
148 expect the field name as an argument and should return a value.
149 Values returned by form may be undef, scalar, arrayref, or
150 coderef (coderef values should expect an argument of field name
151 and should return a value). The code ref options are available
152 to delay or add options to the bringing in of form informatin -
153 without having to tie the hash. Coderefs are not available in
154 HTML::FillInForm. Also HTML::FillInForm only allows CGI objects
155 if an arrayref is used.
157 NOTE: Only one of the form, fdat, and fobject arguments are
161 The name of the form that the fields should be filled to. The
162 default value of undef, means to fill in all forms in the html.
165 Boolean value defaults to 1. If set to zero - password fields
169 Specify which fields to not fill in. It takes either array ref
170 of names, or a hashref with the names as keys. The hashref
171 option is not available in CGI::Ex::Fill.
173 Other named arguments are available for compatiblity with
174 HTML::FillInForm. They may only be used as named arguments.
177 Almost the same as the argument text. If scalarref is used, the
178 filled html will be returned. If text is used the html passed is
182 An array ref of lines of the document. Forces a returned filled
186 An filename that will be opened, filled, and returned.
189 A hashref of key value pairs.
192 A cgi style object or arrayref of cgi style objects used for
193 getting the key value pairs. Should be capable of the ->param
194 method and ->cookie method as document in CGI.
196 See CGI::Ex::Fill for more information about the filling process.
199 Returns the CGI object that is currently being used by CGI::Ex. If
200 none has been set it will automatically generate an object of type
201 $PREFERRED_CGI_MODULE which defaults to CGI.
204 Validate has a wide range of options available. (See
205 CGI::Ex::Validate for a full explanation of functionality). Validate
209 Can be either a hashref to be validated, or a CGI style object
210 (which has the param method).
213 The val_hash can be one of three items. First, it can be a
214 straight perl hashref containing the validation to be done.
215 Second, it can be a YAML document string. Third, it can be the
216 path to a file containing the validation. The validation in a
217 validation file will be read in depending upon file extension.
220 Very similar to CGI->new->Vars except that arrays are returned as
221 arrays. Not sure why CGI::Val didn't do this anyway (well - yes -
222 legacy Perl 4 - but at some point things need to be updated).
225 Allow for setting a custom form hash. Useful for testing, or other
229 Returns a hash of all cookies.
232 Takes a hash and returns a query_string. A second optional argument
233 may contain an arrayref of keys to use from the hash in building the
234 query_string. First argument is undef, it will use the form stored
235 in itself as the hash.
238 Can be called multiple times during the same session. Will only
239 print content-type once. (Useful if you don't know if something else
240 already printed content-type). Calling this sends the Content-type
241 header. Trying to print ->content_type is an error. For clarity, the
242 method ->print_content_type is available.
245 Arguments are the same as those to CGI->new->cookie({}). Uses CGI's
246 cookie method to create a cookie, but then, depending on if content
247 has already been sent to the browser will either print a Set-cookie
248 header, or will add a <meta http-equiv='set-cookie'> tag (this is
249 supported on most major browsers). This is useful if you don't know
250 if something else already printed content-type.
253 Depending on if content has already been sent to the browser will
254 either print a Location header, or will add a <meta
255 http-equiv='refresh'> tag (this is supported on all major browsers).
256 This is useful if you don't know if something else already printed
257 content-type. Takes single argument of a url.
260 Depending on if content has already been sent to the browser will
261 either print a Last-Modified header, or will add a <meta
262 http-equiv='Last-Modified'> tag (this is supported on most major
263 browsers). This is useful if you don't know if something else
264 already printed content-type. Takes an argument of either a time
265 (may be a CGI -expires style time) or a filename.
268 Depending on if content has already been sent to the browser will
269 either print a Expires header, or will add a <meta
270 http-equiv='Expires'> tag (this is supported on most major
271 browsers). This is useful if you don't know if something else
272 already printed content-type. Takes an argument of a time (may be a
273 CGI -expires style time).
276 Send a custom status. Works in both CGI and mod_perl. Arguments are
277 a status code and the content (optional).
280 Send a http header. Works in both CGI and mod_perl. Arguments are a
281 header name and the value for that header.
284 Prints out a javascript file. Does everything it can to make sure
285 that the javascript will cache. Takes either a full filename, or a
286 shortened name which will be looked for in @INC. (ie
287 /full/path/to/my.js or CGI/Ex/validate.js or CGI::Ex::validate)
290 This is intended as a simple yet strong subroutine to swap in tags
291 to a document. It is intended to be very basic for those who may not
292 want the full features of a Templating system such as
293 Template::Toolkit (even though they should investigate them because
294 they are pretty nice). The default allows for basic template toolkit
295 variable swapping. There are two arguments. First is a string or a
296 reference to a string. If a string is passed, a copy of that string
297 is swapped and returned. If a reference to a string is passed, it is
298 modified in place. The second argument is a form, or a CGI object,
299 or a cgiex object, or a coderef (if the second argument is missing,
300 the cgiex object which called the method will be used). If it is a
301 coderef, it should accept key as its only argument and return the
304 my $cgix = CGI::Ex->new;
305 my $form = {foo => 'bar',
306 this => {is => {nested => ['wow', 'wee']}}
309 my $str = $cgix->swap_template("<html>[% foo %]<br>[% foo %]</html>", $form));
310 # $str eq '<html>bar<br>bar</html>'
312 $str = $cgix->swap_template("[% this.is.nested.1 %]", $form));
315 $str = "[% this.is.nested.0 %]";
316 $cgix->swap_template(\$str, $form);
319 # may also be called with only one argument as follows:
320 # assuming $cgix had a query string of ?foo=bar&baz=wow&this=wee
321 $str = "<html>([% foo %]) <br>
323 ([% this %]) </html>";
324 $cgix->swap_template(\$str);
325 #$str eq "<html>(bar) <br>
329 For further examples, please see the code contained in
330 t/samples/cgi_ex_* of this distribution.
332 If at a later date, the developer upgrades to Template::Toolkit, the
333 templates that were being swapped by CGI::Ex::swap_template should
334 be compatible with Template::Toolkit.
337 The following is a list of existing validator and formfiller modules at
338 the time of this writing (I'm sure this probably isn't exaustive).
340 "Email::Valid" - Validator
341 "SSN::Validate" - Validator
342 "Embperl::Form::Validate" - Validator
343 "Data::CGIForm" - Validator
344 "HTML::FillInForm" - Form filler-iner
345 "CGI" - CGI Getter. Form filler-iner
348 Add an integrated template toolkit interface.
350 Add an integrated debug module.
353 See also CGI::Ex::Fill.
355 See also CGI::Ex::Validate.
357 See also CGI::Ex::Conf.
359 See also CGI::Ex::Die.
361 See also CGI::Ex::App.
363 See also CGI::Ex::Dump.
369 This module may be distributed under the same terms as Perl itself.