# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1360437305 -3600
# Node ID 6c21fb6d057f62bb4cd943f9d5ae06eb17ac178a
# Parent  3e82a1ac3057fdefdded0a2c6c6d97067e1086fe
Added details of the revised validation mechanism to the action development section.

diff -r 3e82a1ac3057 -r 6c21fb6d057f pages/HelpOnMoinForms
--- a/pages/HelpOnMoinForms	Sat Feb 09 19:55:38 2013 +0100
+++ b/pages/HelpOnMoinForms	Sat Feb 09 20:15:05 2013 +0100
@@ -284,43 +284,43 @@
 
     "An example form handler."
 
-    def finished(self, fields, form):
+    def validateFields(self, fields, structure):
 
         """
-        Given a valid form with the given 'fields' and the request's
-        'form' dictionary, perform additional validation.
+        Determine whether the submission is valid, first using the 'fields' and
+        'structure' in a basic validation of the form structure, then using
+        rules specific to this action.
         """
 
+        valid = MoinFormHandlerAction.validateFields(self, fields, structure)
+
+        # This defines the errors for the activity-error message field and
+        # overrides any underlying validity decision.
+
+        if not fields.get("activity"):
+            fields["activity-error"] = [_("Need at least one activity.")]
+            return False
+
+        return valid
+
+    def finished(self, fields, form):
+
+        "Handle the apparently finished 'fields' and 'form'."
+
         _ = self.request.getText
 
-        # This defines the errors for the activity-error message field.
-
-        errors = []
-
-        if not fields.get("activity"):
-            errors.append(_("Need at least one activity."))
-
-        # Insist on the "finish" button being pressed and no errors.
-        # If these conditions are not met, report the errors and act
-        # as if the form is unfinished.
-
-        if errors or not fields.has_key("finish"):
-            fields["activity-error"] = errors
-            self.unfinished(fields, form)
-
         # Upon successful validation, a special field is used to store
         # messages and the underlying action method is called.
 
-        else:
-            fields["form-complete"] = [_("The form was correct.")]
-            MoinFormHandlerAction.finished(self, fields, form)
+        fields["form-complete"] = [_("The form was correct.")]
+        MoinFormHandlerAction.finished(self, fields, form)
 
 def execute(pagename, request):
     ExampleFormAction(pagename, request).processForm()
 }}}
 
-By overriding the `finished` method, it is possible to take advantage of the field-level validation and form manipulation supported by the default form handler whilst adding logic and preventing forms from being accepted until such additional logic considers them to be correct.
+By overriding the `validateFields` method, it is possible to take advantage of the field-level validation and form manipulation supported by the default form handler whilst adding logic and preventing forms from being accepted until such additional logic considers them to be correct.
 
-Where a form is considered to be unfinished, the corresponding `unfinished` method should be invoked. Unless additional messages need to be added to the form, it is not necessary to override this method in an application-specific action.
+By overriding the `finished` method, additional messages can be added to the form as well as operations that might modify the default behaviour and prevent the underlying `finished` method from being called. It is not necessary to override this method in an application-specific action, but usually some form of feedback is desirable to indicate that the form was submitted successfully.
 
 Like normal form fields, the fields populated with error messages also use collections of values instead of single values. To show all values, use repeating message sections as described above.