NAME

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

VERSION

    version 2.49

CGI::Ex SYNOPSIS

        ### You probably don't want to use CGI::Ex directly
        ### You probably should use CGI::Ex::App instead.
    
        my $cgix = CGI::Ex->new;
    
        $cgix->print_content_type;
    
        my $hash = $cgix->form;
    
        if ($hash->{'bounce'}) {
    
            $cgix->set_cookie({
                name  => ...,
                value => ...,
            });
    
            $cgix->location_bounce($new_url_location);
            exit;
        }
    
        if (scalar keys %$form) {
             my $val_hash = $cgix->conf_read($pathtovalidation);
             my $err_obj = $cgix->validate($hash, $val_hash);
             if ($err_obj) {
                 my $errors  = $err_obj->as_hash;
                 my $input   = "Some content";
                 my $content = "";
                 $cgix->swap_template(\$input, $errors, $content);
                 $cgix->fill({text => \$content, form => $hashref});
                 print $content;
                 exit;
             } else {
                 print "Success";
             }
        } else {
             print "Main page";
        }

DESCRIPTION

    CGI::Ex provides a suite of utilities to make writing CGI scripts more
    enjoyable. Although they can all be used separately, the main
    functionality of each of the modules is best represented in the
    CGI::Ex::App module. CGI::Ex::App takes CGI application building to the
    next step. CGI::Ex::App is not quite a framework (which normally
    includes pre-built html) instead CGI::Ex::App is an extended
    application flow that dramatically reduces CGI build time in most
    cases. It does so using as little magic as possible. See CGI::Ex::App.

    The main functionality is provided by several other modules that may be
    used separately, or together through the CGI::Ex interface.

    CGI::Ex::Template

      A Template::Toolkit compatible processing engine. With a few
      limitations, CGI::Ex::Template can be a drop in replacement for
      Template::Toolkit.

    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.

    CGI::Ex::Auth

      A highly configurable web based authentication system. See
      CGI::Ex::Auth for more information.

CGI::Ex 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 modified 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 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 information - 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 compatibility 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. Should be capable of the ->param
	method and ->cookie method as document in CGI.

      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->Vars except that arrays are returned as
      arrays. Not sure why CGI didn't do this anyway (well - yes - legacy
      Perl 4 - but at some point things need to be updated).

          my $hash = $cgix->get_form;
          my $hash = $cgix->get_form(CGI->new);
          my $hash = get_form();
          my $hash = get_form(CGI->new);

    ->set_form

      Allow for setting a custom form hash. Useful for testing, or other
      purposes.

          $cgix->set_form(\%new_form);

    ->get_cookies

      Returns a hash of all cookies.

          my $hash = $cgix->get_cookies;
          my $hash = $cgix->get_cookies(CGI->new);
          my $hash = get_cookies();
          my $hash = get_cookies(CGI->new);

    ->set_cookies

      Allow for setting a custom cookies hash. Useful for testing, or other
      purposes.

          $cgix->set_cookies(\%new_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. First argument is undef, it will use the form stored in
      itself as the hash.

    ->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). Calling this sends the Content-type
      header. Trying to print ->content_type is an error. For clarity, the
      method ->print_content_type is available.

          $cgix->print_content_type;
      
          # OR
          $cgix->print_content_type('text/html');
      
          # OR
          $cgix->print_content_type('text/html', 'utf-8');

    ->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)

          #!/usr/bin/perl
          use CGI::Ex;
          CGI::Ex->print_js($ENV{'PATH_INFO'});

    ->swap_template

      This is intended as a simple yet strong subroutine to swap in tags to
      a document. It is intended to be very basic for those who may not
      want the full features of a Templating system such as
      Template::Toolkit (even though they should investigate them because
      they are pretty nice). The default allows for basic template toolkit
      variable swapping. There are two arguments. First is a string or a
      reference to a string. If a string is passed, a copy of that string
      is swapped and returned. If a reference to a string is passed, it is
      modified in place. The second argument is a form, or a CGI object, or
      a cgiex object, or a coderef (if the second argument is missing, the
      cgiex object which called the method will be used). If it is a
      coderef, it should accept key as its only argument and return the
      proper value.

        my $cgix = CGI::Ex->new;
        my $form = {foo  => 'bar',
                    this => {is => {nested => ['wow', 'wee']}}
                   };
      
        my $str =  $cgix->swap_template("<html>[% foo %]<br>[% foo %]</html>", $form));
        # $str eq '<html>bar<br>bar</html>'
      
        $str = $cgix->swap_template("[% this.is.nested.1 %]", $form));
        # $str eq 'wee'
      
        $str = "[% this.is.nested.0 %]";
        $cgix->swap_template(\$str, $form);
        # $str eq 'wow'
      
        # may also be called with only one argument as follows:
        # assuming $cgix had a query string of ?foo=bar&baz=wow&this=wee
        $str = "<html>([% foo %]) <br>
                ([% baz %]) <br>
                ([% this %]) </html>";
        $cgix->swap_template(\$str);
        #$str eq "<html>(bar) <br>
        #        (wow) <br>
        #        (wee) </html>";

      For further examples, please see the code contained in
      t/samples/cgi_ex_* of this distribution.

      If at a later date, the developer upgrades to Template::Toolkit, the
      templates that were being swapped by CGI::Ex::swap_template should be
      compatible with Template::Toolkit.

MODULES

    See also CGI::Ex::App.

    See also CGI::Ex::Auth.

    See also CGI::Ex::Conf.

    See also CGI::Ex::Die.

    See also CGI::Ex::Dump.

    See also CGI::Ex::Fill.

    See also CGI::Ex::Template.

    See also CGI::Ex::Validate.

LICENSE

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

AUTHOR

    Paul Seamons <perl at seamons dot com>