view release on metacpan or  search on metacpan

lib/Apache2/WebApp.pm  view on Meta::CPAN

#----------------------------------------------------------------------------+
#
#  Apache2::WebApp - Simplified web application framework
#
#  DESCRIPTION
#  mod_perl request handler that provides URI to class/method dispatching.
#
#  AUTHOR
#  Marc S. Brooks <mbrooks@cpan.org>
#
#  This module is free software; you can redistribute it and/or
#  modify it under the same terms as Perl itself.
#
#----------------------------------------------------------------------------+

package Apache2::WebApp;

use strict;
use warnings;
no  warnings qw( uninitialized );
use base 'Apache2::WebApp::Base';
use Apache2::Request;
use Apache2::RequestRec;
use Apache2::RequestUtil;
use Apache2::Connection;
use Apache2::Upload;
use Apache2::Const qw( :common :http );
use Apache2::Log;

our $VERSION = 0.391;

use Apache2::WebApp::AppConfig;
use Apache2::WebApp::Plugin;
use Apache2::WebApp::Stash;
use Apache2::WebApp::Template;

#~~~~~~~~~~~~~~~~~~~~~~~~~~[  OBJECT METHODS  ]~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~#

#----------------------------------------------------------------------------+
# handler(\%request_rec)
#
# mod_perl handler - Instanciate Apache2::WebApp::Toolkit objects.

sub handler : method {
    my ($self, $r) = @_;

    my $config = Apache2::WebApp::AppConfig->new;

    $self->{CONFIG} = $config->parse( $ENV{'WEBAPP_CONF'} );

    $self->{REQUEST} = Apache2::Request->new($r,
        DISABLE_UPLOADS => $self->{CONFIG}->{apache_disable_uploads},
        POST_MAX        => $self->{CONFIG}->{apache_post_max},
        TEMP_DIR        => $self->{CONFIG}->{apache_temp_dir}
      );

    $self->{PLUGIN}   = Apache2::WebApp::Plugin->new;
    $self->{STASH}    = Apache2::WebApp::Stash->new;
    $self->{TEMPLATE} = Apache2::WebApp::Template->new( $self->{CONFIG} ); 

    $self->dispatch;
}

lib/Apache2/WebApp.pm  view on Meta::CPAN

    if ($method) {
        if ($method =~ /^\_/) {
            $self->error("The method ($method) contains a leading underscore");
            return HTTP_BAD_REQUEST;
        }

        if ( $module->can($method) ) {
            $class->$method($c);
        }
        else {
            $self->error("The method ($method) doesn't exist in ($module)");
            return DECLINED;
        }
    }
    else {
        if ( $module->can('_default') ) {
            $class->_default($c);
        }
        else {
            $self->error("The class ($module) is missing a _default() method");
            return DECLINED;
        }
    }

    return OK;
}

#----------------------------------------------------------------------------+
# module_exists($file)
#
# Search %INC for the selected module; return filename if exists.

sub module_exists {
    my ($self, $file) = @_;
    return unless $file;

    my $project = $self->config->{project_title};
    foreach (sort keys %INC) {
        return $_ if (/\A $project\/$file\.pm \z/xi);
    }
    return;
}

#----------------------------------------------------------------------------+
# error(\%controller, $mesg)
#
# Quietly, output errors/exceptions to error_log

sub error {
    my ($c, $mesg) = @_;
    $c->request->log_error($mesg);
}

1;

__END__

=head1 NAME

Apache2::WebApp - Simplified web application framework - EOL (for reference only)

=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;
  }