NAME

Maypole - MVC web application framework

SYNOPSIS

See Maypole.

DESCRIPTION

A large number of web programming tasks follow the same sort of pattern: we have some data in a datasource, typically a relational database. We have a bunch of templates provided by web designers. We have a number of things we want to be able to do with the database - create, add, edit, delete records, view records, run searches, and so on. We have a web server which provides input from the user about what to do. Something in the middle takes the input, grabs the relevant rows from the database, performs the action, constructs a page, and spits it out.

Maypole aims to be the most generic and extensible "something in the middle" - an MVC-based web application framework.

An example would help explain this best. You need to add a product catalogue to a company's web site. Users need to list the products in various categories, view a page on each product with its photo and pricing information and so on, and there needs to be a back-end where sales staff can add new lines, change prices, and delete out of date records. So, you set up the database, provide some default templates for the designers to customize, and then write an Apache handler like this:

    package ProductDatabase;
    use base 'Maypole';
    __PACKAGE__->set_database("dbi:mysql:products");
    ProductDatabase->config->{uri_base} = "http://your.site/catalogue/";
    ProductDatabase::Product->has_a("category" => ProductDatabase::Category); 
    # ...

    sub authenticate {
        my ($self, $request) = @_;
        return OK if $request->{ar}->get_remote_host() eq "sales.yourcorp.com";
        return OK if $request->{action} =~ /^(view|list)$/;
        return DECLINED;
    }
    1;

You then put the following in your Apache config:

    <Location /catalogue>
        SetHandler perl-script
        PerlHandler ProductDatabase
    </Location>

And copy the templates found in templates/factory into the catalogue/factory directory off the web root. When the designers get back to you with custom templates, they are to go in catalogue/custom. If you need to do override templates on a database-table-by-table basis, put the new template in catalogue/table.

This will automatically give you add, edit, list, view and delete commands; for instance, a product list, go to

    http://your.site/catalogue/product/list

For a full example, see the included "beer database" application.

HOW IT WORKS

There's some documentation for the workflow in Maypole::Workflow, but the basic idea is that a URL part like product/list gets translated into a call to ProductDatabase::Product->list. This propagates the request with a set of objects from the database, and then calls the list template; first, a product/list template if it exists, then the custom/list and finally factory/list.

If there's another action you want the system to do, you need to either subclass the model class, and configure your class slightly differently:

    package ProductDatabase::Model;
    use base 'Maypole::Model::CDBI';

    sub supersearch :Exported {
        my ($self, $request) = @_;
        # Do stuff, get a bunch of objects back
        $r->objects(\@objects);
        $r->template("template_name");
    }

Then your top-level application package should change the model class: (Before calling setup)

    ProductDatabase->config->{model_class} = "ProductDatabase::Model";

(The :Exported attribute means that the method can be called via the URL /table/supersearch/....)

Alternatively, you can put the method directly into the specific model class for the table:

    sub ProductDatabase::Product::supersearch :Exported { ... }

By default, the view class uses Template Toolkit as the template processor, and the model class uses Class::DBI; it may help you to be familiar with these modules before going much further with this, although I expect there to be other subclasses for other templating systems and database abstraction layers as time goes on. The article at http://www.perl.com/pub/a/2003/07/15/nocode.html is a great introduction to the process we're trying to automate.

USING MAYPOLE

You should probably not use Maypole directly. Maypole is an abstract class which does not specify how to communicate with the outside world. The most popular subclass of Maypole is Apache::MVC, which interfaces the Maypole framework to Apache mod_perl.

If you are implementing Maypole subclasses, you need to provide at least the get_request and parse_location methods. See the Maypole::Workflow documentation for what these are expected to do.

AUTHOR

Simon Cozens, simon@cpan.org

LICENSE

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

cpanm Maypole

perl -MCPAN -e shell
install Maypole