From: Simon Cozens <simon@simon-cozens.org>
Date: Sat, 13 Mar 2004 14:17:38 +0000 (+0000)
Subject: Some more work; about to move to autodoc.
X-Git-Tag: 2.10~276
X-Git-Url: https://git.decadent.org.uk/gitweb/?a=commitdiff_plain;h=71d2d50f29d9567782dac884b51680900eff2852;p=maypole.git

Some more work; about to move to autodoc.


git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@86 48953598-375a-da11-a14b-00016c27c3ee
---

diff --git a/doc/StandardTemplates.pod b/doc/StandardTemplates.pod
index 9a933bd..dd76189 100644
--- 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
 
@@ -253,9 +253,57 @@ 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.
+C<objects> and displays the object's properties in a table. It gets
+the displayable form of a column's name from the hash returned from
+the C<column_names> method:
+
+    <TR>
+        <TD class="field"> [% classmetadata.colnames.$col; %] </TD>
+
+One interesting macro used in this template is C<maybe_link_view>:
+
+        maybe_link_view(item.$col);
+
+This tests whether or not the returned value is an object, and if so,
+creates a link to a page viewing that object; if not, it just displays
+the text as normal. The object is linked using its stringified name;
+by default this calls the C<name> method, or returns the object's ID
+if there is no C<name> method or other stringification method defined.
+
+The C<view> template also displays a list of other objects related to the first
+one via C<has_many> style relationships; this is done by calling the
+C<related_accessors> method - see L<Model/related_accessors> - to return
+a list of has-many accessors. Next it calls each of those accessors, and
+displays the results in a table.
 
 =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 %]
+