You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by ds...@apache.org on 2005/09/21 01:47:19 UTC
svn commit: r290586 - in /jakarta/tapestry/trunk: ./
doc/src/ComponentReference/
framework/src/documentation/content/xdocs/tapestry/ComponentReference/
Author: dsolis
Date: Tue Sep 20 16:47:11 2005
New Revision: 290586
URL: http://svn.apache.org/viewcvs?rev=290586&view=rev
Log:
Fix bug:TAPESTRY-473. Document ListEdit component.
Removed:
jakarta/tapestry/trunk/doc/src/ComponentReference/ListEdit.html
Modified:
jakarta/tapestry/trunk/framework/src/documentation/content/xdocs/tapestry/ComponentReference/Foreach.xml
jakarta/tapestry/trunk/framework/src/documentation/content/xdocs/tapestry/ComponentReference/ListEdit.xml
jakarta/tapestry/trunk/status.xml
Modified: jakarta/tapestry/trunk/framework/src/documentation/content/xdocs/tapestry/ComponentReference/Foreach.xml
URL: http://svn.apache.org/viewcvs/jakarta/tapestry/trunk/framework/src/documentation/content/xdocs/tapestry/ComponentReference/Foreach.xml?rev=290586&r1=290585&r2=290586&view=diff
==============================================================================
--- jakarta/tapestry/trunk/framework/src/documentation/content/xdocs/tapestry/ComponentReference/Foreach.xml (original)
+++ jakarta/tapestry/trunk/framework/src/documentation/content/xdocs/tapestry/ComponentReference/Foreach.xml Tue Sep 20 16:47:11 2005
@@ -77,7 +77,7 @@
</td>
<td>
- Used to update the current value on each iteration..
+ Used to update the current value on each iteration.
</td>
</tr>
<tr>
@@ -90,7 +90,7 @@
</td>
<td>
- Used to store the index of the current value within the stream of elements provided by the source parameter. The index parameter is explicitly updated before the value parameter..
+ Used to store the index of the current value within the stream of elements provided by the source parameter. The index parameter is explicitly updated before the value parameter.
</td>
</tr>
<tr>
@@ -103,7 +103,7 @@
</td>
<td>
- If specified, then the component acts like an &Any;, emitting an open and close tag before and after each iteration. Most often, the element is "tr" when the Foreach is part of an HTML table. Any informal parameters are applied to the tag. If no element is specified, informal parameters are ignored..
+ If specified, then the component acts like an &Any;, emitting an open and close tag before and after each iteration. Most often, the element is "tr" when the Foreach is part of an HTML table. Any informal parameters are applied to the tag. If no element is specified, informal parameters are ignored.
</td>
</tr>
@@ -126,7 +126,7 @@
<section>
<title>Examples</title>
<p> The Foreach component is used to generate a table from a Customer List.</p>
- <p>Template</p>
+ <p><strong>Template</strong></p>
<source><![CDATA[
<table cellspacing="6">
<tr>
@@ -148,14 +148,14 @@
</tr>
</table>
]]></source>
- <p>Page Specification</p>
+ <p><strong>Page Specification</strong></p>
<source><![CDATA[
.....
<property-specification name="customerList" type="java.util.List" persistent="yes"/>
<property-specification name="customer" type="Customer"/>
.....
]]></source>
- <p>Java</p>
+ <p><strong>Java</strong></p>
<source><![CDATA[
public abstract class SalesPage extends BasePage {
public abstract List getCustomerList();
Modified: jakarta/tapestry/trunk/framework/src/documentation/content/xdocs/tapestry/ComponentReference/ListEdit.xml
URL: http://svn.apache.org/viewcvs/jakarta/tapestry/trunk/framework/src/documentation/content/xdocs/tapestry/ComponentReference/ListEdit.xml?rev=290586&r1=290585&r2=290586&view=diff
==============================================================================
--- jakarta/tapestry/trunk/framework/src/documentation/content/xdocs/tapestry/ComponentReference/ListEdit.xml (original)
+++ jakarta/tapestry/trunk/framework/src/documentation/content/xdocs/tapestry/ComponentReference/ListEdit.xml Tue Sep 20 16:47:11 2005
@@ -28,13 +28,19 @@
<body>
-<p> <strong>THIS PAGE UNDER CONSTRUCTION</strong>
+<p>A component used to iterate through a list of items within a &Form;. The ListEdit is similar to a &Foreach; but uses hidden input fields within the &Form; to store the items in the list.
+An instance of &DataSqueezer; is used to convert arbitrary objects into Strings and then back into objects. However, for best efficiency, the list should be simple Strings or numeric types, typically a primary key or other identifier from which the rest of an object may be retrieved or constructed. Serializable objects will work, but the resultant string can be very, very large.
</p>
<p>
- <strong>See also:</strong>
+ <strong>See also:</strong> &For;
</p>
+ <warning>
+ This component has been deprecated; Tapestry 4.0 adds the &For; component which
+ replaces &Foreach; and ListEdit components.
+ </warning>
+
<section>
<title>Parameters</title>
@@ -47,15 +53,82 @@
<th>Default</th>
<th>Description</th>
</tr>
+ <tr>
+ <td>source</td>
+ <td>Iterator, Collection, Object[], or Object</td>
+
+ <td>in</td>
+ <td>yes</td>
+ <td>
+
+ </td>
+ <td>
+ The list of values to be editted within the form. This list is only read when the component renders; it records hidden input fields in the form to guide things when the form is submitted.
+The source can contain objects of any type, though they should be serializable. Ideally, the objects should be String or wrapper types such as Integer. In other words, the source should be a list of primary keys of the objects being editted.
+ </td>
+ </tr>
+ <tr>
+ <td>value</td>
+ <td>Object</td>
+
+ <td>out</td>
+ <td>no</td>
+ <td>
+
+ </td>
+ <td>
+ The value for each iteration through the list (during render or rewind).
+ </td>
+ </tr>
+ <tr>
+ <td>index</td>
+ <td>int</td>
+
+ <td>out</td>
+ <td>no</td>
+ <td>
+
+ </td>
+ <td>
+ The index (starting at zero) for each iteration through the list.
+ </td>
+ </tr>
+ <tr>
+ <td>listener</td>
+ <td>&IActionListener;</td>
+
+ <td>in</td>
+ <td>no</td>
+ <td>
+
+ </td>
+ <td>
+ A listener that is informed after the value parameter is updated. This allows the data set operated on by the rest of the Form components to be synchronized to the value stored in the hidden field.
+A typical use is to encode the primary key of an entity as a Hidden; when the form is submitted, the Hidden's listener re-reads the corresponding entity from the database.
+ </td>
+ </tr>
+ <tr>
+ <td>element</td>
+ <td>String</td>
+
+ <td>in</td>
+ <td>no</td>
+ <td>
+
+ </td>
+ <td>
+ If specified, then a tag for the specified element is placed around the content on each iteration. This emulates the &Any; component. Most often the element specified is "tr" when the ListEdit is part of a table. Any informal parameters are applied to the element.
+ </td>
+ </tr>
</table>
<p>
- Body: <strong>removed / allowed</strong>
+ Body: <strong>allowed</strong>
</p>
<p>
- Informal parameters: <strong>allowed / forbidden</strong>
+ Informal parameters: <strong>allowed</strong>
</p>
<p>
@@ -66,7 +139,75 @@
<section>
<title>Examples</title>
-
+ <p> This ListEdit control is typically used in conjuction with the ListEditMap class. To understand how the ListEdit control works you need to understand the how forms are rewound. But before we get into that lets see an example of the ListEdit control in action. This example is from the vlib sample application and allows the user to edit a list of publishers.</p>
+ <p><strong>Template</strong></p>
+ <p>The following code sets up list of TextField components for editing the publisher names. A checkbox is used to mark publishers to be deleted from the database. It's pretty similar to a Foreach component at this stage.</p>
+ <source><![CDATA[
+ <tr jwcid="listEdit">
+ <td class="control"><input jwcid="inputName@TextField" value="ognl:publisher.name" size="40" maxlength="40"/>
+ </td>
+ <td class="checkbox"><input type="checkbox" jwcid="delete@Checkbox" selected="ognl:listEditMap.deleted"/>
+ </td>
+ </tr>
+ ]]></source>
+ <p><strong>Page Specification</strong></p>
+ <p>The page specification sets up some page properties for the ListEditMap and current publisher. The listEdit component is where it gets interesting. The source binding is the set of all keys in the list edit map. Basically the list of all the publishers identifers. The value is the current key. It would actually be possible to use the publisher object as the value however because each value object is serialized this could get pretty inefficient. Instead what happens is a listener is setup. This listener sets up the actual publisher object from the key when the form is rewound.</p>
+ <source><![CDATA[
+ .....
+ <property-specification name="listEditMap" type="org.apache.tapestry.form.ListEditMap"/>
+ <property-specification name="publisher" type="org.apache.tapestry.vlib.ejb.Publisher"/>
+
+ <component id="listEdit" type="ListEdit">
+ <binding name="source" expression="listEditMap.keys"/>
+ <binding name="value" expression="listEditMap.key"/>
+ <static-binding name="element" value="tr"/>
+ <binding name="listener" expression="listeners.synchronizePublisher"/>
+ </component>
+ .....
+ ]]></source>
+ <p><strong>Java</strong></p>
+ <p>In the code part of this example consists of the abstract properties we set up earlier and three important methods. The synchronizePublisher() method is used to set the Publisher object from the keys we are storing in the listEditMap property. The secret to understanding how it works lies in understanding the rewind cycle. During rewind the listener method is called multiple times - once for each row. The rewind process calls listEditMap.setKey(). This effects the current value returned by listEditMap.getValue(). Once the current publisher is setup calls from the TextField component control the setting of the necessary publisher object properties.
+The next two methods are easier to understand. The readPublishers() call populates the listEditMap property with the set of all publishers to be edited. It is called from pageBeginRender(). The processForm() method handles the form submit. All updated publishers are in map.getValues() and deleted publishers are returned by map.getDeletedKeys(). </p>
+ <source><![CDATA[
+ public abstract ListEditMap getListEditMap();
+ public abstract void setListEditMap(ListEditMap listEditMap);
+ public abstract Publisher getPublisher();
+ public abstract void setPublisher(Publisher publisher);
+
+ public void synchronizePublisher(IRequestCycle cycle)
+ {
+ ListEditMap map = getListEditMap();
+
+ Publisher publisher = (Publisher) map.getValue();
+
+ if (publisher == null)
+ {
+ setError(getMessage("out-of-date"));
+ throw new PageRedirectException(this);
+ }
+
+ setPublisher(publisher);
+ }
+
+ private void readPublishers()
+ {
+ ...
+ ListEditMap map = new ListEditMap();
+ int count = Tapestry.size(publishers);
+ for (i = 0; i < count; i++)
+ map.add(publishers[i].getId(), publishers[i]);
+ setListEditMap(map);
+ }
+
+ public void processForm(IRequestCycle cycle)
+ {
+ ...
+ ListEditMap map = getListEditMap();
+ List updateList = map.getValues();
+ List deletedIds = map.getDeletedKeys();
+ // update and delete publishers
+ }
+ ]]></source>
</section>
</body>
</document>
Modified: jakarta/tapestry/trunk/status.xml
URL: http://svn.apache.org/viewcvs/jakarta/tapestry/trunk/status.xml?rev=290586&r1=290585&r2=290586&view=diff
==============================================================================
--- jakarta/tapestry/trunk/status.xml (original)
+++ jakarta/tapestry/trunk/status.xml Tue Sep 20 16:47:11 2005
@@ -53,6 +53,7 @@
<release version="4.0-beta-8" date="unreleased">
<action type="fix" dev="DS" fixes-bug="TAPESTRY-465">Document Foreach component</action>
<action type="fix" dev="MB" fixes-bug="TAPESTRY-654">Foreach and For cache the 'source' parameter even when they should not</action>
+ <action type="fix" dev="DS" fixes-bug="TAPESTRY-473">Document ListEdit component</action>
</release>
<release version="4.0-beta-7" date="Sep 17 2005">
<action type="fix" dev="HLS" fixes-bug="TAPESTRY-341">Need better line-precise reporting for listener method</action>
---------------------------------------------------------------------
To unsubscribe, e-mail: tapestry-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tapestry-dev-help@jakarta.apache.org