#!/usr/bin/perl -T
use Bufferlass;
use lib '/home/pgcroft/sites/bufferlass.org.uk/trunk/src/';
use strict;
use warnings;

## The Instance script
## can contain
## new(), run(),
## new make take the params TMPL_PATH, QUERY, PARAMS as hashes of values
##     e.g. TMPL_PATH => 'MyApp/'
##          QUERY is an already existing CGI query object
##          PARAMS => { 'custom_thing_1' => 1, 'custom_thing_2' => '20', 'another' => qw/123 456/ }

my $bufferlass = Bufferlass->new();
$bufferlass->run();


##</code><code>##

package Bufferlass::Bufferlass;
use base 'CGI::Application';
use strict;
##

## methodology
## Subclassing and Override mehods.
## this module must define the setup(), teardown(), cgiapp_init(), cgiapp_prerun(), cgiapp_postrun(), cgiapp_get_query(), delete()
## Application Module Methods
## delete(), dump(), dump_html(), error_mode(), get_current_runmode(), header_add(), header_props(), header_type(), load_tmpl()
## mode_param(), param(), prerun_mode(), query(), run_mode(), start_mode(), tmpl_path()
#
##
## Subclassing and Override methods
##
sub setup { ## called by inherited new structure
## should contain
##    mode_param()
##    start_mode()
##    error_mode()
##    run_modes()
##    tmpl_path()
## is a good place to to define properties specific to the application using the $webapp->param() approach
## can simply be a defn of run_modes and start_mode
}
sub teardown { ## called *automatically* after application runs
## clean up after operations
## e.g. disconnect database connection established in setup()
## can also be used to store info about the app on server
}
sub cgiapp_init { ## called *automatically* just before the setup() method
## provides an optional initialisation hook
### receives all the parameters sent to the new() method
## could be used in an application superclass which inherits CGI::Application then base all web-based applications on this.
## thereby having a suite of applications that share particular charactertistics
}
sub cgiapp_prerun { ## called *automatically* before a selected run_mode
## provides an optional pre_run mode hook
##  receives the value of the run_mode
## as with cgiapp_init the cgiapp_prerun could be places in a superclass based on CGI::Application
## subsequent applications based on the superclass would then inherit similar characeritsics.
}
sub cgiapp_postrun { ## will be called after a run_mode has finished but before HTTP headers are generated
## receives a reference to output from a run method in addition to the CGI-App object
## useful when
##    want to emclose the output in further HTML
##    run_mode returns structured data such as XML which needs to be transformed in some way e.g. via XSLT
##    post-process CGI-App output through something like HTML::Mason
##    need to modify HTTP headers in a particular way across all run_modes
## have access to all CGI-App object methods normally available in a run_mode
## could use load_tmpl() to change the template used
## could change the headers to a redirect via header_type() and header_prop() methods.
## could make changes only when in a certain run_mode and with certain param() value .
}
sub cgiapp_get_query { ## loads CGI.pm via require.
## returns a CGIquery object
## can be overridden to use a different query object which must be compatible with CGI.pm or wrap chosen
## query interface in a wrapper class to achieve compatibility
}
##
## Inherited Methods
##
sub delete { ## deletes a parameter previously stroed via PARAMS parameter to new() or param() method.
## Useful where application makes decisions on existence of certain parameters
}
sub dump { ## debugging function
## retruns text containing the environment and web-form data of the request
## human readable format
}
sub dump_html { ## debugging function
## returns environment and web-form data of request
## human readable via browser
}
sub error_mode { ##contains name of run_mode to call when planned run_mode fails
## death not trapped so can die here
}
sub get_current_runmode { ## returns name of run_mode being run as text scalar
## will return undef if the run mode has not been initialised e.g. in setup()
}
sub header_add { ## adds headers to the outgoing response headers.
## refer to CGI.pm docs on header() for exact usage.
## preserves existing headers,
## scalar value replaces existing value for that key
## array ref values appended to existing values for that key
## useful for setting an additional cookie after one has been set
}
sub header_props { ## expects a hash of CGI.pm compatible HTTP header properties
## these values will be passed to the CGI.pm header() and redirect() methods
## clobbers existing headers
## works in conjunction with header_type() method
}
sub header_type { ## expects 'header', 'redirect', 'none'
## specifies type of header to be sent back to browser
## defaults to header
## 'none' hides headers
}
sub load_tmpl { ## expects name of a template file, reference to template data or a FILEHANDLE
## returns an HTML::Template object
## defaults to the name of the run_mode with the extension '.html' if argument not found
## uses HTML::Template methods for arguments
## sets HTML::Template path option if tmpl_path() value set
## sends remaining parameters to relevant HTML::Template method
## can be overrridden to enable use of other templating systems such as TT or Petal
}
sub mode_param { ## accessor/mutator method
## generally called via setup()
## determines run mode to call
## takes string, code reference, or uses $ENV{PATH_INFO} via path_info => n
}
sub param { ## sets application instance properties accessible throughout application
## sets or gets
## retruns an array of all currently existing paramaetrs if used in array context
## set lots of params using hash or hashref
## useful where similar applications need to share code base
}
sub prerun_mode { ## accessor/mutator changing the run mode about to be executed
## e.g. force back to login page
## may only be called in the context of a cgiapp_prerun() method.
}
sub query { ## retrieves CGI.pm query object
## new() method creates one automagically or uses that of the QUERY parameter
}
sub run_modes { ## accessor/mutator specifies dispatch table for application states
## arrayref of run mode names that represent the subroutine names directly
## hashref allows use of anternative name or code ref
## can be called multiple times with new values for existing run_modes overwriting existing values
## and adding new ones
## run method uses this data to send application to correct function by reading the CGI paramater specified by mode_param()
## and defaults to 'rm' for run mode.
## use AUTOLOAD to catch exceptions on non-existent run modes
}
sub start_mode { ## contains the name of mode as specified by the run_modes() table
## The mode key specified here will be used whenever the value of CGI form parameter specified bu mode_param()
## is not defined - typically the first time an application is executed.
}
sub tmpl_path() { ## accessor/mutator sets/gets path to directories where templates are stored
## accepts text scalar or array ref of multiple paths.
## used by load_templ to find template files
## uses HTML::Template path option
}

1;

##</code><code>##

Can't locate Bufferlass.pm in @INC (@INC contains: /etc/perl /usr/local/lib/perl/5.8.8 /usr/local/share/perl/5.8.8 /usr/lib/perl5 /usr/share/perl5 /usr/lib/perl/5.8 /usr/share/perl/5.8 /usr/local/lib/site_perl) at ./bufferlass.cgi line 2.
BEGIN failed--compilation aborted at ./bufferlass.cgi line 2.
##</code><code>##

 perl -T -I/home/pgcroft/sites/bufferlass.org.uk/trunk/src/Bufferlass bufferlass.cgi
Can't locate object method "new" via package "Bufferlass" at bufferlass.cgi line 15.