Displays a subset of array elements.

Class Name

atg.droplet.Range

Component

/atg/dynamo/droplet/Range

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>
    &nbsp;
    <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">&nbsp;</dsp:valueof>
  </dsp:oparam>
</dsp:droplet>