I AM NOT SUPPOSED TO BE WORKING TODAY.

[maypole.git] / doc / StandardTemplates.pod

diff --git a/doc/StandardTemplates.pod b/doc/StandardTemplates.pod
index c3c4dd31db76a5257bb63e48567a445ad8e0f94b..9a933bdd106450cdeb1ed8f09b4d987f08413802 100644 (file)
--- a/doc/StandardTemplates.pod
+++ b/doc/StandardTemplates.pod
@@ -193,16 +193,69 @@ Notice that this does use hard-coded names for the templates to go to next.
 Feel free to override this in your subclasses:
 
     sub do_edit :Exported {
-        my ($class, $r) = shift;
+        my ($class, $r) = @_;
         $class->SUPER::do_edit($r);
         $r->template("my_edit");
     }
 
 =head3 delete
 
+The delete method takes a number of arguments and deletes those rows from the
+database; it then loads up all rows and heads to the F<list> template.
+You almost certainly want to override this to provide some kind of
+authentication.
 
 =head3 list
 
+Listing, like viewing, is a matter of selecting objects for
+presentation. This time, instead of a single object specified in the
+URL, we want, by default, all the records in the table:
+
+    sub list :Exported {
+        my ($class, $r) = @_;
+        $r->objects([ $self->retrieve_all ])
+    }
+
+However, things are slightly complicated by paging and ordering by
+column; the default implementation also provides a C<Class::DBI::Pager>
+object to the templates and uses that to retrieve the appropriate bit of
+the data, as specified by the C<page> URL query parameter. See the F<pager> 
+template below.
+
 =head3 search
 
+Searching also uses paging, and creates a query from the C<POST>
+parameters. It uses the F<list> template to display the objects once
+they've been selected from the database.
+
 =head2 The templates and macros
+
+Once these actions have done their work, they hand a set of objects to
+the templates; if you haven't specified your own custom template
+globally or for a given class, you'll be using the factory specified
+template. Let's take a look now at each of these and how they're put
+together.
+
+The beauty of the factory specified templates is that they make use of
+the classes' metadata as supplied by the view class. Although you're
+strongly encouraged to write your own templates, in which you don't need
+to necessarily be as generic, the factory templates will always do the
+right thing for any class without further modification.
+
+=head3 Commonalities
+
+There are certain common elements to a template, and these are extracted
+out. For instance, all the templates call the F<header> template to
+output a HTML header, and nearly all include the F<macros> template to
+load up some common template functions. We'll look at these common
+macros as we come across them.
+
+=head3 F<view> 
+
+The C<view> template takes some objects (usually just one) from
+C<objects> and displays the object's properties in a table. It also
+displays a list of other objects related to the first one via 
+C<has_many> style relationships.
+
+=head3 F<edit>
+=head3 F<list>