ClassName |
|
---|---|
Component |
|
The ForEach
servlet bean 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.
There are three input parameters that are not described below because there is a more favorable method for accomplishing their tasks:
elementName
andindexName
let you provide a parameter name other thanelement
andindex
, respectively. A better way to provide a different parameter name is to use the dsp:setvalue tag. See dsp:setvalue for details.reverseOrder
permits you to decide whether items should be counted in their natural order or the reverse. Use thesortProperties
input parameter instead.
Input Parameters
array
This optional parameter defines the list of items to output. This parameter can be Collection (Vector, List, or Set), Enumeration, Iterator, Map, Dictionary, or array. If you skip this parameter or specify an empty parameter, the empty
open parameter is rendered.
sortProperties
This optional parameter holds a string that specifies the order the items in the array are rendered. The syntax of this parameter depends on the type of item in the array: JavaBeans, Dynamic Beans, or on Dates, Numbers, or Strings.
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 as many properties as you like. The first property name specifies the primary sort, the second property name specifies the secondary sort, and so on. Use +
followed by a property name to indicate that items in the array should be sorted in ascending order and followed by the property name to indicate descending order.
For example, to sort an array of JavaBeans first by an alphabetical ordering of title
and then by descending order of size
, use this input parameter:
<dsp:param name="sortProperties" value="+title,
size"/>
If your array consists of Dates, Numbers, or Strings, specify the value of sortProperties
with either a single +
or a single to indicate ascending or descending order respectively.
For example, to sort an output array of Strings in alphabetical order:
<dsp:param name="sortProperties" value="+"/>
When you are sorting elements of a Map, and you want to sort by the key, set the value to the ascending/descending indicator followed by _key
:
<dsp:param name="sortProperties" value="
_key"/>
When one servlet bean is nested in another and both accept the sortProperties
parameter, the child servlet bean inherits the sortProperties
setting applied by the enclosing servlet bean unless the child specifies another sortProperties
setting or is assigned an empty value:
<dsp:param name="sortProperties" value=""/>
Output Parameters
index
This parameter is set to the zero-based index of the current element
of the array each time that the output
parameter is rendered. The value of index
for the first iteration is 0.
count
This parameter is set to the one-based index of the current element
of the array each time that the output
parameter is rendered. The value of count
for the first iteration is 1.
key
If the array
parameter is a Map or Dictionary, this parameter is set to the value of the key in the Map or Dictionary.
element
This parameter is set to the current element of the array each time that the index
increments and the output
parameter is rendered.
size
This parameter is 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
This parameter is rendered once for each element
in the array.
outputStart
If the array is not empty, this parameter is rendered before any output elements. It can be used to render the heading of a table, for instance.
outputEnd
If the array is not empty, this parameter is rendered after all output elements. It can be used to render text following a table, for instance.
empty
This optional parameter is rendered if the array contains no elements
.
Example
The following example uses the ForEach
servlet bean 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 another standard ATG Servlet Bean, Switch
, to render different output for each person on the list. See Switch for more information on that servlet bean.
The following example uses the ForEach
servlet bean 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 the ForEach
servlet bean 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 demonstrates 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 would pass the "CurrentStudent" to another page fragment which will display more student information: --%> has the following grades: <dsp:include page="displayStudentGrades.jsp" flush="true"> <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>