NAME

CGI::Ex::App - Simple CGI::Application type module

DESCRIPTION

Fill in the blanks and get a ready made CGI. This module is somewhat similar to CGI::Application and CGI::Path and CGI::Builder and any other "CGI framework." As with the others, CGI::App tries to do as much as possible, in a simple manner, without getting in the developer's way. Your milage may vary.

HOOKS / METHODS

Hooks are basically methods calls that look for a variety of method names. See the discussion under the method named "hook" for more details. Hooks and methods are looked for in the following order:

Method ->new

Object creator. Takes a hash or hashref.

Method ->init

Called by the default new method. Allows for any object initilizations.

Method ->form

Returns a hashref of the items passed to the CGI. Returns $self->{form}. Defaults to CGI::Ex::get_form.

Method ->navigate

This is the main loop runner. Figures out path and runs all of the appropriate hooks. Once all steps in the path run successfully, it will call it self with a path set to ['main'] to allow for a default main path to run.

Method ->path

Return an arrayref (modifyable) of the steps in the path. For each step the remaining hooks can be run. Hook methods are looked up and ran using the method "run_hook" which uses the method "hook" to lookup the hook. A history of ran hooks is stored in $self->{history}. Default will be a single step path looked up in $form->{path} or in $ENV{PATH_INFO}.

Method ->valid_paths

Returns a hashref of path steps that are allowed. If step found in default method path is not in the hash, the method path will return a single step "forbidden" and run its hooks. If no hash or undef is returned, all paths are allowed (default).

Method ->pre_loop

Called right before the navigation loop is started. At this point the path is set (but could be modified). The only argument is a reference to the path array.

Method ->run_hook

Calls "hook" to get a code ref which it then calls and returns the result. Arguments are the same as that for "hook".

Method ->hook

Arguments are a pathstep name, a hook name, and an optional code sub or default value (default value will be turned to a sub) (code sub will be called as method of $self).

  my $code = $self->hook('main', 'info_complete', sub {return 0});
  ### will look first for $self->main_info_complete();
  ### will then look  for $self->info_complete();
  ### will then run       $self->$default_passed_sub(); # sub {return 0}

Method ->handle_error

If anything dies during execution, handle_error will be called with the error that had happened. Default is to debug the error and path history.

Hook ->pre_step

Ran at the beginning of the loop before info_compelete is called. If it returns true, execution of navigate is returned and no more steps are processed.

Hook ->info_complete

Checks to see if all the necessary form elements have been passed in. Calls hooks ready_validate, and validate.

Hook ->ready_validate

Should return true if enough information is present to run validate.

Hook ->validate

Runs validation on the information posted in $self->form. Uses CGI::Ex::Validate for the validation. Calls the hook hash_validation to load validation information. Should return true if enough information is present to run validate. Errors are stored as a hash in $self->{hash_errors} via method add_errors and can be checked for at a later time with method has_errors (if the default validate was used).

Hook ->hash_validation

Returns a hash of the validation information to check form against. By default, will look for a filename using the hook file_val and will pass it to CGI::Ex::Validate::get_validation.

Hook ->file_val

Returns a filename containing the validation. Adds method base_dir_rel to hook name_module, and name_step and adds on the default file extension found in $self->ext_val which defaults to the global $EXT_VAL (the property $self->{ext_val} may also be set). File should be readible by CGI::Ex::Validate::get_validation.

Hook ->hash_form

Called in preparation for print after failed info_complete. Should contain a hash of any items needed to be swapped into the html during print.

Hook ->hash_fill

Called in preparation for print after failed info_complete. Should contain a hash of any items needed to be filled into the html form during print.

Hook ->hash_errors

Called in preparation for print after failed info_complete. Should contain a hash of any errors that occured. Will be merged into hash_form before the pass to print. Eash error that occured will be passed to method format_error before being added to the hash. If an error has occurred, the default validate will automatically add {has_errors =>1}. To the error hash at the time of validation. has_errors will also be added during the merge incase the default validate was not used.

Hook ->hash_common

A hash of common items to be merged with hash_form - such as pulldown menues.

Hook ->file_print

Returns a filename of the content to be used in the default print hook. Adds method base_dir_rel to hook name_module, and name_step and adds on the default file extension found in $self->ext_print which defaults to the global $EXT_PRINT (the property $self->{ext_print} may also be set). Should be a file that can be handled by hook print.

Hook ->print

Take the information and print it out. Default incarnation uses Template. Arguments are: step name, form hashref, and fill hashref.

Hook ->post_print

A hook which occurs after the printing has taken place. Is only run if the information was not complete. Useful for printing rows of a database query.

Hook ->post_step

Ran at the end of the step's loop if info_complete returned true. Allows for cleanup. If a true value is returned, execution of navigate is returned and no more steps are processed.

Method ->post_loop

Ran after all of the steps in the loop have been processed. If this point is reached, the post_loop hook will be called, and then the object will run $self->navigate({path => ['main']}) to fall back to the main method.