Out of Box

  # change "Apache1" to "Apache2" as needed.

  <Location />
  SetHandler perl-script
  PerlHandler Plack::Handler::Apache1
  PerlSetVar psgi_app /path/to/app.psgi
  </Location>

  <Perl>
  use Plack::Handler::Apache1;
  Plack::Handler::Apache1->preload("/path/to/app.psgi");
  </Perl>

Under CGI:

This would be the instance script for your application, such as /cgi-bin/dispatch.cgi:

    ### in your dispatch.psgi:
    # ( in a persistent environment, use FindBin::Real instead. )
    use FindBin 'Bin';
    use lib "$Bin/../perllib';
    use Your::Application::Dispatch;
    Your::Application::Dispatch->as_psgi;

    ### In Your::Application::Dispatch;
    package Your::Application::Dispatch;
    use base 'CGI::Application::Dispatch::PSGI';

With a dispatch table

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

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

The ".psgi" file is constructed as above.

With a custom query object

    sub {
        my $env = shift;
        my $app = CGI::Application::Dispatch::PSGI->as_psgi(
            table => [
                '/:rm'    =>    { app => 'TestApp' }
            ],
            args_to_new => {
                QUERY    => CGI::PSGI->new($env)
            }
        );
        return $app->($env);
    }

as_psgi(%args)

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

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

This method accepts the following name value pairs:

default

Specify a value to use for the path if one is not available. 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 its 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.

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".

dispatch_args()

    {
        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($input)

The following transformations are performed on the input:

The text is split on '_'s (underscores) and each word has its 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 its 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)

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

VOCABULARY

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 slashes "/". Anything set of characters between slashes is called a "token".

URL MATCHING

A rule consists of slashes 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 slash. 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 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.

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

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

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

Getting the module name

    /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 powerful 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

    /module_name/mode2

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

mod_rewrite related code in the dispatch script.

  # mod_rewrite alters the PATH_INFO by turning it into a file system path,
  # so we repair it.
  $ENV{PATH_INFO} =~ s/^$ENV{DOCUMENT_ROOT}// 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

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>