Make @template support two alternate templates for error and ok cases.

Setting @template=oktmpl|errortmpl in a form will display the next
page using the oktmpl if the change did not cause an error. If
submitting the form caused an error (raised by an auditor or something
else), the user is displayed a page using the errortmpl. Docs in
customizing.tmpl. Look for modal edit.

Author: rouilj

CHANGES.txt

@@ -160,6 +160,13 @@ Features:
   string, the string is appended to the displayed option value. This
   allows the user to reset the value for the menu (select) to the
   original value. (John Rouillard)
+- @template html url parameter can be set to "oktmpl|errortmpl". When
+  a form is submitted, if the form passes validation the oktmpl is
+  used for the resulting page. If the form fails submission the
+  errortmpl page is used to display the form. The errortmpl will
+  usually be the same template used to edit the form. See the section
+  on "Implementing Modal Editing Using @template" in
+  ``customizing.txt``. (John Rouillard)
 
 Fixed:
 

doc/customizing.txt

@@ -1825,6 +1825,48 @@ template doesn't exit it will try to use
 ``test/_generic.item.html``. If that template doesn't exist
 it will return an error.
 
+Implementing Modal Editing Using @template
+------------------------------------------
+
+Many item templates allow you to edit the item. They contain
+code that renders edit boxes if the user has edit permissions.
+Otherwise the template will just display the item information.
+
+In some cases you want to do a modal edit. The user has to take some
+action (click a button or follow a link) to shift from display mode to
+edit mode. When the changes are submitted, ending the edit mode,
+the user is returned to display mode.
+
+Modal workflows usually slow things down and are not implemented by
+default templates. However for some workflows a modal edit is useful.
+For example a batch edit mode that allows the user to edit a number of
+issues all from one form could be implemented as a modal workflow of:
+
+* search for issues to modify
+* switch to edit mode and change values
+* exit back to the results of the search
+
+To implement the modal edit, assume you have an issue.edit.html
+template that implements an edit form.  On the display page (a version
+of issue.item.html modified to only display information) add a link
+that calls the display url, but adds ``@template=edit`` to the link.
+
+This will now display the edit page. On the edit page you want to add
+a hidden text field to your form named ``@template`` with the value:
+``item|edit``.  When the form is submitted it is validated. If the
+form is correct the user will see the item rendered using the item
+template. If there is an error (validation failed) the item will be
+rendered using the edit template. The edit template that is rendered
+will display all the changes that the user made to the form before it
+was submitted. The user can correct the error and resubmit the changes
+until the form validates.
+
+If the form failed to validate but the ``@template`` field had the
+value ``item`` the user would still see the error, but all of the data
+the user entered would be discarded. The user would have to redo all
+the edits again.
+
+
 How the templates work
 ----------------------
 
@@ -2219,7 +2261,7 @@ list        lists all of the active (not retired) items in the class.
 csv         return the items of this class as a chunk of CSV text.
 propnames   lists the names of the properties of this class.
 filter      lists of items from this class, filtered and sorted. Two
-            options are avaible for sorting:
+            options are available for sorting:
 
             1. by the current *request* filterspec/filter/sort/group args
             2. by the "filterspec", "sort" and "group" keyword args.

roundup/cgi/client.py

@@ -1163,6 +1163,13 @@ def selectTemplate(self, name, view):
             classname (name parameter) and template request variable
             (view parameter) and return its name.
 
+            View can be a single template or two templates separated
+            by a vbar '|' character.  If the Client object has a
+            non-empty _error_message attribute, the right hand
+            template (error template) will be used. If the
+            _error_message is empty, the left hand template (ok
+            template) will be used.
+
             In most cases the name will be "classname.view", but
             if "view" is None, then template name "classname" will
             be returned.
@@ -1172,6 +1179,20 @@ def selectTemplate(self, name, view):
 
             [ ] cover with tests
         """
+
+        # determine if view is oktmpl|errortmpl. If so assign the
+        # right one to the view parameter. If we don't have alternate
+        # templates, just leave view alone.
+        if (view.find('|') != -1 ):
+            # we have alternate templates, parse them apart.
+            (oktmpl, errortmpl) = view.split("|", 2)
+            if self._error_message: 
+                # we have an error, use errortmpl
+                view = errortmpl
+            else:
+                # no error message recorded, use oktmpl
+                view = oktmpl
+
         loader = self.instance.templates
 
         # if classname is not set, use "home" template

test/test_cgi.py

@@ -1269,6 +1269,40 @@ def testrenderContext(self):
         self.assertNotEqual(-1, result.index('ok message'))
         # print result
 
+    def testRenderAltTemplates(self):
+        # check that right page is returned when rendering
+        #  @template=oktempl|errortmpl
+
+        # set up the client;
+        # run determine_context to set the required client attributes
+        # run renderContext(); check result for proper page
+
+        # Test ok state template that uses user.forgotten.html
+        self.client.form=makeForm({"@template": "forgotten|item"})
+        self.client.path = 'user'
+        self.client.determine_context()
+        self.assertEqual((self.client.classname, self.client.template, self.client.nodeid), ('user', 'forgotten|item', None))
+        self.assertEqual(self.client._ok_message, [])
+        
+        result = self.client.renderContext()
+        self.assertNotEqual(-1,
+                            result.index('<!-- SHA: 6fdb58c55fd854904ae98906d5935549a221fabf -->'))
+
+        # now set an error in the form to get error template user.item.html
+        self.client.form=makeForm({"@template": "forgotten|item",
+                                   "@error_message": "this is an error"})
+        self.client.path = 'user'
+        self.client.determine_context()
+        self.assertEqual((self.client.classname, self.client.template, self.client.nodeid), ('user', 'forgotten|item', None))
+        self.assertEqual(self.client._ok_message, [])
+        self.assertEqual(self.client._error_message, ["this is an error"])
+        
+        result = self.client.renderContext()
+        print result
+        self.assertNotEqual(-1,
+                            result.index('<!-- SHA: 3b7ce7cbf24f77733c9b9f64a569d6429390cc3f -->'))
+
+
     def testexamine_url(self):
         ''' test the examine_url function '''