X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=lib%2FMaypole.pm;h=9f1af35366433899221fa6cf1fe191eb42dd8cfa;hb=dc0c8b4a91ac443404c0a397cd53d2a78f23f97e;hp=cd9ec49951099656ed7325290a5f9dcf1f020a22;hpb=4043f9681bc177aa9ba86effd589c7cccf4b6783;p=maypole.git diff --git a/lib/Maypole.pm b/lib/Maypole.pm index cd9ec49..9f1af35 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. 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 @@ -205,38 +280,79 @@ Called by C. This method builds the Maypole model hierarchy. A likely target for over-riding, if you need to build a customised model. +This method also ensures any code in custom model classes is loaded, so you +don't need to load them in the driver. + =cut sub setup_model { - my $calling_class = shift; + my $class = shift; - $calling_class = ref $calling_class if ref $calling_class; + $class = ref $class if ref $class; - my $config = $calling_class->config; + my $config = $class->config; $config->model || $config->model('Maypole::Model::CDBI'); $config->model->require or die sprintf "Couldn't load the model class %s: %s", $config->model, $@; - $config->model->setup_database($config, $calling_class, @_); + # among other things, this populates $config->classes + $config->model->setup_database($config, $class, @_); foreach my $subclass ( @{ $config->classes } ) { no strict 'refs'; unshift @{ $subclass . "::ISA" }, $config->model; - $config->model->adopt($subclass) - if $config->model->can("adopt"); - - # TODO: I think we should also load these classes, in case there is any - # custom code. It would save the developer from needing to put - # lots of use MyApp::SomeTable statements in the driver, and should - # help eliminate some of those annoying silent errors if there's a - # syntax error. + + # 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. @@ -281,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 @@ -339,7 +431,8 @@ sub handler : method $self->get_request($req); $self->parse_location; - # hook useful for declining static requests e.g. images + # hook useful for declining static requests e.g. images, or perhaps for + # sanitizing request parameters my $status = $self->start_request_hook; return $status unless $status == Maypole::Constants::OK(); @@ -373,7 +466,7 @@ sub handler_guts { my ($self) = @_; - $self->__load_model; + $self->__load_request_model; my $applicable = $self->is_model_applicable; @@ -430,7 +523,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) ); @@ -665,6 +758,7 @@ sub call_exception return $self->exception($error); } + =item exception This method is called if any exceptions are raised during the authentication or @@ -726,11 +820,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); @@ -849,6 +943,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 @@ -1005,6 +1118,8 @@ Alias for C. =head3 Utility methods +=over 4 + =item redirect_request Sets output headers to redirect based on the arguments provided @@ -1055,9 +1170,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 @@ -1066,12 +1282,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