NAME

Apache2::Controller::Dispatch - dispatch base class for Apache::Controller

SYNOPSIS

# vhost.conf:
PerlModule MyApp::Dispatch

<Location />
    SetHandler modperl
    PerlOptions +SetupEnv
    PerlInitHandler MyApp::Dispatch
</Location>

# lib/MyApp/Dispatch:

package MyApp::Dispatch;

use strict;
use warnings FATAL => 'all';

use base qw( Apache2::Controller::Dispatch::Simple );

our %dispatch_map = (
    foo        => 'MyApp::C::Foo',
    bar        => 'MyApp::C::Bar',
    biz        => 'MyApp::C::Biz',
    'biz/baz'  => 'MyApp::C::Biz::Baz',
);

sub handler { Apache2::Controller::Dispatch::handler(@_) } # required

1;

DESCRIPTION

Apache2::Controller::Dispatch forms the base for the PerlInitHandler module to dispatch incoming requests to libraries based on their URL.

Natively, this does not try to figure out the appropriate module using any complex magic. Instead, you spell out the uris under the root handler location and what controller modules you want to handle paths under that URL.

You do not absolutely need to implement any methods in your dispatch class. Instead, use multiple bases that add features which will be called by the process() method in proper sequence. Caveat: some of the other dispatch base modules, like Apache2::Controller::Session::Cookie require that you implement certain methods, for example in that case, to access your database.

The handler subroutine that kicks up to Apache::Controller::Dispatch is essential here, otherwise there is no way for that module to know the class name of your dispatch module.

METHODS

$handler->init()

You can limit HTTP methods in your child class:

package MyApp::Dispatch;
use base qw( Apache2::Controller::Dispatch );
my @LIMIT_HTTP_METHODS = qw( GET POST ); # but not HEAD or PUT, etc

This gets processed by init() which is run from Apache2::Controller::NonResponseBase if the method is available.

$handler->process()

process() is the main guts of Apache2::Controller::Dispatch logic. It calls $self->find_controller(), which is implemented in another base class. (See Apache2::Controller::Dispatch::Simple.) If that works, then it creates an Apache2::Request object from $r, which will supposedly parse the query string once for all further handlers that create Apache2::Request objects.

EXAMPLE

# configuration for <Location>:
# PerlInitHandler MyApp::Dispatch

package MyApp::Dispatch;
use base qw( 
    Apache2::Controller::Dispatch
    Apache2::Controller::Dispatch::Simple
);

my @LIMIT_HTTP_METHODS = qw( GET );

our %dispatch_map = (
    foo        => 'MyApp::C::Foo',
    bar        => 'MyApp::C::Bar',
    biz        => 'MyApp::C::Biz',
);

1;

SEE ALSO

Apache2::Controller::Dispatch::Simple, Apache2::Controller

AUTHOR

Mark Hedges, <hedges at scriptdolphin.org>

COPYRIGHT & LICENSE

Copyright 2008 Mark Hedges, all rights reserved.

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