14.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 14-3 shows an example of how the selectRangeChoiceBar component might look like in a table.

Figure 14-3 SelectRangeChoiceBar in a Table

14.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:

<af:table rows="#{bindings.LoggedInUserServiceRequests.rangeSize}".../>

The EL expression in the rows attribute evaluates to the iterator's range size, which is defined in the page definition file:

<executables>
  <iterator id="ServiceRequestsByStatusIterator" RangeSize="10"
            Binds="ServiceRequestsByStatus" DataControl="SRService"/>
  </executables>

By default, the RangeSize value is 10, which means that 10 records are returned at a time for display in the current page.

To change the number of records to return for display in the current page, edit the RangeSize value in the page definition file (instead of editing directly the rows attribute on the table component).

If you change the rows attribute on the table component directly instead of changing the RangeSize value on the iterator, make sure the value of rows is equal to or less than the iterator's RangeSize value. For additional information about the RangeSize attribute, see Section 13.4.2.2, "Iterator RangeSize Attribute".

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

The rows attribute on a table component is used in conjunction with the first attribute to set the ranges. The first attribute, which is a zero-based index of the rows in a range, determines the first row in the current range. 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 also uses an EL expression, but the expression binds 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.LoggedInUserServiceRequests.rangeSize}"
          first="#{bindings.LoggedInUserServiceRequests.rangeStart}"

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

14.3.3 What Happens at Runtime

To determine the range sets for the selectRangeChoiceBar to use, the view object retrieves the first "RangeSize" number of rows and then stops, and the table makes a separate SELECT COUNT(*) FROM (...) query by calling the getEstimatedRowCount() method, which estimates the total number of rows the query would retrieve without actually retrieving them all. For more information about the getEstimatedRowCount() method, see Section 5.6.2, "Counting the Number of Rows in a RowSet".

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 17.5, "Overriding Declarative Methods".

14.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 13. For more information, see Section 13.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 14-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 13.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.