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 selectRangeChoiceBar component that is automatically included with table components. The selectRangeChoiceBar component renders a dropdown menu and Previous and Next links for selecting a range of records to display in the current page. Figure 7-3 shows an example of how the selectRangeChoiceBar component might look like in a table.

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

The rows attribute on a table component determines the maximum number of rows to display in a range. When you use the Data Control Palette to create a table, by default JDeveloper sets the table to display a range of rows equal to the iterator's rangeSize value, as shown in the following code snippet for the rows attribute on the SRList table:

#{bindings.findServiceRequests1.rangeSize}

You can modify the rows 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 Navigation Controls in a Table

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 (as illustrated in Figure 7-3). When you change the RangeSize attribute on the iterator, the selectRangeChoiceBar component automatically changes to show the new range sets.

You use the rows attribute on a table component 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 data objects in the collection exceeds the value of the rows attribute, the table displays the selectRangeChoiceBar component, which allows the user to navigate through the row sets.

Unlike navigation operations which rely on logic in an action binding to provide navigation, the selectRangeChoiceBar component sends a RangeChangeEvent event. 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 RangeChangeEvent 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 RangeChangeEvent 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 complementary 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. Like in forms, in tables the current row (or range or rows) displayed in the page you see when you use the browser Back button may no longer correspond with the iterator binding's notion of the current row and range.

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 EnableTokenValidation to be true (as described in the procedure in Section 6.4.4, "What You May Need to Know About the Browser Back Button"), 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, an error indicating that the current row is out of sync is shown. This is because the page displayed is the previous page, whose token was set to 0, while the iterator is at 4.