Oracle ADF Data Visualizations Graph

An Oracle JDeveloper How To Document
Written by Katarina Obradovic-Sarkic, Oracle Corporation
November, 2007

Introduction to ADF Data Visualization Components

ADF Data Visualization components are a set of rich interactive ADF Faces components that provide significant graphical and tabular capabilities for analyzing data. Data Visualization components provide the following common features:

  • Design time creation using data control palette, JSF visual editor, property inspector and component palette
  • Support for data binding to standard rowset as well hierarchical data controls

Getting Started

This document is intended for users who want to learn more advanced topics related to the DVT components. The following steps are recommended to get started with creating and using Data Visualization components:

ADF Data Visualizations Graph

ADF DVT Graph supports more than 50 types such as bar, pie, line, scatter, and stock graphs that allow you to evaluate data points on multiple axes in a variety of ways. Part of JDeveloper since 10g, Graph is now a JSF component. New features for Graph include:

  • New graph types: Funnel, Floating Bar Graph, Fit to Curve
  • Flash rendering
  • SVG rendering
  • Interactivity: zooming, scrolling, time selector window, line and legend highlighting/fading, dynamic reference lines and areas
  • Advanced JSF graph tag as well as simplified tags for 17 commonly used graph types
  • UI for design time data binding and editing, including support for live data at design time

This document provides guidance and examples for using ADF DVT Graph in common application scenarios. The following sections explain how to:

  • Enable a Time Selector for a Graph
  • Use Time Selector to drive a detail graph via a parameterized ADF Business Components View
  • Change color for a series
  • Position or hide the Graph legend
  • Display curved lines in a line Graph
  • Explode a pie slice in a pie graph
  • Display text for pie slices instead of percentages
  • Format pie slice tooltips
  • Listen for a click event on a Graph series
  • Change Graph type at run time

1. Advanced Graph Formatting and Time Selector

Time selector is a window that can appear on any Graph with a Time axis (an axis displaying Time data). The end user can move this window and drag its edges to select a time period. An application can listen for the time selector events to get the new start and end dates for the time period user selected.

The image below displays an example of a Time axis graph with a Time Selector window. This Line Graph is displaying the number of service requests that came into a call center on every day of the past month.

Time Selector Graph Example

Create the Master Graph with a Time Selector

To create the above Line graph with a Time axis, follow these steps:

1. Download the SRDemo schema.

2. Create a new Fusion Web Application.

3. In the Model project, create a new View object named "Master" with the following SQL query that returns the number of Service Requests per day:

select trunc(request_date) "Incident Date", count(svr_id) "Num SRs Opened"
 from service_requests 
 group by trunc(request_date) order by trunc(request_date)

4. In the ViewController project, create a new JSPX page. Choose to expose the UI components on your page in a managed bean called SampleGraph. You will need to use the managed bean to create the Time Selector listener method.

5. Drag and drop the data control Master on the page and choose to create Advanced graph. In the Graph Binding dialog, choose to display NumSrsOpened for the Numeric Value, and IncidentDate for the Group Attribute.

Time Selector Binding

Format the Master Graph

1. In the Property Inspector, under Common properties, change the Graph type to Line( "LINE_VERT_ABS").

2. Under Appearance, in the Style section change the graph style to Comet and in the Image section change the image format to Flash.

3. To display a curved Line on the Graph, from the Component Palette -> ADF Data Visualization -> Graph -> General tab insert the tag dvt:seriesSet as a child of the dvt:graph tag. Using the Property Inspector, change the default marker type to MT_CURVE_LINE.

4. To change the series color for the line, insert a dvt:series tag as a child of dvt:seriesSet tag. Using the Property Inspector, change the color for the series to #FDB026.

5. To display the legend on the bottom, insert a dvt:legendArea tag from the Component Palette -> ADF Data Visualization -> Graph -> General. Using the Property Inspector set the position property to LAP_BOTTOM.

Enable Time Selector on the Master Graph

1. Insert a dvt:timeSelector tag as a child of the dvt:graph tag. Using the Property Inspector, specify the following properties for the dvt:timeSelector tag:

<dvt:timeSelector id="timeSelector1"
                              
mode="EXPLICIT"
explicitStart="#{sampleGraph.startDate}"
explicitEnd="#{sampleGraph.endDate}"
borderColor="#313675" fillColor="#33FFFFFF"/>

2. Add a Time Selector listener to the graph by setting the following property using the Property Inspector:

                               
timeSelectorListener="#{sampleGraph.processTimeSelector}"

                            

Here is the complete code for the Master graph:

                               
<dvt:graph id="master" graphType="LINE_VERT_ABS" 
           value="#{bindings.master1Graph.graphModel}"
           stylePath="Comet" imageFormat="FLASH"  
           timeSelectorListener="#{sampleGraph.processTimeSelector}">

            
                                
<dvt:timeSelector id="timeSelector1"
                                  
mode="EXPLICIT"
explicitStart="#{sampleGraph.startDate}"
explicitEnd="#{sampleGraph.endDate}"
borderColor="#313675" fillColor="#33FFFFFF"/>
<dvt:legendArea position="LAP_BOTTOM"/> <dvt:seriesSet defaultMarkerType="MT_CURVE_LINE"> <dvt:series id="0" color="#FDB026"/> </dvt:seriesSet> </dvt:graph>

Create a Detail Graph

1. In the Model project, create a new View object named "SRsByProduct" with the following SQL query that returns the top 5 products based on a number of incidents in the given time interval:

                               
                                 
select * from (select products.name "Product", count(products.prod_id) "Num Incidents" from products 
     join service_requests on products.prod_id = service_requests.prod_id 
     where service_requests.request_date >= :start_date and service_requests.request_date <= :end_date
     group by products.name order by count(products.prod_id) desc) where rownum < 6
                              
                            

Define start_date and end_date as variables of type Date.

2. Drag and drop the data control SRsByDate on the page and choose to create a Pie graph.

3. In the Graph Binding dialog, choose to display NumIncidents for the Numeric Value, and Product for the Group Attribute.

Pie Graph Binding

Format the Detail Graph and Explode a Pie Slice

The detail Graph is a pie Graph displaying the top 5 products based on the number of service incidents.

1. To explode the first pie slice to highlight the product with the largest number of service requests, drag a dvt:seriesSet into the page as a child of dvt:pieGraph. Drag a dvt:series tag to the page as a child of the dvt:seriesSet. Using the Property Inspector, set the pieSliceExplode property to 100.

2. Using the Property Inspector, set the threeDEffect to true, imageFormat to FLASH, and stylePath to Comet for the Pie graph. Set the partialTriggers property to "master", the id of the Master graph.

3. From the Component Palette under ADF Data Visualization -> Graph -> Graph Type-Specific, insert a dvt:sliceLabel tag as a child of the dvt:pieGraph tag. Using the Property Inspector, change the textType to LD_TEXT. This ensures that the pie slice labels will show product names instead of the percent values (default).

4. From the Component Palette under ADF Data Visualization -> Shared Child Tags, insert a dvt:numberFormat tag as a child of the dvt:sliceLabel tag. Using the Property Inspector, set the decimalDigit to 0.

5. From the Component Palette under ADF Data Visualization -> Graph -> General, insert a dvt:legendArea tag as a child of dvt:pieGraph tag. Set the rendered property to "false".

The Detail graph should look as follows:

Pie Graph

Here is the complete code for the detail Graph:

<dvt:pieGraph id="pieGraph" stylePath="Comet"
     imageFormat="FLASH" threeDEffect="true"
     value="#{bindings.SRsByProduct1.graphModel}"
     partialTriggers="master">
     <dvt:seriesSet>
          <dvt:series id="0" pieSliceExplode="100"/>
     </dvt:seriesSet>
     <dvt:sliceLabel textType="LD_TEXT">
          <dvt:numberFormat decimalDigit="0"/>
     </dvt:sliceLabel>
     <dvt:legendArea rendered="false"/>
</dvt:graph>

Create the Time Selector Listener

The Time selector listener receives the event when the Time Selector window is moved on the Master graph, passes the new start and end date to the Detail graph, and executes the Detail graph binding to get the new data. To create the Time Selector listener add the following code in the backing bean SampleGraph.java:

 public void processTimeSelector(TimeSelectorEvent event) throws AbortProcessingException
 {
      Date sdate = new Date(event.getStartTime());
      Date edate = new Date(event.getEndTime());
      
      oracle.jbo.domain.Date startDate = new oracle.jbo.domain.Date(sdate );
      oracle.jbo.domain.Date endDate =   new oracle.jbo.domain.Date(edate);
      JUCtrlAttrsBinding sd = (JUCtrlAttrsBinding)_bindings.get("start_date");
      JUCtrlAttrsBinding ed = (JUCtrlAttrsBinding)_bindings.get("end_date");
      sd.setInputValue(startDate);
      ed.setInputValue(endDate);
 
      try {
            JUCtrlActionBinding  actionBinding = (JUCtrlActionBinding) _bindings.get("ExecuteWithParams1");
            actionBinding.execute();
      }
      catch(Exception e) {
            System.out.println("Error executing the binding with new dates: " + e);

      }
 }

2. How To Click on a Graph Series and Perform an Action

An application often needs to track whether the user clicked on a graph series and perform an action based on the location of the click.

1. To create a listener for the Graph click event, add the following method in the backing bean for your application (for example SampleGraph.java used above):

public void processClick(ClickEvent event)
{
     ComponentHandle handle = event.getComponentHandle();
 
     if (handle instanceof DataComponentHandle)
     {
         DataComponentHandle dhandle = (DataComponentHandle)handle;
         // Get the value displayed in the series
         System.out.println("Value: " + dhandle.getValue(DataComponentHandle.UNFORMATTED_VALUE));
 
         // Get the series attributes
         Attributes [] seriesInfo = dhandle.getSeriesAttributes();
         if(seriesInfo != null)
         {
             for(Attributes attrs: seriesInfo)
             {
                 System.out.println("Series value: " + attrs.getValue(Attributes.LABEL_VALUE));
                 System.out.println("Series name: " + attrs.getValue(Attributes.LABEL_ATTRIBUTE));
                 System.out.println("Series value id: " + attrs.getValue(Attributes.ID_VALUE));
                 System.out.println("Series name id: " + attrs.getValue(Attributes.ID_ATTRIBUTE));
             }
         }
         // Get the group attributes
         Attributes [] groupInfo = dhandle.getGroupAttributes();
         if(groupInfo != null)
         {
             for(Attributes attrs: groupInfo)
             {
                 System.out.println("Group value: " + attrs.getValue(Attributes.LABEL_VALUE));
                 System.out.println("Group name: " + attrs.getValue(Attributes.LABEL_ATTRIBUTE)); 
             }
         }
     }
 }

2. Set the click listener on the graph tag:

clickListener="#{sampleGraph.processClick}"

3. How to Change the Graph Type at Run Time

To change the graph type at run time, use an advanced Graph and bind the graphType property to a backing bean. The graph type property can then be chnaged at run time using any ADF Faces UI control.

1. Create a Graph from the Data Control palette by following the steps outlined in the section "Create a Master Graph" above.

2. Bind the graphType property to a backing bean as follows:

graphType="#{sampleGraph.graphType}"

3. Set the partialTriggerts property on the graph to the ID of the UI contorl that will control the graph type at run time:

partialTriggers="graphTypeChoice"

3. The code for the graph should look as follows:

<dvt:graph id="graph1"
     value="#{bindings.master1.graphModel}"
     graphType="#{sampleGraph.graphType}" 
     partialTriggers="graphTypeChoice" />

                               

4. The Graph type can be controlled by any UI control. In this example we will use a simple choice control.
From the Component Palette -> ADF Faces insert the component af:selectOneChoice into the page. Set the autoSubmit property to "true" and the id property to "graphTypeChoice". Create the following labelk/value choices for the af:selectOneChoice:

  • Vertical Bar, BAR_VERT_CLUST
  • Line, LINE_VERT_ABS
  • Area, AREA_VERT_ABS
  • Horizontal Bar, BAR_HORIZ_CLUST

The code for the af:selectOneChoice should be as follows:

<af:selectOneChoice label="Graph Type" value="#{sampleGraph.graphType}"
                    autoSubmit="true" id="graphTypeChoice">
    <af:selectItem label="Vertical Bar" value="BAR_VERT_CLUST"/>
    <af:selectItem label="Line" value="LINE_VERT_ABS"/>
    <af:selectItem label="Area" value="AREA_VERT_ABS"/>
    <af:selectItem label="Horizontal Bar" value="BAR_HORIZ_CLUST"/>
 </af:selectOneChoice>

5. In the backing bean SampleGraph.java, add the accessor methods for the graphType property as follows:

 public String getGraphType() {
        return m_graphType;
 }
 
 public void setGraphType(String type) {
        m_graphType = type;
 }
 
 String m_graphType;

6. Run the page and use the choice control to change the graph type at run time:

Change Graph Type Change Graph Type Area

Where to Get More Information

For more information on using the Data Visualization components consult the chapter "Creating Databound Graphs, Gauges, Pivot Tables, Maps, and Gantt Charts" in the Fusion Developer's Guide for Oracle ADF and the chapter "Using Data Visualization Components" in the ADF Faces Component Guide, as well as other resources listed in the "Getting Started" section of this document.

 

false ,,,,,,,,,,,,,,,