29 Using ADF Hierarchy Viewer Components

29.1.1 Understanding the Hierarchy Viewer Component

JDeveloper generates the following elements in JSF pages when you drag and drop components from the Component Gallery onto a JSF page or when you use the Create Hierarchy Viewer dialog to create a hierarchy viewer component as described in the "Creating Databound Hierarchy Viewers" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

• dvt:hierarchyViewer

  This element wraps the dvt:node and the dvt:link elements.

• dvt:node

  A node is a shape that references the data in a hierarchy (for example, employees in an organization or computers in a network). You configure the child elements of the dvt:node element to reference whatever data you want to display. The dvt:node element supports the use of one or more f:facet elements that display content at different zoom levels (100%, 75%, 50%, and 25%). The f:facet element supports the use of many ADF Faces components, such as af:outputText, af:image, and af:panelGroupLayout in addition to the ADF Data Visualization dvt:panelCard component.

  At runtime, the node contains controls that allow users to navigate between nodes and to show or hide other nodes by default. For information about specifying node content and defining zoom levels, see Section 29.4.1, "How to Specify Node Content".

• dvt:link

  You set values for the attributes of the dvt:link element to connect one node with another node.

• dvt:panelCard

  The f:facet element supports the use of a dvt:panelCard element. A dvt:panelCard element in turn can contain one or more af:showDetailItem elements that you can use to define multiple sets of content. At runtime, the end user uses the controls on the node to dynamically switch between the content that the af:showDetailItem elements reference. For more information, see Section 29.6, "Using Panel Cards".

  Note:

  Unlike the other elements, the dvt:panelCard element is not generated if you choose the default quick layout option when using the Create Hierarchy Viewer dialog.

29.1.2 Hierarchy Viewer Elements and Terminology

Figure 29-1 shows a segment of a hierarchy viewer component at runtime that includes a control panel, a number of nodes, and links that connect the nodes.

Figure 29-1 Hierarchy Viewer Component with Control Panel and Nodes

The Control Panel provides controls so that a user can manipulate the position and appearance of a hierarchy viewer component at runtime. By default, it appears in a hidden state in the upper left-hand corner of the hierarchy viewer component as illustrated by Figure 29-2.

Figure 29-2 Control Panel in Hidden State

You cannot configure the Control Panel to appear in another location. Users click the Hide or Show Control Panel button shown in Figure 29-2 to hide or expand the Control Panel. Figure 29-3 shows the expanded Control Panel.

Figure 29-3 Control Panel in Show State

You can configure the hierarchy viewer component so that the Control Panel does not appear to the user at runtime. For more information, see Section 29.7.3, "How to Configure the Display of the Control Panel".

Table 29-1 describes the functionality that the controls in the Control Panel provide to users. The Panel Selector is automatically enabled if a node in your hierarchy viewer component contains a dvt:panelCard element with one or more af:showDetailItem elements. The Layout Selector appears automatically if the hierarchy viewer component uses one of the following layouts:

• Vertical Top Down

• Horizontal Left to Right

• Tree

For more information about layouts for a hierarchy viewer component, see Section 29.1.3, "Available Hierarchy Viewer Layout Options".

Table 29-1 Elements in the Control Panel

Control	Name	Description
	Pan control	Allows user to reposition the hierarchy viewer component within the viewport.
	Zoom to Fit	Allows user to zoom a hierarchy viewer component so that all nodes are visible within the viewport.
	Zoom Control	Allows user to zoom the hierarchy viewer component.
	Hide or Show	Hides or shows the Control Panel.
	Panel Selector	Displays a list of node panels that you have defined. Users can use the panel selector to show the same panel on all nodes at once.
	Layout Selector	Allows a choice of layouts. Users can change the layout of the hierarchy viewer component from the layout you defined to one of the layout options presented by the hierarchy viewer component. For more information, see Section 29.1.3, "Available Hierarchy Viewer Layout Options".

29.1.3 Available Hierarchy Viewer Layout Options

You can choose from one of the following layouts for a hierarchy viewer component:

• Vertical Top Down

• Vertical Bottom Up

• Horizontal Left to Right

• Horizontal Right to Left

• Tree

• Radial

29.3.1 How to Configure Upward Navigation in a Hierarchy Viewer

If you want to configure upward navigation for a hierarchy view component, you configure a value for the hierarchy viewer component's navigateUpListener property.

To configure upward navigation for a hierarchy viewer component:

1. In the Structure window, select dvt:hierarchyViewer and open the Property Inspector.

2. Expand the Behavior section of the Property Inspector and write a value for the hierarchy viewer component's Navigate Up property (navigateUpListener) that specifies a method to update the data model so that it references the new anchor node when the user navigates up to a new anchor node.

3. Click OK.

29.3.2 How to Configure Same-Level Navigation in a Hierarchy Viewer

Same-level navigation between the nodes in a hierarchy viewer component is enabled by default. You can configure the hierarchy viewer component to determine how many nodes to display at a time. When you do this, controls appear that enable users to navigate to the following:

• Left or right to view the next set of nodes

• First or last set of nodes in the collection of available nodes

To configure same-level navigation in a hierarchy viewer component:

1. In the Structure window, right-click the dvt:hierarchyViewer node and select Go to Properties.

2. Expand the Common section of the Property Inspector and specify the number of nodes that you want to appear at runtime in the Nodes Per Level field (levelFetchSize).

   For example, the following entry appears in the JSF page if you entered 3 as the number of nodes:

   levelFetchSize="3"

3. Click OK.

29.3.3 What Happens When You Configure Same-Level Navigation in a Hierarchy Viewer

At runtime, the hierarchy viewer component renders the number of nodes that you specified as a value for the hierarchy viewer component's levelFetchSize property. It also renders controls that allow users to do the following:

• Navigate to the left or right to view the next set of nodes

• Navigate to the first or last set of nodes in the collection of available nodes

Figure 29-4 shows a runtime example where levelFetchSize="3". When a user moves the mouse over the control, as shown in the circled area in Figure 29-4, the control that allows users to navigate to the last set of nodes appears.

Figure 29-4 Hierarchy Viewer Component with Same-level Navigation

29.4.1 How to Specify Node Content

Although a node contains controls by default that allow you to navigate to a node and show or hide nodes, nodes do not include content by default unless you used a quick start layout when creating the hierarchy viewer component. You must define what content a node renders at runtime. You can specify node content when you associate data bindings with the hierarchy viewer component as described in the "Creating Databound Hierarchy Viewers" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. After you create a hierarchy viewer component by associating data bindings, you can add nodes to the hierarchy viewer component using the Component Palette.

By default, a hierarchy viewer component that you create contains one node with one facet element that has a zoom level of 100%:

<f:facet name="zoom100"/>

You can insert three more instances of the facet element into the hierarchy viewer component with the following zoom levels:

• 25%: zoom25

• 50%: zoom50

• 75%: zoom75

You can define a subset of the available data collection within one or more of the facet elements. For example, if you have a data collection with node attributes that references data about a company department such as its name or its number and location, you could specify a facet element with a zoom level of 50% that references the node attribute for the department's name.

Each of the facet elements that you insert can be used to reference other components. You can use one or more of the following components when you define content for a node in a hierarchy viewer component:

• af:commandButton

• af:commandImageLink

• af:commandLink

• af:commandMenuItem

• af:goButton

• af:goLink

• af:image

  For information about how to use the af:image component, see Section 29.7.2, "How to Include Images in a Hierarchy Viewer".

• af:menu

• af:outputFormatted

• af:outputText

• af:panelFormLayout

• af:panelGroupLayout

  For information about how to use the panelGroupLayout component, see Section 8.12.1, "How to Use the panelGroupLayout Component".

• af:panelLabelAndMessage

• af:separator

• af:showDetailItem

• af:showPopupBehavior

  For information about how to use the af:showPopupBehavior component, see Section 29.5.1, "Configure a Hierarchy Viewer to Invoke a Popup Window".

• af:spacer

• dvt:panelCard

  For more information about how to use the dvt:panelCard component, see Section 29.6, "Using Panel Cards".

The hierarchy viewer component renders in a Flash Player only. For this reason, certain properties of ADF Faces components that you specify as node content may not be supported and the component will not render as you expect.

To add a node to a hierarchy viewer component:

1. In the Structure window, right-click the dvt:hierarchyViewer node and select Insert inside dvt:hierarchyViewer > Node.

   The following entry appears in the JSF page:

   <dvt:node>
   <f:facet name="zoom100"/>
   </dvt:node>
   

2. In the Structure window, right-click the dvt:node and select Go to Properties.

3. Configure the appropriate properties in the Property Inspector.

   For example, write a value for the type property to specify a specific accessor for the node.

29.4.2 How to Configure the Controls on a Node

The node component (dvt:node) exposes a number of properties that allow you to determine if controls such as Restore, Isolate, Show or Hide appear at runtime. It also exposes properties that determine the size and shape of the node at runtime.

To configure the controls on a node:

1. In the Structure window, select the dvt:node component that you want to configure.

2. Configure properties in the Appearance section of the Property Inspector for the dvt:node component as described in the following table.

   To...	Set the following value for this property...
   Configure so that the Hide or Show controls appear on a node.	Set showExpandChildren to True (default) to display the controls.
   Configure so that the Restore or Isolate controls appear on the node.	Set the showNavigateUp and showIsolate properties to True (default) to enable these controls on the node. If you set the showNavigateUp property to True, you must also set a value for the hierarchy viewer component's navigateUpListener property as described in Section 29.3.1, "How to Configure Upward Navigation in a Hierarchy Viewer".
   Configure the height and width of a node.	Set values for the width and height properties.
   Select the shape of the node.	Select a value from the Shape dropdown list. Available values are: ellipse rect roundedRect

   
   

3. For information about configuring the properties in the Style section of the Property Inspector for the node component, see Section 20.4, "Changing the Style Properties of a Component".

29.4.3 Specifying a Node Definition for an Accessor

By default, you associate a node component with an accessor when you use the Create Hierarchy Viewer dialog to create a hierarchy viewer component as described in the "Creating Databound Hierarchy Viewers" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. The Create Hierarchy Viewer dialog sets the node component's type property to a specific accessor.

You can configure a node component's type property to use one or more specified accessors. Alternatively, you can configure a node component's rendered property to use a node definition across accessors, as described in Section 29.4.4, "Associating a Node Definition with a Particular Set of Data Rows". When the hierarchy viewer component determines which node definition to use for a particular data row, it first checks for a match on the type property:

• If the type property matches, the hierarchy viewer component uses the node definition.

• If the type property does not match, the hierarchy viewer component checks for a value of the rendered property that evaluates to true. The result of evaluating the rendered property does not affect the type property.

29.4.4 Associating a Node Definition with a Particular Set of Data Rows

You can use a node component's rendered property to associate the node with a particular set of data rows or a single data row. The rendered property accepts a boolean value so you can write an EL expression that evaluates to true or false to determine what data rows you associate with a node definition. For example, assume that you want a node to display data based on job title. You write an EL expression for the node component's rendered property similar to the following pseudo EL expression that evaluates to true when job title matches the value you specify (in this example, CEO):

#{node.title == 'CEO'}

When you use the node component's rendered property in this way, you do not define a value for the node component's type property.

29.4.5 Specifying Ancestor Levels for an Anchor Node

The anchor node of a hierarchy viewer component is the root of the hierarchy returned by the tree binding. Depending on the use case, there can be multiple anchor nodes (for example, a hierarchy viewer component that renders an organization chart with one or more managers). When a hierarchy viewer component renders at runtime, the node that has focus is the anchor node. If a user clicks another node that has a value specified for its setActionListener property, that node becomes the anchor node:

You can specify the number of ancestor levels for an anchor node.

To specify the number of ancestor levels for an anchor node:

1. In the Structure window, right-click the dvt:hierarchyViewer node and select Go to Properties.

2. Expand the Common section of the Property Inspector.

3. Specify the number of levels of ancestor nodes that you want to appear at runtime above the anchor node in the Ancestor Levels field (displayLevelsAncestor).

   For example, the following entry appears in the JSF page if you entered 2 as the number of ancestor levels for the anchor node.

   displayLevelsAncestor="2"

4. Save changes to the JSF page.

29.5.1 Configure a Hierarchy Viewer to Invoke a Popup Window

You can invoke a popup window by specifying values for the af:showPopupBehavior tag and invoking it from a command component (for example, af:commandButton). You must nest the command component that invokes the popup window inside an f:facet element in a node of the hierarchy viewer component. Note that the triggerType property of an af:showPopupBehavior tag used in this scenario supports only the following values:

• action

• mouseHover

For more information about using the af:showPopupBehavior tag, see Section 13.3, "Using Command Components to Show Popup Elements".

29.5.2 Configure a Hierarchy View Node to Invoke a Menu

You can configure a node component (dvt:node) within a hierarchy viewer to invoke a menu by using the af:menu component. You can configure one or more af:commandMenuItem elements for the af:menu component. Nodes within a hierarchy viewer component do not support the nesting of af:menu components.

For more information about using the af:menu component, see Chapter 13, "Using Popup Dialogs, Menus, and Windows".

29.6.1 How to Create a Panel Card

You can insert a panel card component into the JSF page that renders the hierarchy viewer component by using the context menu that appears when you select the Facet zoom element in the Structure window for the JSF page.

To create a panel card:

1. In the Structure window, right-click the zoom level within the node where you want to create a panel card.

   For example, select f:facet - zoom100.

2. Select Insert inside f:facet -zoom100 > Panel Card.

3. Use the Property Inspector to configure the properties of the panel card component.

   For example, set a value for the Effect property in the Advanced properties for the panel card component. Valid values are:

   • Horizontal Slide (default)

   • Panel Flip

   • Node Flip

   • No Animation

4. In the Structure window, right-click dvt:panelCard and select Insert inside dvt:panelCard > Show Detail Item.

5. Repeat Step 4 as necessary.

6. Use the Property Inspector to configure the properties of the af:showDetailItem elements that you insert.

29.6.2 What Happens at Runtime When a Panel Card Component Is Rendered

At runtime, a node appears and displays one panel card component. Users can click the navigation buttons to navigate to the next set of content referenced by one of the panel card's af:showDetailItem child elements.

Figure 29-7 shows a node with a panel card component where two different af:showDetailItem child elements reference different sets of information (Contact and Address). The user can use the provided controls to navigate between the different sets of information.

Figure 29-7 Runtime View of a Node with a Panel Card

29.7.1 How to Adjust the Size of a Hierarchy Viewer

You can adjust the size of the hierarchy viewer component by setting values for a number of the hierarchy viewer component's attributes using the Property Inspector.

To adjust the size of a hierarchy viewer:

1. In the Structure window for the JSF page that contains the hierarchy viewer component, select the dvt:hierarchyViewer node.

2. In the Property Inspector, write values for the InlineStyle property as described in the following list:

   • width

     Write a value in percent (%) or pixels (px). For example, the default value for width is 100%.

   • height

     Write a value in percent (%) or pixels (px). For example, the default value for height is 600px.

   The final value that you enter for the InlineStyle property must use the syntax shown in the following example:

   width:100%;height:600px;

3. Save changes to the JSF page.

29.7.2 How to Include Images in a Hierarchy Viewer

You can configure a hierarchy viewer component to display images in the nodes of a hierarchy viewer component at runtime. This can be useful where, for example, you want pictures to appear in an organization chart. Wrap the af:panelGroupLayout component within an af:facet component that is referenced by a dvt:node component. The following code example shows an af:panelGroupLayout component that references an instance of the af:image component from within an af:facet component. The af:image component renders an image for the person referenced by node.PersonId.

<af:panelGroupLayout>
<af:image source="/render_image?person_id=#{node.PersonId}"
inlineStyle="width:64px;height:90px;"/>                                
</af:panelGroupLayout>

For more information about the af:panelGroupLayout component, see Section 8.12.1, "How to Use the panelGroupLayout Component".

29.7.3 How to Configure the Display of the Control Panel

You can configure the hierarchy viewer component so that the Control Panel described in Section 29.1.2, "Hierarchy Viewer Elements and Terminology" acts as follows when the hierarchy viewer component renders at runtime:

• Appears in an expanded or show state

• Appears in a collapsed or hidden state

• Does not appear to users

To configure the display of the Control Panel:

1. In the Structure window, right-click the dvt:hierarchyViewer node and select Go to Properties.

2. Expand the Appearance section and select one of the following values from the ControlPanelBehavior dropdown list:

   • hidden

     Select this value if you do not want the Control Panel to appear at runtime.

   • initCollapsed

     This is the default value. The Control Panel appears in a collapsed or hidden state at runtime.

   • initExpanded

     Select this value if you want the Control Panel to appear in an expanded or show state at runtime.

3. Save changes to the JSF page.