Add constants; refactor View classes and tests to use them; refactor out handler_guts

[maypole.git] / doc / StandardTemplates.pod

diff --git a/doc/StandardTemplates.pod b/doc/StandardTemplates.pod
index c3c4dd31db76a5257bb63e48567a445ad8e0f94b..e5eb9f06b2f32aeaebde9438469bb90301b9b2d1 100644 (file)
--- a/doc/StandardTemplates.pod
+++ b/doc/StandardTemplates.pod
@@ -176,7 +176,6 @@ is then sent back to the C<edit> template.
 
         if (my %errors = $obj->cgi_update_errors) {
             # Set it up as it was:
-            warn "There were errors: ".Dumper(\%errors)."\n";
             $r->{template_args}{cgi_params} = $r->{params};
             $r->{template_args}{errors} = \%errors;
             $r->{template} = "edit";
@@ -193,16 +192,97 @@ 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, and as such are
+useful examples of how to build Maypole templates.
+
+=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> 
+
+=template view
+
+=head3 F<edit>
+
+The F<edit> template is pretty much the same as F<view>, but it uses the
+C<to_field> method on each column of an object to return a C<HTML::Element>
+object representing a form element to edit that property. These elements
+are then rendered to HTML with C<as_HTML>. It expects to see a list of
+editing errors, if any, in the C<errors> template variable:
+
+     FOR col = classmetadata.columns;
+        NEXT IF col == "id";
+        "<P>";
+        "<B>"; classmetadata.colnames.$col; "</B>";
+        ": ";
+            item.to_field(col).as_HTML;
+        "</P>";
+        IF errors.$col;
+            "<FONT COLOR=\"#ff0000\">"; errors.$col; "</FONT>";
+        END;
+    END;
+
+=head3 F<list>
+
+Browsing records and search results are both handled by the F<list> template.
+The C<search> template argument is used to distinguish between the two cases:
+
+    [% IF search %]
+    <h2> Search results </h2>
+    [% ELSE %]
+    <h2> Listing of all [% classmetadata.plural %]</h2>
+    [% END %]
+
+=head1 Customizing Generic CRUD Applications