Skip Headers

Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3) B25386-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 7.3 Incorporating Range Navigation into Tables

Instead of using built-in operations to perform navigation as forms do, ADF Faces tables provide built-in navigation using the included `SelectRangeChoiceBar` component. You do not need to add it, as the component is automatically included with an ADF Faces table. Figure 7-3 shows the `SelectRangeChoiceBar` component in the table on the SRList page of the SRDemo application.

Figure 7-3 SelectRangeChoiceBar in a Table

## 7.3.1 How to Use Navigation Controls in a Table

By default, a table is set to display a range of rows equal to its `rangeSize` attribute. This attribute is set using an EL expression that evaluates to the iterator's range size. For example, the `rows` attribute on the SRList table has the following EL expression:

    #{bindings.findServiceRequests1.rangeSize}

You can modify the `row` attribute to display a different range size. For example, you may want the iterator to return 50 records, but you want the table to display only 5 at a time. However, if you plan on displaying the same amount you are retrieving, instead of changing the table's range size, you should keep this attribute bound to the iterator's range size, and then change the iterator. For more information, see Section 6.4.2.2, "Iterator RangeSize Attribute".

To change the table's range size:

1. Select the table in the Structure window.

2. In the Property Inspector, for the `rows` attribute, enter a value for the number of rows to display at a time.

   Alternatively, you can manually set the `rows` attribute in the JSF code:

       <af:table rows="5">

   WARNING: The value of the `rows` attribute must be equal to or less than the corresponding iterator's `rangeSize` value.

## 7.3.2 What Happens When You Use the SelectRangeChoiceBar Component

The `SelectRangeChoiceBar` component provides navigational links that allow a user to select the next and previous range of objects in the collection. If the total size of the collection is known, the component provides a dropdown menu that lets the user navigate directly to a particular range set in the collection.

You use the `rows` attribute in conjunction with the `first` attribute to set the ranges. The `first` attribute determines the current range to display. This attribute is an index (based at zero) of each row in the list. By default, the `rows` attribute uses an EL expression that binds its value to the value of the `rangeSize` attribute of the associated iterator. The `first` attribute uses an EL expression that binds its value to the value of the iterator's `rangeStart` attribute. For example, the `rows` and `first` attribute on the table on the SRList page have the following values:

    <af:table rows="#{bindings.findServiceRequests1.rangeSize}"
              first="#{bindings.findServiceRequests1.rangeStart}"

Each range starts with the row identified by `first`, and contains only as many rows as indicated by the `rows` attribute.

## 7.3.3 What Happens at Runtime

When the total number of objects returned by the iterator exceeds the value of the `rows` attribute, the table displays the `SelectRangeChoiceBar` component, which allows the users to navigate through the row sets. Unlike navigation operations which rely on logic in an action binding to provide navigation, the `SelectRangeChoiceBar` component listens for `RangeChange` Events.

When a user navigates to a different range by selecting one of the navigation links provided by the `SelectRangeChoiceBar` component, (such as Previous or Next), the table generates a `RangeChangeEvent` event. This event includes the index of the object that should now be at the top of the range. The table responds to this event by changing the value of the `first` attribute to this new index.

The range change event has an associated listener. You can bind the `RangeChangeListener` attribute on the table to a method on a managed bean. This method will then be invoked in response to the range change event, in other words whenever the table has changed the `first` attribute in response to the user changing a range on the table. This binding can be helpful when some action needs to happen in response to user navigation, for example if you need to release cached data created for a previous range. For information about adding logic before or after built-in operations, see Section 10.5, "Overriding Declarative Methods".

## 7.3.4 What You May Need to Know About the Browser Back Button

Note that using the browser Back button has the same issues as described in Chapter 6 For more information, see Section 6.4.4, "What You May Need to Know About the Browser Back Button". Because the iterator keeps track of the current object, when a user clicks a browser's Back button instead of using navigation buttons on the page, the iterator becomes out of sync with the page displayed because the iterator has been bypassed. However, unlike forms, multiple records are shown on one page, making it more difficult to decipher the current object for the iterator and what the page believes to be the current object.

For example, in the SRList page shown in Figure 7-1, if you select the service request with the ID of `4` and then navigate off the page using either the ID's link or the View or Edit buttons, the iterator is set to the object that represents service request 4. If you set `StateTokenValididation` to be enabled, then the page's token is also set to 4. When you use the browser's Back button, everything seems to be fine, the same range is displayed. However, if you click another button, a validation error is thrown. This is because the page displayed is the previous page, whose token was set to 0, while the iterator is at 4.