Dave Rolsky > MasonX-WebApp-0.12 > MasonX::WebApp

Download:
MasonX-WebApp-0.12.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.12   Source  

NAME ^

MasonX::WebApp - Works with Mason to do processing before Mason is invoked

SYNOPSIS ^

  # Create a subclass of MasonX::WebApp
  package My::WebApp;

  use base 'MasonX::WebApp';

  sub _init
  {
      # do something interesting, like making sure all incoming
      # arguments are UTF-8
  }

  # Create a handler() for it

  package My::MasonHandler;

  my $ah = MasonX::WebApp::ApacheHandler->new( ... );

  sub handler
  {
      # see docs for details
  }

  # In your Apache config file

  <Location />
    SetHandler   perl-script
    PerlHandler  My::MasonHandler
  </Location>

DESCRIPTION ^

MasonX::WebApp works with Mason to let you do processing before Mason is ever invoked. There are a number of things that one might want to do:

USAGE ^

To use MasonX::WebApp, you should create a MasonX::WebApp subclass. By itself, MasonX::WebApp won't do a whole lot for you, but it provides a nice framework for building on.

What MasonX::WebApp Provides

MasonX::WebApp, out of the box, provides the following:

You can set some parameters for your subclass declaratively, by calling class methods. These methods store data using Class::Data::Inheritable, so you can inherit from your subclasses and inherit these parameters.

Declarative Parameters

The following class methods are offered for declaring parameters:

Exceptions

Some methods throw exceptions. Exceptions classes are created using Exception::Class.

Public Methods

The folowing methods are public, and can be called from subclasses or from elsewhere, like in Mason components.

Protected Methods

These methods are intended to be called directly or overridden by your subclass.

Hash Keys in the WebApp and Session Objects

In order to avoid stepping on your toes, all hash keys in the webapp object, and all keys that it creates in the session object, are of the form "__blahblah__". In other words, they always start and end with two underscores (__). This should make it easy to avoid name conflicts when subclassing this module or when using the session it provides.

The Default handler() Method

The MasonX::WebApp class provides a default handler method.

I would recommend that instead of using this method, you create your own mod_perl handler that does something similar, because the default is not very efficient, given that it creates a new MasonX::WebApp::ApacheHandler object for each request. It is provided primarily as a reference implementation, and so that others can experiment with this webapp code quickly.

When creating your own handler, it might be useful to copy the one in this module as a reference.

In your own handler, there are several important guidelines you should follow.

You can, of course, do anything you want in your own handler() method. I often create an Apache::Request object with a "POST_MAX" parameter, in order to prevent a DoS from a ridiculously large POST.

I also often handle errors without dying, and instead will log them and present a more friendly page to the user. If you want to do this, keep in mind that constructing a webapp object can throw exceptions, so you may want to trap these in an eval block.

If you do something cool with this code, write about it on the Mason HQ site, masonhq.com (which is a big wiki), or send a post to the Mason users list.

Example handler()

Here is an example of an alternate handler(). This one is written as a function, not a method.

  package My::MasonHandler;

  sub handler
  {
      my $apr = Apache::Request->new(shift);

      my $args = $ah->request_args($apr);

      my $app = $class->new( apache_req => $apr, args => $args );

      return $app->abort_status if $app->aborted;

      local $My::ComponentPackage::WebApp = $app;

      my $return = eval { $ah->handle_request($r) };

      my $err = $@;

      $app->clean_session if $class->UseSession;

      die $err if $err;

      return $return;
   }

Then in your Apache configuration, you would use this handler:

  <Location />
    SetHandler   perl-script
    PerlHandler  My::MasonHandler
  </Location>

SEE ALSO ^

If you like the basic idea of this code (run things before a Mason component is invoked), but you don't want to create a subclass, I encourage you to take a look at David Wheeler's MasonX::Interp::WithCallbacks module. In fact, I encourage you to take a look at it anyway, since it may be more appropriate than this one, depending on your needs.

SUPPORT ^

Bug reports and requests for help should be sent to the mason-users list. See http://www.masonhq.com/resources/mailing_lists.html for more details.

AUTHOR ^

Dave Rolsky, <autarch@urth.org>

COPYRIGHT ^

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

The full text of the license can be found in the LICENSE file included with this module.

syntax highlighting: