Displays a subset of array elements.
Class Name |
|
---|---|
Component |
|
Required Input Parameters
array
The list of items to output: a Collection (Vector, List, or Set), Iterator, Enumeration, Map, Dictionary, or array.
howMany
The number of array elements to display. If howMany
is greater than the number of array elements, Range
renders the number of elements available.
Optional Input Parameters
start
The initial array element, where a setting of 1 (the default) specifies the array’s first element. If start
is greater than the number of elements in the array, the empty
parameter (if specified) is rendered.
sortProperties
A string that specifies the order in which array items are rendered. The value assigned to this parameter depends on the item type: JavaBeans, Dynamic Beans, 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 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 input parameter sorts a JavaBean array alphabetically by title, then in descending order of size
:
<dsp:param name="sortProperties" value="+title,
size"/>
If the array contains 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 each time the output
parameter is rendered. For example, if start
is set to 1, the value of index
for the first iteration is 0.
count
The one-based index of the current array element each time the output
parameter is rendered. For example, if start
is set to 1, the value of count
for the first iteration is 1.
key
If the array
parameter is a Map or Dictionary, set to the Map or Dictionary key.
element
The current array element each time the index
increments and the output
parameter is rendered.
size
The total number of items in the source array.
end
When the result set is divided into subsets, causes the last element in a subset to display its numbered value. This parameter uses a one-based count.
hasPrev
Set to true before any output parameters are rendered, indicates whether the array includes any items that precede the current array set.
prevStart
Set before any output parameters are rendered and only if hasPrev
is true, indicates the value of start
that should be used to display the previous array set. Use this parameter to create a link or form submission that displays the previous elements of the array.
prevEnd
Set before any output parameters are rendered, and only if hasPrev
is true, indicates the (one-based) count of the last element in the previous array set.
prevHowMany
Set before any output parameters are rendered, and only if hasPrev
is true, indicates the number of elements in the previous array set.
hasNext
Set to true before any output parameters are rendered, indicates whether the array includes any items that follow the current array set.
nextStart
Set before any output parameters are rendered, and only if hasNext
is true, indicates the value of start
that should be used to display the next array set.
nextEnd
Set before any output parameters are rendered, and only if hasNext
is true, indicates the (one-based) count of the last element in the next array set.
nextHowMany
Set before any output parameters are rendered, and only if hasNext
is true, indicates the number of elements in the next array set.
Open Parameters
output
Rendered once for each element
in the subset of the array defined by the start
and howMany
parameters.
outputStart
If the array is not empty, rendered before any output elements. For example, this parameter can be used to render a heading.
outputEnd
If the array is not empty, rendered after all output elements. For example, this parameter can be used to render a footer.
empty
Rendered if the array or the specified subset of the array contains no elements.
Usage Notes
Range is similar to the ForEach servlet bean, except it can render a subset of the output array rather than the entire array. Range renders its output
parameter for each element in its array
parameter, beginning with the array element that corresponds to the start
parameter and continuing until it has rendered a number of elements equal to the howMany
parameter. The array
parameter can be a Collection (Vector, List, or Set), Iterator, Enumeration, Map, Dictionary, or array.
Example
The following example displays the values of the initialServices
property of ATG’s Initial
component. The values are displayed two at a time. This example uses a Switch servlet bean to create navigational links after each pair of values. Links are provided to the sets of values that precede and follow the current pair, if any.
<dsp:importbean bean="/atg/dynamo/droplet/Range"/> <dsp:importbean bean="/atg/dynamo/droplet/Switch"/> <dsp:droplet name="Range"> <dsp:param bean="/Initial.initialServices" name="array"/> <dsp:param name="howMany" value="2"/> <dsp:oparam name="outputStart"><h3>Initial Services:</h3><ul></dsp:oparam> <dsp:oparam name="outputEnd"> </ul> <dsp:droplet name="Switch"> <dsp:param name="value" param="hasPrev"/> <dsp:oparam name="true"> <dsp:getvalueof var="a27" bean="/OriginatingRequest.pathInfo" vartype="java.lang.String"> <dsp:a href="${a27}"> <dsp:param name="start" param="prevStart"/> Previous <dsp:valueof param="prevHowMany"/> </dsp:a> </dsp:getvalueof> </dsp:oparam> </dsp:droplet> <dsp:droplet name="Switch"> <dsp:param name="value" param="hasNext"/> <dsp:oparam name="true"> <dsp:getvalueof var="a46" bean="/OriginatingRequest.pathInfo" vartype="java.lang.String"> <dsp:a href="${a46}"> <dsp:param name="start" param="nextStart"/> Next <dsp:valueof param="nextHowMany"/> </dsp:a> </dsp:getvalueof> </dsp:oparam> </dsp:droplet> </dsp:oparam> <dsp:oparam name="output"> <li><dsp:valueof param="element.absoluteName"> </dsp:valueof> </dsp:oparam> </dsp:droplet>