8.5 Using Tree Tables to Display Master-Detail Relationships

Use the ADF Faces tree table component <af:treeTable> to display a hierarchy of master-detail collections in a table. The advantage of using a tree table rather than a tree is that the tree table provides a mechanism that enables users to focus the view on a particular node in the tree. Figure 8-6 shows an example of a tree table that displays three levels of nodes: users, service requests, and service history. Each root node represents an individual user. Each root node branches to display the service requests associated with that user. Finally, each service request node branches to display the service history for each service request.

Figure 8-6 ADF Faces Tree Table Created with ADF Bindings

An ADF Faces tree table displays one root node at a time, but each root node can display any number of branches. In the example, the root node is a single user, which branches to display service requests, and then service history.

The tree table component includes the following built-in functionality:

Navigation mechanism: The user can click the Previous and Next navigation buttons to display to navigate through the root nodes.
Focusing capabilities: When the user clicks on the focusing icon next to a node, the page is redisplayed showing only that node. A navigation link is provided to enable the user to return to the parent node.
Mechanisms for expanding and collapsing the tree: The user can open or close each node individually or use the Expand All or Collapse All command links.
Range navigation: The range navigation enables the user to navigate to a specific root node in the data collection using a selection list.

8.5.1 How to Create an ADF Faces Databound Tree Table

The steps for creating an ADF Faces databound tree table are exactly the same as those for creating an ADF Faces databound tree, except that you drop the data collection as an ADF Tree Table instead of an ADF Tree. For more information, see Section 8.4.1, "How to Create a Databound Tree Using the Data Control Palette".

8.5.2 What Happens When You Create an ADF Faces Databound Tree Table

When you drag and drop from the Data Control Palette, JDeveloper does many things for you. For a full description of what happens and what is created when you use the Data Control Palette, see Section 5.2.3, "What Happens When You Create a Component From the Data Control Palette".

When you create a databound tree table using the Data Control Palette, JDeveloper adds binding objects to the page definition file, and it also adds the tree table to the JSF Page. The resulting UI component is fully functional and does not require any further modification.

8.5.2.1 Code Generated in the JSF Page

Example 8-5 shows the code generated in a JSF page when you use the Data Control Palette to create a tree table. This sample tree table displays three levels of nodes: users, service requests, and service history. The User collection is returned by the findAllStaff method.

By default, the <af:treeTable> tag is created inside a form. The value attribute of the tree table tag contains an EL expression that binds the tree component to the binding object that will populate it with data, which in the example is the findAllStaff1 tree binding object. The treeModel property refers to an ADF class that defines how the tree hierarchy is displayed, based on the underlying data model. The var attribute provides access to the current node.

Example 8-5 Code Generated in the JSF Page for an ADF Faces Tree Table with ADF Bindings

<h:form>
  <af:treeTable value="#{bindings.findAllStaff1.treeModel}" var="node">
     <f:facet name="nodeStamp">
       <af:column>
          <af:outputText value="#{node}"/>
          </af:column>
       </f:facet>
       <f:facet name="pathStamp">
         <af:outputText value="#{node}"/>
       </f:facet>
   </af:treeTable>
</h:form>

In the <f:facet> tag, the nodeStamp facet is used to display the data for each node. Instead of having a component for each node, the tree repeatedly renders the nodeStamp facet, similar to the way rows are rendered for the ADF Faces table component. The pathStamp facet renders the column and the path links above the table that enable the user to return to the parent node after focusing on a detail node.

8.5.2.2 Binding Objects Added to the Page Definition File

Example 8-6 shows the binding objects created in the page definition file for a tree table. The binding objects created in the page definition file for a tree table are exactly the same as those created for a tree. For more information about tree binding objects, see Section 8.4.2.2, "Binding Objects Added to the Page Definition File"

Example 8-6 Binding Objects Added to the Page Definition File for a Databound ADF Faces Tree Table

<executables>
  <methodIterator id="findAllStaffIter" Binds="findAllStaff.result"
                  DataControl="SRDemoSessionDataControl" RangeSize="10"
                  BeanClass="oracle.srdemo.model.User"/>
</executables>
<bindings>
  <methodAction id="findAllStaff" InstanceName="SRDemoSessionDataControl"
                DataControl="SRDemoSessionDataControl"
                MethodName="findAllStaff" RequiresUpdateModel="true"
                Action="999"
                ReturnName="SRDemoSessionDataControl.methodResults.
                            SRDemoSessionDataControl_findAllStaff_result"/>
  <tree id="findAllStaff1" IterBinding="findAllStaffIter">
    <AttrNames>
      <Item Value="userId"/>
      <Item Value="userRole"/>
      <Item Value="email"/>
      <Item Value="firstName"/>
      <Item Value="lastName"/>
      <Item Value="streetAddress"/>
      <Item Value="city"/>
      <Item Value="stateProvince"/>
      <Item Value="postalCode"/>
      <Item Value="countryId"/>
    </AttrNames>
    <nodeDefinition DefName="oracle.srdemo.model.User" id="UserNode">
      <AttrNames>
        <Item Value="firstName"/>
        <Item Value="lastName"/>
      </AttrNames>
      <Accessors>
        <Item Value="ServiceRequestCollectionAssignedTo"/>
      </Accessors>
    </nodeDefinition>
    <nodeDefinition DefName="oracle.srdemo.model.ServiceRequest"
                    id="ServiceRequestNode">
      <AttrNames>
        <Item Value="svrId"/>
        <Item Value="status"/>
        <Item Value="problemDescription"/>
      </AttrNames>
      <Accessors>
        <Item Value="serviceHistoryCollection"/>
      </Accessors>
    </nodeDefinition>
  </tree>
</bindings>

8.5.3 What Happens at Runtime

Tree components use oracle.adf.view.faces.model.TreeModel to access data. This class extends CollectionModel, which is used by the ADF Faces table component to access data. For more information about the TreeModel class, refer to the ADF Faces Javadoc.

When a page with a tree table is displayed, the iterator binding on the tree component populates the root node and listens for a row navigation event (such as the user clicking the Next or Previous buttons or selecting a row from the range navigator). When the user initiates a row navigation event, the iterator returns the appropriate row.

If the user changes the view focus (by clicking on the component's focus icon), the tree table generates a focus event (FocusEvent). The node to which the user wants to change focus is made the current node before the event is delivered. The tree table then modifies the focusPath property accordingly. You can bind the FocusListener attribute on the tree to a method on a managed bean. This method will then be invoked in response to the focus event; in other words whenever a user changes the focus.

When a user collapses or expands a node, a disclosure event (DisclosureEvent) is sent. The isExpanded method on this event determines whether the user is expanding or collapsing the node. The disclosure event has an associated listener. The DisclosureListener attribute on the tree table is bound to the accessor method specified in the node rule defined in the page definition file. This accessor method is invoked in response to the disclosure event; in other words whenever a user expands or collapses a node.

The tree table also includes Expand All and Collapse All links. When a user clicks one of these links, the table sends a DisclosureAllEvent event. The isExpandAll method on this event determines whether the user is expanding or collapsing all the nodes. The table then expands or collapses the nodes that are children of the root node currently in focus. In large trees, the expand all command will not expand nodes beyond the immediate children. The ADF Faces tree table component uses an instance of the oracle.adf.view.faces.model.PathSet class to determine expanded nodes. This instance is stored as the treeState attribute on the component. You can use this instance to programmatically control the expanded or collapsed state of a node in the hierarchy. Any node contained by the PathSet instance is deemed expanded. All other nodes are collapsed. This class also supports operations like addAll() and removeAll().

Like the ADF Faces table component, a tree table component provides for range navigation. However, instead of using the rows attribute, the tree table uses a rowsByDepth attribute whose value is a space-separated list of non-negative numbers. Each number defines the range size for a node level on the tree. The first number is the root node of the tree, and the last number is for the branch nodes. If there are more branches in the tree than numbers in the rowsByDepth attribute, the tree uses the last number in the list for the remaining branches. Each number defines the limit on the number items displayed at one time in each branch. If you want to display all items in a branch, specify 0 in that position of the list.

For example, if the rowsByDepth attribute is set to 0 0 3, all root nodes will be displayed, all direct children of the root nodes will be displayed, but only three nodes will display per branch after that. The tree table component includes links to navigate to additional nodes, enabling the user to display the additional nodes.