When objects have a master-detail relationship, you can declaratively create pages that display the data from both objects simultaneously. For example, the page shown in Figure 34-1 displays an entry for a customer in a form at the top of the page and a table of the customer's orders at the bottom of the page. This is possible because the objects have a master-detail relationship. In this example, the Customers view object is the master object and OrdersForCustomer is the detail object. ADF iterators automatically manage the synchronization of the detail data objects displayed for a selected master data object. Iterator bindings simplify building user interfaces that allow scrolling and paging through collections of data and drilling-down from summary to detail information.

You display master and detail objects in forms, tables, trees, and tree tables. You can display these objects on the same page or on separate pages. For example, you can display the master object in a table on one page and detail objects in a read-only form on another page.

A master object can have many detail objects, and each detail object can in turn have its own detail objects, down to many levels of depth. If one of the detail objects in this hierarchy is dropped from the Applications window as a master-detail form on a page, only its immediate parent master object displays on the page. The hierarchy will not display all the way up to the topmost parent object.

If you display the detail object as a tree or tree table object, it is possible to display the entire hierarchy with multiple levels of depth, starting with the topmost master object, and traversing detail children objects at each node.

Figure 34-1 shows an example of a master form with detail table. When the user navigates through the customers using the command buttons, the table lists the orders that the customer has made.

Figure 34-2 shows a tree that has two levels of nodes. You can use trees to display hierarchical information. In this example, a tree is used to display customers grouped by countries. The user can expand nodes to traverse down a branch of the tree to access the leaf items.

Figure 34-3 shows the same grouping of customers by country, but using a tree table instead of a tree. In addition to the hierarchical node levels of a tree, a tree table can also display column information for each node. You can also focus on subtrees as well as collapsing and expanding the elements.

You may find it helpful to understand other Oracle ADF features before you configure or use the ADF Model layer. Additionally, you may want to read about what you can do with your model layer configurations. Following are links to other functionality that may be of interest.

• ADF view objects and view links: Much of how the components display and function in the form is controlled by the corresponding view objects. For more information about creating view objects and establishing a master-detail hierarchy in your data model with view links, see Working with Multiple Tables in a Master-Detail Hierarchy.

• ADF application modules: The Data Controls panel, from which you drag databound components to your pages, is populated with representations of view objects that you have added to application modules. See Implementing Business Services with Application Modules.

• Adapter-based data controls: If you are using other types of business services, such as EJB components or web services, you can create data control for those business services as described in Creating and Configuring EJB Data Controls of the Developing Applications with Oracle ADF Data Controls.

• ADF Model and data binding: When you create forms in an ADF web application, you use ADF Model and data binding. See Using ADF Model in a Fusion Web Application.

• ADF Faces: You also use ADF Faces UI components. For detailed information about developing with ADF Faces, see Introduction to ADF Faces in Developing Web User Interfaces with Oracle ADF Faces.

• ADF forms and tables: If you want to modify the default forms or tables, see Creating Basic Forms Using Data Control Collections or Creating a Basic Table.

• Task flows: If your form takes part in a transaction, then you may need to use an ADF task flow to invoke certain operations before or after the form is rendered. See Creating ADF Task Flows.

• Event handling: You may need to write listener methods to process client-side events. See Handling Events in Developing Web User Interfaces with Oracle ADF Faces.

• Managed beans: You may need to create managed beans for event handling and other front-end processing. For information about creating and using managed beans, see Using a Managed Bean in a Fusion Web Application.

1. From the Data Controls panel, locate the detail object, as described in How to Identify Master-Detail Objects on the Data Controls Panel.
2. Drag and drop the detail object onto the JSF page.
3. From the Master-Detail submenu of the context menu, choose one of the following components:

   • ADF Master Table, Detail Form: Displays the master objects in a read-only table and the detail objects in a read-only form under the table.

     When a specific data object is selected in the master table, the first related detail data object is displayed in the form below it. The user must use the form navigation to scroll through each subsequent detail data object.

   • ADF Master Form, Detail Table: Displays the master objects in a read-only form and the detail objects in a read-only table under the form.

     When a specific master data object is displayed in the form, the related detail data objects are displayed in a table below it.

   • ADF Master Form, Detail Form: Displays the master and detail objects in separate read-only forms.

     When a specific master data object is displayed in the top form, the first related detail data object is displayed in the form below it. The user must use the form navigation to scroll through each subsequent detail data object.

   • ADF Master Table, Detail Table: Displays the master and detail objects in separate read-only tables.

     When a specific master data object is selected in the top table, the first set of related detail data objects is displayed in the table below it.

   If you want to modify the default forms or tables, see Modifying the UI Components and Bindings on a Form and Modifying the Attributes Displayed in the Table.

1. Create the detail widget by dragging a child collection from the Data Controls panel and dropping it as a table or a form on the JSF page or fragment that corresponds to the detail view activity. For more information, see How to Identify Master-Detail Objects on the Data Controls Panel.

   For more information on creation of the individual components, see Creating Basic Forms Using Data Control Collections and Creating a Basic Table.

2. Create the master widget by dragging the collection that is the parent of the collection in step 1 and dropping it as a table or a form on the JSF page or fragment that corresponds to the master view activity.

When you drag and drop a collection from the Data Controls panel, JDeveloper does many things for you, including adding code to the JSF page and the corresponding entries in the page definition file. For a general description of what happens and what is created when you use the Data Controls panel, see What Happens When You Use the Data Controls Panel.

<executables>
  <variableIterator id="variables"/>
  <iterator Binds="Customers" RangeSize="25" DataControl="BackOfficeAppModuleDataControl" id="CustomersIterator"
            ChangeEventPolicy="ppr"/>
  <iterator Binds="OrdersForCustomer" RangeSize="25" DataControl="BackOfficeAppModuleDataControl"
            id="OrdersForCustomerIterator" ChangeEventPolicy="ppr"/>
</executables>
<bindings>
  <action IterBinding="CustomersIterator" id="First" RequiresUpdateModel="true" Action="first"/>
  <action IterBinding="CustomersIterator" id="Previous" RequiresUpdateModel="true" Action="previous"/>
  <action IterBinding="CustomersIterator" id="Next" RequiresUpdateModel="true" Action="next"/>
  <action IterBinding="CustomersIterator" id="Last" RequiresUpdateModel="true" Action="last"/>
  <attributeValues IterBinding="CustomersIterator" id="Id">
    <AttrNames>
      <Item Value="Id"/>
    </AttrNames>
  </attributeValues>
  <attributeValues IterBinding="CustomersIterator" id="Name">
    <AttrNames>
      <Item Value="Name"/>
    </AttrNames>
  </attributeValues>
  <attributeValues IterBinding="CustomersIterator" id="Phone">
    <AttrNames>
      <Item Value="Phone"/>
    </AttrNames>
  </attributeValues>
. . .
  <tree IterBinding="OrdersForCustomerIterator" id="OrdersForCustomer">
    <nodeDefinition DefName="oracle.summit.model.views.OrdVO"
                    Name="OrdersForCustomer0">
      <AttrNames>
        <Item Value="Id"/>
        <Item Value="CustomerId"/>
        <Item Value="DateOrdered"/>
...
      </AttrNames>
    </nodeDefinition>
  </tree>
</bindings>

At runtime, an ADF iterator determines which row from the master table object to display in the master-detail form. When the form first displays, the first master table object row appears highlighted in the master section of the form. Detail table rows that are associated with the master row display in the detail section of the form.

As described in Binding Objects Defined in a Master-Detail Page Definition File, ADF iterators are associated with underlying rowsetIterator objects. These iterators manage which data objects, or rows, currently display on a page. At runtime, the row set iterators manage the data displayed in the master and detail components.

Both the master and detail row set iterators listen to row set navigation events, such as the user clicking the range navigation buttons, and display the appropriate row in the UI. In the case of the default master-detail components, the row set navigation events are the command buttons on a form (First, Previous, Next, Last).

The row set iterator for the detail collection manages the synchronization of the detail data with the master data. Because of the underlying view link from the master view object to the detail view object, the detail row set iterator listens for row navigation events in both the master and detail collections. If a row set navigation event occurs in the master collection, the detail row set iterator automatically executes and returns the detail rows related to the current master row.

1. Create an ADF task flow as described in How to Create a Task Flow.

   If you plan to use page fragments to hold the master and detail components, select the Create with Page Fragments checkbox in this step.

2. Add two view activities to the task flow, one for the master view and one for the detail view, as described in How to Add an Activity to a Task Flow.
3. In the task flow definition file, add a control flow case from the master view to the detail view, and a control flow case to return from the detail view to the master view. For more information, see How to Add a Control Flow Rule to a Task Flow.
4. Create two JSF pages or two JSF fragments to hold the master and detail components.

   You can create a page or fragment for a view activity by clicking on the view activity in the overview editor for task flow.

   If you already have pages or fragments that you want to map to the view activities, you can do so by selecting the view activity in the overview editor for the task flow, navigating to the Properties window, and specifying the JSF page or fragment in the Page property.

5. Create the detail component by dragging a child collection from the Data Controls panel and dropping it as a table or a form on the JSF page or fragment that corresponds to the detail view activity. For more information, see How to Identify Master-Detail Objects on the Data Controls Panel.

   For more information on creating forms and tables, see Creating Basic Forms Using Data Control Collections and Creating a Basic Table.

6. Create the master component by dragging the collection that is the parent of the collection in step 5 and dropping it as a table or a form on the JSF page or fragment that corresponds to the master view activity.
7. Add command buttons or links to each page.
8. In the action attribute of each button, specify the control flow case that is used to navigate to the other page. You can get this value from the from-outcome property of the corresponding control flow case.

1. Drag the master object from the Data Controls panel, and drop it onto the page. This should be the master data that will represent the root level of the tree.
2. From the context menu, choose Tree > ADF Tree.

   JDeveloper displays the Edit Tree Binding dialog, as shown in Figure 34-10. You use the binding editor to define a rule for each level that you want to appear in the tree.

   When the dialog first appears, the collection that you dragged is displayed in the Root Data Source dropdown list and the corresponding view object is displayed in the Tree Level Rules list. This will represent the master data collection.

   Tip:

   If you don't see the data collection you want in the Root Data Source list, click the Add button. In the Add Data Source dialog, select a data control and an iterator name to create a new data source. Then click the Add Rule icon and select Add Rule to add the master rule.

   Figure 34-10 Edit Tree Binding Dialog

   
   Description of "Figure 34-10 Edit Tree Binding Dialog"
3. Click the Add Rule icon and then select a detail collection to add to the Tree Level Rules list.

   A detail data source should appear under the master data source, as shown in Figure 34-11.

   Figure 34-11 Master-Detail Tree Level Rules

   
   Description of "Figure 34-11 Master-Detail Tree Level Rules "

   If you are creating a tree with a recursive master-detail hierarchy, then you only need to define a rule that specifies a data source with a self accessor. A recursive tree displays root nodes based on a single collection and displays the child nodes from the attributes of a self accessor that recursively fetches data from that collection. The recursive tree differs from a typical master-detail tree because it requires only a single rule to define the branches of the tree. A recursive data source should display the data source followed by the name of the self accessor in brackets, as shown in Figure 34-12.

   Repeat this step for any additional nodes (or further levels of hierarchy) that you want to add to the tree.

   Figure 34-12 Recursive Tree Level Rule

   
   Description of "Figure 34-12 Recursive Tree Level Rule"
4. In the Tree Level Rules list, select one of the rules.
5. In the bottom part of the dialog, set the attribute or attributes that you want to be used for the node's display by shuttling those attributes to the to the Display Attributes list.
6. Repeat steps 4 and 5 for each of the rest of the rules.
7. Click OK.

When you drag and drop from the Data Controls panel, JDeveloper does many things for you. For a general description of what happens and what is created when you use the Data Controls panel, see How to Use the Data Controls Panel.

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

<af:tree value="#{bindings.Countries.treeModel}"
          var="node"
          selectionListener="#{bindings.Countries.treeModel.makeCurrent}"
          rowSelection="single" id="t1"
   <f:facet name="nodeStamp">
      <af:outputText value="#{node}" id="ot1"/>
   </f:facet>
</af:tree>

<executables>
...
      <iterator Binds="Countries" RangeSize="25"
                DataControl="BackOfficeAppModuleDataControl"
                id="CountriesIterator"/>
</executables>
<bindings>
...
   <tree IterBinding="CountriesIterator" id="Countries">
      <nodeDefinition DefName="oracle.summit.model.views.CountryVO"
                      Name="Countries0">
         <AttrNames>
            <Item Value="Country"/>
         </AttrNames>
         <Accessors>
            <Item Value="CustomerVO"/>
         </Accessors>
      </nodeDefinition>
      <nodeDefinition DefName="oracle.summit.model.views.CustomerVO"
                      Name="Countries1"
                      TargetIterator="${bindings.CustomersIterator}">
         <AttrNames>
            <Item Value="Id"/>
            <Item Value="Name"/>
         </AttrNames>
      </nodeDefinition>
   </tree>
</bindings>

Tree components use org.apache.myfaces.trinidad.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 is displayed, the iterator binding on the tree populates the root nodes. When a user collapses or expands a node to display or hide its branches, a DisclosureEvent event is sent. The isExpanded method on this event determines whether the user is expanding or collapsing the node. The DisclosureEvent event has an associated listener.

The DisclosureListener attribute on the tree is bound to the accessor attribute specified in the node rule defined in the page definition file. This accessor attribute is invoked in response to the DisclosureEvent event; in other words, whenever a user expands the node the accessor attribute populates the branch nodes.

1. From the Data Controls panel, drag the detail collection from which a record will be displayed based on the user selection in a tree, and drop it as a form or another databound component.
2. From the Data Controls panel, drag the parent collection of the detail collection that you just dropped and choose Create > Tree > ADF Tree (or ADF Tree Table).
3. In the Edit Tree Binding dialog, configure tree binding rules for all of the levels of the tree hierarchy as described in How to Display Master-Detail Objects in Trees, and leave the dialog open.
4. Select the detail tree-level rule that corresponds to the same collection that is used in step 1.
5. Expand the Target Data Source node and click the EL Picker button.
6. In the Variables dialog, expand ADF Bindings, expand bindings, and select the iterator binding for the component that you created in step 1.

   The expression will display in the Expression text area. The expression should look something like ${bindings.CustomersIterator}. This expression will then be used to set the target iterator when a user clicks a detail node.

7. Click OK to exit the Variables dialog, and click OK to exit the Edit Tree Binding dialog.

When you drag and drop from the Data Controls panel, JDeveloper does many things for you. For a full description of what happens and what is created when you use the Data Controls panel, see How to Use the Data Controls Panel.

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

<af:treeTable value="#{bindings.Countries.treeModel}" var="node"
              selectionListener="#{bindings.Countries.treeModel.makeCurrent}"
              rowSelection="single"
              id="tt1">
    <f:facet name="nodeStamp">
        <af:column id="c1">
            <af:outputText value="#{node}" id="ot1"/>
        </af:column>
    </f:facet>
    <f:facet name="pathStamp">
        <af:outputText value="#{node}" id="ot2"/>
    </f:facet>
</af:treeTable>

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 treeTable 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 displays the appropriate row.

If the user changes the view focus (by clicking on the component's focus icon), the treeTable component 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 treeTable component 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.

When a user collapses or expands a node, a disclosure event (DisclosureEvent) is sent. The isExpanded method on the disclosure event determines whether the user is expanding or collapsing the node. The disclosure event has an associated listener, DisclosureListener. The DisclosureListener attribute on the tree table is bound to the accessor attribute specified in the node rule defined in the page definition file. This accessor attribute is invoked in response to a disclosure event (for example, the user expands a node) and returns the collection that populates that node.

The treeTable component includes Expand All and Collapse All links. When a user clicks one of these links, the treeTable 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 treeTable 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().

For more information about the ADF Faces treeTable component, refer to the oracle.adf.view.faces.component.core.data.CoreTreeTable class in the ADF Faces Javadoc.

1. From the Data Controls panel, locate the detail object, as described in How to Identify Master-Detail Objects on the Data Controls Panel.
2. From the Data Controls panel, drag the detail collection onto the page and choose Table/List View > ADF List View.
3. On the first page of the create List View wizard, select a layout component and select Include header using parent collection.
4. If you have selected the Panel Grid Layout option on the first page the wizard, use the next two pages of the wizard to organize the size and arrangement of the grid cells.

   For more information about using these wizard pages, press the F1 key or click Help.

5. On the List Item Data page, determine which fields to display for the detail data by setting the bindings and setting the corresponding components to use for each.
6. In the same page, click the Group Header Data tab, and set the bindings and components for the master data.
7. Click Finish.
8. Use the Properties window to further configure the layout components.

   For complete information about using the panelGridLayout component, see the Arranging Content in a Grid section of the Developing Web User Interfaces with Oracle ADF Faces. For more information about the panelGroupLayout component, see the Grouping Related Items section of the Developing Web User Interfaces with Oracle ADF Faces.

When you use the wizard to create a listView component with group headers, JDeveloper creates and configures the listView, listItem, and layout components. The listView contains a listItem for the detail items and a facet for the group header stamp, which in turn contains a listItem for the master items.

The bindings are the same as for a table—the listView component is bound to the parent of the collection dropped from the Data Controls panel. The value of the var attribute on this component is used by the outputFormatted components to access the data, in the same way as a table. For more information about the page definition code and the JSP code for collections, see What Happens When You Create a Table.

The following example shows the page code for the simple table shown in Figure 34-14.

<af:form id="f1">
  <af:panelGridLayout id="pgl1">
    <af:gridRow height="100%" id="gr1">
      <af:gridCell width="100%" halign="stretch" valign="stretch" id="gc1">
        <!-- Content -->
        <af:listView value="#{bindings.Customers.treeModel}" var="item"
                     emptyText="#{bindings.Customers.viewable ? 'No data to
                                  display.' : 'Access Denied.'}"
                     fetchSize="#{bindings.Customers.rangeSize}" id="lv1">
          <af:listItem id="li1">
            <af:panelGroupLayout layout="horizontal" id="pgl2">
              <f:facet name="separator">
                <af:spacer width="10" id="s1"/>
              </f:facet>
              <af:outputFormatted 
                    value="#{item.bindings.DateOrdered.inputValue}" id="of1">
                <af:convertDateTime
                    pattern="#{bindings.Customers.hints.DateOrdered.format}"/>
              </af:outputFormatted>
              <af:outputFormatted value="#{item.bindings.Total.inputValue}"
                                  id="of2">
                <af:convertNumber groupingUsed="false"
                           pattern="#{bindings.Customers.hints.Total.format}"/>
              </af:outputFormatted>
            </af:panelGroupLayout>
          </af:listItem>
          <f:facet name="groupHeaderStamp">
            <af:listItem id="li2" inlineStyle="font-size:medium;">
              <af:panelGroupLayout layout="horizontal" id="pgl3">
                <f:facet name="separator">
                  <af:spacer width="10" id="s2"/>
                </f:facet>
                <af:outputFormatted value="#{item.bindings.Name.inputValue}"
                                    id="of3"/>
              </af:panelGroupLayout>
            </af:listItem>
          </f:facet>
        </af:listView>
      </af:gridCell>
    </af:gridRow>
  </af:panelGridLayout>
</af:form>