1Maypole(3) User Contributed Perl Documentation Maypole(3)
2
6 Maypole - MVC web application framework
7
9 The canonical example used in the Maypole documentation is the beer
10 database:
11 package BeerDB;
13 use strict;
14 use warnings;
15 # choose a frontend, initialise the config object, and load a plugin
17 use Maypole::Application qw/Relationship/;
18 # set everything up
20 __PACKAGE__->setup("dbi:SQLite:t/beerdb.db");
21 # get the empty config object created by Maypole::Application
23 my $config = __PACKAGE__->config;
24 # basic settings
26 $config->uri_base("http://localhost/beerdb");
27 $config->template_root("/path/to/templates");
28 $config->rows_per_page(10);
29 $config->display_tables([qw/beer brewery pub style/]);
30 # table relationships
32 $config->relationships([
33 "a brewery produces beers",
34 "a style defines beers",
35 "a pub has beers on handpumps",
36 ]);
37 # validation
39 BeerDB::Brewery->untaint_columns( printable => [qw/name notes url/] );
40 BeerDB::Pub->untaint_columns( printable => [qw/name notes url/] );
41 BeerDB::Style->untaint_columns( printable => [qw/name notes/] );
42 BeerDB::Beer->untaint_columns(
43 printable => [qw/abv name price notes/],
44 integer => [qw/style brewery score/],
45 date => [ qw/date/],
46 );
47 # note : set up model before calling this method
49 BeerDB::Beer->required_columns([qw/name/]);
50 1;
52
54 This documents the Maypole request object. See the Maypole::Manual, for
55 a detailed guide to using Maypole.
56 Maypole is a Perl web application framework similar to Java's struts.
58 It is essentially completely abstracted, and so doesn't know anything
59 about how to talk to the outside world.
60 To use it, you need to create a driver package which represents your
62 entire application. This is the "BeerDB" package used as an example in
63 the manual.
64 This needs to first use Maypole::Application which will make your pack‐
66 age inherit from the appropriate platform driver such as "Apache::MVC"
67 or "CGI::Maypole". Then, the driver calls "setup". This sets up the
68 model classes and configures your application. The default model class
69 for Maypole uses Class::DBI to map a database to classes, but this can
70 be changed by altering configuration (before calling setup.)
71
73 Note that some details in some of these resources may be out of date.
74 The Maypole Manual
76 The primary documentation is the Maypole manual. This lives in the
77 "Maypole::Manual" pod documents included with the distribution.
78 Embedded POD
80 Individual packages within the distribution contain (more or less)
81 detailed reference documentation for their API.
82 Mailing lists
84 There are two mailing lists - maypole-devel and maypole-users - see
85 http://maypole.perl.org/?MailingList
86 The Maypole Wiki
88 The Maypole wiki provides a useful store of extra documentation -
89 http://maypole.perl.org
90 In particular, there's a FAQ (http://maypole.perl.org/?FAQ) and a
92 cookbook (http://maypole.perl.org/?Cookbook). Again, certain infor‐
93 mation on these pages may be out of date.
94 Web applications with Maypole
96 A tutorial written by Simon Cozens for YAPC::EU 2005 -
97 http://www.aarontrevena.co.uk/opensource/maypole/maypole-tuto‐
98 rial.pdf [228KB].
99 A Database-Driven Web Application in 18 Lines of Code
101 By Paul Barry, published in Linux Journal, March 2005.
102 http://www.linuxjournal.com/article/7937
104 "From zero to Web-based database application in eight easy steps".
106 Maypole won a 2005 Linux Journal Editor's Choice Award
108 (http://www.linuxjournal.com/article/8293) after featuring in this
109 article.
110 Build Web apps with Maypole
112 By Simon Cozens, on IBM's DeveloperWorks website, May 2004.
113 http://www-128.ibm.com/developerworks/linux/library/l-maypole/
115 Rapid Web Application Deployment with Maypole
117 By Simon Cozens, on O'Reilly's Perl website, April 2004.
118 http://www.perl.com/pub/a/2004/04/15/maypole.html
120 Authentication
122 Some notes written by Simon Cozens. A little bit out of date, but
123 still very useful: http://www.aarontrevena.co.uk/opensource/may‐
124 pole/authentication.html
125 CheatSheet
127 There's a refcard for the Maypole (and Class::DBI) APIs on the wiki
128 - http://maypole.perl.org/?CheatSheet. Probably a little out of
129 date now - it's a wiki, so feel free to fix any errors!
130 Plugins and add-ons
132 There are a large and growing number of plugins and other add-on
133 modules available on CPAN -
134 http://search.cpan.org/search?query=maypole&mode=module
135 del.icio.us
137 You can find a range of useful Maypole links, particularly to sev‐
138 eral thoughtful blog entries, starting here:
139 http://del.icio.us/search/?all=maypole
140 CPAN ratings
142 There are a couple of short reviews here: http://cpanrat‐
143 ings.perl.org/dist/Maypole
144
146 As a framework, Maypole provides a number of hooks - methods that are
147 intended to be overridden. Some of these methods come with useful
148 default behaviour, others do nothing by default. Hooks include:
149 Class methods
151 -------------
152 debug
153 setup
154 setup_model
155 load_model_subclass
156 init
157 Instance methods
159 ----------------
160 start_request_hook
161 is_model_applicable
162 get_session
163 authenticate
164 exception
165 additional_data
166 preprocess_path
167
169 debug
170 sub My::App::debug {1}
171 Returns the debugging flag. Override this in your application class
173 to enable/disable debugging.
174 You can also set the "debug" flag via Maypole::Application.
176 Some packages respond to higher debug levels, try increasing it to
178 2 or 3.
179 config
181 Returns the Maypole::Config object
182 setup
184 My::App->setup($data_source, $user, $password, \%attr);
185 Initialise the Maypole application and plugins and model classes.
187 Your application should call this after setting up configuration
188 data via "config".
189 It calls the hook "setup_model" to setup the model. The %attr hash
191 contains options and arguments used to set up the model. See the
192 particular model's documentation. However here is the most usage of
193 setup where Maypole::Model::CDBI is the base class.
194 My::App->setup($data_source, $user, $password,
196 { options => { # These are DB connection options
197 AutoCommit => 0,
198 RaiseError => 1,
199 ...
200 },
201 # These are Class::DBI::Loader arguments.
202 relationships => 1,
203 ...
204 }
205 );
206 Also, see Maypole::Manual::Plugins.
208 setup_model
210 Called by "setup". This method builds the Maypole model hierarchy.
211 A likely target for over-riding, if you need to build a customised
213 model.
214 This method also ensures any code in custom model classes is
216 loaded, so you don't need to load them in the driver.
217 load_model_subclass($subclass)
219 This method is called from "setup_model()". It attempts to load the
220 $subclass package, if one exists. So if you make a customized
221 "BeerDB::Beer" package, you don't need to explicitly load it.
222 If automatic loading causes problems, Override load_model_subclass
224 in your driver.
225 sub load_model_subclass {};
227 Or perhaps during development, if you don't want to load up custom
229 classes, you can override this method and load them manually.
230 init
232 Loads the view class and instantiates the view object.
233 You should not call this directly, but you may wish to override
235 this to add application-specific initialisation - see Maypole::Man‐
236 ual::Plugins.
237 new Constructs a very minimal new Maypole request object.
239 view_object
241 Get/set the Maypole::View object
242
244 Workflow
245 handler
247 This method sets up the class if it's not done yet, sets some
248 defaults and leaves the dirty work to "handler_guts".
249 component
251 Run Maypole sub-requests as a component of the request
252 [% request.component("/beer/view_as_component/20") %]
254 Allows you to integrate the results of a Maypole request into an existing
256 request. You'll need to set up actions and templates
257 which return fragments of HTML rather than entire pages, but once you've
258 done that, you can use the C<component> method of the Maypole request object
259 to call those actions. You may pass a query string in the usual URL style.
260 You should not fully qualify the Maypole URLs.
262 Note: any HTTP POST or URL parameters passed to the parent are not
264 passed to the component sub-request, only what is included in the
265 url passed as an argyument to the method
266 handler_guts
268 This is the main request handling method and calls various methods
269 to handle the request/response and defines the workflow within May‐
270 pole.
271 Currently undocumented and liable to be refactored without warning.
273 get_request
275 You should only need to define this method if you are writing a new
276 Maypole backend. It should return something that looks like an
277 Apache or CGI request object, it defaults to blank.
278 parse_location
280 Turns the backend request (e.g. Apache::MVC, Maypole, CGI) into a
281 Maypole request. It does this by setting the "path", and invoking
282 "parse_path" and "parse_args".
283 You should only need to define this method if you are writing a new
285 Maypole backend.
286 start_request_hook
288 This is called immediately after setting up the basic request. The
289 default method does nothing.
290 The value of "$r->status" is set to "OK" before this hook is run.
292 Your implementation can change the status code, or leave it alone.
293 After this hook has run, Maypole will check the value of "status".
295 For any value other than "OK", Maypole returns the "status" immedi‐
296 ately.
297 This is useful for filtering out requests for static files, e.g.
299 images, which should not be processed by Maypole or by the templat‐
300 ing engine:
301 sub start_request_hook
303 {
304 my ($r) = @_;
305 $r->status(DECLINED) if $r->path =~ /\.jpg$/;
307 }
308 Multiple plugins, and the driver, can define this hook - Maypole
310 will call all of them. You should check for and probably not change
311 any non-OK "status" value:
312 package Maypole::Plugin::MyApp::SkipFavicon;
314 sub start_request_hook
316 {
317 my ($r) = @_;
318 # check if a previous plugin has already DECLINED this request
320 # - probably unnecessary in this example, but you get the idea
321 return unless $r->status == OK;
322 # then do our stuff
324 $r->status(DECLINED) if $r->path =~ /favicon\.ico/;
325 }
326 is_applicable
328 This method is deprecated as of version 2.11. If you have overrid‐
329 den it, please override "is_model_applicable" instead, and change
330 the return type from a Maypole:Constant to a true/false value.
331 Returns a Maypole::Constant to indicate whether the request is
333 valid.
334 is_model_applicable
336 Returns true or false to indicate whether the request is valid.
337 The default implementation checks that "$r->table" is publicly
339 accessible and that the model class is configured to handle the
340 "$r->action".
341 get_session
343 Called immediately after "start_request_hook()".
344 This method should return a session, which will be stored in the
346 request's "session" attribute.
347 The default method is empty.
349 get_user
351 Called immediately after "get_session".
352 This method should return a user, which will be stored in the
354 request's "user" attribute.
355 The default method is empty.
357 call_authenticate
359 This method first checks if the relevant model class can authenti‐
360 cate the user, or falls back to the default authenticate method of
361 your Maypole application.
362 authenticate
364 Returns a Maypole::Constant to indicate whether the user is authen‐
365 ticated for the Maypole request.
366 The default implementation returns "OK"
368 call_exception
370 This model is called to catch exceptions, first after authenticate,
371 then after processing the model class, and finally to check for
372 exceptions from the view class.
373 This method first checks if the relevant model class can handle
375 exceptions the user, or falls back to the default exception method
376 of your Maypole application.
377 exception
379 This method is called if any exceptions are raised during the
380 authentication or model/view processing. It should accept the
381 exception as a parameter and return a Maypole::Constant to indicate
382 whether the request should continue to be processed.
383 additional_data
385 Called before the model processes the request, this method gives
386 you a chance to do some processing for each request, for example,
387 manipulating "template_args".
388 send_output
390 Sends the output and additional headers to the user.
391 Path processing and manipulation
393 path
395 Returns the request path
396 parse_path
398 Parses the request path and sets the "args", "action" and "table"
399 properties. Calls "preprocess_path" before parsing path and setting
400 properties.
401 preprocess_path
403 Sometimes when you don't want to rewrite or over-ride parse_path
404 but want to rewrite urls or extract data from them before it is
405 parsed.
406 This method is called after parse_location has populated the
408 request information and before parse_path has populated the model
409 and action information, and is passed the request object.
410 You can set action, args or table in this method and parse_path
412 will then leave those values in place or populate them if not
413 present
414 make_path( %args or \%args or @args )
416 This is the counterpart to "parse_path". It generates a path to use
417 in links, form actions etc. To implement your own path scheme, just
418 override this method and "parse_path".
419 %args = ( table => $table,
421 action => $action,
422 additional => $additional, # optional - generally an object ID
423 );
424 \%args = as above, but a ref
426 @args = ( $table, $action, $additional ); # $additional is optional
428 "id" can be used as an alternative key to "additional".
430 $additional can be a string, an arrayref, or a hashref. An arrayref
432 is expanded into extra path elements, whereas a hashref is trans‐
433 lated into a query string.
434 make_uri( @segments )
436 Make a URI object given table, action etc. Automatically adds the
437 "uri_base".
438 If the final element in @segments is a hash ref, "make_uri" will
440 render it as a query string.
441 parse_args
443 Turns post data and query string paramaters into a hash of
444 "params".
445 You should only need to define this method if you are writing a new
447 Maypole backend.
448 get_template_root
450 Implementation-specific path to template root.
451 You should only need to define this method if you are writing a new
453 Maypole backend. Otherwise, see "template_root" in Maypole::Config
454 Request properties
456 model_class
458 Returns the perl package name that will serve as the model for the
459 request. It corresponds to the request "table" attribute.
460 objects
462 Get/set a list of model objects. The objects will be accessible in
463 the view templates.
464 If the first item in "$self->args" can be "retrieve()"d by the
466 model class, it will be removed from "args" and the retrieved
467 object will be added to the "objects" list. See Maypole::Model for
468 more information.
469 object
471 Alias to get/set the first/only model object. The object will be
472 accessible in the view templates.
473 When used to set the object, will overwrite the request objects
475 with a single object.
476 template_args
478 $self->template_args->{foo} = 'bar';
479 Get/set a hash of template variables.
481 Maypole reserved words for template variables will over-ride values
483 in template_variables.
484 Reserved words are : r, request, object, objects, base, config and
486 errors, as well as the current class or object name.
487 stash
489 A place to put custom application data. Not used by Maypole itself.
490 template
492 Get/set the template to be used by the view. By default, it returns
493 "$self->action"
494 error
496 Get/set a request error
497 output
499 Get/set the response output. This is usually populated by the view
500 class. You can skip view processing by setting the "output".
501 table
503 The table part of the Maypole request path
504 action
506 The action part of the Maypole request path
507 args
509 A list of remaining parts of the request path after table and
510 action have been removed
511 headers_in
513 A Maypole::Headers object containing HTTP headers for the request
514 headers_out
516 A HTTP::Headers object that contains HTTP headers for the output
517 document_encoding
519 Get/set the output encoding. Default: utf-8.
520 content_type
522 Get/set the output content type. Default: text/html
523 get_protocol
525 Returns the protocol the request was made with, i.e. https
526 Request parameters
528 The source of the parameters may vary depending on the Maypole backend,
530 but they are usually populated from request query string and POST data.
531 Maypole supplies several approaches for accessing the request parame‐
533 ters. Note that the current implementation (via a hashref) of "query"
534 and "params" is likely to change in a future version of Maypole. So
535 avoid direct access to these hashrefs:
536 $r->{params}->{foo} # bad
538 $r->params->{foo} # better
539 $r->{query}->{foo} # bad
541 $r->query->{foo} # better
542 $r->param('foo') # best
544 param
546 An accessor (get or set) for request parameters. It behaves simi‐
547 larly to CGI::param() for accessing CGI parameters, i.e.
548 $r->param # returns list of keys
550 $r->param($key) # returns value for $key
551 $r->param($key => $value) # returns old value, sets to new value
552 params
554 Returns a hashref of request parameters.
555 Note: Where muliple values of a parameter were supplied, the
557 "params" value will be an array reference.
558 query
560 Alias for "params".
561 Utility methods
563 redirect_request
565 Sets output headers to redirect based on the arguments provided
566 Accepts either a single argument of the full url to redirect to, or
568 a hash of named parameters :
569 $r->redirect_request('http://www.example.com/path');
571 or
573 $r->redirect_request(protocol=>'https', domain=>'www.example.com',
575 path=>'/path/file?arguments', status=>'302', url=>'..');
576 The named parameters are protocol, domain, path, status and url
578 Only 1 named parameter is required but other than url, they can be
580 combined as required and current values (from the request) will be
581 used in place of any missing arguments. The url argument must be a
582 full url including protocol and can only be combined with status.
583 redirect_internal_request
585 make_random_id
586 returns a unique id for this request can be used to prevent or
587 detect repeat submissions.
588
590 See Maypole::Manual::Workflow for a detailed discussion of the sequence
591 of calls during processing of a request. This is a brief summary:
592 INITIALIZATION
594 Model e.g.
595 BeerDB Maypole::Model::CDBI
596 ⎪ ⎪
597 setup ⎪ ⎪
598 o-------->⎪⎪ ⎪
599 ⎪⎪ setup_model ⎪ setup_database() creates
600 ⎪⎪------+ ⎪ a subclass of the Model
601 ⎪⎪⎪<----+ ⎪ for each table
602 ⎪⎪⎪ ⎪ ⎪
603 ⎪⎪⎪ setup_database ⎪ ⎪
604 ⎪⎪⎪--------------------->⎪⎪ 'create' *
605 ⎪⎪⎪ ⎪⎪----------> $subclass
606 ⎪⎪⎪ ⎪ ⎪
607 ⎪⎪⎪ load_model_subclass ⎪ ⎪
608 foreach ⎪⎪⎪------+ ($subclass) ⎪ ⎪
609 $subclass ⎪⎪⎪⎪<----+ ⎪ require ⎪
610 ⎪⎪⎪⎪--------------------------------------->⎪
611 ⎪⎪⎪ ⎪ ⎪
612 ⎪⎪⎪ adopt($subclass) ⎪ ⎪
613 ⎪⎪⎪--------------------->⎪⎪ ⎪
614 ⎪ ⎪ ⎪
615 ⎪ ⎪ ⎪
616 ⎪-----+ init ⎪ ⎪
617 ⎪⎪<---+ ⎪ ⎪
618 ⎪⎪ ⎪ new ⎪ view_object: e.g.
619 ⎪⎪---------------------------------------------> Maypole::View::TT
620 ⎪ ⎪ ⎪ ⎪
621 ⎪ ⎪ ⎪ ⎪
622 ⎪ ⎪ ⎪ ⎪
623 ⎪ ⎪ ⎪ ⎪
624 ⎪ ⎪ ⎪ ⎪
625 HANDLING A REQUEST
627 BeerDB Model $subclass view_object
629 ⎪ ⎪ ⎪ ⎪
630 handler ⎪ ⎪ ⎪ ⎪
631 o-------->⎪ new ⎪ ⎪ ⎪
632 ⎪-----> r:BeerDB ⎪ ⎪ ⎪
633 ⎪ ⎪ ⎪ ⎪ ⎪
634 ⎪ ⎪ ⎪ ⎪ ⎪
635 ⎪ ⎪⎪ ⎪ ⎪ ⎪
636 ⎪ ⎪⎪-----+ parse_location ⎪ ⎪ ⎪
637 ⎪ ⎪⎪⎪<---+ ⎪ ⎪ ⎪
638 ⎪ ⎪⎪ ⎪ ⎪ ⎪
639 ⎪ ⎪⎪-----+ start_request_hook ⎪ ⎪ ⎪
640 ⎪ ⎪⎪⎪<---+ ⎪ ⎪ ⎪
641 ⎪ ⎪⎪ ⎪ ⎪ ⎪
642 ⎪ ⎪⎪-----+ get_session ⎪ ⎪ ⎪
643 ⎪ ⎪⎪⎪<---+ ⎪ ⎪ ⎪
644 ⎪ ⎪⎪ ⎪ ⎪ ⎪
645 ⎪ ⎪⎪-----+ get_user ⎪ ⎪ ⎪
646 ⎪ ⎪⎪⎪<---+ ⎪ ⎪ ⎪
647 ⎪ ⎪⎪ ⎪ ⎪ ⎪
648 ⎪ ⎪⎪-----+ handler_guts ⎪ ⎪ ⎪
649 ⎪ ⎪⎪⎪<---+ ⎪ ⎪ ⎪
650 ⎪ ⎪⎪⎪ class_of($table) ⎪ ⎪ ⎪
651 ⎪ ⎪⎪⎪------------------------->⎪⎪ ⎪ ⎪
652 ⎪ ⎪⎪⎪ $subclass ⎪⎪ ⎪ ⎪
653 ⎪ ⎪⎪⎪<-------------------------⎪⎪ ⎪ ⎪
654 ⎪ ⎪⎪⎪ ⎪ ⎪ ⎪
655 ⎪ ⎪⎪⎪-----+ is_model_applicable⎪ ⎪ ⎪
656 ⎪ ⎪⎪⎪⎪<---+ ⎪ ⎪ ⎪
657 ⎪ ⎪⎪⎪ ⎪ ⎪ ⎪
658 ⎪ ⎪⎪⎪-----+ call_authenticate ⎪ ⎪ ⎪
659 ⎪ ⎪⎪⎪⎪<---+ ⎪ ⎪ ⎪
660 ⎪ ⎪⎪⎪ ⎪ ⎪ ⎪
661 ⎪ ⎪⎪⎪-----+ additional_data ⎪ ⎪ ⎪
662 ⎪ ⎪⎪⎪⎪<---+ ⎪ ⎪ ⎪
663 ⎪ ⎪⎪⎪ process ⎪ ⎪ ⎪
664 ⎪ ⎪⎪⎪--------------------------------->⎪⎪ fetch_objects
665 ⎪ ⎪⎪⎪ ⎪ ⎪⎪-----+ ⎪
666 ⎪ ⎪⎪⎪ ⎪ ⎪⎪⎪<---+ ⎪
667 ⎪ ⎪⎪⎪ ⎪ ⎪⎪ ⎪
668 ⎪ ⎪⎪⎪ ⎪ ⎪⎪ $action
669 ⎪ ⎪⎪⎪ ⎪ ⎪⎪-----+ ⎪
670 ⎪ ⎪⎪⎪ ⎪ ⎪⎪⎪<---+ ⎪
671 ⎪ ⎪⎪⎪ process ⎪ ⎪ ⎪
672 ⎪ ⎪⎪⎪------------------------------------------->⎪⎪ template
673 ⎪ ⎪⎪⎪ ⎪ ⎪ ⎪⎪-----+
674 ⎪ ⎪⎪⎪ ⎪ ⎪ ⎪⎪⎪<---+
675 ⎪ ⎪⎪⎪ ⎪ ⎪ ⎪
676 ⎪ ⎪⎪ send_output ⎪ ⎪ ⎪
677 ⎪ ⎪⎪-----+ ⎪ ⎪ ⎪
678 ⎪ ⎪⎪⎪<---+ ⎪ ⎪ ⎪
679 $status ⎪ ⎪⎪ ⎪ ⎪ ⎪
680 <------------------⎪⎪ ⎪ ⎪ ⎪
681 ⎪ ⎪ ⎪ ⎪ ⎪
682 ⎪ X ⎪ ⎪ ⎪
683 ⎪ ⎪ ⎪ ⎪
684 ⎪ ⎪ ⎪ ⎪
685 ⎪ ⎪ ⎪ ⎪
686
688 There's more documentation, examples, and information on our mailing
689 lists at the Maypole web site:
690 <http://maypole.perl.org/>
692 Maypole::Application, Apache::MVC, CGI::Maypole.
694
696 Maypole is currently maintained by Aaron Trevena.
697
699 Simon Cozens, "simon#cpan.org"
700 Simon Flack maintained Maypole from 2.05 to 2.09
702 Sebastian Riedel, "sri#oook.de" maintained Maypole from 1.99_01 to 2.04
704
706 Sebastian Riedel, Danijel Milicevic, Dave Slack, Jesse Sheidlower, Jody
707 Belka, Marcus Ramberg, Mickael Joanne, Randal Schwartz, Simon Flack,
708 Steve Simms, Veljko Vidovic and all the others who've helped.
709
711 You may distribute this code under the same terms as Perl itself.
712perl v5.8.8 2005-11-23 Maypole(3)