/ 
CGI-Application-Dispatch-2.10_02
River stage two • 9 direct dependents • 11 total dependents
/ CGI::Application::Dispatch

NAME

CGI::Application::Dispatch - Dispatch requests to CGI::Application based objects

SYNOPSIS

Out of Box

Under mod_perl

<Location /app>
    SetHandler perl-script
    PerlHandler CGI::Application::Dispatch
</Location>

Under normal cgi

#!/usr/bin/perl
use strict;
use CGI::Application::Dispatch;
CGI::Application::Dispatch->dispatch();

With a dispatch table

package MyApp::Dispatch;
use base 'CGI::Application::Dispatch';

sub dispatch_args {
    return {
        prefix  => 'MyApp',
        table   => [
            ''                => { app => 'Welcome', rm => 'start' },
            ':app/:rm'        => { },
            'admin/:app/:rm'  => { prefix   => 'MyApp::Admin' },
        ],
    };
}

Under mod_perl

<Location /app>
    SetHandler perl-script
    PerlHandler MyApp::Dispatch
</Location>

Under normal cgi

#!/usr/bin/perl
use strict;
use MyApp::Dispatch;
MyApp::Dispatch->dispatch();

DESCRIPTION

This module provides a way (as a mod_perl handler or running under vanilla CGI) to look at the path ($r->path_info or $ENV{PATH_INFO}) of the incoming request, parse off the desired module and it's run mode, create an instance of that module and run it.

It currently supports both generations of mod_perl (1.x and 2.x). Although, for simplicity, all examples involving Apache configuration and mod_perl code will be shown using mod_perl 1.x. This may change as mp2 usage increases.

It will translate a URI like this (under mod_perl):

/app/module_name/run_mode

or this (vanilla cgi)

/app/index.cgi/module_name/run_mode

into something that will be functionally similar to this

my $app = Module::Name->new(..);
$app->mode_param(sub {'run_mode'}); #this will set the run mode

METHODS

dispatch()

This is the primary method used during dispatch. Even under mod_perl, the handler method uses this under the hood.

#!/usr/bin/perl
use strict;
use CGI::Application::Dispatch;

CGI::Application::Dispatch->dispatch(
    prefix  => 'MyApp',
    default => 'module_name',
);

This method accepts the following name value pairs:

default

Specify a value to use in place of PATH_INFO if PATH_INFO is not provided. This could be the case if the default page is selected (eg: "/" ).

prefix

This option will set the string that will be prepended to the name of the application module before it is loaded and created. So to use our previous example request of

/app/index.cgi/module_name/run_mode

This would by default load and create a module named 'Module::Name'. But let's say that you have all of your application specific modules under the 'My' namespace. If you set this option to 'My' then it would instead load the 'My::Module::Name' application module instead.

args_to_new

This is a hash of arguments that are passed into the new() constructor of the application.

table

In most cases, simply using Dispatch with the default and prefix is enough to simplify your application and your URLs, but there are many cases where you want more power. Enter the dispatch table. Since this table can be slightly complicated, a whole section exists on it's use. Please see the "DISPATCH TABLE" section.

debug

Set to a true value to send debugging output for this module to STDERR. Off by default.

not_found

This is a URI to which the application will be redirected if the incoming request's PATH_INFO does not match anything in the "DISPATCH TABLE". This will also be used if there was a match, but the module could not be loaded, or the run mode did not exist.

If this value is not present, then Dispatch will return a NOT FOUND error either to the browser (under CGI) or to Apache (under mod_perl).

auto_rest

This tells Dispatch that you are using REST by default and that you care about which HTTP method is being used. Dispatch will append the HTTP method name (upper case by default) to the run mode that is determined after finding the appropriate dispatch rule. So a GET request that translates into MyApp::Module-foo> will become MyApp::Module-foo_GET>.

This can be overridden on a per-rule basis in a custom dispatch table.

auto_rest_lc

In combinaion with auto_rest this tells Dispatch that you prefer lower cased HTTP method names. So instead of foo_POST and foo_GET you'll have foo_post and foo_get.

handler()

This method is used so that this module can be run as a mod_perl handler. When it creates the application module it passes the $r argument into the PARAMS hash of new()

<Location /app>
    SetHandler perl-script
    PerlHandler CGI::Application::Dispatch
    PerlSetVar  CGIAPP_DISPATCH_PREFIX  MyApp
    PerlSetVar  CGIAPP_DISPATCH_DEFAULT /module_name
</Location>

The above example would tell apache that any url beginning with /app will be handled by CGI::Application::Dispatch. It also sets the prefix used to create the application module to 'MyApp' and it tells CGI::Application::Dispatch that it shouldn't set the run mode but that it will be determined by the application module as usual (through the query string). It also sets a default application module to be used if there is no PATH_INFO. So, a url of /app/module_name would create an instance of MyApp::Module::Name.

Using this method will add the Apache-request> object to your application's PARAMS as 'r'.

# inside your app
my $request = $self->param('r');

If you need more customization than can be accomplished with just prefix and default, then it would be best to just subclass CGI::Application::Dispatch and override dispatch_args since this method uses dispatch to do the heavy lifting.

package MyApp::Dispatch;
use base 'CGI::Application::Dispatch';

sub dispatch_args {
    return {
        prefix  => 'MyApp',
        table   => [
            ''                => { app => 'Welcome', rm => 'start' },
            ':app/:rm'        => { },
            'admin/:app/:rm'  => { prefix   => 'MyApp::Admin' },
        ],
        args_to_new => {
            PARAMS => {
                foo => 'bar',
                baz => 'bam',
            },
        }
    };
}

1;

And then in your httpd.conf

<Location /app>
    SetHandler perl-script
    PerlHandler MyApp::Dispatch
</Location>

dispatch_args

Returns a hashref of args that will be passed to dispatch(). It will return the following structure by default.

{
    prefix      => '',
    args_to_new => {},
    table       => [
        ':app'      => {},
        ':app/:rm'  => {},
    ],
}

This is the perfect place to override when creating a subclass to provide a richer dispatch table.

When called, it receives 1 argument, which is a reference to the hash of args passed into dispatch.

translate_module_name

This method is used to control how the module name is translated from the matching section of the PATH_INFO (see "PATH_INFO Parsing". The main reason that this method exists is so that it can be overridden if it doesn't do exactly what you want.

The following transformations are performed on the input:

The text is split on '_'s (underscores) and each word has it's first letter capitalized. The words are then joined back together and each instance of an underscore is replaced by '::'.
The text is split on '-'s (hyphens) and each word has it's first letter capitalized. The words are then joined back together and each instance of a hyphen removed.

Here are some examples to make it even clearer:

module_name         => Module::Name
module-name         => ModuleName
admin_top-scores    => Admin::TopScores

require_module($module_name)

This class method is used internally by CGI::Application::Dispatch to take a module name (supplied by get_module_name) and require it in a secure fashion. It is provided as a public class method so that if you override other functionality of this module, you can still safely require user specified modules. If there are any problems requiring the named module, then we will croak.

CGI::Application::Dispatch->require_module('MyApp::Module::Name');

DISPATCH TABLE

Sometimes it's easiest to explain with an example, so here you go:

CGI::Application::Dispatch->dispatch(
  prefix      => 'MyApp',
  args_to_new => {
      TMPL_PATH => 'myapp/templates'
  },
  table       => [
      ''                         => { app => 'Blog', rm => 'recent'},
      'posts/:category'          => { app => 'Blog', rm => 'posts' },
      ':app/:rm/:id'             => { app => 'Blog' },
      'date/:year/:month?/:day?' => {
          app         => 'Blog',
          rm          => 'by_date',
          args_to_new => { TMPL_PATH = "events/" },
      },
  ]
);

So first, this call to dispatch set's the prefix and passes a TMPL_PATH into args_to_new. Next it sets the table.

VOCABULARY

Just so we all understand what we're talking about....

A table is an array where the elements are gouped as pairs (similar to a hash's key-value pairs, but as an array to preserve order). The first element of each pair is called a rule. The second element in the pair is called the rule's arg list. Inside a rule there are backslashes /. Anything set of characters between backslashes is called a token.

URL MATCHING

When a URL comes in, Dispatch tries to match it against each rule in the table in the order in which the rules are given. The first one to match wins.

A rule consists of backslashes and tokens. A token can one of the following types:

literal

Any token which does not start with a colon (:) is taken to be a literal string and must appear exactly as-is in the URL in order to match. In the rule

'posts/:category'

posts is a literal token.

variable

Any token which begins with a colon (:) is a variable token. These are simply wild-card place holders in the rule that will match anything in the URL that isn't a backslash. These variables can later be referred to by using the $self->param mechanism. In the rule

'posts/:category'

:category is a variable token. If the URL matched this rule, then you could retrieve the value of that token from whithin your application like so:

my $category = $self->param('category');

There are some variable tokens which are special. These can be used to further customize the dispatching.

:app

This is the module name of the application. The value of this token will be sent to the translate_module_name method and then prefixed with the prefix if there is one.

:rm

This is the run mode of the application. The value of this token will be the actual name of the run mode used.

optional-variable

Any token which begins with a colon (:) and ends with a question mark (<?>) is considered optional. If the rest of the URL matches the rest of the rule, then it doesn't matter whether it contains this token or not. It's best to only include optional-variable tokens at the end of your rule. In the rule

'date/:year/:month?/:day?'

:month? and :day? are optional-variable tokens.

Just like with variable tokens, optional-variable tokens' values can also be retrieved by the application, if they existed in the URL.

if( defined $self->param('month') ) {
    ...
}
wildcard

The wildcard token "*" allows for partial matches. The token MUST appear at the end of the rule.

'posts/list/*'

By default, the dispatch_url_remainder param is set to the remainder of the URL matched by the *. The name of the param can be changed by setting "*" argument in the "ARG LIST".

'posts/list/*' => { '*' => 'post_list_filter' }
method

You can also dispatch based on HTTP method. This is similar to using auto_rest but offers more fine grained control. You include the method (case insensitive) at the end of the rule and enclose it in square brackets.

':app/news[post]'   => { rm => 'add_news'    },
':app/news[get]'    => { rm => 'news'        },
':app/news[delete]' => { rm => 'delete_news' },

The main reason that we don't use regular expressions for dispatch rules is that regular expressions provide no mechanism for named back references, like variable tokens do.

ARG LIST

Each rule can have an accompanying arg-list. This arg list can contain special arguments that override something set higher up in dispatch for this particular URL, or just have additional args passed available in $self->param()

For instance, if you want to override prefix for a specific rule, then you can do so.

'admin/:app/:rm' => { prefix => 'MyApp::Admin' },

PATH_INFO Parsing

This section will describe how the application module and run mode are determined from the PATH_INFO if no "DISPATCH TABLE" is present, and what options you have to customize the process.

Getting the module name

To get the name of the application module the PATH_INFO is split on backslahes (/). The second element of the returned list is used to create the application module. So if we have a path info of

/module_name/mode1

then the string 'module_name' is used. This is passed through the translate_module_name method. Then if there is a prefix (and there should always be a prefix) it is added to the beginning of this new module name with a double colon :: separating the two.

If you don't like the exact way that this is done, don't fret you do have a couple of options. First, you can specify a "DISPATCH TABLE" which is much more powerfule and flexible (in fact this default behavior is actually implemented internally with a dispatch table). Or if you want something a little simpler, you can simply subclass and extend the translate_module_name method.

Getting the run mode

Just like the module name is retrieved from splitting the PATH_INFO on backslashes, so is the run mode. Only instead of using the second element of the resulting list, we use the third as the run mode. So, using the same example, if we have a path info of

/module_name/mode2

Then the string 'mode2' is used as the run mode.

MISC NOTES

  • CGI query strings

    CGI query strings are unaffected by the use of PATH_INFO to obtain the module name and run mode. This means that any other modules you use to get access to you query argument (ie, CGI, Apache::Request) should not be affected. But, since the run mode may be determined by CGI::Application::Dispatch having a query argument named 'rm' will be ignored by your application module.

CLEAN URLS WITH MOD_REWRITE

With a dispatch script, you can fairly clean URLS like this:

/cgi-bin/dispatch.cgi/module_name/run_mode

However, including "/cgi-bin/dispatch.cgi" in ever URL doesn't add any value to the URL, so it's nice to remove it. This is easily done if you are using the Apache web server with mod_rewrite available. Adding the following to a .htaccess file would allow you to simply use:

/module_name/run_mode

If you have problems with mod_rewrite, turn on debugging to see exactly what's happening:

RewriteLog /home/project/logs/alpha-rewrite.log
RewriteLogLevel 9

This seemed necessary to put in the dispatch script to make mod_rewrite happy. Perhaps it's specific to using RewriteBase. Refactorings welcome!

# mod_rewrite alters the PATH_INFO by turning it into a file system path,
# so we repair it.
use FindBin qw/$Bin/;
use Cwd 'abs_path';
chdir $Bin;
# Location of the www root in relation to the dispatcher. (Adjust as needed!)
my $www = abs_path("../");
# fix /home versus /usr/home difference
$www =~ s{/usr}{};

# the final removal of the file system stuff mod_rewrite added.
# PATH_INFO won't defined if "/" is requested.
$ENV{PATH_INFO} =~ s/^$www//g if defined $ENV{PATH_INFO};

Simple Apache Example

RewriteEngine On

# You may want to change the base if you are using the dispatcher within a
# specific directory.
RewriteBase /

# If an actual file or directory is requested, serve directly
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d

# Otherwise, pass everything through to the dispatcher
RewriteRule ^(.*)$ /cgi-bin/dispatch.cgi/$1 [L,QSA]

More complex rewrite: dispatching "/" and multiple developers

Here is a more complex example that dispatches "/", which would otherwise be treated as a directory, and also supports multiple developer directories, so /~mark has its own seperate dispatching system beneath it.

Note that order matters here! The Location block for "/" needs to come before the user blocks.

<Location />
  RewriteEngine On
  RewriteBase /

  # Run "/" through the dispatcher
  RewriteRule ^home/project/www/$ /cgi-bin/dispatch.cgi [L,QSA]

  # Don't apply this rule to the users sub directories.
  RewriteCond %{REQUEST_URI} !^/~.*$
  # If an actual file or directory is requested, serve directly
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  # Otherwise, pass everything through to the dispatcher
  RewriteRule ^(.*)$ /cgi-bin/dispatch.cgi/$1 [L,QSA]
</Location>

<Location /~mark>
  RewriteEngine On
  RewriteBase /~mark

  # Run "/" through the dispatcher
  RewriteRule ^/home/mark/www/$ /~mark/cgi-bin/dispatch.cgi [L,QSA]

   # Otherwise, if an actual file or directory is requested, serve directly
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d

   # Otherwise, pass everything through to the dispatcher
  RewriteRule ^(.*)$ /~mark/cgi-bin/dispatch.cgi/$1 [L,QSA]

  # These examples may also be helpful, but are unrelated to dispatching.
  SetEnv DEVMODE mark
  SetEnv PERL5LIB /home/mark/perllib:/home/mark/config
  ErrorDocument 404 /~mark/errdocs/404.html
  ErrorDocument 500 /~mark/errdocs/500.html
</Location>

SUBCLASSING

While Dispatch tries to be flexible, it won't be able to do everything that people want. Hopefully we've made it flexible enough so that if it doesn't do The Right Thing you can easily subclass it.

AUTHOR

Michael Peters <mpeters@plusthree.com>

Thanks to Plus Three, LP (http://www.plusthree.com) for sponsoring my work on this module

COMMUNITY

This module is a part of the larger CGI::Application community. If you have questions or comments about this module then please join us on the cgiapp mailing list by sending a blank message to "cgiapp-subscribe@lists.erlbaum.net". There is also a community wiki located at http://www.cgi-app.org/

CONTRIBUTORS

  • Shawn Sorichetti

  • Timothy Appnel

  • dsteinbrunner

  • ZACKSE

  • Stew Heckenberg

  • Drew Taylor <drew@drewtaylor.com>

  • James Freeman <james.freeman@smartsurf.org>

  • Michael Graham <magog@the-wire.com>

  • Cees Hek <ceeshek@gmail.com>

  • Mark Stosberg <mark@summersault.com>

  • Viacheslav Sheveliov <slavash@aha.ru>

SECURITY

Since C::A::Dispatch will dynamically choose which modules to use as the content generators, it may give someone the ability to execute random modules on your system if those modules can be found in you path. Of course those modules would have to behave like CGI::Application based modules, but that still opens up the door more than most want. This should only be a problem if you don't use a prefix. By using this option you are only allowing Dispatch to pick from a namespace of modules to run.

SEE ALSO

CGI::Application, Apache::Dispatch

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.