1Maypole::Manual::Model(U3s)er Contributed Perl DocumentatMiaoynpole::Manual::Model(3)
2
3
4

NAME

6       Maypole::Manual::Model - Maypole Model Classes
7

DESCRIPTION

9       Maypole's model classes provide an interface to your data store.  In
10       principle Maypole can connect to pretty much any data source, but the
11       default model is based on the popular Class::DBI object interface that
12       uses the near-universal DBI Perl interface to databases.
13
14   Maypole::Model::CDBI
15       Maypole model classes are pretty evil. The very first thing a Maypole
16       model class will do in a Maypole application is to cause a load of
17       table-based classes to come into being, and then assimilate them.
18
19       What I mean by this is that when you set up a Maypole application, in
20       your driver class, you'll say something like this:
21
22           BeerDB->setup("dbi:mysql:beerdb");
23
24       "setup" is a Maypole method, and it hands its parameter to the model
25       class. In our case, the argument is a DBI connect string, because
26       that's what "Maypole::Model::CDBI", the "Class::DBI"-based model
27       expects. "Maypole::Model::CDBI" has a method called "setup_database"
28       that creates all the "Class::DBI" table classes after connecting to the
29       database with that connect string. It does this by using
30       "Class::DBI::Loader", a utility module which asks a database about its
31       schema and sets up classes such as "BeerDB::Beer" to inherit from
32       "Class::DBI".
33
34       Now it gets interesting. The names of these classes are stashed away in
35       the application's configuration, and then Maypole forcibly has these
36       classes inherit from the model class. Our "BeerDB::Beer" now inherits
37       both from "Class::DBI" and "Maypole::Model::CDBI".
38
39       This is useful for two reasons. The first reason is that
40       "Maypole::Model::CDBI" is stuffed full of "Class::DBI" goodies that
41       make writing Maypole applications a lot easier:
42
43           package Maypole::Model::CDBI;
44           use base qw(Maypole::Model::Base Class::DBI);
45           use Maypole::Model::CDBI::AsForm;
46           use Class::DBI::FromCGI;  # probabyly broken .
47           use Class::DBI::Loader;
48           use Class::DBI::AbstractSearch;
49           use Class::DBI::Plugin::RetrieveAll;
50           use Class::DBI::Pager;
51
52       We'll meet most of these goodies in the Standard Templates and Actions
53       chapter, where we explain how "Maypole::Model::CDBI" works.
54
55       The second reason why we want our table classes to inherit from
56       "Maypole::Model::CDBI" is because it provides a useful set of default
57       actions. So what's an action, and why are they useful?
58
59   Maypole::Model::CDBI::Plain
60       The 'Plain' maypole Model : "Maypole::Model::CDBI" allows you
61
62           package Foo;
63           use 'Maypole::Application';
64
65           Foo->config->model("Maypole::Model::CDBI::Plain");
66           Foo->setup([qw/ Foo::SomeTable Foo::Other::Table /]);
67
68           # untaint columns and provide custom actions for each class
69
70           Foo::SomeTable->untaint_columns(email => ['email'], printable => [qw/name description/]);
71
72           Foo::Other::Table->untaint_columns ( ... );
73
74           sub Foo::SomeTable::SomeAction : Exported {
75
76               . . .
77
78           }
79
80   Extending a model class with actions
81       Maypole operates primarily by turning URLs into method calls on a model
82       class. All that the model stage of Maypole's operation does, when it
83       comes down to it, is maintain a mapping of tables to classes, and
84       despatch a HTTP request to a method call on the relevant table class.
85       This means that if you request a URL such as
86
87           http://localhost/beerdb/brewery/delete/20
88
89       Maypole's first stage of operation is to turn that into
90       "BeerDB::Brewery->delete(20)". Now, it's slightly more complex than
91       that. Firstly because it doesn't actually pass the parameter 20, but it
92       passes an object representing row 20 in the database, but we can gloss
93       over that for the second. No, the real issue is that Maypole does not
94       allow you to call just any method in the table class; that would be
95       somewhat insecure.
96
97       Instead, Maypole makes a distinction between the kind of methods that
98       only the class itself and other Perl code can call, and the kind of
99       methods that anyone can call from a URL. This latter set of methods are
100       called exported methods, and exporting is done by means of Perl
101       attributes. You define a method to be exported like so:
102
103           sub drink :Exported {
104
105       This will allow the user to access "/beerdb/beer/drink" over the web.
106       An exported method accompanied with a template to render its output is
107       sometimes called an action.
108
109       Maypole model classes like "Maypole::Model::CDBI" come with a
110       relatively handy set of actions which are all you need to set up a CRUD
111       (Create, Read, Update, Delete) database front-end: viewing a row in a
112       database, editing it, adding a new one, deleting, and so on. The most
113       important thing about Maypole, though, is that it doesn't stop there.
114       You can add your own.
115
116       For instance, in our beer database application, we could create a
117       "BeerDB::Beer" package, and put some additional actions in there.
118
119           package BeerDB::Beer;
120           sub top_five :Exported {
121               my ($class, $r) = @_;
122               $r->objects([ ($r->retrieve_all_sorted_by("score"))[-5..-1] ]);
123           }
124
125       Our action is called as a class method with the Maypole request object.
126       It uses the "Class::DBI::Plugin::RetrieveAll" module's
127       "retrieve_all_sorted_by" mixin to get the top five scoring beers, and
128       puts these in the "objects" slot of the request of object. Next, the
129       view class will come along and process the "top_five" template with
130       these five beers.
131
132       We'll look more at how to put together actions in the Standard
133       Templates and Actions chapter and our case studies.
134
135   Links
136       Contents, Next Maypole View Classes, Previous Introduction to Maypole
137
138
139
140perl v5.34.0                      2022-01-21         Maypole::Manual::Model(3)
Impressum