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
*/
