You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by hl...@apache.org on 2011/03/03 20:38:25 UTC

svn commit: r1076749 - /tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Loop.java

Author: hlship
Date: Thu Mar  3 19:38:25 2011
New Revision: 1076749

URL: http://svn.apache.org/viewvc?rev=1076749&view=rev
Log:
Fix up the Javadoc for the Loop component

Modified:
    tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Loop.java

Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Loop.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Loop.java?rev=1076749&r1=1076748&r2=1076749&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Loop.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Loop.java Thu Mar  3 19:38:25 2011
@@ -40,16 +40,22 @@ import org.apache.tapestry5.services.Hea
 
 /**
  * Basic looping class; loops over a number of items (provided by its source parameter), rendering its body for each
- * one. It turns out that gettting the component to <em>not</em> store its state in the Form is very tricky and, in
- * fact, a series of commands for starting and ending heartbeats, and advancing through the iterator, are still stored.
- * For a non-volatile Loop inside the form, the Loop stores a series of commands that start and end heartbeats and store
- * state (either as full objects when there the encoder parameter is not bound, or as client-side objects when there is
- * an encoder). For a Loop that doesn't need to be aware of the enclosing Form (if any), the formState parameter should
- * be bound to 'none'.
+ * one. When a Loop is inside a {@link Form}, it records quite a bit of state into the Form to coordinate access
+ * to the same (or equivalent) objects during the form submission as during the render. This is controlled by
+ * the formState parameter (of type {@link LoopFormState}) and can be 'none' (nothing stored into the form), 'values'
+ * (which stores the individual values looped over, or via a {@link ValueEncoder}, just the value's ids), and
+ * 'iteration' (which just stores indexes to the values within the source parameter, which means that the source
+ * parameter will be accessed during the form submission).
+ * <p>
+ * For a non-volatile Loop inside the form, the Loop stores a series of commands that start and end
+ * {@linkplain Heartbeat heartbeats}, and stores state for each value in the source parameter (either as full objects
+ * when the encoder parameter is not bound, or as client-side objects when there is an encoder). For a Loop that doesn't
+ * need to be aware of the enclosing Form (if any), the formState parameter should be bound to 'none'.
  * <p/>
  * When the Loop is used inside a Form, it will generate an
  * {@link org.apache.tapestry5.EventConstants#SYNCHRONIZE_VALUES} event to inform its container what values were
- * submitted and in what order.
+ * submitted and in what order; this can allow the container to pre-load the values in a single batch form external
+ * storage, if that is appropriate.
  */
 @SupportsInformalParameters
 @Events(EventConstants.SYNCHRONIZE_VALUES)