NAME

MasonX::Maypole - use Mason as the frontend and view for Maypole version 2

SYNOPSIS

package BeerDB;
use warnings;
use strict;

use Class::DBI::Loader::Relationship;

use Maypole::Application qw( -Debug2 MasonX AutoUntaint );

BeerDB->setup( 'dbi:mysql:beerdb', 'username', 'password' );

BeerDB->config->{template_root}  = '/home/beerdb/www/www/htdocs';
BeerDB->config->{uri_base}       = '/';
BeerDB->config->{rows_per_page}  = 10;
BeerDB->config->{display_tables} = [ qw( beer brewery pub style ) ];
BeerDB->config->{application_name} = 'The Beer Database';

BeerDB->config->masonx->{comp_root}  = [ [ factory => '/var/www/maypole/factory' ] ];
BeerDB->config->masonx->{data_dir}   = '/home/beerdb/www/www/mdata';
BeerDB->config->masonx->{in_package} = 'BeerDB::TestApp';

BeerDB->auto_untaint;

BeerDB->config->{loader}->relationship($_) for (
    'a brewery produces beers',
    'a style defines beers',
    'a pub has beers on handpumps',
    );

1;

** API CHANGES **

Version 0.5 contains major modifications, and changes to error handling. See the Changes file for details.

DESCRIPTION

A frontend and view for Maypole, using Mason.

EXAMPLES

Example BeerDB.pm and a httpd.conf VirtualHost setup are included in the /doc directory of the distribution.

A working example of the BeerDB application is at http://beerdb.riverside-cms.co.uk, including the BeerDB.pm and httpd.conf used for that site.

CONFIGURING MASON

Set any parameters for the Mason ApacheHandler in <BeerDB-config->{masonx}>>. This is where to tell Maypole/Mason where the factory templates are stored.

Note that the user the server runs as must have permission to read the files in the factory templates directory, which also means all directories in the path to the templates must be readable and executable (i.e. openable). If Mason can't read these templates, you may get a cryptic 'file doesn't exist' error, but you will not get a 'not permitted' error.

Maypole::Application

Maypole::Application needs to be patched before it will work with MasonX::Maypole. You can download a patched copy from http://beerdb.riverside-cms.co.uk, until the required updates are included in the version distributed with Maypole.

TEMPLATES

This distribution includes Masonized versions of the standard Maypole templates, plus a dhandler and autohandler. The autohandler simply takes care of adding a header and footer to every page, while the dhandler loads the template specified in the Maypole request object.

So if you set the factory comp_root to point at the Maypole factory templates, the thing should Just Work right out of the box. Except for maypole.css, which you will need to copy to the right place on your server.

METHODS

init

This method is called by Maypole while processing the first request the server receives. Probably better under mod_perl to call this explicitly at the end of your setup code (BeerDB->init) to share memory among Apache children. Sets up the Mason ApacheHandler, including the search path behaviour.

parse_args

Uses Mason to extract the request arguments from the request.

send_output

Template variables have already been exported to Mason components namespace in MasonX::Maypole::View::template. This method now runs the Mason exec phase to generate and send output.

get_template_root

Returns template_root from the config.

This varies from Apache::MVC, which concatenates document_root and location from the Apache request server config.

get_request

Replaces Apache::MVC::get_request, using Apache::Request::instance() instead of Apache::Request::new() to obtain the APR object. Calling new means Mason and Maypole have different APR objects, and the Mason one doesn't have any POST data.

AUTHOR

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

TODO

Currently hard-coded to use Apache/mod_perl. Shouldn't be too hard to use CGI instead.

BUGS

Please report any bugs or feature requests to bug-masonx-maypole2@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

TESTS

There are none. The module loads Mason::ApacheHandler, which causes compile time errors unless loaded within mod_perl.

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2004 David Baird, All Rights Reserved.

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