/ 
CGI-Application-Demo-Dispatch-1.05
River stage zero No dependents
/ CGI::Application::Demo::Dispatch

NAME

CGI::Application::Demo::Dispatch - Demonstrate the delights of CGI::Application::Dispatch

Synopsis

A classic CGI script:

	use strict;
	use warnings;

	use CGI;
	use CGI::Application::Dispatch;

	# ---------------------

	my($cgi) = CGI -> new();

	CGI::Application::Dispatch -> dispatch
	(
		args_to_new => {QUERY => $cgi},
 		prefix      => 'CGI::Application::Demo::Dispatch',
 		table       =>
		[
 		''         => {app => 'Menu', rm => 'display'},
 		':app'     => {rm => 'initialize'},
 		':app/:rm' => {},
		],
	);

A Plack script:

#!/usr/bin/env perl
#
# Run with:
# starman -l 127.0.0.1:5021 --workers 1 httpd/cgi-bin/cgi/application/demo/dispatch/dispatch.psgi &
# or, for more debug output:
# plackup -l 127.0.0.1:5021 httpd/cgi-bin/cgi/application/demo/dispatch/dispatch.psgi &

use strict;
use warnings;

use CGI::Application::Dispatch::PSGI;

use Plack::Builder;

# ---------------------

my($app) = CGI::Application::Dispatch -> as_psgi
(
	 prefix      => 'CGI::Application::Demo::Dispatch',
	 table       =>
	 [
	  ''         => {app => 'Menu', rm => 'display'},
	  ':app'     => {rm => 'initialize'},
	  ':app/:rm' => {},
	 ],
);

builder
{
	enable "Plack::Middleware::Static",
	path => qr!^/(assets|favicon|yui)/!,
	root => '/dev/shm/html';
	$app;
};

A modern FCGI script:

use strict;
use warnings;

use CGI::Application::Dispatch;
use CGI::Fast;
use FCGI::ProcManager;

# ---------------------

my($proc_manager) = FCGI::ProcManager -> new({n_processes => 2});

$proc_manager -> pm_manage();

my($cgi);

while ($cgi = CGI::Fast -> new() )
{
	$proc_manager -> pm_pre_dispatch();

	CGI::Application::Dispatch -> dispatch
	(
	 args_to_new => {QUERY => $cgi},
	 prefix      => 'CGI::Application::Demo::Dispatch',
	 table       =>
	 [
	  ''         => {app => 'Menu', rm => 'display'},
	  ':app'     => {rm => 'initialize'},
	  ':app/:rm' => {},
	 ],
	);

	$proc_manager -> pm_post_dispatch();
}

Description

CGI::Application::Demo::Dispatch demonstrates the delights CGI::Application::Dispatch.

It ships with:

Two instance scripts: dispatch.cgi and dispatch

dispatch.cgi is a trivial CGI script, while dispatch is a fancy script which uses FCGI::ProcManager.

Both use CGI::Application::Dispatch.

Trivial here refers to using a classic CGI-style script, while fancy refers to using a modern FCGID-style script.

The word fancy was chosen because it allows you to use fancier URLs. For samples, see Start Testing, below.

The scripts are shipped as ./httpd/cgi-bin/dispatch.cgi and ./htdocs/local/dispatch.

These directory names were chosen because you'll be installing dispatch.cgi in your web server's cgi-bin/ directory, whereas you'll install dispatch in a directory under your web server's doc root.

For home-grown modules, I use the namespace Local::*, and for local web server scripts I use the directory local/ under Apache's doc root.

For FCGID, see http://fastcgi.coremail.cn/.

FCGID is a replacement for the older FastCGI. For FastCGI, see http://www.fastcgi.com/drupal/.

Also, edit dispatch.cgi and dispatch to fix the 'use lib' line. See the Note in those files for details.

A set of HTML::Template templates: *.tmpl

See ./htdocs/assets/templates/cgi/application/demo/dispatch/*.

A patch to httpd.conf, if you run Apache and FCGID.

See ./httpd/conf/httpd.conf.

Yes, I realise that if you run FCGID you already have this patch installed, but there's nothing wrong with having such information documented in various places.

This Perl module: CGI::Application::Demo::Dispatch

Distributions

This module is available as a Unix-style distro (*.tgz).

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing distros.

Installation

All these assume your doc root is /dev/shm/html (/dev/shm/ is Debian's RAM disk). This really should be read from a config file. See Base.pm line 18.

You will need to patch CGI::Application::Demo::Dispatch::Base, since it where HTML::Template's tmpl_path is stored, if using another path.

Install the module

Note: Build.PL and Makefile.PL refer to FCGI::ProcManager. If you are not going to use the fancy script, you don't need FCGI::ProcManager.

Install CGI::Application::Demo::Dispatch as you would for any Perl module:

Run cpan: shell>sudo cpan CGI::Application::Demo::Dispatch

or unpack the distro, and then either:

perl Build.PL
./Build
./Build test
sudo ./Build install

or:

perl Makefile.PL
make (or dmake)
make test
make install

Install the HTML::Template files.

Copy the distro's ./htdocs/assets/ directory to your doc root.

Install the trivial instance script

Copy the distro's ./httpd/cgi-bin/dispatch.cgi to your cgi-bin/ directory, and make dispatch.cgi executable.

Install the fancy instance script

Copy the distro's ./htdocs/local/ directory to your doc root, and make dispatch executable.

Configure Apache to use /local/dispatch

If in fancy mode, add these to Apache's httpd.conf:

LoadModule fcgid_module modules/mod_fcgid.so

and:

<Location /local>
	SetHandler fcgid-script
	Options ExecCGI
	Order deny,allow
	Deny from all
	Allow from 127.0.0.1
</Location>

Note: My use of '/local' is not mandatory; you could use any URL fragment there.

And don't forget to restart Apache after editing it's httpd.conf.

Start testing

Point your broswer at http://127.0.0.1/cgi-bin/dispatch.cgi (trivial script), or http://127.0.0.1/local/dispatch (fancy script).

Author

CGI::Application::Demo::Dispatch was written by Ron Savage <ron@savage.net.au> in 2009.

Home page: http://savage.net.au/index.html

Copyright

Australian copyright (c) 2009, Ron Savage. All Programs of mine are 'OSI Certified Open Source Software'; you can redistribute them and/or modify them under the terms of The Artistic License, a copy of which is available at: http://www.opensource.org/licenses/index.html