Constructs an RQL query and renders its output parameter once for each element returned by the query.

Class Name

atg.repository.servlet.RQLQueryForEach

Component

/atg/dynamo/droplet/RQLQueryForEach

Required Input Parameters

repository

The repository to query.

itemDescriptor

The name of the item type to query.

queryRQL

The RQL query to execute.

Optional Input Parameters

transactionManager

The Transaction Manager to use. For example:

<dsp:param name="transactionManager"
  bean="/atg/dynamo/transaction/TransactionManager"/>

sortProperties

Holds a string that specifies the order to render array items. 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 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 returned row.

count

The one-based number of the returned row.

element

A dynamic bean that has properties for accessing the values returned in the result set. To return a particular property value for each item in the result set, use the convention element.name, where name is any property name supported by the item descriptor.

repositoryException

If a RepositoryException is thrown, set to the exception.

Open Parameters

The following open parameters control the formatting for the returned results:

output

Rendered once for each array element.

outputStart

Rendered before any output tags if the array is not empty.

outputEnd

Rendered after all output tags if the array is not empty.

empty

Rendered if the array contains no elements.

error

Rendered if there is an error when the query executes.

Usage Notes

RQLQueryForEach executes a RQL query and renders its output open parameter once for each element returned by the query. The query can be a simple query or can include parameters. The syntax for specifying a parameter is different from the syntax normally used in RQL. For example, you might want to issue this RQL query:

age > ?0

RQLQueryForEach can specify the query as follows:

<dsp:param name="queryRQL" value="age > :whatAge"/>

The value for the whatAge argument is supplied through a parameter. For example, the link to the page containing the servlet bean might be:

<dsp:a href="http://www.example.com/over35.jsp">Click here if you are
over 35<dsp:param name="whatAge" value="35"/>
</dsp:a>

For more information about RQL, see the Repository Queries chapter of the ATG Repository Guide.

Example

The following example uses RQLQueryForEach to display a list of all users in the Personalization profile repository whose profiles indicate they are eligible to receive email.

<p>The following customers are eligible to receive email:

<dsp:droplet name="/atg/dynamo/droplet/RQLQueryForEach">
  <dsp:param name="queryRQL" value="receiveEmail=true"/>
  <dsp:param name="repository"
  value="/atg/userprofiling/ProfileAdapterRepository"/>
  <dsp:param name="itemDescriptor" value="user"/>
  <dsp:oparam name="output">
    <p><dsp:valueof param="element.lastName"/>
  </dsp:oparam>
</dsp:droplet>