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 215c4ca1f4de24f22564f7a422696d44c309651d..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";
@@ -240,8 +239,50 @@ 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.
+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