For

Loops over a collection of source values. May also emulate an element (like an Any component). If this component is placed in a Form, it will automatically store the collection in Hidden fields so that the structure of the page is preserved when the form is submitted even if the values in the source parameter have changed.

See also: org.apache.tapestry.components.ForBean , org.apache.tapestry.utils.DefaultPrimaryKeyConverter

Parameters

Name Type Direction Required Default Description
source Iterator, Collection, Object[], or Object in yes The source of objects to be iterated, which may be a Collection, an Iterator, an array of Objects, or a even a single Object (which is treated as a singleton collection).

The source parameter may even be null, in which case the For's body is never renderred.
value Object out no If provided, the parameter is updated with the current value on each iteration.
index int out no If provided, the parameter is updated with the index of the loop on each iteration.
element String in no If provided, the component wraps its content with the requested element. Informal parameters become attributes of that element.
keyExpression String in no Only active in a form. An OGNL expression that returns the primary key of the iterated value. The primary keys are stored in hidden fields during rendering and are loaded from the form during a rewind to ensure that the iterations remain the same.

This is a simpler, but a less efficient alternative of the 'converter' parameter. If needed, please use in conjuction with 'fullSource' to reference objects not currently present in 'source'. Use the 'defaultValue' parameter to define the object to be returned if a value corresponding to a particular primary key cannot be found.
fullSource Iterator, Collection, Object[], or Object in no Only active in a form. If an object with a representation stored in the form cannot be found in the 'source' parameter, then the objects provided by this parameter are searched for a match next.
defaultValue Object in no Only active in a form. The value to be used when no match for a given representation stored in the hidden fields cannot be found.
converter IPrimaryKeyConverter in no Only active in a form. Defines how the items iterated upon will be stored in the form as hidden values and how the stored information will be converted back to objects.

This interface allows only the primary key of the items to be stored, rather than the whole item.
primaryKeys List out no Only active in a form. If provided, the parameter is automatically updated during a rewind with the list of primary keys stored in the form. The parameter is updated right before the iterations begin in a rewind and could be used to preload the relevant objects in the provided 'converter'.
match boolean in no true Only active in a form. This parameter allows the matching of the string representation of the values stored in the hidden fields with that of the values in 'source'. It guarantees that the values iterated upon are physically identical to the ones provided.

The method is sometimes slower than simple unsqueezing, but it eliminates a number of potential pitfalls. Please disable with caution.
volatile boolean in no false Only active in a form. Determines whether to avoid creating hidden fields within a form. Using this parameter may make the form structure different during render and rewind, and cause exceptions as a result. Please use with caution.

Body: allowed

Informal parameters: allowed

Reserved parameters: none

Examples

View list of customers

This example displays a list of customers:

<table cellspacing="10">
  <tr>
    <td>ID</td>
    <td>Name</td>
    <td>Level</td>
  </tr>
  <tr>
    <td colspan="3"><hr></td>
  </tr>
  <tr jwcid="@For" source="ognl:customerList" value="ognl:customer" element="tr">
    <td><span jwcid="@Insert" value="ognl:customer.id"/></td>
    <td><span jwcid="@Insert" value="ognl:customer.fullName"/></td>
    <td><span jwcid="@Insert" value="ognl:customer.memberLevel"/></td>
  </tr>
</table>



Edit a list of customers

This examples allows the user to edit a list of customers. The 'keyExpression' parameter is optional. It tells the component to use the 'id' expression to obtain the primary key of the customers. The parameter is particularly useful when the Customer object is not Serializable, as only the primary key is stored in the hidden fields, rather than the full Customer record. 

<table cellspacing="10">
  <tr>
    <td>ID</td>
    <td>Name</td>
    <td>Level</td>
  </tr>
  <tr>
    <td colspan="3"><hr></td>
  </tr>
  <tr jwcid="@For" source="ognl:customerList" keyExpression="id"
      value="ognl:customer" element="tr">
    <td><span jwcid="@Insert" value="ognl:customer.id"/></td>
    <td><span jwcid="@TextField" value="ognl:customer.fullName"/></td>
    <td><span jwcid="@PropertySelection" value="ognl:customer.memberLevel"
              model="ognl:@com.mycorp.Customer@MEMBER_LEVEL_MODEL"/></td>
  </tr>
</table>

Hints

Representing data as a string

If the For component is used in a form, it will automatically convert the provided data to strings and store it in hidden fields in order to ensure that the form is processed correctly when submitted.

If the data is in one of the basic types or if the data is serializable, Tapestry will automatically build string representation of the objects. If it is not serializable however, an ApplicationRuntimeException will be thrown with the message 'Could not find a strategy instance for class'.

There are several options to resolve this problem:

  1. Store only the primary keys of your data objects

    You can define the name of a property that contains the primary keys using the keyExpression parameter.

    The second example shows that approach and uses the id property to represent the object.

    Alternatively, you can implement the IPrimaryKeyConverter interface and use the converter parameter to define how the primary key is obtained from the object.
  2. Make your data class Serializable.

    Tapestry will automatically convert Serializable data into a string and store it in the form.
  3. Define your own way to convert the class into a string. To do this, implement the SqueezeAdaptor interface and register your squeeze adaptor in the WEB-INF/hivemodule.xml file. Please refer to the documentation for more information.
  4. Make the For component volatile by setting the volatile parameter to 'true'. This approach is discouraged, since the data will not be stored in the form as a result. That may cause a StaleLinkException to be thrown if the data changes between the form rendering and the form submission. To avoid this problem you must make sure that the data stays the same.
Either of the above options will work, but the first two are preferred.