r1375 - in
packages/libcgi-application-perl/branches/upstream/current: .
lib/CGI t
Jaldhar H. Vyas
jaldhar at costa.debian.org
Sat Sep 24 23:59:21 UTC 2005
Author: jaldhar
Date: 2005-09-24 23:59:20 +0000 (Sat, 24 Sep 2005)
New Revision: 1375
Added:
packages/libcgi-application-perl/branches/upstream/current/t/mode_param_overwritten.t
Removed:
packages/libcgi-application-perl/branches/upstream/current/ANNOUNCE
Modified:
packages/libcgi-application-perl/branches/upstream/current/Changes
packages/libcgi-application-perl/branches/upstream/current/MANIFEST
packages/libcgi-application-perl/branches/upstream/current/META.yml
packages/libcgi-application-perl/branches/upstream/current/README
packages/libcgi-application-perl/branches/upstream/current/lib/CGI/Application.pm
packages/libcgi-application-perl/branches/upstream/current/t/11callbacks.t
packages/libcgi-application-perl/branches/upstream/current/t/mode_param_path_info.t
Log:
Load /tmp/tmp.FOUgz3/libcgi-application-perl-4.03 into
packages/libcgi-application-perl/branches/upstream/current.
Deleted: packages/libcgi-application-perl/branches/upstream/current/ANNOUNCE
===================================================================
--- packages/libcgi-application-perl/branches/upstream/current/ANNOUNCE 2005-09-22 13:12:23 UTC (rev 1374)
+++ packages/libcgi-application-perl/branches/upstream/current/ANNOUNCE 2005-09-24 23:59:20 UTC (rev 1375)
@@ -1,77 +0,0 @@
-Version 4.0 of CGI::Application is now available via CPAN!
-
-Download site for CGI::Application:
-
- http://search.cpan.org/dist/CGI-Application/
-
-CHANGES SINCE VERSION 3.31:
- This release adds a major new feature of special interest to plugin
- authors: 'hooks'. This concept helps to create plugins that are more powerful
- and simpler to use for end users. See the documentation on writing plugins for
- details.
-
- Special thanks to Cees Hek and Michael Graham for their effort to develop
- and refine the hook system.
-
- Since the last major release, there has been an explosion of new plugins
- developed. This is an incomplete list of modules below the
- 'CGI::Application::Plugin' namespace. Expect more to be added and updated soon
- with the advent of the hook system:
-
- ::AnyTemplate - Use any templating system with a unified interface
- ::Apache - Use Apache::* modules without interference
- ::AutoRunmode - Automatically register runmodes
- ::ConfigAuto - Integration with Config::Auto
- ::Config::Context - Integration with Config::Context
- ::Config::General - Integration with Config::General
- ::Config::Simple - Integration with Config::Simple
- ::CompressGzip - Add Gzip compression
- ::DBH - Integration with DBI
- ::LogDispatch - Integration with Log::Dispatch
- ::Session - Integration with CGI::Session
- ::Stream - Help stream files to the browser
- ::TT - Use Template::Toolkit as an alternative to HTML::Template
- ::ValidateRM - Integration with Data::FormValidator and HTML::FillInForm
-
- The following additional changes are also present in this release:
-
- - Enhanced tests and documentation for error_mode(). (Rob Kinyon).
- - Clarified Plug-in documentation (Timothy Appnel)
- - Avoid some warnings when getting run mode from PATH_INFO (Emanuele Zeppieri)
- - Use query() object to get PATH_INFO, to workaround bug in IIS web server. (Mark Stosberg)
- - Documented return value of header_props()
-
-Read the article "Using CGI::Application" on Perl.com for an
-overview of this module and its usage:
-
- http://www.perl.com/pub/a/2001/06/05/cgi.html
-
-
-CGI::Application is intended to make it easier to create sophisticated,
-reusable web-based applications. This module implements a methodology which,
-if followed, will make your web software easier to design, easier to
-document, easier to write, and easier to evolve.
-
-CGI::Application builds on standard, non-proprietary technologies and
-techniques, such as the Common Gateway Interface and Lincoln D. Stein's
-excellent CGI.pm module. CGI::Application judiciously avoids employing
-technologies and techniques which would bind a developer to any one set
-of tools, operating system or web server.
-
-The guiding philosophy behind CGI::Application is that a web-based
-application can be organized into a specific set of "Run Modes." Each
-Run Mode is roughly analogous to a single screen (a form, some output, etc).
-All the Run Modes are managed by a single "Application Module" which is a
-Perl module. In your web server's document space there is an "Instance
-Script" which is called by the web server as a CGI (or an Apache::Registry
-script if you're using Apache + mod_perl).
-
-CGI::Application is an Object-Oriented Perl module which implements an
-Abstract Class. It is not intended that this package be instantiated
-directly. Instead, it is intended that your Application Module will be
-implemented as a Sub-Class of CGI::Application.
-
-If you have any questions, comments, bug reports or feature suggestions,
-post them to the support mailing list! To join the mailing list, simply
-send a blank message to "cgiapp-subscribe at lists.erlbaum.net".
-
Modified: packages/libcgi-application-perl/branches/upstream/current/Changes
===================================================================
--- packages/libcgi-application-perl/branches/upstream/current/Changes 2005-09-22 13:12:23 UTC (rev 1374)
+++ packages/libcgi-application-perl/branches/upstream/current/Changes 2005-09-24 23:59:20 UTC (rev 1375)
@@ -1,7 +1,31 @@
-# $Id: Changes,v 1.36 2004/05/08 21:07:49 mark Exp $
-
Revision history for Perl extension CGI::Application.
+4.03 Thu Aug 04, 2005
+ - Fixed important bug introducted in 4.02 in which a mode_param
+ set in a sub-class would have been ignored. A new automated test
+ was added to prevent this regression in the future.
+
+4.02 Sat Jul 30, 2005
+
+ - Documented existence of CGI::Application::Plugin::FillInForm.
+
+ - path_info option to mode_param now supports negative index numbers
+ to grab the run mode name from the other end of the PATH_INFO.
+ (Thilo Planz)
+
+ - Altered how "start_mode" default is set, allowing it to be set
+ through the hook system in the 'init' phase. Existing applications
+ should be unaffected.
+
+ - Return value of run_modes() was documented.
+
+ - Integrate more examples of using plugins into the documentation.
+
+ - 'error' hook was added, which is executed just before error_mode() might
+ be called. An example use of this would be a logging plugin that wants to
+ log that the application died. Although it's unlikely to change, it is marked
+ as experimental for now.
+
4.01 Tue Jun 14, 2005
NOTE: This release has an important incompatibility from the 4.0 release
Modified: packages/libcgi-application-perl/branches/upstream/current/MANIFEST
===================================================================
--- packages/libcgi-application-perl/branches/upstream/current/MANIFEST 2005-09-22 13:12:23 UTC (rev 1374)
+++ packages/libcgi-application-perl/branches/upstream/current/MANIFEST 2005-09-24 23:59:20 UTC (rev 1375)
@@ -1,4 +1,3 @@
-ANNOUNCE
lib/CGI/Application.pm
lib/CGI/Application/Mailform.pm
ARTISTIC
@@ -24,6 +23,7 @@
t/10errormode.t
t/11callbacks.t
t/mode_param_path_info.t
+t/mode_param_overwritten.t
t/load_tmpl_hook.t
test/TestApp.pm
test/TestApp2.pm
Modified: packages/libcgi-application-perl/branches/upstream/current/META.yml
===================================================================
--- packages/libcgi-application-perl/branches/upstream/current/META.yml 2005-09-22 13:12:23 UTC (rev 1374)
+++ packages/libcgi-application-perl/branches/upstream/current/META.yml 2005-09-24 23:59:20 UTC (rev 1375)
@@ -1,6 +1,6 @@
--- #YAML:1.0
name: CGI-Application
-version: 4.01
+version: 4.03
author:
- Jesse Erlbaum <jesse at erlbaum.net>
abstract: Framework for building reusable web-applications
@@ -14,7 +14,7 @@
provides:
CGI::Application:
file: lib/CGI/Application.pm
- version: 4.01
+ version: 4.03
CGI::Application::Mailform:
file: lib/CGI/Application/Mailform.pm
-generated_by: Module::Build version 0.2606
+generated_by: Module::Build version 0.2611
Modified: packages/libcgi-application-perl/branches/upstream/current/README
===================================================================
--- packages/libcgi-application-perl/branches/upstream/current/README 2005-09-22 13:12:23 UTC (rev 1374)
+++ packages/libcgi-application-perl/branches/upstream/current/README 2005-09-24 23:59:20 UTC (rev 1375)
@@ -11,49 +11,12 @@
http://search.cpan.org/dist/CGI-Application/
-CHANGES SINCE VERSION 3.31:
- This release adds a major new feature of special interest to plugin
- authors: 'hooks'. This concept helps to create plugins that are more powerful
- and simpler to use for end users. See the documentation on writing plugins for
- details.
+See the 'Changes' file for recent changes.
- Special thanks to Cees Hek and Michael Graham for their effort to develop
- and refine the hook system.
+For more information about this module, please see our website at:
- Since the last major release, there has been an explosion of new plugins
- developed. This is an incomplete list of modules below the
- 'CGI::Application::Plugin' namespace. Expect more to be added and updated soon
- with the advent of the hook system:
+http://www.cgi-app.org/
- ::AnyTemplate - Use any templating system with a unified interface
- ::Apache - Use Apache::* modules without interference
- ::AutoRunmode - Automatically register runmodes
- ::ConfigAuto - Integration with Config::Auto
- ::Config::Context - Integration with Config::Context
- ::Config::General - Integration with Config::General
- ::Config::Simple - Integration with Config::Simple
- ::CompressGzip - Add Gzip compression
- ::DBH - Integration with DBI
- ::LogDispatch - Integration with Log::Dispatch
- ::Session - Integration with CGI::Session
- ::Stream - Help stream files to the browser
- ::TT - Use Template::Toolkit as an alternative to HTML::Template
- ::ValidateRM - Integration with Data::FormValidator and HTML::FillInForm
-
- The following additional changes are also present in this release:
-
- - Enhanced tests and documentation for error_mode(). (Rob Kinyon).
- - Clarified Plug-in documentation (Timothy Appnel)
- - Avoid some warnings when getting run mode from PATH_INFO (Emanuele Zeppieri)
- - Use query() object to get PATH_INFO, to workaround bug in IIS web server. (Mark Stosberg)
- - Documented return value of header_props()
-
-Read the article "Using CGI::Application" on Perl.com for an
-overview of this module and its usage:
-
- http://www.perl.com/pub/a/2001/06/05/cgi.html
-
-
HOW DO I INSTALL IT?
To install this module, cd to the directory that contains this README
@@ -88,4 +51,6 @@
post them to the support mailing list! To join the mailing list, simply
send a blank message to "cgiapp-subscribe at lists.erlbaum.net".
+We also have an IRC channel named #cgiapp on irc.perl.org.
+
Modified: packages/libcgi-application-perl/branches/upstream/current/lib/CGI/Application.pm
===================================================================
--- packages/libcgi-application-perl/branches/upstream/current/lib/CGI/Application.pm 2005-09-22 13:12:23 UTC (rev 1374)
+++ packages/libcgi-application-perl/branches/upstream/current/lib/CGI/Application.pm 2005-09-24 23:59:20 UTC (rev 1375)
@@ -1,11 +1,9 @@
-# $Id: Application.pm,v 1.42 2004/05/12 17:04:08 jesse Exp $
-
package CGI::Application;
use Carp;
use strict;
use Class::ISA;
-$CGI::Application::VERSION = '4.01';
+$CGI::Application::VERSION = '4.03';
my %INSTALLED_CALLBACKS = (
# hook name package sub
@@ -14,6 +12,7 @@
postrun => { 'CGI::Application' => [ 'cgiapp_postrun' ] },
teardown => { 'CGI::Application' => [ 'teardown' ] },
load_tmpl => { },
+ error => { },
);
###################################
@@ -33,16 +32,15 @@
my $self = {};
bless($self, $class);
- ### SET UP DEFAULT VALUES ###
- #
- # We set them up here and not in the setup() because a subclass
- # which implements setup() still needs default values!
+ ### SET UP DEFAULT VALUES ###
+ #
+ # We set them up here and not in the setup() because a subclass
+ # which implements setup() still needs default values!
- $self->header_type('header');
- $self->mode_param('rm');
- $self->start_mode('start');
+ $self->header_type('header');
+ $self->mode_param('rm');
+ $self->start_mode('start');
-
# Process optional new() parameters
my $rprops;
if (ref($args[0]) eq 'HASH') {
@@ -155,6 +153,7 @@
};
if ($@) {
my $error = $@;
+ $self->call_hook('error', $error);
if (my $em = $self->error_mode) {
$body = $self->$em( $error );
} else {
@@ -236,7 +235,6 @@
sub setup {
my $self = shift;
- $self->start_mode('start');
$self->run_modes(
'start' => 'dump_html',
);
@@ -638,6 +636,8 @@
# In "WebApp.pm"...
package WebApp;
use base 'CGI::Application';
+
+ # ( setup() can even be skipped for common cases. See docs below. )
sub setup {
my $self = shift;
$self->start_mode('mode1');
@@ -659,22 +659,17 @@
my $webapp = WebApp->new();
$webapp->run();
+=head1 INTRODUCTION
-=head1 USAGE EXAMPLE
-
CGI::Application is intended to make it easier to create sophisticated,
-reusable web-based applications. This module implements a methodology
-which, if followed, will make your web software easier to design,
+high-performance, reusable web-based applications. This module implements a
+methodology which, if followed, will make your web software easier to design,
easier to document, easier to write, and easier to evolve.
-CGI::Application builds on standard, non-proprietary technologies
-and techniques, such as the Common Gateway Interface and
-Lincoln D. Stein's excellent CGI.pm module. CGI::Application
-judiciously avoids employing technologies and techniques which would
-bind a developer to any one set of tools, operating system or
-web server.
+CGI::Application judiciously avoids employing technologies and techniques which
+would bind a developer to any one set of tools, operating system or web server.
-Following is an example of the typical usage of CGI::Application.
+=head1 USAGE EXAMPLE
Imagine you have to write an application to search through a database
of widgets. Your application has three screens:
@@ -711,7 +706,7 @@
use strict;
# Needed for our database connection
- use DBI;
+ use CGI::Application::Plugin::DBH;
sub setup {
my $self = shift;
@@ -722,15 +717,15 @@
'mode3' => 'showdetail'
);
- # Connect to DBI database
- $self->param('mydbh' => DBI->connect());
+ # Connect to DBI database, with the same args as DBI->connect();
+ $self->dbh_config();
}
sub teardown {
my $self = shift;
- # Disconnect when we're done
- $self->param('mydbh')->disconnect();
+ # Disconnect when we're done, (Although DBI usually does this automatically)
+ $self->dbh->disconnect();
}
sub showform {
@@ -755,7 +750,7 @@
my $self = shift;
# Get our database connection
- my $dbh = $self->param('mydbh');
+ my $dbh = $self->dbh();
# Get CGI query object
my $q = $self->query();
@@ -786,7 +781,7 @@
my $self = shift;
# Get our database connection
- my $dbh = $self->param('mydbh');
+ my $dbh = $self->dbh();
# Get CGI query object
my $q = $self->query();
@@ -841,10 +836,14 @@
Apache is NOT a requirement for CGI::Application. Web applications based on
CGI::Application will run equally well on NT/IIS or any other
-CGI-compatible environment. CGI::Application-based applications
+CGI-compatible environment. CGI::Application-based projects
are, however, ripe for use on Apache/mod_perl servers, as they
-naturally encourage Good Programming Practices. As always, use strict!
+naturally encourage Good Programming Practices and will often work
+in persistent environments without modification.
+For more information on using CGI::Application with mod_perl, please see our
+website at http://www.cgi-app.org/, as well as
+L<CGI::Application::Plugin::Apache>, which integates with L<Apache::Request>.
=head1 DESCRIPTION
@@ -880,7 +879,6 @@
number of built-in methods. The following are those which
are expected to be called from your Instance Script.
-
=over 4
=item new()
@@ -899,14 +897,20 @@
This method may take some specific parameters:
-TMPL_PATH - This optional parameter adds value to the load_tmpl()
-method (specified below). This sets a path using HTML::Template's
-C<path> option when you call load_tmpl() to get your HTML::Template
-object. This run-time parameter allows you to further encapsulate
-instantiating templates, providing potential for more re-usability.
-It can be either a scalar or an array reference of multiple paths.
+B<TMPL_PATH> - This optional parameter defines a path to a directory of templates.
+This is used by the load_tmpl() method (specified below), and may also be used
+for the same purpose by other template plugins. This run-time parameter allows
+you to further encapsulate instantiating templates, providing potential for
+more re-usability. It can be either a scalar or an array reference of multiple
+paths.
-PARAMS - This parameter, if used, allows you to set a number
+B<QUERY> - This optional parameter allows you to specify an
+already-created CGI.pm query object. Under normal use,
+CGI::Application will instantiate its own CGI.pm query object.
+Under certain conditions, it might be useful to be able to use
+one which has already been created.
+
+B<PARAMS> - This parameter, if used, allows you to set a number
of custom parameters at run-time. By passing in different
values in different instance scripts which use the same application
module you can achieve a higher level of re-usability. For instance,
@@ -916,13 +920,21 @@
all use this "Mailform.pm" module, but which set different recipients
or different forms.
-QUERY - This optional parameter allows you to specify an
-already-created CGI.pm query object. Under normal use,
-CGI::Application will instantiate its own CGI.pm query object.
-Under certain conditions, it might be useful to be able to use
-one which has already been created.
+One common use of instance scripts is to provide a path to a config file. This
+design allows you to define project wide configuration objects used by many
+several instance scripts. There are several plugins which simplify the syntax
+for this and provide lazy loading. Here's an example using
+L<CGI::Application::Plugin::ConfigAuto>, which uses L<Config::Auto> to support
+many configuration file formats.
+ my $app = WebApp->new(PARAMS => { cfg_file => 'config.pl' });
+ # Later in your app:
+ my %cfg = $self->cfg()
+ # or ... $self->cfg('HTML_ROOT_DIR');
+
+See the list of of plugins below for more config file integration solutions.
+
=item run()
The run() method is called upon your Application Module object, from
@@ -945,10 +957,19 @@
the specified mode is not found in the run_modes() table, run() will
croak().
+B<Handling unexpected death>
+
If the runmode dies for whatever reason, run() will see if you have set a
value for error_mode(). If you have, run() will call that method
as a run mode, passing $@ as the only parameter.
+Plugins authors will be interested to know that just before C<error_mode()> is
+called, the C<error> hook will be executed, with the error message passed in as
+the only parameter. This hook is still considered experimental, although it is
+unlikely to change.
+
+For a complete integrated logging solution, check out L<CGI::Application::Plugin::LogDispatch>.
+
=back
=head2 Sub-classing and Override Methods
@@ -989,6 +1010,15 @@
$self->param('myprop3', ['p3v1', 'p3v2', 'p3v3']);
}
+However, often times all that needs to be in setup() is defining your run modes
+and your start mode. L<CGI::Application::Plugin::AutoRunmode> allows you to do
+this with a simple syntax, using run mode attributes:
+
+ use CGI::Application::Plugin::AutoRunmode;
+
+ sub show_first : StartRunmode { ... };
+ sub do_next : Runmode { ... }
+
=item teardown()
If implemented, this method is called automatically after your application runs. It
@@ -1008,7 +1038,7 @@
An example of the benefits provided by utilizing this hook is
creating a custom "application super-class" from which which all
-your CGI applications would inherit, instead of CGI::Application.
+your web applications would inherit, instead of CGI::Application.
Consider the following:
@@ -1046,7 +1076,7 @@
Another benefit provided by utilizing this hook is
creating a custom "application super-class" from which all
-your CGI applications would inherit, instead of CGI::Application.
+your web applications would inherit, instead of CGI::Application.
Consider the following:
@@ -1132,20 +1162,15 @@
=item cgiapp_get_query()
-This method is called when CGI::Application retrieves the CGI query object.
+This method is called when CGI::Application retrieves the query object.
The cgiapp_get_query() method loads CGI.pm via "require" and returns a
CGI.pm query object. The implementation is as follows:
sub cgiapp_get_query {
my $self = shift;
- # Include CGI.pm and related modules
require CGI;
-
- # Get the query object
- my $q = CGI->new();
-
- return $q;
+ return CGI->new();
}
You may override this method if you wish to use a different query
@@ -1185,7 +1210,7 @@
print STDERR $webapp->dump();
The dump() method is a debugging function which will return a
-chunk of text which contains all the environment and CGI form
+chunk of text which contains all the environment and web form
data of the request, formatted nicely for human readability.
Useful for outputting to STDERR.
@@ -1195,7 +1220,7 @@
my $output = $webapp->dump_html();
The dump_html() method is a debugging function which will return
-a chunk of text which contains all the environment and CGI form
+a chunk of text which contains all the environment and web form
data of the request, formatted nicely for human readability via
a web browser. Useful for outputting to a browser.
@@ -1204,8 +1229,8 @@
$webapp->error_mode('my_error_rm');
The error_mode contains the name of a run mode to call in the event that the
-planned run mode call fails C<eval>. No error_mode is defined by default.
-The death of your error_mode() run mode is not trapped, so you can also use
+planned run mode call fails C<eval>. No C<error_mode> is defined by default.
+The death of your C<error_mode()> run mode is not trapped, so you can also use
it to die in your own special way.
=item get_current_runmode()
@@ -1296,15 +1321,18 @@
you're working in a slightly more exotic environment), you can set
header_type() to "none". This will completely hide headers.
+
=item load_tmpl()
my $tmpl_obj = $webapp->load_tmpl('some.tmpl');
This method takes the name of a template file and returns an
-HTML::Template object. The HTML::Template->new_file() constructor
-is used for create the object. Refer to L<HTML::Template> for specific usage
-of HTML::Template.
+HTML::Template object. ( For integration with other template systems
+and automated template names, see "Alternatives to load_tmpl() below. )
+The HTML::Template->new_file() constructor is used for create the object.
+Refer to L<HTML::Template> for specific usage of HTML::Template.
+
If tmpl_path() has been specified, load_tmpl() will set the
HTML::Template C<path> option to the path(s) provided. This further
assists in encapsulating template usage.
@@ -1318,14 +1346,33 @@
cache => 1
);
-If your application requires more specialized behavior than this, you have a
-couple of options to replace or extend it. You can replace it by overriding
-load_tmpl() by implementing your own load_tmpl() in your CGI::Application
-sub-class application module.
+B<Alternatives to load_tmpl()>
-You can also extend it by registering a callback that will be executed just before
-load_tmpl() returns:
+If your application requires more specialized behavior than this, you can
+always replace it by overriding load_tmpl() by implementing your own
+load_tmpl() in your CGI::Application sub-class application module.
+First, you may want to check out the template related plugins.
+
+L<CGI::Application::Plugin::AnyTemplate> provides a consistent interface to
+HTML::Template, Template Toolkit, and Petal, automatic default file names, and
+other features. Check this one out first.
+
+L<CGI::Application::Plugin::TT> focuses just on Template Toolkit integration,
+and features pre-and-post features, singleton support and more.
+
+L<CGI::Application::Plugin::Stream> can help if you want to return a stream and
+not a file. It features a simple syntax and MIME-type detection.
+
+
+
+
+
+B<The load_tmpl() callback>
+
+Plugin authors will be intersted to know that you can register a callback that
+will be executed just before load_tmpl() returns:
+
$self->add_callback('load_tmpl',\&your_method);
When C<your_method()> is executed, it will be passed three arguments:
@@ -1425,7 +1472,7 @@
This syntax allows you to easily set the run mode from $ENV{PATH_INFO}. It
will try to set the run mode from the first part of $ENV{PATH_INFO} (before the
-first "/"). To specify that you would rather get the run name from the 2nd
+first "/"). To specify that you would rather get the run mode name from the 2nd
part of $ENV{PATH_INFO}:
$webapp->mode_param( path_info=> 2 );
@@ -1433,6 +1480,11 @@
This also demonstrates that you don't need to pass in the C<param> hash key. It will
still default to C<rm>.
+You can also set C<path_info> to a negative value. This works just like a negative
+list index: if it is -1 the run mode name will be taken from the last part of
+$ENV{PATH_INFO}, if it is -2, the one before that, and so on.
+
+
If no run mode is found in $ENV{PATH_INFO}, it will fall back to looking in the
value of a the CGI form field defined with 'param', as described above. This
allows you to use the convenient $ENV{PATH_INFO} trick most of the time, but
@@ -1482,8 +1534,12 @@
if ( $p{path_info} && $self->query->path_info() ) {
my $pi = $self->query->path_info();
- # computer scientists like to start counting from zero.
- my $idx = $p{path_info} - 1;
+ my $idx = $p{path_info};
+ # two cases: negative or positive index
+ # negative index counts from the end of path_info
+ # positive index needs to be fixed because
+ # computer scientists like to start counting from zero.
+ $idx -= 1 if ($idx > 0) ;
# remove the leading slash
$pi =~ s!^/!!;
@@ -1613,29 +1669,48 @@
=item run_modes()
- $webapp->run_modes('mode1' => 'some_sub_by_name', 'mode2' => \&some_other_sub_by_ref);
+ # The common usage: an arrayref of run mode names that exactly match subroutine names
+ $webapp->run_modes([qw/
+ form_display
+ form_process
+ /]);
-This accessor/mutator expects a hash which specifies the dispatch table for the
-different CGI states. The run() method uses the data in this table
-to send the CGI to the correct function as determined by reading
-the CGI parameter specified by mode_param() (defaults to 'rm' for "Run Mode").
-These functions are referred to as "run mode methods".
+ # With a hashref, use a different name or a code ref
+ $webapp->run_modes(
+ 'mode1' => 'some_sub_by_name',
+ 'mode2' => \&some_other_sub_by_ref
+ );
+This accessor/mutator specifies the dispatch table for the
+application states, using the syntax examples above. It returns
+the dispatch table as a hash.
+
+The run_modes() method may be called more than once. Additional values passed
+into run_modes() will be added to the run modes table. In the case that an
+existing run mode is re-defined, the new value will override the existing value.
+This behavior might be useful for applications which are created via inheritance
+from another application, or some advanced application which modifies its
+own capabilities based on user input.
+
+The run() method uses the data in this table to send the application to the
+correct function as determined by reading the CGI parameter specified by
+mode_param() (defaults to 'rm' for "Run Mode"). These functions are referred
+to as "run mode methods".
+
The hash table set by this method is expected to contain the mode
name as a key. The value should be either a hard reference (a subref)
-to the run mode method which you want to be called when the CGI enters
+to the run mode method which you want to be called when the application enters
the specified run mode, or the name of the run mode method to be called:
'mode_name_by_ref' => \&mode_function
'mode_name_by_name' => 'mode_function'
-The run mode method specified is expected to return a block of text
-(e.g.: HTML) which will eventually be sent back to the web browser.
-The your run mode method may return its block of text as a scalar
-or a scalar-ref.
+The run mode method specified is expected to return a block of text (e.g.:
+HTML) which will eventually be sent back to the web browser. The run mode
+method may return its block of text as a scalar or a scalar-ref.
An advantage of specifying your run mode methods by name instead of
-by reference is that you can more easily create derivative application
+by reference is that you can more easily create derivative applications
using inheritance. For instance, if you have a new application which is
exactly the same as an existing application with the exception of one
run mode, you could simply inherit from that other application and override
@@ -1649,19 +1724,11 @@
your run mode methods by reference and not by name. The speed differences
are generally small, however, so specifying by name is preferred.
-The run_modes() method may be called more than once. Additional values passed
-into run_modes() will be added to the run modes table. In the case that an
-existing run mode is re-defined, the new value will override the existing value.
-This behavior might be useful for applications which are created via inheritance
-from another application, or some advanced application which modifies its
-own capabilities based on user input.
+Specifying the run modes by array reference:
-The run_modes() method also supports a second interface for designating
-run modes and their methods: Via array reference:
-
$webapp->run_modes([ 'mode1', 'mode2', 'mode3' ]);
-This is the same as the following, via hash:
+Is is the same as using a hash, with keys equal to values
$webapp->run_modes(
'mode1' => 'mode1',
@@ -1816,6 +1883,10 @@
=item *
+L<CGI::Application::Plugin::FillInForm> - Integration with L<HTML::FillInForm>.
+
+=item *
+
L<CGI::Application::Plugin::LogDispatch> - Integration with L<Log::Dispatch>
=item *
@@ -1828,6 +1899,12 @@
=item *
+L<CGI::Application::Plugin::TemplateRunner> - Allows for more of an ASP-style
+code structure, with the difference that code and HTML for each screen are in
+seperate files.
+
+=item *
+
L<CGI::Application::Plugin::TT> - Use L<Template::Toolkit> as an alternative to HTML::Template.
=item *
@@ -2117,7 +2194,7 @@
=head1 COMMUNITY
-There a couple of primary resources available for those who wish to learn more
+Therese are primary resources available for those who wish to learn more
about CGI::Application and discuss it with others.
B<Wiki>
@@ -2134,11 +2211,30 @@
post them to the support mailing list! To join the mailing list, simply
send a blank message to "cgiapp-subscribe at lists.erlbaum.net".
+B<IRC>
+
+You can also drop by C<#cgiapp> on C<irc.perl.org> with a good chance of finding
+some people involved with the project there.
+
=head1 SEE ALSO
-L<CGI>, L<HTML::Template>, L<CGI::Application::ValidateRM> perl(1)
+=over 4
+=item o
+L<CGI>
+
+=item o
+
+L<HTML::Template>
+
+=item o
+
+B<CGI::Application::Framework> - A full-featured web application based on
+CGI::Application. http://www.cafweb.org/
+
+=back
+
=head1 AUTHOR
Jesse Erlbaum <jesse at erlbaum.net>
Modified: packages/libcgi-application-perl/branches/upstream/current/t/11callbacks.t
===================================================================
--- packages/libcgi-application-perl/branches/upstream/current/t/11callbacks.t 2005-09-22 13:12:23 UTC (rev 1374)
+++ packages/libcgi-application-perl/branches/upstream/current/t/11callbacks.t 2005-09-24 23:59:20 UTC (rev 1375)
@@ -178,7 +178,8 @@
######################################
{
package My::Framework;
- use base 'CGI::Application';
+ use vars qw/@ISA/;
+ @ISA = ('CGI::Application');
sub cgiapp_init { main::record_event('init') }
sub cgiapp_prerun { main::record_event('prerun') }
sub cgiapp_postrun { main::record_event('postrun') }
@@ -188,7 +189,8 @@
######################################
{
package My::Project;
- use base 'My::Framework';
+ use vars qw/@ISA/;
+ @ISA = ('My::Framework');
import CGI::Application::Plugin::Foo;
# install another init callback for all users of My::Project
@@ -206,7 +208,8 @@
######################################
{
package Other::Project;
- use base 'My::Framework';
+ use vars qw/@ISA/;
+ @ISA = ('My::Framework');
import CGI::Application::Plugin::Baz;
import CGI::Application::Plugin::Bam;
@@ -225,7 +228,8 @@
######################################
{
package My::App;
- use base 'My::Project';
+ use vars qw/@ISA/;
+ @ISA = ('My::Project');
import CGI::Application::Plugin::Bar;
sub setup {
@@ -258,7 +262,8 @@
######################################
{
package Other::App;
- use base 'Other::Project';
+ use vars qw/@ISA/;
+ @ISA = 'Other::Project';
import CGI::Application::Plugin::Bam;
@@ -286,7 +291,8 @@
{
package Unrelated::App;
- use base 'CGI::Application';
+ use vars qw/@ISA/;
+ @ISA = ('CGI::Application');
sub setup {
my $self = shift;
Added: packages/libcgi-application-perl/branches/upstream/current/t/mode_param_overwritten.t
===================================================================
--- packages/libcgi-application-perl/branches/upstream/current/t/mode_param_overwritten.t 2005-09-22 13:12:23 UTC (rev 1374)
+++ packages/libcgi-application-perl/branches/upstream/current/t/mode_param_overwritten.t 2005-09-24 23:59:20 UTC (rev 1375)
@@ -0,0 +1,20 @@
+# This is for a bug introduced in 4.02 where mode_param
+# didn't work if it was set in a sub-class.
+
+package My::CA;
+use base 'CGI::Application';
+
+sub cgiapp_init {
+ my $self = shift;
+ $self->mode_param('mine');
+}
+
+
+package main;
+use Test::More qw/no_plan/;
+
+{
+ my $app = My::CA->new();
+ is( $app->mode_param, 'mine', "setting mode_param in a sub-class works");
+}
+
Modified: packages/libcgi-application-perl/branches/upstream/current/t/mode_param_path_info.t
===================================================================
--- packages/libcgi-application-perl/branches/upstream/current/t/mode_param_path_info.t 2005-09-22 13:12:23 UTC (rev 1374)
+++ packages/libcgi-application-perl/branches/upstream/current/t/mode_param_path_info.t 2005-09-24 23:59:20 UTC (rev 1375)
@@ -1,4 +1,4 @@
-use Test::More tests=>12;
+use Test::More tests=>14;
# Include the test hierarchy
use lib './test';
@@ -62,3 +62,15 @@
eval { $out = $app->run() };
is($@, '', 'avoided eval() death');
like($out,qr/Hello World/, $test_name);
+
+####
+
+$test_name = "mode_param( path_info => -2 ), expecting success ";
+$ENV{PATH_INFO} = '/my_ses_id/basic_test1/foo';
+ $app = TestApp5->new( QUERY => $q );
+$app->mode_param( path_info => -2, );
+eval { $out = $app->run() };
+is($@, '', 'avoided eval() death');
+like($out,qr/Hello World/, $test_name);
+
+####
More information about the Pkg-perl-cvs-commits
mailing list