view release on metacpan or  search on metacpan

lib/CGI/Snapp/Dispatch.pm  view on Meta::CPAN

1;

=pod

=head1 NAME

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

=head1 Synopsis

=head2 CGI Scripts

Here is a minimal CGI instance script. I<Note the call to new()!>

	#!/usr/bin/env perl

	use CGI::Snapp::Dispatch;

	CGI::Snapp::Dispatch -> new -> dispatch;

(The use of new() is discussed in detail under L</PSGI Scripts>, just below.)

But, to override the default dispatch table, you probably want something like this:

MyApp/Dispatch.pm:

	package MyApp::Dispatch;
	parent 'CGI::Snapp::Dispatch';

	sub dispatch_args
	{
		my($self) = @_;

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

And then you can write ...  I<Note the call to new()!>

	#!/usr/bin/env perl

	use MyApp::Dispatch;

	MyApp::Dispatch -> new -> dispatch;

=head2 PSGI Scripts

Here is a PSGI script in production on my development machine. I<Note the call to new()!>

	#!/usr/bin/env perl
	#
	# Run with:
	# starman -l 127.0.0.1:5020 --workers 1 httpd/cgi-bin/local/wines.psgi &
	# or, for more debug output:
	# plackup -l 127.0.0.1:5020 httpd/cgi-bin/local/wines.psgi &

	use strict;
	use warnings;

	use CGI::Snapp::Dispatch;

	use Plack::Builder;

	# ---------------------

	my($app) = CGI::Snapp::Dispatch -> new -> as_psgi
	(
		prefix => 'Local::Wines::Controller', # A sub-class of CGI::Snapp.
		table  =>
		[
		''              => {app => 'Initialize', rm => 'display'},
		':app'          => {rm => 'display'},
		':app/:rm/:id?' => {},
		],
	);

	builder
	{
		enable "ContentLength";
		enable "Static",
		path => qr!^/(assets|favicon|yui)!,
		root => '/dev/shm/html'; # /dev/shm/ is Debian's RAM disk.
		$app;
	};

I<Warning!> The line my($app) = ... contains a call to L</new()>. This is definitely not the same as if you
were using L<CGI::Application::Dispatch> or L<CGI::Application::Dispatch::PSGI>. They look like this:

	my($app) = CGI::Application::Dispatch -> as_psgi

The lack of a call to new() there tells you I've implemented something very similar but different.
You have been warned...

The point of this difference is that new() returns an object, and passing that into L</as_psgi(@args)> as $self
allows the latter method to be much more sophisticated than it would otherwise be. Specifically, it can now share
a lot of code with L</dispatch(@args)>.

Lastly, if you want to use regexps to match the path info, see L<CGI::Snapp::Dispatch::Regexp>.

=head1 Description

This module provides a way to automatically look at the path info - $ENV{PATH_INFO} - of the incoming HTTP request,
and to process that path info like this:

=over 4

=item o Parse off a module name

=item o Parse off a run mode

=item o Create an instance of that module (i.e. load it)

=item o Run that instance