svn commit: r613701 - in /tapestry/tapestry5/trunk/tapestry-core/src: main/java/org/apache/tapestry/corelib/components/Form.java site/apt/guide/validation.apt

[hl...@apache.org]

Author: hlship
Date: Sun Jan 20 15:15:12 2008
New Revision: 613701

URL: http://svn.apache.org/viewvc?rev=613701&view=rev
Log:
TAPESTRY-1599: Make it possible to differentiate between preparing for a Form render vs. preparing for a Form submission

Modified:
    tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Form.java
    tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/validation.apt

Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Form.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Form.java?rev=613701&r1=613700&r2=613701&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Form.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Form.java Sun Jan 20 15:15:12 2008
@@ -42,14 +42,15 @@
 /**
  * An HTML form, which will enclose other components to render out the various types of fields.
  * <p/>
- * A Form emits several notification events; when it renders it sends a {@link #PREPARE prepare} notification event, to
- * allow any listeners to set up the state of the page prior to rendering out the form's content.
+ * A Form emits many notification events. When it renders, it fires a {@link #PREPARE_FOR_RENDER} notification, followed
+ * by a {@link #PREPARE} notification.
  * <p/>
- * When the form is submitted, the component emits four notifications: first another prepare event to allow the page to
- * update its state as necessary to prepare for the form submission, then (after components enclosed by the form have
- * operated), a "validate" event is emitted, to allow for cross-form validation. After that, either a "success" or
- * "failure" event (depending on whether the {@link ValidationTracker} has recorded any errors). Lastly, a "submit"
- * event, for any listeners that care only about form submission, regardless of success or failure.
+ * When the form is submitted, the component emits several notifications: first a {@link #PREPARE_FOR_SUBMIT}, then a
+ * {@link #PREPARE}: these allow the page to update its state as necessary to prepare for the form submission, then
+ * (after components enclosed by the form have operated), a {@link #VALIDATE}event is emitted, to allow for cross-form
+ * validation. After that, either a {@link #SUCCESS} OR {@link #FAILURE} event (depending on whether the {@link
+ * ValidationTracker} has recorded any errors). Lastly, a {@link #SUBMIT} event, for any listeners that care only about
+ * form submission, regardless of success or failure.
  * <p/>
  * For all of these notifications, the event context is derived from the <strong>context</strong> parameter. This
  * context is encoded into the form's action URI (the parameter is not read when the form is submitted, instead the
@@ -57,6 +58,18 @@
  */
 public class Form implements ClientElement, FormValidationControl
 {
+
+
+    /**
+     * Invoked before {@link #PREPARE} when rendering out the form.
+     */
+    public static final String PREPARE_FOR_RENDER = "prepareForRender";
+
+    /**
+     * Invoked before {@link #PREPARE} when the form is submitted.
+     */
+    public static final String PREPARE_FOR_SUBMIT = "prepareForSubmit";
+
     /**
      * Invoked to let the containing component(s) prepare for the form rendering or the form submission.
      */
@@ -197,6 +210,8 @@
 
         Object[] contextArray = _context == null ? new Object[0] : _context.toArray();
 
+        _resources.triggerEvent(PREPARE_FOR_RENDER, contextArray, null);
+
         _resources.triggerEvent(PREPARE, contextArray, null);
 
         Link link = _resources.createActionLink(TapestryConstants.ACTION_EVENT, true, contextArray);
@@ -290,6 +305,10 @@
         try
         {
             ComponentResultProcessorWrapper callback = new ComponentResultProcessorWrapper(_eventResultProcessor);
+
+            _resources.triggerEvent(PREPARE_FOR_SUBMIT, context, callback);
+
+            if (callback.isAborted()) return true;
 
             _resources.triggerEvent(PREPARE, context, callback);
 

Modified: tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/validation.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/validation.apt?rev=613701&r1=613700&r2=613701&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/validation.apt (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/validation.apt Sun Jan 20 15:15:12 2008
@@ -26,14 +26,16 @@
   The Form component generates a number of {{{event.html}component events}} that
   you may provide event handler methods for.
   
-  When rendering, the Form component emits a "prepare" notification, to allow the 
-  Form's container to setup any fields or properties that will be referenced in the form.
+  When rendering, the Form component emits two notifications: first, "prepareForRender", then "prepare". These
+  allow the Form's container to setup any fields or properties that will be referenced in the form.
   For example, this is a good chance to create a temporary entity object to be rendered, or
   to load an entity from a database to be editted.
   
   When user submits the form on the client, a series of steps occur on the server.
   
-  First, the Form emits a "prepare" notification, as it did when the Form was rendered.
+  First, the Form emits a "prepareForSubmit" notification,
+  then a "prepare" notification.  These allow the container to ensure that objects are set up
+  and ready to receive information from the form submission.
   
   Next, all the fields inside the form are activated to pull values out of the
   incoming request, validate them and (if valid) store the changes.