A little bit of refactoring and documentation.

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

diff --git a/templates/factory/addnew b/templates/factory/addnew
index f541e27b995f2a4fb680e7e93100a29b42dda5e3..56e794b095c2fb208327e2fc08b6dd747bd904d3 100644 (file)
--- a/templates/factory/addnew
+++ b/templates/factory/addnew
@@ -1,3 +1,15 @@
+[%#
+
+=head1 addnew
+
+This is the interface to adding a new instance of an object. (or a new
+row in the database, if you want to look at it that way) It displays a
+form containing a list of HTML components for each of the columns in the
+table.
+
+=cut
+
+#%]
 <h3>Add a new [%classmetadata.moniker%]</h3>
 <FORM METHOD="post" ACTION="[%base%]/[%classmetadata.moniker%]/do_edit/">
     <INPUT TYPE="hidden" NAME="action" VALUE="create">

diff --git a/templates/factory/edit b/templates/factory/edit
index 712348a074635240665f574b5185e9e8f98a293f..0de9f7924fd0d9b0e4dd7090bda2b43ad5cc711d 100644 (file)
--- a/templates/factory/edit
+++ b/templates/factory/edit
@@ -1,3 +1,12 @@
+[%#
+
+=head1 edit
+
+This is the edit page. It edits the passed-in object, by displaying a
+form similar to L<add_new> but with the current values filled in.
+
+#%]
+
 [% PROCESS macros %]
 [% INCLUDE header %]
 

diff --git a/templates/factory/macros b/templates/factory/macros
index 044ba456ad44c4d82016e6abd526920db94d04a0..7e3284c3861196d45be137e0e57b1765ef9a40a3 100644 (file)
--- a/templates/factory/macros
+++ b/templates/factory/macros
@@ -1,19 +1,61 @@
-[% MACRO maybe_link_view(object) BLOCK;
+[%#
+
+=head1 MACROS
+
+These are some default macros which are used by various templates in the
+system.
+
+=head2 link
+
+This creates an <A HREF="... to a command in the Apache::MVC system by
+catenating the base URL, table, command, and any arguments.
+
+#%]
+[%
+MACRO link(table, command, additional, label) BLOCK;
+    '<A HREF="' _ base _ table _ "/" _ command _ "/" _ additional _ '">';
+    label;
+    "</A>";
+END;
+%]
+
+[%#
+
+=head2 maybe_link_view
+
+C<maybe_link_view> takes something returned from the database - either
+some ordinary data, or an object in a related class expanded by a
+has-a relationship. If it is an object, it constructs a link to the view
+command for that object. Otherwise, it just displays the data.
+
+#%]
+
+[%
+MACRO maybe_link_view(object) BLOCK;
     IF object.moniker; # It's an object, i.e. a has-a
-        "<A HREF='" _ base _ object.moniker _ "/view/" _ object.id _"'>";
-        object;
-        "</A>";
+        link(object.moniker, "view", object.id, object);
     ELSE;
         object;
     END;
 END;
 %]
 
+[%#
+
+=head2 display_line
+
+C<display_line> is used in the list template to display a row from the
+database, by iterating over the columns and displaying the data for each
+column. It misses out the C<id> column by default, and magically
+URLifies columns called C<url>. This may be considered too much magic
+for some.
+
+#%]
 [% MACRO display_line(item) BLOCK;
      FOR col = classmetadata.columns;
         NEXT IF col == "id";
         "<td>";
-        IF col == "url";  # Possibly too much magic.
+        IF col == "url";
             "<A HREF="; item.url; "> "; item.url; "</A>";
         ELSIF col == "name";
             maybe_link_view(item);
@@ -25,7 +67,15 @@ END;
     button(item, "edit");
     button(item, "delete");
 END %]
+[%#
+
+=head2 button
 
+This is a generic button, which performs an action on an object.
+
+=cut
+
+#%]
 [% MACRO button(obj, action) BLOCK; %]
 <TD>
 <FORM METHOD="post" ACTION="[%base%]/[%obj.moniker%]/[%action%]/[%obj.id%]">
@@ -33,8 +83,20 @@ END %]
 </FORM>
 </TD>
 [% END %]
+[%#
+
+=head2 view_related
 
-[% MACRO view_related(object) BLOCK;
+This takes an object, and looks up the C<related_accessors>; this should
+give a list of accessors that can be called to get a list of related
+objects. It then displays a title for that accessor, (i.e. "Beers" for a
+brewery) calls the accesor, and displays a list of the results. 
+
+=cut
+
+#%]
+[% 
+MACRO view_related(object) BLOCK;
     FOR accessor = classmetadata.related_accessors.list;
         "<H3>"; accessor | ucfirst; "</H3>\n";
         "<UL id=\"vlist\">";
@@ -44,4 +106,11 @@ END %]
         "</UL>";
     END; 
 END;
+
+MACRO test_xxxx(myblock) BLOCK;
+    FOR col = classmetadata.columns;
+        NEXT IF col == "id";
+        myblock;
+    END;
+END;
 %]

diff --git a/templates/factory/navbar b/templates/factory/navbar
index 3e5c1c5e4f6b6787ffd265b9e052b0350a387277..b2dac727dd7af23a6d7f5ff5156b0c59769f4a17 100644 (file)
--- a/templates/factory/navbar
+++ b/templates/factory/navbar
@@ -1,14 +1,25 @@
+[%#
+
+=head1 navbar
+
+This is a navigation bar to go across the page. (Or down the side, or
+whatetver you want to do with it.) It displays all the tables which are
+accessible, with a link to the list page for each one.
+
+#%]
+[% PROCESS macros %]
 <div id="navcontainer">
 <ul id="navlist">
 [%
     FOR table = config.display_tables;
-        '<LI '; 'id="active"' IF table == classmetadata.moniker;
-        '>';
-        '<A HREF="';
-        base; table; "/list/";
-        '"';
-        ' id="current"' IF table == classmetadata.moniker;
-        '> '; table; "</A>";
+        '<LI '; 'id="active"' IF table == classmetadata.moniker; '>';
+
+        # Hack
+        SET active = '" id="current' IF table == classmetadata.moniker;
+
+        link(table, "list", active, table);
+        SET active = "";
+        '</LI>';
     END;
 %]
 </ul>

diff --git a/templates/factory/pager b/templates/factory/pager
index 9defa40e0417d6efd028e0ed31579da4a3ffe487..aa8fbde90c8c95988032dfd304bedd4d64a4aea6 100644 (file)
--- a/templates/factory/pager
+++ b/templates/factory/pager
@@ -1,3 +1,12 @@
+[%#
+
+=head1 pager
+
+This controls the pager display at the bottom (by default) of the list
+and search views. It expects a C<pager> template argument which responds
+to the L<Data::Page> interface.
+
+#%]
 [%
 IF pager AND pager.first_page != pager.last_page;
 %]
@@ -8,9 +17,9 @@ IF pager AND pager.first_page != pager.last_page;
           IF num == pager.current_page;
             "["; num; "] ";
           ELSE;
-          '<A HREF="'; base; classmetadata.moniker; "/list/?page="; num; '">';
-            "["; num; "]";
-          '</A> ';
+            SET args = "?page=" _ num; # Order?
+            SET label = "[" _ num _ "]";
+          link(classmetadata.moniker, "list", args, label);
           END;
      END;
 %]