NAME

MasonX::Maypole - provide a Mason frontend to Maypole

SYNOPSIS

Your in your Maypole driver class:

package BeerDB;
use base 'MasonX::Maypole';
BeerDB->config->{ view } = 'Maypole::View::Base';

# ... rest of BeerDB driver configuration

1;

In beerdb/autohandler:

% %ARGS = ( %ARGS, BeerDB->vars );
<h1><a href="/<% $ARGS{ base } %>">Beer Database</a></h1>
<& /navbar, %ARGS &>
% $m->call_next( %ARGS );

In beerdb/dhandler:

<& '/' . $ARGS{ request }->{ template }, %ARGS &>

In the Mason handler.pl script:

my $ah = HTML::Mason::ApacheHandler->new(
            comp_root => [ [ main    => $main_comp_root ], # for the rest of your website
                           [ beerdb  => '/path/to/beerdb' ],
                           [ factory => '/path/to/maypole/factory/templates' ],
                           # ... maybe some others, whatever you already have
                           ],
            ...
            
            # continue along

DESCRIPTION

This module removes most of the 'view' processing from the Maypole request cycle, leaving all that to Mason.

Templates

The templates provided are XHTMLized, Mason-ized versions of the standard Maypole factory templates. A basic CSS file is included.

The Maypole::View::TT way of working is to inject the template variables into the namespace of each template. For Mason users, this would be similar to defining the variables as request globals. Instead, the template variables are retrieved by the root autohandler and placed in the %ARGS hash. This means that the template vars have to be passed around manually between components.

The link template has been renamed mplink because you may already have a utility component called link in a shared component root. Well, at any rate, I do.

All templates are placed in the same directory, since there is no difference in Mason between a template and a macro. They're all components.

template paths

The Mason configuration shown gives a variation on the template search path behaviour used in the standard Maypole setup. If a table-specific template - /path/to/beerdb/<table/<template>> exists, that will be used. Otherwise, a database-specific template /path/to/beerdb/<template> will be used, if it exists. Finally, the generic factory template in /path/to/maypole/factory/templates is used. You are free to place them anywhere else you prefer, and to add more search paths if appropriate (or remove them).

Methods

prepare_request

This method replaces Maypole::handler (and Maypole::handler_guts) as the workflow controller that coordinates the various tasks carried out during a Maypole request. Basically, the output phase of the Maypole request has been removed (and is delegated to Mason).

Returns the Maypole request object.

Note

For requests to unknown tables or actions, this method currently removes the base_url portion of the path and sets the template slot of the Maypole request object to the remaining path. That path is then used in the dhandler to start the Mason search of component roots for a suitable component.

Whether this is the Right Thing to do will depend on how you have set up the Mason component roots. I think. Frankly, this bit confuses me, but seems to work for the setup described above.

So don't rely on this behaviour in future releases, it may change if someone can explain to me how this stuff should really work.

vars

A bit of sugar to wrap the call to prepare_request and extract the template variables in a single call.

parse_path

Used by parse_location to extract things from the URL.

This implements a URL structure. If you prefer a different structure, override this method in your Maypole driver. You will also need to edit the mplink factory template. See Maypole::Request.

The structure here is [uri_base]/[table]/[action]/[arg].html or [uri_base]/[table]/[action].html. Typically arg will be an integer ID.

get_request

Stores the Apache::Request in the Maypole request object.

parse_location

Mason has already extracted any form data and URL queries and combined them into a single set of parameters. This method retrieves that data, plus data encoded in the URL (extracted with parse_path) and stores it in the Maypole request.

BUGS

Please report all bugs via the CPAN Request Tracker at http://rt.cpan.org/NoAuth/Bugs.html?Dist=MasonX-Maypole.

COPYRIGHT AND LICENSE

Copyright 2004 by David Baird.

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

AUTHOR

David Baird, cpan@riverside-cms.co.uk

SEE ALSO

Apache::MVC, Maypole::View::Mason.