Constructs an RQL query of an SQL database and renders its output parameter for a selected subset of the elements returned by the query.
Class Name |
|
|---|---|
Component |
|
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"/>
calculateSize
Specifies whether to calculate the number of items in the array returned by this query. This parameter must be set to true in order to use the output parameter size.
howMany
The number of array elements to display. If howMany is greater than the number of array elements, RQLQueryRange renders the number of elements available.
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 array elements, the empty parameter (if specified) is rendered.
sortProperties
A string that specifies how to sort the list of items in the output array. Sorting can be performed on properties of JavaBeans, Dynamic Beans, or on Dates, Numbers, or Strings.
To sort JavaBeans, specify the value of sortProperties as a comma-separated list of property names. The first name specifies the primary sort, the second specifies the secondary sort, and so on. If the first character of each keyword is a +, this sort is performed in ascending order. If it has a , it is performed in descending order.
The following example sorts an output array of JavaBeans first alphabetically by title property and in descending order of the size property:
<dsp:param name="sortProperties" value="+title,size"/>
To sort 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="+"/>
When the items to sort are stored in a Map or Dictionary, use the following syntax:
{+|-}_name
where name is the key or Dictionary name.
For example:
<dsp:param name="sortProperties" value="_id"/>
If this example involves a Map property, id is a key of the Map indicated in the array attribute. All IDs associated with the id key are returned in descending order.
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.
size
Set to the number of array items returned by the query. This output parameter is set only if the input parameter calculateSize is set to true; otherwise, it is empty.
end
When the result set is divided into subsets, set to the one-based value of the last element in a subset.
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 to use in order to display the previous array set. You can 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.
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
RQLQueryRange executes an RQL query and renders its output open parameter for a selected subset of the elements 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
RQLQueryRange 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 RepositoryQueries chapter of the ATG Repository Guide.
