View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Ron Savage > CGI-Application-Demo-Dispatch > CGI::Application::Demo::Dispatch



Annotate this POD

View/Report Bugs
Module Version: 1.05   Source  


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 --workers 1 httpd/cgi-bin/cgi/application/demo/dispatch/dispatch.psgi &
        # or, for more debug output:
        # plackup -l 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' => {},

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

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();


        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

FCGID is a replacement for the older FastCGI. For FastCGI, see

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 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 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 test
        sudo ./Build install


        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/


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

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 (trivial script), or (fancy script).

Author ^

CGI::Application::Demo::Dispatch was written by Ron Savage <> in 2009.

Home page:

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:

syntax highlighting: