view release on metacpan or  search on metacpan

README.pod  view on Meta::CPAN

=head1 NAME

Apache2::WebApp - Simplified web application framework

=head1 SYNOPSIS

This module should not be used directly; it is intended to be run as a I<mod_perl> handler 
that can be configured as such by adding the following directives to your C<httpd.conf>

  PerlRequire /path/to/project/bin/startup.pl

  <Perl>
      use Apache2::WebApp;
      $Apache2::WebApp = Apache2::WebApp->new;
  </Perl>

  <Location /app>
      SetHandler perl-script
      PerlHandler $Apache2::WebApp->handler
      SetEnv WEBAPP_CONF /path/to/project/conf/webapp.conf
  </Location>

=head1 DESCRIPTION

The WebApp::Toolkit is a I<mod_perl> web application framework for the Perl programming 
language.  It defines a set of methods, processes, and conventions that help provide a 
consistent application environment.

The way this package works is actually pretty simple.  For every HTTP request, a I<mod_perl>
handler is executed that instanciates a new C<WebApp> controller object.  This object is 
then passed to a C<dispatch()> method that parses the URI request and maps the result to
a public class/method while passing the C<%controller> as the first argument.

Example:

  # URI                                    # Class                          # Method
  /app/project           --> maps to -->   Project
  /app/project/foo       --> maps to -->   Project::Foo        --> or -->   Project->foo()
  /app/project/foo/bar   --> maps to -->   Project::Foo::Bar   --> or -->   Project::Foo->bar()

If the target method does not exist, the C<distpatch()> will execute the class C<_global()>
and C<_default()> methods.  Below is an example of what a class (.pm) would look like.

Example:

  package Project::Foo;

  use strict;
  use warnings;

  # construct as an object (optional)
  sub _new {
      my $class = shift;
      return bless({
          attr1 => 'biz',
          attr2 => 'baz',
      }, $class);
  }

  # this method is executed for every request (optional)
  sub _global {
      my ($self, $c) = @_;

      $c->stash('baz','qux');

      return $c;
  }

  # if the target method doesn't exist, this will be executed
  sub _default {
      my ($self, $c) = @_;

      $self->_print_result($c, 'bar');
  }

  # _ always denotes a private method (not URI accessible)
  sub _print_result {
      my ($self, $c, $output) = @_;

      $c->request->content_type('text/html');

      print $output;
      exit;
  }