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

cpanm CGI::Application::Demo::Dispatch

perl -MCPAN -e shell
install CGI::Application::Demo::Dispatch