[Zope3-checkins] CVS: Zope3/src/zope/app/interfaces/browser - form.py:1.5.8.2

[Guido van Rossum]

Update of /cvs-repository/Zope3/src/zope/app/interfaces/browser
In directory cvs.zope.org:/tmp/cvs-serv22675/zope/app/interfaces/browser

Modified Files:
      Tag: local-utility-branch
	form.py 
Log Message:
Another checkpoint.

=== Zope3/src/zope/app/interfaces/browser/form.py 1.5.8.1 => 1.5.8.2 ===
--- Zope3/src/zope/app/interfaces/browser/form.py:1.5.8.1	Tue Mar 18 11:55:46 2003
+++ Zope3/src/zope/app/interfaces/browser/form.py	Tue Mar 18 16:10:03 2003
@@ -26,21 +26,32 @@
 
     In particular, when the context of an add form is not an IAdding,
     a subclass needs to override nextURL and one of add or createAndAdd.
+
+    To see how all this fits together, here's pseudo code for the
+    update() method of the form:
+
+    def update(self):
+        self.beforeUpdateHook()
+        data = <get data from widgets> # a dict
+        self.createAndAdd(data)
+        self.request.response.redirect(self.nextURL())
+
+    def createAndAdd(self, data):
+        content = <create the content from the data>
+        content = self.add(content) # content wrapped in some context
+        <set after-add attributes on content>
+
     """
-    
-    def nextURL():
-        """Return the URL to be displayed after the add operation
-        """
 
-    def add(content):
-        """Add the given content
+    def beforeUpdateHook():
+        """Hook called just before form data is computed
 
-        This method is overridden when the context of the add form is
-        not an IAdding.  In this case, the class that customizes the
-        form must take over adding the object.
+        Add forms can be harder to create because there is less
+        context for determining things like widget default and allowed
+        values. This hook is provided to allow you to manipulate
+        widgets before they are used to render data or get values.
 
-        The content should be returned wrapped in the context of the
-        object that it was added to.
+        The default implementation does nothing.
         """
 
     def createAndAdd(data):
@@ -50,15 +61,31 @@
 
         If any user errors occur, they should be collected into a list
         and raised as a WidgetsError.
+
+        (For the default implementation, see pseudo-code in class docs.)
         """
 
-    def beforeUpdateHook():
-        """Hook called just before form data is computed
+    def add(content):
+        """Add the given content
 
-        Add forms can be harder to create because there is less
-        context for determining things like widget default and allowed
-        values. This hook is provided to allow forms to manipulate
-        widgets before they are used to render data or get values.
+        This method is overridden when the context of the add form is
+        not an IAdding.  In this case, the class that customizes the
+        form must take over adding the object.
+
+        The content should be returned wrapped in the context of the
+        object that it was added to.
+
+        The default implementation returns self.context.add(content),
+        i.e. it delegates to the IAdding view.
+        """
+    
+    def nextURL():
+        """Return the URL to be displayed after the add operation.
+
+        This can be relative to the view's context.
+
+        The default implementation returns self.context.nextURL(),
+        i.e. it delegates to the IAdding view.
         """