NAME

MasonX::Maypole - provide a Mason frontend to Maypole

SYNOPSIS

In your Maypole driver class:

package BeerDB;
use base 'MasonX::Maypole';
BeerDB->setup( 'dbi:mysql:beerdb' );
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:

# loading BeerDB.pm could instead go in the autohandler,
# or else in httpd.conf (PerlModule BeerDB)
use BeerDB; 

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 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.

template variables

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, and you could do that if you prefer. However, for simplicity, in the setup shown above 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.

Mason doesn't differentiate between URL args (i.e. the query) and POSTed content. Query parameters and POSTed data can be accessed directly in the Mason components. This is different from standard Maypole, where query arguments are stored in the Maypole request ($request-{query}>) and POSTed arguments are available in $request-{params}>.

So in the Mason templates, you can access submitted data directly by name, via %ARGS, or via the Maypole template variables which are added to %ARGS in the autohandler. These include the Maypole request, so finally you can get at the submitted data through $ARGS{ request }-{ params }> (or $request-{ params }> if you specify $request in the Mason %args block). $request-{ query }> will always be empty.

template paths

The Mason configuration shown above 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).

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. But really that's up to you.

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.

You will not normally need to call this directly - see the vars method.

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

Calls prepare_request and extracts and returns the template variables.

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 and various other bits (mostly form action parameters) in other templates. See Maypole::Request.

The structure used 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.

DEPENDENCIES

Mason and Maypole.

HTML::Element is used in the search template, but is not a dependency of MasonX::Maypole per se.

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

Most of the code comes from Maypole and Apache::MVC, by Simon Cozens.

SEE ALSO

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