X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=lib%2FApache%2FMVC.pm;h=68f2c0af1fdf0319d4ffa4de080532f5f787bba5;hb=9bbeafd23117d2b489a298cc002a97b133de17bd;hp=5d999be45e93d971dcb6a1586fef27cceb03b9d5;hpb=48b7f94a68422ee2d1ee9ca6bf9cd5c2ee34e189;p=maypole.git diff --git a/lib/Apache/MVC.pm b/lib/Apache/MVC.pm index 5d999be..68f2c0a 100644 --- a/lib/Apache/MVC.pm +++ b/lib/Apache/MVC.pm @@ -30,14 +30,13 @@ sub parse_location { =head1 NAME -Apache::MVC - Web front end to a data source +Apache::MVC - Apache front-end to Maypole =head1 SYNOPSIS package BeerDB; use base 'Apache::MVC'; - sub handler { Apache::MVC::handler("BeerDB", @_) } - BeerDB->set_database("dbi:mysql:beerdb"); + BeerDB->setup("dbi:mysql:beerdb"); BeerDB->config->{uri_base} = "http://your.site/"; BeerDB->config->{display_tables} = [qw[beer brewery pub style]]; # Now set up your database: @@ -48,102 +47,73 @@ Apache::MVC - Web front end to a data source =head1 DESCRIPTION -A large number of web programming tasks follow the same sort of pattern: -we have some data in a datasource, typically a relational database. We -have a bunch of templates provided by web designers. We have a number of -things we want to be able to do with the database - create, add, edit, -delete records, view records, run searches, and so on. We have a web -server which provides input from the user about what to do. Something in -the middle takes the input, grabs the relevant rows from the database, -performs the action, constructs a page, and spits it out. - -This module aims to be the most generic and extensible "something in the -middle". - -An example would help explain this best. You need to add a product -catalogue to a company's web site. Users need to list the products in -various categories, view a page on each product with its photo and -pricing information and so on, and there needs to be a back-end where -sales staff can add new lines, change prices, and delete out of date -records. So, you set up the database, provide some default templates -for the designers to customize, and then write an Apache handler like -this: - - package ProductDatabase; - use base 'Apache::MVC'; - __PACKAGE__->set_database("dbi:mysql:products"); - BeerDB->config->{uri_base} = "http://your.site/catalogue/"; - ProductDatabase::Product->has_a("category" => ProductDatabase::Category); - # ... - - sub authenticate { - my ($self, $request) = @_; - return OK if $request->{ar}->get_remote_host() eq "sales.yourcorp.com"; - return OK if $request->{action} =~ /^(view|list)$/; - return DECLINED; - } - 1; +Maypole is a Perl web application framework to Java's struts. It is +essentially completely abstracted, and so doesn't know anything about +how to talk to the outside world. C is a mod_perl based +subclass of Maypole. -You then put the following in your Apache config: +To use it, you need to create a package which represents your entire +application. In our example above, this is the C package. - - SetHandler perl-script - PerlHandler ProductDatabase - +This needs to first inherit from C, and then call setup. +This will give your package an Apache-compatible C subroutine, +and then pass any parameters onto the C method of the +model class. The default model class for Maypole uses L to +map a database to classes, but this can be changed by messing with the +configuration. (B calling setup.) -And copy the templates found in F into the -F directory off the web root. When the designers get -back to you with custom templates, they are to go in -F. If you need to do override templates on a -database-table-by-table basis, put the new template in -F>. +Next, you should configure your application through the C +method. Configuration parameters at present are: -This will automatically give you C, C, C, C and -C commands; for instance, a product list, go to +=over - http://your.site/catalogue/product/list +=item uri_base -For a full example, see the included "beer database" application. +You B specify this; it is the base URI of the application, which +will be used to construct links. -=head1 HOW IT WORKS +=item display_tables -There's some documentation for the workflow in L, -but the basic idea is that a URL part like C gets -translated into a call to Clist>. This -propagates the request with a set of objects from the database, and then -calls the C template; first, a C template if it -exists, then the C and finally C. +If you do not want all of the tables in the database to be accessible, +then set this to a list of only the ones you want to display -If there's another action you want the system to do, you need to either -subclass the model class, and configure your class slightly differently: +=item rows_per_page - package ProductDatabase::Model; - use base 'Apache::MVC::Model::CDBI'; +List output is paged if you set this to a positive number of rows. - sub supersearch :Exported { - my ($self, $request) = @_; - # Do stuff, get a bunch of objects back - $r->objects(\@objects); - $r->template("template_name"); - } +=back - ProductDatabase->config->{model_class} = "ProductDatabase::Model"; +You should also set up relationships between your classes, such that, +for instance, calling C on a C object returns an +object representing its associated brewery. + +For a full example, see the included "beer database" application. -(The C<:Exported> attribute means that the method can be called via the -URL C/supersearch/...>.) +=head1 INSTALLATION -Alternatively, you can put the method directly into the specific model -class for the table: +Create a driver module like the one above. + +Put the following in your Apache config: + + + SetHandler perl-script + PerlHandler BeerDB + + +Copy the templates found in F into the +F directory off the web root. When the designers get +back to you with custom templates, they are to go in +F. If you need to do override templates on a +database-table-by-table basis, put the new template in +F>. + +This will automatically give you C, C, C, C and +C commands; for instance, a list of breweries, go to - sub ProductDatabase::Product::supersearch :Exported { ... } + http://your.site/beer/brewery/list -By default, the view class uses Template Toolkit as the template -processor, and the model class uses C; it may help you to be -familiar with these modules before going much further with this, -although I expect there to be other subclasses for other templating -systems and database abstraction layers as time goes on. The article at -C is a great -introduction to the process we're trying to automate. +For more information about how the system works and how to extend it, +see L. =head1 AUTHOR