Maypole...ritance(3)

📦
version 2.13 · 2 versions
, in fedora 43

Maypole::Manual::Inheritance 💖

okay bestie, so this is a page from the User Contributed Perl Documentation — it's the Maypole...ritance(3) one, aka Maypole::Manual::Inheritance. grab a boba, we're doing architecture today 🧋✨

🌸 NAME 🌸

Maypole::Manual::Inheritance — the whole vibe of how a Maypole application is structured 🦋

✨ DESCRIPTION ✨

So basically this page walks you through the inheritance structure of two things: a basic Maypole app and a more advanced one. That's it, that's the whole thing. lowkey iconic.

🎀 CONVENTIONS 🎀

okay so before we get into it, here's the legend, the key, the little diagram decoder ring 💅

inheritance is drawn like this:

inheritance
            +
            |
         +-   -+
            |
            +

notes look like this — a target with a lil asterisk and a note hanging off it:

        target *-------- note about the target

association is an arrow pointing from source to target, no cap:

        source ------> target

👑 Structure of a standard Maypole application 👑

A minimal Maypole app — like the Beer database example from the Maypole synopsis, you know the one 🍓 — is literally just three things:

  • a custom driver (or controller) class, and in this case it's BeerDB.pm
  • a bunch of auto-generated model classes
  • and a view class

and here's the whole situation drawn out, no filter:

                  THE DRIVER
                                                 +------- init() is a factory method,
                          1      Maypole         |           it sets up the view
          Maypole::Config <----- config();       |              classes
          model();               init(); *-------+                           THE VIEW
           |                     view_object(); -------+
           |    +--------------* setup();              |      Maypole::View::Base
           |    |                   +                  |              +
           |    |                   |                  |     1        |
           |    |    PLUGINS    Apache::MVC *-----+    +-----> Maypole::View::TT
           |    |       +           +             |             (or another view class)
           |    |       |           |             |
           |    |       +-----+-----+             |
           |    |             |                   |
           |    |           BeerDB                +----- or CGI::Maypole
           |    |                                         or MasonX:::Maypole
           |    |
           |   setup() is a factory method,
           |     it sets up the model
           |         classes
           |
           |                                             THE MODEL
           |
           |  Maypole::Model::Base    Class::DBI
           |             +             +      +
           |             |             |      |
           +-------> Maypole::Model::CDBI   Class::DBI::<db_driver>
                             +                     +
                             |                     |
                  +------------+--------+-------+---------+
                  |            |        |       |         |
              BeerDB::Pub      |   BeerDB::Beer | BeerDB::Brewery
              beers();         |   pubs();      | beers();
                               |   brewery();   |
                               |   style();     |
                 BeerDB::Handpump               |
                 pub();                      BeerDB::Style
                 beer();                     beers();

like… look at it. it's giving family tree but make it Perl 🌈

😭 Ouch, that's a lot of inheritence! 😭

fr fr, that is a LOT of inheritence. at some point in the future — probably Maypole 3.x — they're gonna move to Class::C3. so yeah. noted. 📝

💅 What about Maypole::Application — loading plugins 💅

okay so Maypole::Application's whole main character job is to insert the plugins into the hierarchy. that's it. that's the job.

it's ALSO its responsibility to decide which frontend to use. here's the order of operations, bestie:

  1. it builds the list of plugins 🛠️
  2. then it pushes them onto the driver's @ISA
  3. then it pushes the frontend onto the end of the driver's @ISA

which means method lookup searches all the plugins first, before it even thinks about searching the frontend, and finally Maypole itself. periodt.

✨ from Maypole 2.11 onwards, Maypole::Application makes no appearance at all in the inheritance structure of a Maypole application. (in prior versions it would make itself inherit the plugins, and then insert itself into the hierarchy, but honestly? that was unnecessary. we don't do that anymore 💅)

🧚 Who builds the model? 🧚

first things first, remember we're talking about the standard, unmodified Maypole here. it is totally possible — and actually super common — to override some or all of this stage and build a customised model. see below for one approach (that's the An advanced Maypole application section, in part 2 bestie, patience 🫶). also go peek at Maypole's setup_model() method.

the standard model gets built in 3 stages:

  1. first, Maypole::setup_model calls setup_database on the Maypole model class — in this case Maypole::Model::CDBI. setup_database then uses Class::DBI::Loader to autogenerate individual Class::DBI classes for each of the tables in the database (BeerDB::Beer, BeerDB::Pub etc). and Class::DBI::Loader figures out the appropriate Class::DBI subclass and inserts it into each of these table classes' @ISA (that's the Class::DBI::<db_driver> you see in the diagrams) 🔥
  2. next, Maypole::setup pushes Maypole::Model::CDBI onto the @ISA array of each of these classes.
  3. finally, the relationships among these tables get set up. you can either do this manually, using the standard Class::DBI syntax for configuring table relationships, or you can try Class::DBI::Relationship (which you can use via Maypole::Plugin::Relationship). if you go the plugin route, you need to set up the relationships configuration before calling setup().
⚠️ heads up: some people love the convenience of Class::DBI::Relationship, and other people genuinely cannot stand the abstraction. YMMV. 💀

more chaos incoming in part 2, don't go anywhere 🦋✨

An advanced Maypole application

okay bestie, level two 💅 we're calling this one BeerDB2.

Maypole is a framework, which means you can swap out different bits whenever you want. So what follows is one example of good practice — other people may do things differently and that is completely fine.

We're assuming this application is being built from the ground up, but ngl it will often be straightforward to adapt an existing Class::DBI application to this general model.

The main character idea here: the autogenerated Maypole model is used as a layer on top of a separate Class::DBI model. I'm gonna refer to that separate one as the 'Offline' model, and the Maypole classes as the 'Maypole' model. The whole point is that the Offline model can (potentially, or in actuality) be used as part of another application — maybe a command line program, maybe a cron script, whatever. 🦋

The Offline model does not know about the Maypole model. The Maypole model does know about the Offline model. One-way street, no cap.

Let's call the offline model OfflineBeer. As a traditional Class::DBI application, individual table classes in this model will inherit from a common base (OfflineBeer), which inherits from Class::DBI).

One advantage of this approach is that you can still use Maypole's autogenerated model. ✨ Another is that you do not mix online and offline code in the same packages. 🙈

Building it

Build a driver in a similar way as for the basic app, calling setup() after setting up all the configuration.

It is a good habit to use a custom Maypole model class for each application, as it's a likely first target for customisation. Start it like this:

package BeerDB2::Maypole::Model;
use strict;
use warnings;
use base 'Maypole::Model::CDBI';
1;

You can add methods which should be shared by all table classes to this package as and when required.

Configure it like this, before the setup() call in the driver class:

# in package BeerDB2
__PACKAGE__->config->model('BeerDB2::Maypole::Model');
__PACKAGE__->setup;

The setup() call will ensure your custom model is loaded via require.

Note: by default, this will create Maypole/CDBI classes for all the tables in the database. You can control this by passing options for Class::DBI::Loader in the call to setup().

For each class in the model, you need to create a separate file. So for BeerDB2::Beer, you would write:

package BeerDB2::Beer;
use strict;
use warnings;
use base 'OfflineBeer::Beer';
1;

From Maypole 2.11, this package will be loaded automatically during setup(), and BeerDB2::Maypole::Model is pushed onto it's @ISA.

Configure relationships either in the individual OfflineBeer::* classes, or else all together in OfflineBeer itself i.e. not in the Maypole model. This way, you only define the relationships in one place. 👑

The resulting model looks like this:

                                         Class::DBI
MAYPOLE 'MODEL'                       |
                                      |
 Maypole::Model::Base                 |
         +                            |
         |      +-----------------+---+-----------------+
         |      |                 |                     |
         |      |                 |                     |
   Maypole::Model::CDBI           |                     |     OFFLINE
          +                      |                     |        MODEL
          |                      |                     |
   BeerDB2::Maypole::Model  Class::DBI::<db_driver>  OfflineBeer
     +                            +                     +
     |                            |                     |
     +----------------------------+                     |
     |                                                  |
     +--- BeerDB2::Pub --------+ OfflineBeer::Pub --------+
     |                           beers();                 |
     |                                                    |
     |                           OfflineBeer::Handpump ---+
     |                           beer();                  |
     |                           pub();                   |
     |                                                    |
     +--- BeerDB2::Beer -------+ OfflineBeer::Beer -------+
     |                           pubs();                  |
     |                           brewery();               |
     |                           style();                 |
     |                                                    |
     +--- BeerDB2::Style ------+ OfflineBeer::Style ------+
     |                           beers();                 |
     |                                                    |
     +--- BeerDB2::Brewery ----+ OfflineBeer::Brewery ----+
                                   beers();

Features

  1. Non-Maypole applications using the Offline model are completely isolated from the Maypole application, and need not know it exists at all. 🧚
  2. Methods defined in the Maypole table classes override methods defined in the Offline table classes, because BeerDB2::Maypole::Model was pushed onto the end of each Maypole table class's @ISA. Perl's depth first, left-to-right method lookup from e.g. BeerDB2::Beer starts in BeerDB2::Beer, then BeerDB2::Maypole::Model, Maypole::Model::CDBI, Maypole::Model::Base, and Class::DBI, before moving on to OfflineBeer::Beer and finally OfflineBeer.
CAVEAT — if your Offline model overrides Class::DBI methods, these methods will not be overridden when called from the Maypole application, because the Maypole model provides an alternative path to Class::DBI which is searched first. The solution is to place such methods in a separate package, e.g. OfflineBeer::CDBI. Place this first in the @ISA of both BeerDB2::Maypole::Model and OfflineBeer. Note that OfflineBeer::CDBI does not itself need to inherit from Class::DBI. 😭
  1. Methods defined in the Maypole model base class (BeerDB2::Maypole::Model), override methods in the individual Offline table classes, and in the Offline model base class (Offline).
  2. Relationships defined in the Offline classes are inherited by the Maypole model.
  3. The Maypole model has full access to the underlying Offline model. 🔥

Theory

This layout illustrates more clearly why the Maypole model may be thought of as part of the controller, rather than part of the model of MVC. Its function is to mediate web requests, translating them into method calls on the Offline model, munging the results, and returning them via the Maypole request object.

Another way of thinking about it is that Maypole implements a two-layer controller. The first layer translates a raw request into a single method call on the Maypole model layer, which then translates that call into one or more calls on the underlying model.

Whatever label you prefer to use, this approach provides for clear separation of concerns between the underlying model and the web/user interface, and that's what it's all about. 💖

Advanced applications - building the model by hand ** TODO

  • using Maypole::Model::CDBI::Plain or Maypole::FormBuilder::Model::Plain
  • setup_model() and load_model_subclass()
  • cutting out all those separate paths to CDBI - they're confusing 🙈

Method inheritance ** TODO

More description of Perl's left-to-right, depth-first method lookup, and where it's particularly important in Maypole.

AUTHOR

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

Copyright 2005 David Baird, All Rights Reserved.

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

and that's a wrap, bestie 💅 this whole thing is from perl v5.42.0, dated 2025-07-25, and it's page Maypole...ritance(3) — go forth and inherit responsibly, mwah 🎀

📦 where this page comes from