ATG Page Developer's Guide

The PossibleValues servlet bean uses the specified repository and item descriptor to produce an array of RepositoryItems. If you also include a property name, PossibleValues returns an array of property values, each one an enumerated list of strings.

Input Parameters

itemDescriptorName
The parameter that defines the item descriptor within the repository.

propertyName
If specified, this value contains the name of the property of the repository item. This parameter is mandatory for properties of data-type enumerated. For properties which are themselves item types, you can specify the itemDescriptorName/propertyName of the linked property or simply the itemDescriptorName of the linked-to property.

useCodeForValue
This parameter indicates whether, for the property identified by the propertyName parameter, the string value or integer code value should be returned. Each enumerated property has a string value and integer code value specified for it in the item descriptor that defines the property itself. When useCodeForValue is set to true for the property in its item descriptor and in the PossibleValues servlet bean, the integer code value is provided to the JSP. Any other combination of values causes the string value to be returned. The useCodeForValue parameter accepts a Boolean value.

For information on useCodeForValue in the repository item descriptor, see the EnumeratedProperties section of the SQLRepositoryItemProperties chapter of the ATG Repository Guide.

repository
The parameter specifies the name of the repository. It can also be set via a properties file.

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 an underscore and the term 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 Parameter

values
This parameter contains the array of possible values for the named itemDescriptorName and propertyName.

Open Parameter

output
This parameter is rendered once with the result of the repository query. In the case of enumerated property data types, the result is an array of java.lang.String objects. In the case of properties which are themselves item types, the result is an array of repository items.

Example

The following example uses the PossibleValues and ForEach servlet beans to create a form with input fields used to set the component type and manufacturer for an audio component. A fragment of a repository definition XML file is provided below to better illustrate the retrieval of different property types.

Repository definition fragment:

<item-descriptor name="component">
  ...
  <property name="type" data-type="enumerated" ... >
    <attribute name="useCodeForValue" value="false"/>
    <option value="Receiver" code="0"/>
    <option value="Amplifier" code="1"/>
    <option value="Tuner" code="2"/>
    <option value="CD Player" code="3"/>
    <option value="DVD Player" code="4"/>
    <option value="Cassette Tape Player" code="5"/>
  </property>

  <property name="manufacturer" item-type="manufacturer" ... >

</item-descriptor>

<item-descriptor name="manufacturer">
  ...
  <property name="id" column-name="manufacturer_id"/>
  <property name="displayName" data-type="string"
    column-name="manufacturer_name"/>
  <property name="description" data-type="string" column-name="description"/>
  <property name="longDescription" data-type="big string"
    column-name="long_description"/>
</item-descriptor>

JSP form:

<dsp:form action="Audio.jsp" method="POST">

  <%-- Generate the Component Type select tag from an enumerated type --%>
  <dsp:select bean="AudioComponent.type">
    <dsp:droplet name="PossibleValues">
      <dsp:param name="itemDescriptorName" value="component"/>
      <dsp:param name="propertyName" value="type"/>
      <dsp:oparam name="output">
        <dsp:droplet name="ForEach">
          <dsp:param name="array" param="values"/>
          <dsp:oparam name="output">
            <dsp:option param="element"/>
            <dsp:valueof param="element"/>
          </dsp:oparam>
        </dsp:droplet>
      </dsp:oparam>
    </dsp:droplet>
  </dsp:select>

  <%-- Generate the Component Manufacturer select tag from an item type --%>
  <dsp:select bean="AudioComponent.manufacturer">
    <dsp:droplet name="PossibleValues">
      <dsp:param name="itemDescriptorName" value="component"/>
      <dsp:param name="propertyName" value="manufacturer"/>
      <dsp:param name="sortProperties" value="+displayName"/>
      <dsp:oparam name="output">
        <dsp:droplet name="ForEach">
          <dsp:param name="array" param="values"/>
          <dsp:oparam name="output">
            <dsp:option param="id"/>
            <dsp:valueof param="element.displayName"/>
          </dsp:oparam>
        </dsp:droplet>
      </dsp:oparam>
    </dsp:droplet>
  </dsp:select>

</dsp:form>