X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=lib%2FMaypole.pm;h=b84360cc0262e9e4e77dc6ebf41b05f8d876fccc;hb=6c19a422c2c4bc3457f311ffc0403b8644690074;hp=6c6ff52c0fc8ef0cad989205b9925382ccb03014;hpb=ea4ae8a93a09e21354465c485471e5f10582b784;p=maypole.git diff --git a/lib/Maypole.pm b/lib/Maypole.pm index 6c6ff52..b84360c 100644 --- a/lib/Maypole.pm +++ b/lib/Maypole.pm @@ -22,7 +22,45 @@ Maypole - MVC web application framework =head1 SYNOPSIS -See L. +The canonical example used in the Maypole documentation is the beer database: + + package BeerDB; + use strict; + use warnings; + + # choose a frontend, initialise the config object, and load a plugin + use Maypole::Application qw/Relationship/; + + # get the empty config object created by Maypole::Application + my $config = __PACKAGE__->config; + + # basic settings + $config->uri_base("http://localhost/beerdb"); + $config->template_root("/path/to/templates"); + $config->rows_per_page(10); + $config->display_tables([qw[beer brewery pub style]]); + + # table relationships + $config->relationships([ + "a brewery produces beers", + "a style defines beers", + "a pub has beers on handpumps", + ]); + + # validation + BeerDB::Brewery->untaint_columns( printable => [qw/name notes url/] ); + BeerDB::Pub->untaint_columns( printable => [qw/name notes url/] ); + BeerDB::Style->untaint_columns( printable => [qw/name notes/] ); + BeerDB::Beer->untaint_columns( + printable => [qw/abv name price notes/], + integer => [qw/style brewery score/], + date => [ qw/date/], + ); + + # set everything up + __PACKAGE__->setup("dbi:SQLite:t/beerdb.db"); + + 1; =head1 DESCRIPTION @@ -38,8 +76,8 @@ application. This is the C package used as an example in the manual. This needs to first use L which will make your package inherit from the appropriate platform driver such as C or -C. Then, the driver calls C. This sets up the model classes and -configures your application. The default model class for Maypole uses +C. Then, the driver calls C. This sets up the model classes +and configures your application. The default model class for Maypole uses L to map a database to classes, but this can be changed by altering configuration (B calling setup.) @@ -168,10 +206,47 @@ __PACKAGE__->config( Maypole::Config->new() ); __PACKAGE__->init_done(0); +=head1 HOOKABLE METHODS + +As a framework, Maypole provides a number of B - methods that are +intended to be overridden. Some of these methods come with useful default +behaviour, others do nothing by default. Likely hooks include: + + Class methods + ------------- + debug + setup + setup_model + load_model_subclass + init + + Instance methods + ---------------- + start_request_hook + is_model_applicable + get_session + authenticate + exception + additional_data + preprocess_path + =head1 CLASS METHODS =over 4 +=item debug + + sub My::App::debug {1} + +Returns the debugging flag. Override this in your application class to +enable/disable debugging. + +You can also set the C flag via L. + +=cut + +sub debug { 0 } + =item config Returns the L object @@ -230,17 +305,54 @@ sub setup_model { no strict 'refs'; unshift @{ $subclass . "::ISA" }, $config->model; - $config->model->adopt($subclass) - if $config->model->can("adopt"); - - # Load custom model code, if it exists - nb this must happen after the - # unshift, to allow code attributes to work - eval "use $subclass"; - die "Error loading $subclass: $@" - if $@ and $@ !~ /Can\'t locate \S+ in \@INC/; + + # Load custom model code, if it exists - nb this must happen after the + # unshift, to allow code attributes to work, but before adopt(), + # in case adopt() calls overridden methods on $subclass + $class->load_model_subclass($subclass); + + $config->model->adopt($subclass) if $config->model->can("adopt"); + +# eval "use $subclass"; +# die "Error loading $subclass: $@" +# if $@ and $@ !~ /Can\'t locate \S+ in \@INC/; } } +=item load_model_subclass($subclass) + +This method is called from C. It attempts to load the +C<$subclass> package, if one exists. So if you make a customized C +package, you don't need to explicitly load it. + +If, perhaps during development, you don't want to load up custom classes, you +can override this method and load them manually. + +=cut + +sub load_model_subclass +{ + my ($class, $subclass) = @_; + + my $config = $class->config; + + # Load any external files for the model base class or subclasses + # (e.g. BeerDB/DBI.pm or BeerDB/Beer.pm) based on code borrowed from + # Maypole::Plugin::Loader and Class::DBI. + if ( $subclass->require ) + { + warn "Loaded external module for '$subclass'\n" if $class->debug > 1; + } + else + { + (my $filename = $subclass) =~ s!::!/!g; + die "Loading '$subclass' failed: $@\n" + unless $@ =~ /Can\'t locate \Q$filename\E\.pm/; + warn "Did not find external module for '$subclass'\n" + if $class->debug > 1; + } +} + =item init Loads the view class and instantiates the view object. @@ -285,30 +397,6 @@ sub new Get/set the Maypole::View object -=item debug - - sub My::App::debug {1} - -Returns the debugging flag. Override this in your application class to -enable/disable debugging. - -You can also set the C flag via L. - -=cut - -sub debug { 0 } - -=item get_template_root - -Implementation-specific path to template root. - -You should only need to define this method if you are writing a new Maypole -backend. Otherwise, see L - -=cut - -sub get_template_root {'.'} - =back =head1 INSTANCE METHODS @@ -377,7 +465,7 @@ sub handler_guts { my ($self) = @_; - $self->__load_model; + $self->__load_request_model; my $applicable = $self->is_model_applicable; @@ -434,7 +522,7 @@ sub handler_guts return $self->__call_process_view; } -sub __load_model +sub __load_request_model { my ($self) = @_; $self->model_class( $self->config->model->class_of($self, $self->table) ); @@ -669,6 +757,7 @@ sub call_exception return $self->exception($error); } + =item exception This method is called if any exceptions are raised during the authentication or @@ -730,11 +819,11 @@ sub parse_path $self->$_(undef) for qw/action table args/; $self->preprocess_path; - $self->path || $self->path('frontpage'); - + my @pi = grep {length} split '/', $self->path; - + + $self->table || $self->table(shift @pi); $self->action || $self->action( shift @pi or 'index' ); $self->args || $self->args(\@pi); @@ -853,6 +942,25 @@ Turns post data and query string paramaters into a hash of C. You should only need to define this method if you are writing a new Maypole backend. +=cut + +sub parse_args +{ + die "parse_args() is a virtual method. Do not use Maypole directly; ". + "use Apache::MVC or similar"; +} + +=item get_template_root + +Implementation-specific path to template root. + +You should only need to define this method if you are writing a new Maypole +backend. Otherwise, see L + +=cut + +sub get_template_root {'.'} + =back =head2 Request properties @@ -1061,9 +1169,110 @@ sub make_random_id { =back +=head1 SEQUENCE DIAGRAMS + +See L for a detailed discussion of the sequence of +calls during processing of a request. This is a brief summary: + + INITIALIZATION + Model e.g. + BeerDB Maypole::Model::CDBI + | | + setup | | + o-------->|| | + || setup_model | setup_database() creates + ||------+ | a subclass of the Model + |||<----+ | for each table + ||| | | + ||| setup_database | | + |||--------------------->|| 'create' * + ||| ||----------> $subclass + ||| | | + ||| load_model_subclass | | + foreach |||------+ ($subclass) | | + $subclass ||||<----+ | require | + ||||--------------------------------------->| + ||| | | + ||| adopt($subclass) | | + |||--------------------->|| | + | | | + | | | + |-----+ init | | + ||<---+ | | + || | new | view_object: e.g + ||---------------------------------------------> Maypole::View::TT + | | | | + | | | | + | | | | + | | | | + | | | | + + + + HANDLING A REQUEST + + + BeerDB Model $subclass view_object + | | | | + handler | | | | + o-------->| new | | | + |-----> r:BeerDB | | | + | | | | | + | | | | | + | || | | | + | ||-----+ parse_location | | | + | |||<---+ | | | + | || | | | + | ||-----+ start_request_hook | | | + | |||<---+ | | | + | || | | | + | ||-----+ get_session | | | + | |||<---+ | | | + | || | | | + | ||-----+ handler_guts | | | + | |||<---+ | | | + | ||| class_of($table) | | | + | |||------------------------->|| | | + | ||| $subclass || | | + | |||<-------------------------|| | | + | ||| | | | + | |||-----+ is_model_applicable| | | + | ||||<---+ | | | + | ||| | | | + | |||-----+ call_authenticate | | | + | ||||<---+ | | | + | ||| | | | + | |||-----+ additional_data | | | + | ||||<---+ | | | + | ||| process | | fetch_objects + | |||--------------------------------->||-----+ | + | ||| | |||<---+ | + | ||| | || | + | ||| | || $action + | ||| | ||-----+ | + | ||| | |||<---+ | + | ||| | | | + | ||| process | | | + | |||------------------------------------------->|| template + | ||| | | ||-----+ + | ||| | | |||<---+ + | ||| | | | + | || send_output | | | + | ||-----+ | | | + | |||<---+ | | | + $status | || | | | + <------------------|| | | | + | | | | | + | X | | | + | | | | + | | | | + | | | | + + + =head1 SEE ALSO -There's more documentation, examples, and a information on our mailing lists +There's more documentation, examples, and information on our mailing lists at the Maypole web site: L @@ -1072,12 +1281,15 @@ L, L, L. =head1 AUTHOR -Maypole is currently maintained by Aaron Trevena +Maypole is currently maintained by Aaron Trevena, David Baird, Dave Howorth and +Peter Speltz. =head1 AUTHOR EMERITUS Simon Cozens, C +Simon Flack maintained Maypole from 2.05 to 2.09 + Sebastian Riedel, C maintained Maypole from 1.99_01 to 2.04 =head1 THANKS TO