ForEach

Displays each element of an array.

Class Name

atg.droplet.ForEach

Component

/atg/dynamo/droplet/ForEach

Required Input Parameters

None

Optional Input Parameters

array

The list of items to output: a Collection (Vector, List, or Set), Enumeration, Iterator, Map, Dictionary, or array. If omit this parameter or supply an empty parameter, the open parameter empty is rendered.

sortProperties

Holds a string that specifies the order in which array items are rendered. The syntax of this parameter depends on the array item type: JavaBean, Dynamic Bean, Date, Number, or String.

To sort on the properties of a JavaBean, specify the value of sortProperties as a comma-separated list of property names. You can sort on an unlimited number of properties, where the first property name specifies the primary sort, the second property name specifies the secondary sort, and so on. To specify ascending sort order, prepend the property name with a plus + sign; to specify descending order, prepend with a minus - sign. The following example sorts a JavaBean array alphabetically by title, then in descending order of size, use this input parameter:

<dsp:param name="sortProperties" value="+title,size"/>

If an array consists of Dates, Numbers, or Strings, prepend the sortProperties value with a plus + or minus – sign to specify ascending or descending sort order.

The following example sorts an output array of Strings in alphabetical order:

<dsp:param name="sortProperties" value="+"/>

In order to sort Map elements by key, set the value as follows:

{+|-}_key

For example:

<dsp:param name="sortProperties" value="_key"/>

A nested servlet bean inherits the parent servlet bean’s sortProperties setting, unless the nested servlet bean has its own sortProperties setting. For example, the following setting negates any parent sortProperties setting:

<dsp:param name="sortProperties" value=""/>

Output Parameters

index

The zero-based index of the current array element, incremented each time the output parameter is rendered.

count

The one-based index of the current array element, incremented each time the output parameter is rendered.

key

If the array parameter is a Map or Dictionary, set to the value of the Map or Dictionary key.

element

Set to the current array element each time the index increments and the output parameter is rendered.

size

Set to the size of the array, if applicable. If the array is an Enumeration or Iterator, size is set to -1.

Open Parameters

output

Rendered once for each array element.

outputStart

If the array contains elements, rendered before any elements are output. For example, this parameter can be used to render the table heading.

outputEnd

If the array is not empty, rendered after all output elements. For example, this parameter can be used to render text following a table.

empty

Rendered if the array is empty.

Usage Notes

ForEach renders a listing of elements specified by the array parameter in the order you specify. The array parameter can be a Collection (Vector, List, or Set), Enumeration, Iterator, Map, Dictionary, or array.

Example

The following example uses ForEach to present a list of people. The servlet bean renders the output parameter once for each entry in the people array. It defines a parameter called element (representing a person) on each iteration. Then, the servlet bean passes the element parameter to a page, displayPerson.jsp, which produces the HTML formatting. The displayPerson.jsp page itself uses the Switch servlet bean to render different output for each person on the list.

The following example uses ForEach to display a list of the students enrolled in a class. The servlet bean renders the output parameter once for each student in the enrolledStudents array. As ForEach loops through the array of enrolledStudents, each student is bound to the parameter named currentStudent (which is set to the element parameter). The remaining code shows how you can pass the currentStudent parameter to another JSP and how you can display the property values of currentStudent on the page.

<dsp:droplet name="/atg/dynamo/droplet/ForEach">
<dsp:param name="array" bean="ClassroomService.enrolledStudents" />
<%-- As the ForEach loops thru the array of students, each of the
elements is bound to a parameter named "CurrentStudent": --%>
<dsp:setvalue param="CurrentStudent" paramvalue="element"/>
<dsp:oparam name="empty">
There are no students in this class.<br/>
</dsp:oparam>
<%-- Display a header beforing looping thru students in the array: --%>
<dsp:oparam name="outputStart">
Here is the list of students in this class: <br/>
</dsp:oparam>
<%-- display this output for each of the student array elements: --%>
<dsp:oparam name="output">
Student # <dsp:valueof param="count"/> :
<dsp:valueof param="CurrentStudent.fullName"/> at address:
<%-- Display student's address information – which is fetched from
the student's "address" object property: --%>
<dsp:valueof param="CurrentStudent.address.city"/>
<dsp:valueof param="CurrentStudent.address.State"/><br/>
<%-- This is how you pass the "CurrentStudent" to another page
fragment which displays more student information: --%>
has the following grades:
<dsp:include page="displayStudentGrades.jsp">
<dsp:param name="studentInputParam" param="CurrentStudent"/>
</dsp:include>
</dsp:oparam> <%-- output param --%>
<%-- Display this after looping thru all students in the array: --%>
<dsp:oparam name="outputEnd">
Total number of students: <dsp:valueof param="size"/> <br/>
End of Student list.
</dsp:oparam>
</dsp:droplet>