ADF DVT Speed Date : Meeting The Hierarchy Viewer

Recently the ADF Special Interest Group at AMIS organized an ADF DVT Speed Date. During this speed date, six ADF specialists from our team presented their favorite Data Visualization Component from the DVT library. In a series of blog posts we share the information with a broader audience. In this post you get introduced to the Hierarchy Viewer – which was my own date for this party.

Introduction : The Hierarchy Viewer

A Hierarchy viewer is typically used to display hierarchical data. Examples of this are for instance a tree of life or a mindmap or even a family tree.

The ADF hierarchy viewer consists of several ADF components.

• dvt:hierarchyViewer : This element wraps the dvt:node and the dvt:link elements
• dvt:node : 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%).
• dvt:link : connects one node with another node
• dvt:panelCard : The panel card element provides a method to dynamically switch between multiple sets of content referenced by a node element using animation by, for example, horizontally sliding the content or flipping a node over.

A hierarchy viewer component requires data collections where a master-detail relationship exists between one or more detail collections and a master detail collection. The hierarchy viewer component uses the same data model as the ADF Faces tree component. When you add a hierarchy viewer component to a JSF page, JDeveloper adds a tree binding to the page definition file for the JSF page.

Lets start with creating a simple hierarchy viewer.

Hierarchy Viewer: The basics
A hierarchy viewer component can be used to visually display hierarchical data. Hierarchical data contains master-detail relationships within the data. For example, you could create a hierarchy viewer component that renders an organization chart from a data collection that contains information about the relationships between employees in an organization. Let’s do that. Create a new ADF Enterprise application in JDeveloper.

Creating the Business Components Create ADF Business Components from tables. These Business Components will be used as basis for the Hierarchy Viewer. The connection for this application needs to point to the DVT_USER. (you can use the HR schema as well if you like. If you do, then don’t use the table prefix LBO that I used in this example)

 

1. Skip the first couple of steps in the wizard. In this hands-on we will use read only view objects

2. In step 3 of the wizard (creation of read only view objects) adjust the package name if you want to.

3. Shuttle the LBO_EMP_DETAILS_VIEW to the right. This view contains all the data that is needed for the hierarchy viewer. Rename the instance to EmpDetails

In the next step, create an application module. This is the Application module that is used in this application.

Finish the wizard.

Connecting the employees

In the data in this hands on each employee has a manager (or not). This relationship is used in the hierarchy viewer to display employees as a child node of their manager. To make this work, a we need a view link. 1. Create a new viewlink to connect employees and managers. This link is necessary to be able to display hierarchical data.

Select the EmployeeId and the ManagerId and add the viewlink.

Accept all the defaults and click finish.

Defining the root node

The hierarchy will have one root node. This root node is the node that depicts the highest level of employees. In this case it is the employee with no manager. In order to find the rootnode, you have to create a viewcriteria.

With the viewcriteria created, it is now time to tell the viewobject usage to use this viewcriteria.
Open the application module data model. Step one is to add the employees viewobject usage as a child to the existing viewobject usage.

Step two is to change the EmpDetails usage and add the isRoot viewCriteria. Select the EmpDetails usage and push the “edit” button. In the ViewCriteria dialog shuttle the isRoot criteria to the right.

Now the Business Components part is finished.

Creating the “visible” part.
After finishing the business components it is now time to create the visible part of the hierarchy viewer application. For this you need to create a new page to hold the hierarchy viewer component.

Select the EmpDetails collection and drag it from the datacontrol on to your page and drop it as an hierarchy viewer.

JDeveloper now shows you the hierarchy viewer wizard. In the wizard select the vertical top down layout for the viewer.

In the next part of the wizard you need to create the hierarchy. Check all the checkboxes in order to get the hierarchy viewer’s data. Leave the other zoom levels for now. We will get to that later.

Note that JDeveloper added several attributes to display by default.

Click OK to finish the wizard.

Run the application and expand some nodes in the viewer

Supporting different zoom levels
As mentioned erarlier, the hierarchy viewer supports different zoom levels. These zoom levels are implemented by facets.

There are several ways to add the facets for extra zoom levels. You can go into hierarchy viewer declaration and enable the zoom levels and add the attributes that you want to display.

However, there is a somewhat more convenient approach. This is by recreating the hierarchy viewer with a different layout. Let’s do that now. Start with creatin a brand new page.

Drag and drop the same (EmpDetails) collection on to the page.

Now select the other quick start layout on the bottom of the wizard.

You will see the hierarchy viewer is now preconfigured somewhat different.

1. First you see an Image dropdown box. You can use this to add an image to the hierarchy viewer (duh). Select the employeeId attribute in the dropdown box in order to create an image based on the employeedId. This will not work, however it prepares the hierarchy viewer to use the image. We will fix that later.

Another thing that is different you see when you open any of the zoom levels. JDeveloper already added some of the attributes to the zoom level facet. The only thing you need to do is to actually add the zoom level to the hierarchy viewer by checking the box.

Check the boxes for all the ‘lower’zoom levels.

Finish the wizard by clicking OK.

JDeveloper created a hierarchy viewer with an image. This is implemented by the following code fragment.

 
<af:image source="#{node.EmployeeId}" 
          inlineStyle="width:85px;height:120px;"
          id="i1"/>

Replace that with

 
<af:image inlineStyle="width:108px;height:120px;"  
          source="/resources/images/hv/#{node.EmployeeId}.png"
          id="i1"/>

You can use any images as long as you put them in a folder called “/resources/images/hv/” and place this under the PUBLIC-HTML folder. Or better, as long as the source attribute knows where to find the images… On the file system it should look like this:

Now you will see the image that corresponds to the employee. Feel free to rename the images if you don’t mind to show an image that is not actually displaying the real ‘face’ of the employee. Run the application, zoom to 100% and see what happens

Changing panelcard transition effects

The hierarchy viewer has several panelcards. The transition from one panel card to another can be animated in different ways.

 

Play with the property and see the effect. Maybe even implement a dropdown in your application so the end user can change the effect at runtime. This is not described in the hands on; You need a selectoneChoice (can be hardcoded), a managedbean, and set the effect property to something like “#{mybean.myEffect} Note that in 11gR2 there is an extra value called “cube” which adds even more animation.

Adding search functionallity

The search function in a hierarchy viewer is based on the searchable attributes or columns of the data collection that is the basis of the hierarchy viewer data model. Using a query results collection defined in data controls in Oracle ADF, JDeveloper makes this a declarative task. You drag and drop an ExecuteWithParams operation into an existing hierarchy viewer component on the page.

Preparing Business Components

1. Create a view object that performs the search.

Finish the wizard.

Now expose the viewObject in the application module.

On the empDetails view object we also need to create a bindvariable. This is the one that is used to navigate to the node that was found by the search operation. Go to empDetails and create a bindvariable.

Adjust the where clause in the empDetails to take on the bindvariable.

Create a databound search with a hierarchy viewer:

1. From the Data Controls panel, select the EmployeesSearch and expand the Operations node to display the ExecuteWithParams operation. If you don’t see it, refresh the datacontrol palet. 2. Drag the ExecuteWithParams operation and drop it onto the hierarchy viewer in the visual editor or onto the component in the Structure window. Alternatively, you can drag the parameter onto the hierarchy viewer.

3. In the Create Hierarchy Viewer Search dialog that displays, use the Add icon to specify the list of results to display in the Search Results panel, and specify the following for each result:

a. Display Label: Select the values for the headers of the nodes in the hierarchy. If you select <default>, then the text for the header is automatically retrieved from the data binding.

b. Value Binding: Select the columns in the data collection to use for nodes in the tree for the hierarchy viewer.

c. Component to Use: Select the type of component to display in the node. The default is the ADF Output Text component. d. In the Operation dropdown list select the hierarchy root data collection to use when a search result is selected:

d. ExecuteWithParams: Sets the values to the named bind variables passed as parameters.

4. In the Parameter Mapping table, use the dropdown list in the Results Attribute column to select the results collection attribute to map to the parameter displayed in the Hierarchy Parameter column. In this hands on we need EmployeeId.

 

Now restart the page and see the search at work.

Resources

The information used in this post can be found in the ADF Developerguide here.