Swathes of documentation.

[maypole.git] / lib / Apache / MVC.pm

diff --git a/lib/Apache/MVC.pm b/lib/Apache/MVC.pm
index c9db3ae415008cf9dcf1613abdf95d90fe766515..910562cee6043d84eaebe1dfd14ea4b09d35bfd0 100644 (file)
--- a/lib/Apache/MVC.pm
+++ b/lib/Apache/MVC.pm
@@ -73,7 +73,6 @@ sub handler {
     $r->get_request();
     $r->parse_location();
 
-    warn "Parsed location\n";
     $r->model_class($r->class_of($r->{table}));
     my $status = $r->is_applicable;
     if ($status == OK) { 
@@ -83,12 +82,10 @@ sub handler {
     
         $r->model_class->process($r);
     } else { 
-        warn "Plain template $r->{path}";
         # Otherwise, it's just a plain template.
         delete $r->{model_class};
         $r->{path} =~ s{/}{}; # De-absolutify
         $r->template($r->{path});
-        warn $r->template;
     }
     return $r->view_object->process($r);
 }
@@ -104,7 +101,6 @@ sub parse_location {
     $self->{path} = $self->{ar}->uri;
     my $loc = $self->{ar}->location;
     $self->{path} =~ s/^$loc//; # I shouldn't need to do this?
-    warn "Path is $self->{path}";
     my @pi = split /\//, $self->{path};
     shift @pi while @pi and !$pi[0];
     $self->{table} = shift @pi;
@@ -166,7 +162,7 @@ Apache::MVC - Web front end to a data source
 
     1;
 
-=haed1 DESCRIPTION
+=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
@@ -189,7 +185,86 @@ 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 MyCorp::ProductDatabase;
+    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;
+
+You then put the following in your Apache config:
+
+    <Location /catalogue>
+        SetHandler perl-script
+        PerlHandler ProductDatabase
+    </Location>
+
+And copy the templates found in F<templates/factory> into the
+F<catalogue/factory> directory off the web root. When the designers get
+back to you with custom templates, they are to go in
+F<catalogue/custom>. If you need to do override templates on a
+database-table-by-table basis, put the new template in
+F<catalogue/I<table>>. 
+
+This will automatically give you C<add>, C<edit>, C<list>, C<view> and
+C<delete> commands; for instance, a product list, go to 
+
+    http://your.site/catalogue/product/list
+
+For a full example, see the included "beer database" application.
+
+=head1 HOW IT WORKS
+
+There's some documentation for the workflow in L<Apache::MVC::Workflow>,
+but the basic idea is that a URL part like C<product/list> gets
+translated into a call to C<ProductDatabase::Product-E<gt>list>. This
+propagates the request with a set of objects from the database, and then 
+calls the C<list> template; first, a C<product/list> template if it
+exists, then the C<custom/list> and finally C<factory/list>. 
+
+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:
+
+    package ProductDatabase::Model;
+    use base 'Apache::MVC::Model::CDBI';
+
+    sub supersearch :Exported {
+        my ($self, $request) = @_;
+        # Do stuff, get a bunch of objects back
+        $r->objects(\@objects);
+        $r->template("template_name");
+    }
+
+    ProductDatabase->config->{model_class} = "ProductDatabase::Model";
+
+(The C<:Exported> attribute means that the method can be called via the
+URL C</I<table>/supersearch/...>.)
+
+Alternatively, you can put the method directly into the specific model
+class for the table:
+
+    sub ProductDatabase::Product::supersearch :Exported { ... }
+
+By default, the view class uses Template Toolkit as the template
+processor, and the model class uses C<Class::DBI>; 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<http://www.perl.com/pub/a/2003/07/15/nocode.html> is a great
+introduction to the process we're trying to automate.
+
+=head1 AUTHOR
+
+Simon Cozens, C<simon@cpan.org>
+
+=head1 LICENSE
+
+You may distribute this code under the same terms as Perl itself.