Maypole - MVC web application framework


The canonical example used in the Maypole documentation is the beer database:

    package BeerDB;
    use strict;
    use warnings; 
    # choose a frontend, initialise the config object, and load a plugin
    use Maypole::Application qw/Relationship/;

    # set everything up
    # get the empty config object created by Maypole::Application
    my $config = __PACKAGE__->config;
    # basic settings
    $config->display_tables([qw/beer brewery pub style/]);

    # table relationships
        "a brewery produces beers",
        "a style defines beers",
        "a pub has beers on handpumps",
    # validation
    BeerDB::Brewery->untaint_columns( printable => [qw/name notes url/] );
    BeerDB::Pub->untaint_columns( printable => [qw/name notes url/] );
    BeerDB::Style->untaint_columns( printable => [qw/name notes/] );
        printable => [qw/abv name price notes/],
        integer => [qw/style brewery score/],
        date => [ qw/date/],

    # note : set up model before calling this method



This documents the Maypole request object. See the Maypole::Manual, for a detailed guide to using Maypole.

Maypole is a Perl web application framework similar to Java's struts. It is essentially completely abstracted, and so doesn't know anything about how to talk to the outside world.

To use it, you need to create a driver package which represents your entire application. This is the BeerDB package used as an example in the manual.

This needs to first use Maypole::Application which will make your package inherit from the appropriate platform driver such as Apache::MVC or CGI::Maypole. Then, the driver calls setup. This sets up the model classes and configures your application. The default model class for Maypole uses Class::DBI to map a database to classes, but this can be changed by altering configuration (before calling setup.)


Note that some details in some of these resources may be out of date.

The Maypole Manual

The primary documentation is the Maypole manual. This lives in the Maypole::Manual pod documents included with the distribution.

Embedded POD

Individual packages within the distribution contain (more or less) detailed reference documentation for their API.

Mailing lists

There are two mailing lists - maypole-devel and maypole-users - see

The Maypole Wiki

The Maypole wiki provides a useful store of extra documentation -

In particular, there's a FAQ ( and a cookbook ( Again, certain information on these pages may be out of date.

Web applications with Maypole

A tutorial written by Simon Cozens for YAPC::EU 2005 - [228KB].

A Database-Driven Web Application in 18 Lines of Code

By Paul Barry, published in Linux Journal, March 2005.

"From zero to Web-based database application in eight easy steps".

Maypole won a 2005 Linux Journal Editor's Choice Award ( after featuring in this article.

Build Web apps with Maypole

By Simon Cozens, on IBM's DeveloperWorks website, May 2004.

Rapid Web Application Deployment with Maypole

By Simon Cozens, on O'Reilly's Perl website, April 2004.


Some notes written by Simon Cozens. A little bit out of date, but still very useful:


There's a refcard for the Maypole (and Class::DBI) APIs on the wiki - Probably a little out of date now - it's a wiki, so feel free to fix any errors!

Plugins and add-ons

There are a large and growing number of plugins and other add-on modules available on CPAN -

You can find a range of useful Maypole links, particularly to several thoughtful blog entries, starting here:

CPAN ratings

There are a couple of short reviews here:


As a framework, Maypole provides a number of hooks - methods that are intended to be overridden. Some of these methods come with useful default behaviour, others do nothing by default. Hooks include:

    Class methods
    Instance methods


    sub My::App::debug {1}

Returns the debugging flag. Override this in your application class to enable/disable debugging.

You can also set the debug flag via Maypole::Application.

Some packages respond to higher debug levels, try increasing it to 2 or 3.


Returns the Maypole::Config object

   My::App->setup($data_source, $user, $password, \%attr);

Initialise the Maypole application and plugins and model classes. Your application should call this after setting up configuration data via "config".

It calls the hook setup_model to setup the model. The %attr hash contains options and arguments used to set up the model. See the particular model's documentation. However here is the most usage of setup where Maypole::Model::CDBI is the base class.

 My::App->setup($data_source, $user, $password,
       {  options => {  # These are DB connection options
               AutoCommit => 0,
               RaiseError => 1,
          # These are Class::DBI::Loader arguments.
          relationships  => 1,

Also, see Maypole::Manual::Plugins.


Called by setup. This method builds the Maypole model hierarchy.

A likely target for over-riding, if you need to build a customised model.

This method also ensures any code in custom model classes is loaded, so you don't need to load them in the driver.


This method is called from setup_model(). It attempts to load the $subclass package, if one exists. So if you make a customized BeerDB::Beer package, you don't need to explicitly load it.

If automatic loading causes problems, Override load_model_subclass in your driver.

sub load_model_subclass {};

Or perhaps during development, if you don't want to load up custom classes, you can override this method and load them manually.


Loads the view class and instantiates the view object.

You should not call this directly, but you may wish to override this to add application-specific initialisation - see Maypole::Manual::Plugins.


Constructs a very minimal new Maypole request object.


Get/set the Maypole::View object




This method sets up the class if it's not done yet, sets some defaults and leaves the dirty work to handler_guts.

  Run Maypole sub-requests as a component of the request

  [% request.component("/beer/view_as_component/20") %]

  Allows you to integrate the results of a Maypole request into an existing
request. You'll need to set up actions and templates
which return fragments of HTML rather than entire pages, but once you've
done that, you can use the C<component> method of the Maypole request object
to call those actions. You may pass a query string in the usual URL style.

You should not fully qualify the Maypole URLs.

Note: any HTTP POST or URL parameters passed to the parent are not passed to the component sub-request, only what is included in the url passed as an argument to the method


This is the main request handling method and calls various methods to handle the request/response and defines the workflow within Maypole.


$r->warn('its all gone pete tong');

Warn must be implemented by the backend, i.e. Apache::MVC and warn to stderr or appropriate logfile.

You can also over-ride this in your Maypole driver, should you want to use something like Log::Log4perl instead.



Specify (in an action) whether to build HTML form elements and populate the cgi element of classmetadata in the view.

You can set this globally using the accessor of the same name in Maypole::Config, this method allows you to over-ride that setting per action.


You should only need to define this method if you are writing a new Maypole backend. It should return something that looks like an Apache or CGI request object, it defaults to blank.


Turns the backend request (e.g. Apache::MVC, Maypole, CGI) into a Maypole request. It does this by setting the path, and invoking parse_path and parse_args.

You should only need to define this method if you are writing a new Maypole backend.


This is called immediately after setting up the basic request. The default method does nothing.

The value of $r->status is set to OK before this hook is run. Your implementation can change the status code, or leave it alone.

After this hook has run, Maypole will check the value of status. For any value other than OK, Maypole returns the status immediately.

This is useful for filtering out requests for static files, e.g. images, which should not be processed by Maypole or by the templating engine:

    sub start_request_hook
        my ($r) = @_;
        $r->status(DECLINED) if $r->path =~ /\.jpg$/;

Multiple plugins, and the driver, can define this hook - Maypole will call all of them. You should check for and probably not change any non-OK status value:

    package Maypole::Plugin::MyApp::SkipFavicon;
    sub start_request_hook
        my ($r) = @_;
        # check if a previous plugin has already DECLINED this request
        # - probably unnecessary in this example, but you get the idea
        return unless $r->status == OK;
        # then do our stuff
        $r->status(DECLINED) if $r->path =~ /favicon\.ico/;

This method is deprecated as of version 2.11. If you have overridden it, please override is_model_applicable instead, and change the return type from a Maypole:Constant to a true/false value.

Returns a Maypole::Constant to indicate whether the request is valid.


Returns true or false to indicate whether the request is valid.

The default implementation checks that $r->table is publicly accessible and that the model class is configured to handle the $r->action.


Called immediately after start_request_hook().

This method should return a session, which will be stored in the request's session attribute.

The default method is empty.


Called immediately after get_session.

This method should return a user, which will be stored in the request's user attribute.

The default method is empty.


This method first checks if the relevant model class can authenticate the user, or falls back to the default authenticate method of your Maypole application.


Returns a Maypole::Constant to indicate whether the user is authenticated for the Maypole request.

The default implementation returns OK


This model is called to catch exceptions, first after authenticate, then after processing the model class, and finally to check for exceptions from the view class.

This method first checks if the relevant model class can handle exceptions the user, or falls back to the default exception method of your Maypole application.


This method is called if any exceptions are raised during the authentication or model/view processing. It should accept the exception as a parameter and return a Maypole::Constant to indicate whether the request should continue to be processed.


Called before the model processes the request, this method gives you a chance to do some processing for each request, for example, manipulating template_args.


Sends the output and additional headers to the user.

Path processing and manipulation


Returns the request path


Parses the request path and sets the args, action and table properties. Calls preprocess_path before parsing path and setting properties.


Sometimes when you don't want to rewrite or over-ride parse_path but want to rewrite urls or extract data from them before it is parsed, the preprocess_path/location methods allow you to munge paths and urls before maypole maps them to actions, classes, etc.

This method is called after parse_location has populated the request information and before parse_path has populated the model and action information, and is passed the request object.

You can set action, args or table in this method and parse_path will then leave those values in place or populate them based on the current value of the path attribute if they are not present.


This method is called at the start of parse_location, after the headers in, and allows you to rewrite the url used by maypole, or dynamically set configuration like the base_uri based on the hostname or path.

make_path( %args or \%args or @args )

This is the counterpart to parse_path. It generates a path to use in links, form actions etc. To implement your own path scheme, just override this method and parse_path.

    %args = ( table      => $table,
              action     => $action,        
              additional => $additional,    # optional - generally an object ID
    \%args = as above, but a ref
    @args = ( $table, $action, $additional );   # $additional is optional

id can be used as an alternative key to additional.

$additional can be a string, an arrayref, or a hashref. An arrayref is expanded into extra path elements, whereas a hashref is translated into a query string.

make_uri( @segments )

Make a URI object given table, action etc. Automatically adds the uri_base.

If the final element in @segments is a hash ref, make_uri will render it as a query string.


Turns post data and query string paramaters into a hash of params.

You should only need to define this method if you are writing a new Maypole backend.


Implementation-specific path to template root.

You should only need to define this method if you are writing a new Maypole backend. Otherwise, see "template_root" in Maypole::Config

Request properties


Returns the perl package name that will serve as the model for the request. It corresponds to the request table attribute.


Get/set a list of model objects. The objects will be accessible in the view templates.

If the first item in $self->args can be retrieve()d by the model class, it will be removed from args and the retrieved object will be added to the objects list. See Maypole::Model for more information.


Alias to get/set the first/only model object. The object will be accessible in the view templates.

When used to set the object, will overwrite the request objects with a single object.

    $self->template_args->{foo} = 'bar';

Get/set a hash of template variables.

Maypole reserved words for template variables will over-ride values in template_variables.

Reserved words are : r, request, object, objects, base, config and errors, as well as the current class or object name.


A place to put custom application data. Not used by Maypole itself.


Get/set the template to be used by the view. By default, it returns $self->action


Get/set a request error


Get/set the response output. This is usually populated by the view class. You can skip view processing by setting the output.


The table part of the Maypole request path


The action part of the Maypole request path


A list of remaining parts of the request path after table and action have been removed


A Maypole::Headers object containing HTTP headers for the request


A HTTP::Headers object that contains HTTP headers for the output


Get/set the output encoding. Default: utf-8.


Get/set the output content type. Default: text/html


Returns the protocol the request was made with, i.e. https

Request parameters

The source of the parameters may vary depending on the Maypole backend, but they are usually populated from request query string and POST data.

Maypole supplies several approaches for accessing the request parameters. Note that the current implementation (via a hashref) of query and params is likely to change in a future version of Maypole. So avoid direct access to these hashrefs:

    $r->{params}->{foo}      # bad
    $r->params->{foo}        # better

    $r->{query}->{foo}       # bad
    $r->query->{foo}         # better

    $r->param('foo')         # best

An accessor (get or set) for request parameters. It behaves similarly to CGI::param() for accessing CGI parameters, i.e.

    $r->param                   # returns list of keys
    $r->param($key)             # returns value for $key
    $r->param($key => $value)   # returns old value, sets to new value

Returns a hashref of request parameters.

Note: Where muliple values of a parameter were supplied, the params value will be an array reference.


Alias for params.

Utility methods


Sets output headers to redirect based on the arguments provided

Accepts either a single argument of the full url to redirect to, or a hash of named parameters :



$r->redirect_request(protocol=>'https', domain=>'', path=>'/path/file?arguments', status=>'302', url=>'..');

The named parameters are protocol, domain, path, status and url

Only 1 named parameter is required but other than url, they can be combined as required and current values (from the request) will be used in place of any missing arguments. The url argument must be a full url including protocol and can only be combined with status.


returns a unique id for this request can be used to prevent or detect repeat submissions.


See Maypole::Manual::Workflow for a detailed discussion of the sequence of calls during processing of a request. This is a brief summary:

                               Model e.g.
         BeerDB           Maypole::Model::CDBI
           |                        |
   setup   |                        |
 o-------->||                       |
           || setup_model           |     setup_database() creates
           ||------+                |      a subclass of the Model
           |||<----+                |        for each table
           |||                      |                |
           |||   setup_database     |                |
           |||--------------------->|| 'create'      *
           |||                      ||----------> $subclass
           |||                      |                  |
           ||| load_model_subclass  |                  |
 foreach   |||------+  ($subclass)  |                  |
 $subclass ||||<----+               |    require       |
           |||                      |                  |
           |||   adopt($subclass)   |                  |
           |||--------------------->||                 |
           |                        |                  |
           |                        |                  |
           |-----+ init             |                  |
           ||<---+                  |                  |
           ||                       |     new          |     view_object: e.g.
           ||---------------------------------------------> Maypole::View::TT
           |                        |                  |          |
           |                        |                  |          |
           |                        |                  |          |
           |                        |                  |          |
           |                        |                  |          |


          BeerDB                                Model  $subclass  view_object
            |                                      |       |         |
    handler |                                      |       |         |
  o-------->| new                                  |       |         |
            |-----> r:BeerDB                       |       |         |
            |         |                            |       |         |
            |         |                            |       |         |
            |         ||                           |       |         |
            |         ||-----+ parse_location      |       |         |
            |         |||<---+                     |       |         |
            |         ||                           |       |         |
            |         ||-----+ start_request_hook  |       |         |
            |         |||<---+                     |       |         |
            |         ||                           |       |         |
            |         ||-----+ get_session         |       |         |
            |         |||<---+                     |       |         |
            |         ||                           |       |         |
            |         ||-----+ get_user            |       |         |
            |         |||<---+                     |       |         |
            |         ||                           |       |         |
            |         ||-----+ handler_guts        |       |         |
            |         |||<---+                     |       |         |
            |         |||     class_of($table)     |       |         |
            |         |||------------------------->||      |         |
            |         |||       $subclass          ||      |         |
            |         |||<-------------------------||      |         |
            |         |||                          |       |         |
            |         |||-----+ is_model_applicable|       |         |
            |         ||||<---+                    |       |         |
            |         |||                          |       |         |
            |         |||-----+ call_authenticate  |       |         |
            |         ||||<---+                    |       |         |
            |         |||                          |       |         |
            |         |||-----+ additional_data    |       |         |
            |         ||||<---+                    |       |         |
            |         |||             process      |       |         |
            |         |||--------------------------------->||  fetch_objects
            |         |||                          |       ||-----+  |
            |         |||                          |       |||<---+  |
            |         |||                          |       ||        |
            |         |||                          |       ||   $action
            |         |||                          |       ||-----+  |
            |         |||                          |       |||<---+  |            
            |         |||         process          |       |         |
            |         |||------------------------------------------->|| template
            |         |||                          |       |         ||-----+
            |         |||                          |       |         |||<---+
            |         |||                          |       |         |
            |         ||     send_output           |       |         |
            |         ||-----+                     |       |         |
            |         |||<---+                     |       |         |
   $status  |         ||                           |       |         |
   <------------------||                           |       |         |
            |         |                            |       |         |
            |         X                            |       |         |           
            |                                      |       |         |
            |                                      |       |         |
            |                                      |       |         |


There's more documentation, examples, and information on our mailing lists at the Maypole web site:

Maypole::Application, Apache::MVC, CGI::Maypole.


Maypole is currently maintained by Aaron Trevena.


Simon Cozens,

Simon Flack maintained Maypole from 2.05 to 2.09

Sebastian Riedel, maintained Maypole from 1.99_01 to 2.04


Sebastian Riedel, Danijel Milicevic, Dave Slack, Jesse Sheidlower, Jody Belka, Marcus Ramberg, Mickael Joanne, Randal Schwartz, Simon Flack, Steve Simms, Veljko Vidovic and all the others who've helped.


You may distribute this code under the same terms as Perl itself.