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 9a933bdd106450cdeb1ed8f09b4d987f08413802..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,7 +239,8 @@ 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
 
@@ -252,10 +252,37 @@ 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.
+=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