You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bo...@apache.org on 2011/08/24 04:19:31 UTC
svn commit: r1160962 - in
/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components:
AjaxFormLoop.java Checklist.java Grid.java GridRows.java Hidden.java
Loop.java Palette.java RadioGroup.java Select.java
Author: bobharner
Date: Wed Aug 24 02:19:30 2011
New Revision: 1160962
URL: http://svn.apache.org/viewvc?rev=1160962&view=rev
Log:
TAP5-1614: Updated javadocs to clarify the use of the encoder parameter when it is and isn't marked required, and to make the ValueEncoder phrasing more consistent from component to component. No code changes here, just docs.
Modified:
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/AjaxFormLoop.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Checklist.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Grid.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/GridRows.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Hidden.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Loop.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Palette.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/RadioGroup.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Select.java
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/AjaxFormLoop.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/AjaxFormLoop.java?rev=1160962&r1=1160961&r2=1160962&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/AjaxFormLoop.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/AjaxFormLoop.java Wed Aug 24 02:19:30 2011
@@ -40,9 +40,15 @@ import org.apache.tapestry5.services.Par
import org.apache.tapestry5.services.javascript.JavaScriptSupport;
/**
- * A special form of the {@link org.apache.tapestry5.corelib.components.Loop} component that adds Ajax support to
- * handle adding new rows and removing existing rows dynamically. Expects that the values being iterated over are
- * entities that can be identified via a {@link org.apache.tapestry5.ValueEncoder}.
+ * A special form of the {@link org.apache.tapestry5.corelib.components.Loop}
+ * component that adds Ajax support to handle adding new rows and removing
+ * existing rows dynamically.
+ * <p/>
+ * This component expects that the values being iterated over are entities that
+ * can be identified via a {@link org.apache.tapestry5.ValueEncoder}, therefore
+ * you must either bind the "encoder" parameter to a ValueEncoder or use an
+ * entity type for the "value" parameter for which Tapestry can provide a
+ * ValueEncoder automatically.
* <p/>
* Works with {@link org.apache.tapestry5.corelib.components.AddRowLink} and
* {@link org.apache.tapestry5.corelib.components.RemoveRowLink} components.
@@ -115,8 +121,11 @@ public class AjaxFormLoop
private Block tail;
/**
- * Required parameter used to convert server-side objects (provided from the source) into client-side ids and back.
- * A default encoder may be calculated from the type of property bound to the value parameter.
+ * A ValueEncoder used to convert server-side objects (provided by the
+ * "source" parameter) into unique client-side strings (typically IDs) and
+ * back. Note: this parameter may be OMITTED if Tapestry is configured to
+ * provide a ValueEncoder automatically for the type of property bound to
+ * the "value" parameter.
*/
@Parameter(required = true, allowNull = false)
private ValueEncoder<Object> encoder;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Checklist.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Checklist.java?rev=1160962&r1=1160961&r2=1160962&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Checklist.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Checklist.java Wed Aug 24 02:19:30 2011
@@ -30,8 +30,10 @@ import java.util.List;
import java.util.Set;
/**
- * Multiple selection component, used as an alternative to the {@link Palette} component.
- * Generates a UI consisting of a list of check boxes.
+ * A list of checkboxes, allowing selection of multiple items in a list.
+ * <p/>
+ * For an alternative component that can be used for similar purposes, see
+ * {@link Palette}.
*
* @since 5.3
*
@@ -60,8 +62,10 @@ public class Checklist extends AbstractF
private List<Object> selected;
/**
- * Encoder used to translate between server-side objects and client-side
- * strings.
+ * A ValueEncoder used to convert server-side objects (provided from the
+ * "source" parameter) into unique client-side strings (typically IDs) and
+ * back. Note: this component does NOT support ValueEncoders configured to
+ * be provided automatically by Tapestry.
*/
@Parameter(required = true, allowNull = false)
private ValueEncoder<Object> encoder;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Grid.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Grid.java?rev=1160962&r1=1160961&r2=1160962&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Grid.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Grid.java Wed Aug 24 02:19:30 2011
@@ -58,10 +58,15 @@ import org.apache.tapestry5.services.jav
* <p/>
* A Grid may operate inside a {@link org.apache.tapestry5.corelib.components.Form}. By overriding the cell renderers of
* properties, the default output-only behavior can be changed to produce a complex form with individual control for
- * editing properties of each row. This is currently workable but less than ideal -- if the order of rows provided by
+ * editing properties of each row. There is a big caveat here: if the order of rows provided by
* the {@link org.apache.tapestry5.grid.GridDataSource} changes between render and form submission, then there's the
- * possibility that data will be applied to the wrong server-side objects. In general, when using Grid and Form
- * together, you want to provide the Grid with a {@link org.apache.tapestry5.ValueEncoder} (via the encoder parameter).
+ * possibility that data will be applied to the wrong server-side objects.
+ * <p/>
+ * For this reason, when using Grid and Form together, you should generally
+ * provide the Grid with a {@link org.apache.tapestry5.ValueEncoder} (via the
+ * encoder parameter), or use an entity type for the "row" parameter for which
+ * Tapestry can provide a ValueEncoder automatically. This will allow Tapestry
+ * to use a unique ID for each row that doesn't change when rows are reordered.
*
* @see org.apache.tapestry5.beaneditor.BeanModel
* @see org.apache.tapestry5.services.BeanModelSource
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/GridRows.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/GridRows.java?rev=1160962&r1=1160961&r2=1160962&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/GridRows.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/GridRows.java Wed Aug 24 02:19:30 2011
@@ -46,10 +46,17 @@ import java.util.List;
/**
* Renders out a series of rows within the table.
* <p/>
- * Inside a {@link Form}, a series of row index numbers are stored into the form ( {@linkplain FormSupport#store(Object,
- * ComponentAction) as ComponentActions}). This is not ideal ... in a situation where the data set can shift between the
- * form render and the form submission, this can cause unexpected results, including applying changes to the wrong
- * objects.
+ * Inside a {@link Form}, a series of row index numbers are stored into the form
+ * ( {@linkplain FormSupport#store(Object, ComponentAction) as
+ * ComponentActions}). This can be a problem in situations where the data set
+ * can shift between the form render and the form submission, with a risk of
+ * applying changes to the wrong objects.
+ * <p/>
+ * For this reason, when using GridRows inside a Form, you should generally
+ * provide a {@link org.apache.tapestry5.ValueEncoder} (via the encoder
+ * parameter), or use an entity type for the "row" parameter for which
+ * Tapestry can provide a ValueEncoder automatically. This will allow Tapestry
+ * to use a unique ID for each row that doesn't change when rows are reordered.
*
* @tapestrydoc
*/
@@ -170,9 +177,14 @@ public class GridRows
private boolean volatileState;
/**
- * Changes how state is recorded into the form to store the {@linkplain org.apache.tapestry5.ValueEncoder#toClient(Object)
- * client value} for each row (rather than the index), and restore the {@linkplain
- * org.apache.tapestry5.ValueEncoder#toValue(String) row values} from the client value.
+ * A ValueEncoder used to convert server-side objects (provided by the
+ * "row" parameter) into unique client-side strings (typically IDs) and
+ * back. In general, when using Grid and Form together, you should either
+ * provide the encoder parameter or use a "row" type for which Tapestry is
+ * configured to provide a ValueEncoder automatically. Otherwise Tapestry
+ * must fall back to using the plain index of each row, rather
+ * than the ValueEncoder-provided unique ID, for recording state into the
+ * form.
*/
@Parameter
private ValueEncoder encoder;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Hidden.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Hidden.java?rev=1160962&r1=1160961&r2=1160962&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Hidden.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Hidden.java Wed Aug 24 02:19:30 2011
@@ -27,11 +27,15 @@ import org.apache.tapestry5.services.Req
import org.apache.tapestry5.services.javascript.JavaScriptSupport;
/**
- * Used to record a page property as a value into the form. The value is
- * {@linkplain org.apache.tapestry5.ValueEncoder#toClient(Object) encoded} when rendered, then decoded when the form is
- * submitted,
- * and the value parameter updated.
- *
+ * Used to record a page property as a value into the form. The value is encoded
+ * when the form is rendered, then decoded after the form is submitted back to
+ * the server, and the "value" parameter updated.
+ * <p/>
+ * The encoding and decoding is done via a {@link org.apache.tapestry5.ValueEncoder},
+ * therefore you must either bind the "encoder" parameter to a ValueEncoder or
+ * use an entity type for the "value" parameter for which Tapestry can provide a
+ * ValueEncoder automatically.
+ *
* @tapestrydoc
* @since 5.1.0.2
*/
@@ -53,8 +57,11 @@ public class Hidden implements ClientEle
private NullFieldStrategy nulls;
/**
- * Value encoder for the value, usually determined automatically from the type of the property bound to the value
- * parameter.
+ * A ValueEncoder used to convert the server-side object provided by the
+ * "value" parameter into a unique client-side string (typically an ID) and
+ * back. Note: this parameter may be OMITTED if Tapestry is configured to
+ * provide a ValueEncoder automatically for the type of property bound to
+ * the "value" parameter.
*/
@Parameter(required = true)
private ValueEncoder encoder;
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=1160962&r1=1160961&r2=1160962&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 Wed Aug 24 02:19:30 2011
@@ -39,7 +39,7 @@ import org.apache.tapestry5.services.For
import org.apache.tapestry5.services.Heartbeat;
/**
- * Basic looping class; loops over a number of items (provided by its source parameter), rendering its body for each
+ * A basic looping component; loops over a number of items (provided by its source parameter), rendering its body for each
* 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'
@@ -232,9 +232,14 @@ public class Loop<T>
private Iterable<T> source;
/**
- * Optional value converter; if provided (or defaulted) and inside a form and not volatile, then each iterated value
- * is converted and stored into the form. A default for this is calculated from the type of the property bound to
- * the value parameter.
+ * A ValueEncoder used to convert server-side objects (provided by the
+ * "value" parameter) into unique client-side strings (typically IDs) and
+ * back. In general, when using a non-volatile Loop in a Form, you should
+ * either provide a ValueEncoder with the encoder parameter or use a "value"
+ * type for which Tapestry is configured to provide a ValueEncoder
+ * automatically. Otherwise Tapestry must fall back to using the plain
+ * index of each loop iteration, rather than the ValueEncoder-provided
+ * unique ID, for recording state into the form.
*/
@Parameter
private ValueEncoder<T> encoder;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Palette.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Palette.java?rev=1160962&r1=1160961&r2=1160962&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Palette.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Palette.java Wed Aug 24 02:19:30 2011
@@ -68,6 +68,9 @@ import org.apache.tapestry5.services.jav
* <p/>
* Option groups within the {@link SelectModel} will be rendered, but are not supported by many browsers, and are not
* fully handled on the client side.
+ * <p/>
+ * For an alternative component that can be used for similar purposes, see
+ * {@link Checklist}.
*
* @see Form
* @see Select
@@ -179,7 +182,10 @@ public class Palette extends AbstractFie
private Asset deselect;
/**
- * Encoder used to translate between server-side objects and client-side strings.
+ * A ValueEncoder used to convert server-side objects (provided from the
+ * "source" parameter) into unique client-side strings (typically IDs) and
+ * back. Note: this component does NOT support ValueEncoders configured to
+ * be provided automatically by Tapestry.
*/
@Parameter(required = true, allowNull = false)
private ValueEncoder<Object> encoder;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/RadioGroup.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/RadioGroup.java?rev=1160962&r1=1160961&r2=1160962&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/RadioGroup.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/RadioGroup.java Wed Aug 24 02:19:30 2011
@@ -64,8 +64,11 @@ public class RadioGroup implements Field
private String clientId;
/**
- * Allows a specific implementation of {@link org.apache.tapestry5.ValueEncoder} to be supplied. This is used to
- * create client-side string values for the different radio button values.
+ * A ValueEncoder used to convert server-side objects (provided by the
+ * selected Radio componnent's "value" parameter) into unique client-side
+ * strings (typically IDs) and back. Note: this parameter may be OMITTED if
+ * Tapestry is configured to provide a ValueEncoder automatically for the
+ * type of property bound to the "value" parameter.
*/
@Parameter(required = true, allowNull = false)
private ValueEncoder encoder;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Select.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Select.java?rev=1160962&r1=1160961&r2=1160962&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Select.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Select.java Wed Aug 24 02:19:30 2011
@@ -45,7 +45,7 @@ import org.apache.tapestry5.util.EnumSel
* decorations will go around the entire <select> element.
* <p/>
* A core part of this component is the {@link ValueEncoder} (the encoder parameter) that is used to convert between
- * server-side values and client-side strings. In many cases, a {@link ValueEncoder} can be generated automatically from
+ * server-side values and unique client-side strings. In some cases, a {@link ValueEncoder} can be generated automatically from
* the type of the value parameter. The {@link ValueEncoderSource} service provides an encoder in these situations; it
* can be overriden by binding the encoder parameter, or extended by contributing a {@link ValueEncoderFactory} into the
* service's configuration.
@@ -74,8 +74,11 @@ public class Select extends AbstractFiel
}
/**
- * Allows a specific implementation of {@link ValueEncoder} to be supplied. This is used to create client-side
- * string values for the different options.
+ * A ValueEncoder used to convert the server-side object provided by the
+ * "value" parameter into a unique client-side string (typically an ID) and
+ * back. Note: this parameter may be OMITTED if Tapestry is configured to
+ * provide a ValueEncoder automatically for the type of property bound to
+ * the "value" parameter.
*
* @see ValueEncoderSource
*/