NAME

Geomap::FormApp - base class for Geomap form-based applications

SYNOPSIS

  use base 'Geomap::FormApp';


  ######################################################################
  # Override these methods from base class
  ######################################################################

  sub validator_profile
  {
    my $self = shift;
    # This should be a valid Data::FormValidator profile hash, with
    #   a profile for each runmode you want to validate.
    my $profile = {
      default => {
        required => [qw( fname lname )],
      },
    };
    return $profile;
  }

  sub pretty_errors
  {
    my $self = shift;
    # This should map each 'required' and 'optional' field from the 
    #   validator profile to a pretty-printing name
    my $errors = {
      fname => 'First Name',
      lname => 'Last Name',
    };
    return $errors;
  }
  # Sets up run modes, etc.
  sub setup
  {
    my $self = shift;
    $self->start_mode('default');
    $self->mode_param('view');
    $self->run_modes(
      default    => \&r_default,
      confirm    => \&r_confirm,
      errors     => \&r_errors,
      AUTOLOAD   => \&bad_runmode,
    );
  }


  ######################################################################
  # Runmodes
  #   Runmodes will generally follow this structure
  ######################################################################
  sub r_default
  {
    my $self = shift;
    # Get CGI query object
    my $cgi = $self->query();


    # Generate content
    my $errors = $self->param('_ERRORS');
    my $vars = { ERRORS => $errors };
    my $output = $self->output($vars);

    $output = $self->fill_form($output);

    # Return content as scalar
    return $output;
  }

  ... Other runmodes go here ...

DESCRIPTION

Geomap::FormApp provides a object-oriented base class for creating form-based web applications.

It is based on, and is a subclass of, CGI::Application. For the most part, Geomap::FormApp works like CGI::Application with some additional methods to simplify building applications.

Geomap::FormApp overrides three standard CGI::Application methods. Overriding these methods in your own application will break Geomap::FormApp's default behavior:

load_tmpl()
Overridden to replace use of HTML::Template with the Template-Toolkit.

cgiapp_prerun()
Overridden to provide automatic form validation feature.

teardown()
Overridden to perform database disconnection.

OVERRIDE METHODS

These methods should be overridden in the derived class:

validator_profile()
This method should be overridden to return a valid Data::FormValidator profile hashref, with a profile for each runmode you want to validate.

(See the documentation for Data::FormValidator for details.)

pretty_errors()
This method should be overridden to return a hashref for which the keys are form element names and the values are the ``pretty'' names that should be displayed in error messages.

setup()
This is the standard CGI::Application setup() method, which should be used to define the start_mode, mode_param, and run_modes for the application.

(See the documentation for CGI::Application for details.)

These methods may also be overridden:

validate_extra($previous,$error)
This method can be overridden to provide additional validation beyond that provided by the standard form validation procedure. You can use the error() method to get access to any existing errors (from form validation), and the add_error() method to inform the Geomap::FormApp error reporting system of the error.

(See error(), add_error(), and the section on Error Handling.)

cgiapp_init(@args)
Standard CGI::Application cgiapp_init

GEOMAP::FORMAPP METHODS

These methods add extra functionality to the standard CGI::Application:

OUTPUT METHODS

These methods generate output:

output($vars,[$template_file])
Generate output (such as an HTML page or an e-mail message) using Template-Toolkit. The first parameter should be a hash reference containing definitions of template variables (identical to those used by Template-Toolkit). You can also pass an optional second parameter containing the name of the template file to process. If no template name is passed, output() attempts to use a template based on the runmode.

(For example, 'default.html' for the runmode 'default'.)

(See the documentation for Template-Toolkit for details on using template variables.)

error()
Returns the error 'list', containing all the errors detected so far. The error list is a hash reference for which the keys are error codes and the values contain additional information about the error (if there is any).

The error list is undefined if there have been no errors so far.

Errors can be added to the error list using the add_error() method.

(See add_error() and the section on Error Handling for more information.)

add_error($error_code,[$optional_data])
Adds an error code (and optionally additional data about the error) to the error 'list'. This data is then passed to the error template by Geomap::FormApp's error reporting system.

(See add_error() and the section on Error Handling for more information.)

fill_form($text)
Fills form fields with data from a CGI object using HTML::FillInForm.

send_email($to,$from,$subject,$message)
Sends an e-mail message to a specified address. If either $to or $from are undefined, send_email() will use the configuration params 'email_to' or 'email_from' (as set in the new() constructor).

ACCESSOR/CREATOR METHODS

get_session($session_id)
Get or create the tied session hash or object corresponding to the provided session ID.

get_dbh()
Get or create the connected DBI database handle for this instance.

COOKIE METHODS

get_session_cookie()
Get the session ID from the incoming cookie header.

get_cookie($key)
Return value of incoming cookie matching the provided key.

set_cookie($key,$value)
Set outgoing named cookie key to the provided value.

clear_cookie($key)
Clear the value of the named cookie.

DATABASE METHODS

query_data($query,@params)
Executes a SQL SELECT query (with optional placeholder parameters), and returns a reference to an array of hash references containing the entire result set.

Each array element represents one row of the result set as a hashref in which the keys are column names and the values are the column values.

query_data_row($query,@params)
Like query_data(), but used for queries that will only return a single-row result set. Returns a hashref in which the keys are column names and the values are the column values.

query_data_array($query,@params)
Like query_data(), but used for queries with results sets which will contain only one element per row. Returns an array reference containing the entire result set.

update_data($query,@params)
Executes a SQL UPDATE or INSERT query (with optional placeholder parameters) and returns the number of rows affected.

(As with ordinary DBI queries, update_data() returns '0E0' if zero rows are affected, and undefined on errors. Perl treats '0E0' as 'zero but true'.)

CGI::APPLICATION METHODS

new($config)
This is the standard CGI::Application constructor, but it must be called with the appropriate parameters for the Geomap::FormApp features you will be using in order for the application to work. 
  my $formapp = MyApp->new(
    TMPL_PATH => 'c:/devel/templates',
    PARAMS => {
      db          => 'geomap:192.168.199.100',
      db_user     => 'webdev',
      db_pass     => '',
      error_param => '',
      error_mode  => '',
      email_to    => '',
      email_from  => '',
    }
  );

The standard Geomap::FormApp configuration options are:

  1. TMPL_PATH
    Required for Geomap::FormApp to find the display templates for an application.

  2. PARAMS
    These items should be passed in the PARAMS section of the constructor:

ERROR HANDLING

Under Construction.

EXPORT

None by default.

AUTHOR

Brad Smithart, <brad@smithart.net>

For Geomap Company