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

SRList table can navigate through sets of service requests

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:

Select the table in the Structure window.
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.