NAME
CGI::Ex - Yet Another Form Utility
SYNOPSIS
### CGI Module Extensions
my $cgix = CGI::Ex->new;
my $hashref = $cgix->get_form; # uses CGI by default
$cgix->content_type;
my $val_hash = $cgix->conf_read($pathtovalidation);
my $err_obj = $cgix->validate($hashref, $val_hash);
if ($err_obj) {
my $errors = $err_obj->as_hash;
my $content = "Some content";
$cgix->fill({text => \$content, form => $hashref});
print $content;
}
print "Success\n";
### Filling functionality
$cgix->fill({text => \$text, form => \%hash});
$cgix->fill({text => \$text, fdat => \%hash});
$cgix->fill({text => \$text, fobject => $cgiobject});
$cgix->fill({text => \$text, form => [\%hash1, $cgiobject]});
$cgix->fill({text => \$text); # uses $self->object as the form
$cgix->fill({text => \$text,
form => \%hash,
target => 'formname',
fill_password => 0,
ignore_fields => ['one','two']});
$cgix->fill(\$text); # uses $self->object as the form
$cgix->fill(\$text, \%hash, 'formname', 0, ['one','two']);
my $copy = $cgix->fill({scalarref => \$text, fdat => \%hash});
my $copy = $cgix->fill({arrayref => \@lines, fdat => \%hash});
my $copy = $cgix->fill({file => $filename, fdat => \%hash});
### Validation functionality
my $err_obj = $cgix->validate($form, $val_hash);
my $err_obj = $cgix->validate($form, $path_to_validation);
my $err_obj = $cgix->validate($form, $yaml_string);
### get errors separated by key name
### useful for inline errors
my $hash = $err_obj->as_hash;
my %hash = $err_obj->as_hash;
### get aggregate list of errors
### useful for central error description
my $array = $err_obj->as_array;
my @array = $err_obj->as_array;
### get a string
### useful for central error description
my $string = $err_obj->as_string;
my $string = "$err_obj";
$cgix->{raise_error} = 1;
$cgix->validate($form, $val_hash);
# SAME AS #
my $err_obj = $cgix->validate($form, $val_hash);
die $err_obj if $err_obj;
### Settings functionality
### read file via yaml
my $ref = $cgix->conf_read('/full/path/to/conf.yaml');
### merge all found settings.pl files together
@CGI::Ex::Conf::DEFAULT_PATHS = qw(/tmp /my/data/dir /home/foo);
@CGI::Ex::Conf::DIRECTIVE = 'MERGE';
@CGI::Ex::Conf::DEFAULT_EXT = 'pl';
my $ref = $cgix->conf_read('settings');
DESCRIPTION
CGI::Ex is another form filler / validator / conf reader / template
interface. Its goal is to take the wide scope of validators and other
useful CGI application modules out there and merge them into one utility
that has all of the necessary features of them all, as well as several
extended methods that I have found useful in working on the web.
The main functionality is provided by several other modules that may be
used separately, or together through the CGI::Ex interface.
"CGI::Ex::Fill"
A regular expression based form filler inner (accessed through
->fill or directly via its own functions). Can be a drop in
replacement for HTML::FillInForm. See CGI::Ex::Fill for more
information.
"CGI::Ex::Validate"
A form field / cgi parameter / any parameter validator (accessed
through ->validate or directly via its own methods). Not quite a
drop in for most validators, although it has most of the
functionality of most of the validators but with the key additions
of conditional validation. Has a tightly integrated JavaScript
portion that allows for duplicate client side validation. See
CGI::Ex::Validate for more information.
"CGI::Ex::Conf"
A general use configuration, or settings, or key / value file
reader. Has ability for providing key fallback as well as immutable
key definitions. Has default support for yaml, storable, perl, ini,
and xml and open architecture for definition of others. See
CGI::Ex::Conf for more information.
METHODS
"->fill"
fill is used for filling hash or cgi object values into an existing
html document (it doesn't deal at all with how you got the
document). Arguments may be given as a hash, or a hashref or
positional. Some of the following arguments will only work using
CGI::Ex::Fill - most will work with either CGI::Ex::Fill or
HTML::FillInForm (assume they are available unless specified
otherwise). (See CGI::Ex::Fill for a full explanation of
functionality). The arguments to fill are as follows (and in order
of position):
"text"
Text should be a reference to a scalar string containing the
html to be modified (actually it could be any reference or
object reference that can be modfied as a string). It will be
modified in place. Another named argument scalarref is available
if you would like to copy rather than modify.
"form"
Form may be a hashref, a cgi style object, a coderef, or an
array of multiple hashrefs, cgi objects, and coderefs. Hashes
should be key value pairs. CGI objects should be able to call
the method param (This can be overrided). Coderefs should expect
expect the field name as an argument and should return a value.
Values returned by form may be undef, scalar, arrayref, or
coderef (coderef values should expect an argument of field name
and should return a value). The code ref options are available
to delay or add options to the bringing in of form informatin -
without having to tie the hash. Coderefs are not available in
HTML::FillInForm. Also HTML::FillInForm only allows CGI objects
if an arrayref is used.
NOTE: Only one of the form, fdat, and fobject arguments are
allowed at a time.
"target"
The name of the form that the fields should be filled to. The
default value of undef, means to fill in all forms in the html.
"fill_passwords"
Boolean value defaults to 1. If set to zero - password fields
will not be filled.
"ignore_fields"
Specify which fields to not fill in. It takes either array ref
of names, or a hashref with the names as keys. The hashref
option is not available in CGI::Ex::Fill.
Other named arguments are available for compatiblity with
HTML::FillInForm. They may only be used as named arguments.
"scalarref"
Almost the same as the argument text. If scalarref is used, the
filled html will be returned. If text is used the html passed is
filled in place.
"arrayref"
An array ref of lines of the document. Forces a returned filled
html document.
"file"
An filename that will be opened, filled, and returned.
"fdat"
A hashref of key value pairs.
"fobject"
A cgi style object or arrayref of cgi style objects used for
getting the key value pairs.
See CGI::Ex::Fill for more information about the filling process.
"->object"
Returns the CGI object that is currently being used by CGI::Ex. If
none has been set it will automatically generate an object of type
$PREFERRED_CGI_MODULE which defaults to CGI.
"->validate"
Validate has a wide range of options available. (See
CGI::Ex::Validate for a full explanation of functionality). Validate
has two arguments:
"form"
Can be either a hashref to be validated, or a CGI style object
(which has the param method).
"val_hash"
The val_hash can be one of three items. First, it can be a
straight perl hashref containing the validation to be done.
Second, it can be a YAML document string. Third, it can be the
path to a file containing the validation. The validation in a
validation file will be read in depending upon file extension.
"->get_form"
Very similar to CGI->new->Val except that arrays are returned as
arrays. Not sure why CGI::Val didn't do this anyway.
"->get_cookies"
Returns a hash of all cookies.
"->make_form"
Takes a hash and returns a query_string. A second optional argument
may contain an arrayref of keys to use from the hash in building the
query_string.
"->content_type"
Can be called multiple times during the same session. Will only
print content-type once. (Useful if you don't know if something else
already printed content-type).
"->set_cookie"
Arguments are the same as those to CGI->new->cookie({}). Uses CGI's
cookie method to create a cookie, but then, depending on if content
has already been sent to the browser will either print a Set-cookie
header, or will add a tag (this is
supported on most major browsers). This is useful if you don't know
if something else already printed content-type.
"->location_bounce"
Depending on if content has already been sent to the browser will
either print a Location header, or will add a tag (this is supported on all major browsers).
This is useful if you don't know if something else already printed
content-type. Takes single argument of a url.
"->last_modified"
Depending on if content has already been sent to the browser will
either print a Last-Modified header, or will add a tag (this is supported on most major
browsers). This is useful if you don't know if something else
already printed content-type. Takes an argument of either a time
(may be a CGI -expires style time) or a filename.
"->expires"
Depending on if content has already been sent to the browser will
either print a Expires header, or will add a tag (this is supported on most major
browsers). This is useful if you don't know if something else
already printed content-type. Takes an argument of a time (may be a
CGI -expires style time).
"->send_status"
Send a custom status. Works in both CGI and mod_perl. Arguments are
a status code and the content (optional).
"->send_header"
Send a http header. Works in both CGI and mod_perl. Arguments are a
header name and the value for that header.
"->print_js"
Prints out a javascript file. Does everything it can to make sure
that the javascript will cache. Takes either a full filename, or a
shortened name which will be looked for in @INC. (ie
/full/path/to/my.js or CGI/Ex/validate.js or CGI::Ex::validate)
EXISTING MODULES
The following is a list of existing validator and formfiller modules at
the time of this writing (I'm sure this probably isn't exaustive).
"Email::Valid" - Validator
"SSN::Validate" - Validator
"Embperl::Form::Validate" - Validator
"Data::CGIForm" - Validator
"HTML::FillInForm" - Form filler-iner
"CGI" - CGI Getter. Form filler-iner
TODO
Add an integrated template toolkit interface.
Add an integrated debug module.
MODULES
See also CGI::Ex::Fill.
See also CGI::Ex::Validate.
See also CGI::Ex::Conf.
AUTHOR
Paul Seamons
LICENSE
This module may be distributed under the same terms as Perl itself.