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 <meta http-equiv='set-cookie'> 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 <meta http-equiv='refresh'> 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 <meta http-equiv='Last-Modified'> 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 <meta http-equiv='Expires'> 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.