NAME

VERSION

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

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

"->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:

"->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::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

AUTHOR