Skip Headers
Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)

Part Number B31973-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

23 Using ADF Graph Components

This chapter describes how to use a databound ADF graph component to display data, and the options for graph customization.

This chapter includes the following sections:

For information about the data binding of ADF graphs, see the "Creating Databound ADF Graphs" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

23.1 Introduction to the ADF Graph Component

The ADF graph component gives you the capability of producing more than 50 types of graphs, including a variety of bar graphs, pie graphs, line graphs, scatter graphs, and stock graphs. This component lets you evaluate multiple data points on multiple axes in many ways. For example, a number of graphs assist you in the comparison of results from one group against the results from another group.

A Component Gallery displays available graph categories, types, and descriptions to provide visual assistance when designing graphs and using a quick-start layout. Figure 23-1 shows the Component Gallery for graphs.

Figure 23-1 Component Gallery for Graphs

Component Galler for graphs.

When a graph is inserted into a JSF page using the Component Gallery, a set of child tags that support customization of the graph is automatically inserted. Example 23-1 shows the code for a horizontal bar graph with the quick-start layout selected in the Component Gallery in Figure 23-1.

Example 23-1 Horizontal Bar Graph Sample Code

<dvt:horizontalBarGraph id="horizontalBarGraph1"
                              value="#{bindings.SalesStageDataView1.graphModel}"
                              subType="BAR_HORIZ_CLUST">
        <dvt:background>
          <dvt:specialEffects/>
        </dvt:background>
        <dvt:graphPlotArea/>
        <dvt:seriesSet>
          <dvt:series/>
        </dvt:seriesSet>
        <dvt:o1Axis/>
        <dvt:y1Axis/>
        <dvt:legendArea automaticPlacement="AP_NEVER"/>
      </dvt:horizontalBarGraph>

23.2 Understanding the ADF Graph Tags

Because of the many graph types and the significant flexibility of the graph components, ADF graphs have a large number of DVT tags. The prefix (dvt:) occurs at the beginning of each graph tag name indicating that the tag belongs to the ADF Data Visualization Tools (DVT) tag library. The following list identifies groups of tags related to the ADF graph component:

For complete descriptions of all the tags, their attributes, and a list of valid values, consult the DVT tag documentation. To access this documentation for a specific tag in JDeveloper, select the tag in the Structure window and press F1. To access the full ADF Data Visualization Tools tag library in JDeveloper Help, expand the Javadoc and Tag Library References node in the online Help Table of Contents and click the link to the tag library in the JDeveloper Tag Library Reference topic.

23.2.1 Graph-Specific Tags

The following list describes the 12 graph-specific tags:

  • dvt:areaGraph: Supports an area graph in which data is represented as a filled-in area. Use area graphs to show trends over time, such as sales for the last 12 months. Area graphs require at least two groups of data along an axis. The axis is often labeled with increments of time such as months.

  • dvt:barGraph: Supports a bar graph in which data is represented as a series of vertical bars. Use bar graphs to examine trends over time or to compare items at the same time, such as sales for different product divisions in several regions.

  • dvt:horizontalBarGraph: Creates a graph that displays bars horizontally along the Y-axis. Use horizontal bar graphs to provide an orientation that allows you to show trends or compare values.

  • dvt:bubbleGraph: Creates a graph in which data is represented by the location and size of round data markers (bubbles). Use bubble graphs to show correlations among three types of values, especially when you have a number of data items and you want to see the general relationships. For example, use a bubble graph to plot salaries (X-axis), years of experience (Y-axis), and productivity (size of bubble) for your work force. Such a graph allows you to examine productivity relative to salary and experience.

  • dvt:comboGraph: Creates a graph that uses different types of data markers (bars, lines, or areas) to display different kinds of data items. Use combination graphs to compare bars and lines, bars and areas, lines and areas, or all three combinations.

  • dvt:funnelGraph: Creates a graph that is a visual representation of data related to steps in a process. The steps appear as vertical slices across a horizontal cone-shapted section. As the actual value for a given step or slice approaches the quota for that slice, the slice fills. Typically a funnel graph requires actual values and target values against a stage value, which might be time. For example, use the funnel graph to watch a process where the different sections of the funnel represent different stages in the sales cycle.

  • dvt:lineGraph: Creates a graph in which data is represented as a line, as a series of data points, or as data points that are connected by a line. Line graphs require data for at least two points for each member in a group. For example, a line graph over months requires at least two months. Typically a line of a specific color is associated with each group of data such as the Americas, Europe, and Asia. Use line graphs to compare items over the same time.

  • dvt:paretoGraph: Creates a graph in which data is represented by bars and a percentage line that indicates the cumulative percentage of bars. Each set of bars identifies different sources of defects, such as the cause of a traffic accident. The bars are arranged by value, from the largest number to the lowest number of incidents. A Pareto graph is always a dual-Y graph in which the first Y-axis corresponds to values that the bars represent and the second Y-axis runs from 0% to 100% and corresponds to the cumulative percentage values. Use Pareto graphs to identify and compare the sources of defects.

  • dvt:pieGraph: Creates a graph in which one group of data is represented as sections of a circle causing the circle to look like a sliced pie. Use pie graphs to show the relationship of parts to a whole such as how much revenue comes from each product line.

  • dvt:radarGraph: Creates a graph that appears as a circular line graph. Use radar graphs to show patterns that occur in cycles, such as monthly sales for the last three years.

  • dvt:scatterGraph: Creates a graph in which data is represented by the location of data markers. Use scatter graphs to show correlation between two different kinds of data values such as sales and costs for top products. Use scatter graphs in particular to see general relationships among a number of items. A scatter graph can display data in a directional manner as a polar graph.

  • dvt:stockGraph: Creates a graph in which data shows the high, low, and closing prices of a stock. Each stock marker displays two to four separate values (not counting the optional volume marker) depending on the specific type of stock graph chosen.

23.2.2 Common Graph Child Tags

The following list describes the types of common customization and the related child tags:

  • Animation effects for graphs: dvt:animationOnDisplay and dvt:animationOnDataChange tags.

  • Alerts that highlight a data point with a custom icon: dvt:alertSet and dvt:alert tags.

  • Annotations that insert notes for specific data points: dvt:annotationSet and dvt:annotation tags.

  • Appearance and titles for the graph: dvt:background, dvt:graphFont, dvt:graphFootnote, dvt:graphPlotArea, dvt:graphSubtitle, and dvt:graphTitle tags.

  • Colors and appearance of bars, areas, lines, and pie slices (also known as series items): dvt:seriesSet and dvt:series tags.

  • Legend appearance: dvt:legendArea, dvt:legendText, and dvt:legendTitle tags.

  • Marker customization related to each axis: dvt:markerText, dvt:x1Format, dvt:y1Format, dvt:y2Format, and dvt:zFormat tags.

  • Reference lines and reference areas: dvt:referenceObjectSet and dvt:referenceObject tags.

  • Customization for the ordinal axis (also known as the category axis): dvt:01Axis, dvt:01MajorTick, dvt:01TickLabel, and dvt:01Title tags.

  • Customization for the x-axis: dvt:x1Axis, dvt:x1MajorTick, dvt:x1TickLabel, and dvt:x1Title tags.

  • Customization for the y1-axis: dvt:y1Axis, dvt:y1BaseLine, dvt:y1MajorTick, dvt:y1TickLabel, and dvt:y1Title tags.

  • Customization for the y2-axis: dvt:y2Axis, dvt:y2BaseLine, dvt:y2MajorTick, dvt:y2TickLabel, and dvt:y2Title tags.

23.2.3 Graph-Specific Child Tags

The following list describes the types of graph-specific customizations and the related child tags.

  • Gradients that are used for a graph only in conjunction with dvt:background, dvt:legendArea, dvt:graphPlotArea, dvt:graphPieFrame, dvt:series, or dvt:timeSelector subcomponents: dvt:specialEffects and dvt:gradientStopStyle tags.

  • Interactivity specifications for subcomponents of a graph: dvt:shapeAttrbutesSet and dvt:shapeAttributes tags.

  • Formatting of numbers for dvt:sliceLabel, dvt:stockVolumeFormat, dvt:x1Axis, dvt:x1Format, dvt:y1Axis, dvt:y1Format, dvt:y2Axis, dvt:y2Format, dvt:zFormat, dvt:numberFormat tag.

  • Time axis customization for area, bar, combination, line, and stacked bar graphs: dvt:timeAxisDateFormat, and dvt:timeSelector tags.

  • Selection of a range on a time axis for master-detail graphs: dvt:timeSelector tag.

  • Pareto graphs: dvt:paretoLine and dvt:paretoMarker tags.

  • Pie graphs: dvt:graphPieFrame, dvt:pieFeeler, dvt:slice, and dvt:sliceLabel tags.

  • Stock graphs: dvt:stockMarker, dvt:stockVolumeformat, and dvt:volumeMarker tags.

23.2.4 Child Set Tags

The following shows examples of child set tags:

  • dvt:alertSet tag: Wraps dvt:alert tags that define an additional data point that needs to be highlighted with a separate symbol, such as an error or warning.

  • dvt:annotationSet tag: Wraps dvt:annotation tags that define an annotation on a graph. An annotation is associated with a specific data point on a graph

  • dvt:referenceObjectSet tag: Wraps dvt:referenceObject tags that define a reference line or a reference area for a graph. You can define an unlimited number of reference objects for a given graph.

  • dvt:seriesSet tag: Wraps dvt:series tags that define a series on a graph.

  • dvt:shapeAttributesSet tag: Wraps dvt:shapeAttributes tags that specified interactivity properties on a subcomponent of a graph.

In each case, during design, you must create the wrapper tag first, followed by a related tag for each item in the set. Example 23-2 shows the sequence of the tags when you create a set of alert tags to define two alert points for an area graph.

Example 23-2 Sample Code for a Set of Alert Tags

<dvt:areaGraph id="areaGraph1" subType="AREA_VERT_ABS">
  <dvt:background>
    <dvt:specialEffects/>
  </dvt:background>
  <dvt:graphPlotArea/>
  <dvt:alertSet>
    <dvt:alert xValue="Boston" yValue="3.50"
         yValueAssignment="Y1AXIS" imageSource="myWarning.gif"/>
    <dvt:alert xValue="Boston" yValue="5.50"
         yValueAssignment=""Y1AXIS" imageSource="myError.gif"/>
 </dvt:alertSet>
      <dvt:o1Axis/>
      <dvt:y1Axis/>
     <dvt:legendArea automaticPlacement="AP_NEVER"/>
  </dvt:areaGraph>

23.3 Understanding Data Requirements for Graphs

Data requirements for graphs differ with graph type. Data requirements can be any of the following kinds:

Similar graphs share similar data requirements. For example, you can group the following graphs under the category of area graphs:

23.3.1 Area Graphs Data Requirements

An area graph is one in which data is represented as a filled-in area. The following kinds of area graphs are available:

  • Absolute: Each area marker connects a series of two or more data values. This kind of graph has the following variations: Absolute area graph with a single Y-axis and absolute area graph with a split dual-Y axis.

    In a split dual-Y graph, the plot area is split into two sections, so that sets of data assigned to the different Y-axes appear in different parts of the plot area.

  • Stacked: Area markers are stacked. The values of each set of data are added to the values for previous sets. The size of the stack represents a cumulative total. This kind of graph has the following variations: Stacked area graph with a single Y-axis and stacked area graph with a split dual Y-axis.

  • Percentage: Area markers show the percentage of the cumulative total of all sets of data.

Data guidelines for area graphs are:

  • Area graphs require at least two groups of data. A group is represented by a position along the horizontal axis that runs through all area markers. In a graph that shows data for a three-month period, the groups might be labeled Jan, Feb, and Mar.

  • Area graphs require one or more series of data. A filled-in area represents a series or set of data and is labeled by legend text, such as the continent of the Americas, Europe, and Asia.

  • Percentage area graphs cannot have negative numbers.

  • Dual-Y graphs require two sets of data.

23.3.2 Bar Graph Data Requirements

A bar graph is one in which data is represented as a series of bars. The following kinds of bar graphs are available:

  • Clustered: Each cluster of bars represents a group of data. For example, if data is grouped by employee, one cluster might consist of a Salary bar and a Commission bar for a given employee. This kind of graph includes the following variations: Vertical clustered bar graphs and horizontal clustered bar graphs. All variations of clustered bar graphs can be arranged as single Y-axis, dual Y-axis, and split dual Y-axis graphs.

  • Stacked: Bars for each set of data are appended to previous sets of data. The size of the stack represents a cumulative data total. This kind of graph includes the following variations: Vertical stacked bar graphs and horizontal stacked bar graphs. All variations of stacked bar graphs can be arranged as single Y-axis, dual Y-axis, and split dual Y-axis graphs.

  • Percentage: Bars are stacked and show the percentage of a given set of data relative to the cumulative total of all sets of data. Percentage bar graphs are arranged only with a single Y-axis.

Data guidelines for bar graphs are:

  • Percentage bar graphs cannot have negative numbers.

  • Dual-Y graphs require two sets of data.

23.3.3 Bubble Graph Data Requirements

A bubble graph is one in which data is represented by the location and size of round data markers (bubbles). Each data marker in a bubble graph represents three group values:

  • The first data value is the X value. It determines the marker's location along the X-axis.

  • The second data value is the Y value. It determines the marker's location along the Y-axis.

  • The third data value is the Z value. It determines the size of the marker.

The following kinds of bubble graphs are available: Bubble graph with a single Y-axis and bubble graph with a dual Y-axis.

Data guidelines for a bubble graph are:

  • Bubble graphs require at least three data values for a data marker.

  • For more than one group of data, bubble graphs require that data must be in multiples of three. For example, in a specific bubble graph, you might need three values for Paris, three for Tokyo, and so on. An example of these three values might be: X value is average life expectancy, Y value is average income, and Z value is population.

    Note:

    When you look at a bubble graph, you can identify groups of data by examining tooltips on the markers. However, identifying groups is not as important as looking more at the overall pattern of the data markers.

23.3.4 Combination Graph Data Requirements

A combination graph uses different types of data markers to display different sets of data. The data markers used are bar, area, and line.

Data guidelines for combination graphs are:

  • Combination graphs require at least two sets of data or else the graph cannot show different marker types.

  • Combination graphs require at least two groups of data or else the graph cannot render an area marker or a line marker.

23.3.5 Funnel Graph Data Requirements

A funnel graph is a visual representation of data related to steps in a process. As the value for a given step (or slice) of the funnel approaches the quota for that slice, the slice fills. A funnel renders a three-dimensional chart that represents target and actual values, and levels by color. A funnel graph displays data where the target is considered to be 100%. Therefore, if the actual value is 50 and target is 200, then 25% of the slice will be filled.

Data guidelines for funnel graphs are:

  • Funnel graphs require two series (or sets of data). These two sets of data serve as the target and actual data values. Threshold values appear in the graph legend.

    Another variation of the funnel graph requires only one set of data, where the data values shown are percentages of the total values. To produce this type of funnel graph, you must set the funnelPercentMeasure property on the graph to be True. This setting should be done in the XML for the graph.

  • Funnel graphs require at least one group of data to be used as a stage.

23.3.6 Line Graph Data Requirements

A line graph represents data as a line, as a series of data points, or as data points that are connected by a line. The following kinds of line graphs are available:

  • Absolute: Each line segment connects two data points. This kind of graph can have its axes arranged as single Y-axis, dual Y-axis, and split dual Y-axis.

  • Stacked: Lines for each set of data are appended to previous sets of data. The size of the stack represents a cumulative data total. This kind of graph can have its axes arranged as single Y-axis, dual Y-axis, and split dual Y-axis.

  • Percentage: Lines are stacked and each line shows the percentage of a given set of data relative to the cumulative total of all sets of data. Percentage line graphs are arranged only with a single Y-axis.

Data guidelines for line graphs are:

  • Line graphs require at least two groups of data because lines require at least two points. A group is represented by a marker of each color. The group has a tick label such as the name of a month.

  • Percentage line graphs cannot have negative numbers.

  • Dual-Y graphs require two sets of data.

23.3.7 Pareto Graph Data Requirements

Pareto graphs are specifically designed for identifying sources of defects. In a Pareto graph, a series of bars identifies different sources of defects. These bars are arranged by value, from the greatest number to the lowest number. A line shows the percentage of the cumulative values of the bars to the total values of all the bars in the graph. The line always ends at 100%.

Pareto graphs are always dual-Y graphs. The Y1-axis corresponds to values that the bars represent. The Y2-axis corresponds to the cumulative percentage values.

Data guidelines for Pareto graphs are:

  • Pareto graphs require at least two groups of data.

  • Pareto graphs cannot have negative numbers.

  • If you pass more than one set of data to a Pareto graph, the graph uses only the first set of data.

  • Do not pass percentage values as part of the data for a Pareto graph. The graph calculates the percentages based on the data that you pass.

23.3.8 Pie Graph Data Requirements

A pie graph represents data as sections of one or more circles, making the circles look like sliced pies. The following varieties of pie graphs are available:

  • Pie: The center of each circle is full. Pie graphs can consist of a single pie or multiple pies.

  • Ring: The center of each circle has a hole in which the total pie value is displayed. Ring graphs can consist of a single ring or multiple rings.

The data structure of a pie graph follows:

  • Each pie or ring represents one group of data and has a pie or ring label such as the name of a month. If you have only one group of data, then only one pie or ring appears even if you selected a multiple pie or ring graph type. Also, if any group has all zero data, then the pie or ring for that group is not displayed.

  • A series or set of data is represented by all the slices of the same color. You see legend text for each set of this data. For example, if there is a separate set of data for each country, then the name of each country appears in the legend text.

Data guidelines for pie graphs are:

  • Pie graphs cannot have negative numbers.

  • Multiple pie graphs require at least two groups of data.

23.3.9 Polar Graph Data Requirements

A polar graph is a circular scatter graph. In a polar graph, as in a scatter graph, data is represented by the location of data markers. In a polar graph, the plot area, where the markers appear, is circular. For information about scatter graphs, see Section 23.3.11.

Like scatter graphs, polar graphs are especially useful when you want to see general relationships among a number of data items. Use polar graphs rather than scatter graphs when the data has a directional aspect.

Each data marker in a polar graph represents two data values:

  • The first data value is the X value. It determines the location of the marker along the X-axis, which is the location around the circle, clockwise.

  • The second data value is the Y value. It determines the location of the marker along the Y-axis, which is the distance from the center of the graph.

Data guidelines for a polar graph require at least two data values for each marker.

23.3.10 Radar Graph Data Requirements

A radar graph is a polygonal line graph similar to how a polar graph is a circular scatter graph. Use radar graphs to show patterns that occur in cycles, such as monthly sales for the last three years.

The data structure of a radar graph follows:

  • The number of sides on the polygon is equal to the number of groups of data. Each corner of the polygon represents a group.

  • A series or set of data is represented by a line, all the markers of the same color, or both. It is labeled by legend text.

Data guidelines for radar graphs require at least three groups of data.

23.3.11 Scatter Graph Data Requirements

A scatter graph represents data by the location of data markers. Scatter graphs are especially useful when you want to see general relationships among a number of data points. For example, you can use a scatter graph to examine the relationships between Sales and Profit values for specific products.

Scatter graphs have either a single Y-axis or a dual Y-axis. Each data marker in a scatter graph represents two values:

  • The first data value is the X value. It determines the marker's location along the X-axis.

  • The second data value is the Y value. It determines the marker's location along the Y-axis.

Data guidelines for scatter graphs are:

  • Scatter graphs require two data values for each marker.

  • For more than one group of data, the data must be in multiples of two.

23.3.12 Stock Graph Data Requirements

Stock graphs display stock prices and, optionally, the volume of trading for one or more stocks in a graph. When any stock or candle stock graph includes the volume of trading, the volume appears as bars in the lower part of the graph.

Candle stock graphs display stock prices and, optionally, the volume of trading for only a single stock. When a candle stock graph includes the volume of trading, the volume appears as bars in the lower part of the graph.

Candle stock graphs also show the lesser of the open and close values at the bottom of the candle. The greater value appears at the top of the candle. If the closing value is greater than the opening value, then the candle is green. If the opening value is higher than the closing value, then the candle is red.

23.3.12.1 Stock Graphs: High-Low-Close

Data requirements for a high-low-close stock graph are:

  • Each stock marker requires a group of three data values in the following sequence: High, Low, Close. To display stock data for more than one day, data must be in multiples of three, such as three data values for Monday, three data values for Tuesday, and so on.

  • A series (or set) of data is represented by markers of the same color that represent one stock. A series is labeled by legend text such as Stock A. The legend appears even if you have only one stock. Most high-low-close stock graphs have only one series. If you show more than one series and the prices of the different stocks overlap, then some stock markers obscure other stock markers.

23.3.12.2 Stock Graphs: High-Low-Close with Volume

Data requirements for a high-low-close stock graph with volume are:

  • Each stock marker requires a group of four data values in the following sequence: High, Low, Close, Volume. To display stock data for more than one day, data must be in multiples of four and sequenced as follows: Monday High, Monday Low, Monday Close, Monday Volume, and so on for each additional day.

  • High-low-close stock graphs that also show volume can display the data for only one stock. The label for this stock appears in the legend of the graph.

23.3.12.3 Stock Graphs: Open-High-Low-Close

Data requirements for an open-high-low-close stock graph are:

  • Each stock marker requires a group of four data values in the following sequence: Open, High, Low, Close. To display stock data for more than one day, data must be in multiples of four, such as four data values for Monday, four data values for Tuesday, and so on.

  • A series (or set) of data is represented by markers that have the same color and represent one stock. A series is labeled by legend text such as Stock A. The legend appears even if you have only one stock. Most open-high-low-close stock graphs have only one series. If you show more than one series and the prices of the different stocks overlap, then some stock markers obscure other stock markers.

23.3.12.4 Stock Graphs: Open-High-Low-Close with Volume

Data requirements for an open-high-low-close stock graph with volume are:

  • Each stock marker requires a group of five data values in the following sequence: Open, High, Low, Close, Volume. To display stock data for more than one day, data must be in multiples of five and sequenced as follows: Monday Open, Monday High, Monday Low, Monday Close, Monday Volume, and so on for each additional day.

  • Open-high-low-close stock graphs that also show volume can display the data for only one stock. The label for this stock appears in the legend of the graph.

23.3.12.5 Candle Stock Graphs: Open-Close

Data requirements for an open-close candle stock graph are:

  • Each stock marker requires a group of two data values in the following sequence: Open, Close. To display stock data for more than one day, data must be in multiples of two, such as two data values for Monday, two data values for Tuesday, and so on.

  • A series (or set of data) is represented by markers for one stock. Candle stock graphs allow the display of values for only one stock. For this reason, no legend appears in these graphs and you should show the series label (which is the name of the stock) in the title of the graph.

23.3.12.6 Candle Stock Graphs: Open-Close with Volume

Data requirements for an open-close candle stock graph with volume are:

  • Each stock marker requires a group of three data values in the following sequence: Open, Close, Volume. To display stock data for more than one day, data must be in multiples of three, such as three data values for Monday, three data values for Tuesday, and so on.

  • A series (or set of data) is represented by markers for one stock. Candle stock graphs allow the display of values for only one stock. For this reason, no legend appears in these graphs and you should show the series label (which is the name of the stock) in the title of the graph.

23.3.12.7 Candle Stock Graphs: Open-High-Low-Close

Data requirements for an open-high-low-close candle stock graph are:

  • Each stock marker requires a group of four data values in the following sequence: Open, High, Low, Close. To display stock data for more than one day, data must be in multiples of four, such as four data values for Monday, four data values for Tuesday, and so on.

  • A series (or set) of data is represented by markers for one stock. Candle stock graphs allow the display of values for only one stock. For this reason, no legend appears in these graphs and you should show the series label (which is the name of the stock) in the title of the graph.

23.3.12.8 Candle Stock Graphs: Open-High-Low-Close with Volume

Data requirements for an open-high-low-close candle stock graph with volume are:

  • Each stock marker requires a group of five data values in the following sequence: Open, High, Low, Close, Volume. To display stock data for more than one day, data must be in multiples of five, such as five data values for Monday, five data values for Tuesday, and so on.

  • A series (or set) of data is represented by markers for one stock. Candle stock graphs allow the display of values for only one stock. For this reason, no legend appears in these graphs and you should show the series label (which is the name of the stock) in the title of the graph.

23.4 Creating an ADF Graph

You can use any of the following data sources to create an ADF Faces graph component:

23.4.1 How to Create a Graph Using Tabular Data

The process of creating a graph from tabular data includes the following steps:

  • Storing tabular data in a method in the graph's managed bean.

  • Creating a graph that uses the tabular data stored in the managed bean.

23.4.1.1 Storing Tabular Data for a Graph in a Managed Bean

The tabularData attribute of a dvt:graph component lets you specify a list of data that the graph uses to create a grid and populate itself. To construct this list, you require an understanding of series and groups of data in a graph as well as knowledge of the structure of the list.

23.4.1.1.1 Series and Groups of Data

An ADF graph displays series and groups of data. Series and groups are analogous to the rows and columns of a grid. Usually the rows in the grid appear as a series in a graph and the columns in the grid appear as groups in the graph.

For most graphs, a series appears as a set of markers that are the same color. Usually the graph legend shows the identification and associated color of each series. For example, in a bar graph, the yellow bars might represent the sales of shoes and the green bars might represent the sales of boots.

Groups appear differently in different graph types. In a clustered bar graph, each cluster is a group. In a stacked bar graph, each stack is a group. In a multiple pie graph, each pie is a group. A group might represent time periods, such as years. A group might also represent geographical locations such as regions.

Depending on the data requirements for a graph type, a single group might require multiple data values. For example, a scatter graph requires two values for each data marker. The first value determines where the marker appears along the x-axis while the second value determines where the marker appears along the y-axis.

23.4.1.1.2 Structure of the List of Tabular Data

The list that contains the tabular data consists of a three-member Object array for each data value to be passed to the graph. The members of each array must be organized as follows:

  • The first member (index 0) is the column label, in the grid, of the data value. This is generally a String. If the graph has a time axis, then this should be a Java Date. Column labels typically identify groups in the graph.

  • The second member (index 1) is the row label, in the grid, of the data value. This is generally a String. Row labels appear as series labels in the graph, usually in the legend.

  • The third member (index 2) is the data value, which is usually Double.

23.4.1.1.3 Example of a List of Data

Figure 23-2 has three columns: 2006, 2007, and 2008. This graph also has two row: Shoes and Boots. This data produces a graph that compares annual sales for boots and shoes over a three-year period.

Figure 23-2 Comparison of Annual Sales

Tabular data for graph.

Example 23-3 shows code that creates the list of data required for a graph to compare annual sales of shoes and boots for a three-year period.

Example 23-3 Code to Create a List of Data for a Graph

public List getTabularData() 
{
    ArrayList list = new ArrayList();
    String[] rowLabels  = new String[] {"Boots", "Shoes"};
    String[] colLabels  = new String[] {"2006", "2007", "2008"};
    Double [] [] values = new Double[][]{
        {120000, 122000, 175000},
        {90000, 110000, 150000}
        };
    for (int c = 0; c < colLabels.length; c++)
    {
     for (int r = 0; r < rowLabels.length; r++)
       {
        list.add (new Object [] {colLabels[c], rowLabels[r], 
            new Double (values[r][c])});
       }
    }
    return list;
}

23.4.1.2 Creating a Graph Using Tabular Data

Use the tabularData attribute of a dvt:graph tag to reference data that is stored in a method in a managed bean. Graph-specific tags do not support the tabularData attribute.

To create a graph that uses data from a managed bean:

  1. In the source editor of the .jspx page type in the dvt:graph tag in the desired location on the page.

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

  3. In the Data attributes category of the Property Inspector, click the tabularData attribute dropdown menu and select Expression Builder.

  4. From the ensuing dialog, use the search box to locate the managed bean.

  5. Expand the managed bean node and select the method that contains the list of tabular data.

  6. Click OK.

In the Expression Builder, the tabularData attribute is set to reference the method that you selected in the managed bean. For example, for a managed bean named named sampleGraph and a method named getTabularData, the tabularData attribute has the following setting: #(sampleGraph.tabularData).

23.4.2 What Happens When You Create a Graph Using Tabular Data

When you create a graph that is powered by data obtained from a list referenced the tabulularData attribute a vertical clustered bar graph is created by default. You have the option of changing the settings of the graphType attribute to any of the more than 50 graphs that are available as long as the tabular data meets the data requirements for that graph type. You can also change the settings of the many addtional attributes on the dvt:graph tag.

Customize the graph by dragging any of the graph child tags to the dvt:graph node in the Structure window and providing settings for the attributes that you want to specify.

23.5 Customizing Common Graph Features

Most ADF graph types have common features that are available for customization. The following types of customization are supported by most graph types:

Declarative means for supporting the majority of these customizations are available.

23.5.1 Changing the Color and Style of Graph Bars, Lines, Areas, Points, and Slices

For most graph types, an entry appears in the legend for each set of data values. This entry identifies a set of related data values and displays the color that represents the set in the graph. For example, a sample bar graph might use yellow bars to represent the sales of shoes and green bars to represent the sales of boots. The graph component refers to each set of related data values as a series.

The graph automatically assigns a different color to each set of data points. You can customize the colors assigned to each series, including the fill color and the border color. You can also specify additional characteristics for specific graph types such as the width and style of lines in a line graph (choices include solid lines, dotted lines, lines with dashes, and so on).

Note:

You can also customize the colors of each series in a graph by adding gradient special effects. For more information, see Section 23.7.2, "Using Gradient Special Effects in Graphs".

23.5.1.1 How to Specify the Color and Style for Individual Series Items

Use one dvt:seriesSet tag to wrap all the individual dvt:series tags for a graph.

To specify the color and style for series items in a graph:

  1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Series Set.

  2. Optionally use the Property Inspector to specify values for attributes of the dvt:seriesSet tag.

    The attributes of this tag determine default settings for all series tags in the set. However, you can override these settings for a given series by entering values in the corresponding attributes of a dvt:series tag.

  3. In the Structure window, right-click the seriesSet node and select Insert inside dvt:seriesSet, then Series.

    The first dvt:series tag represents the first series item that appears in the Create Graph Binding dialog.

  4. Use the Property Inspector to specify colors and other characteristics as needed for the dvt:series tag.

  5. Repeat Step 3 and Step 4 for each series item.

23.5.1.2 How to Control the Number of Different Colors Used for Series Items

The graph stores separate properties (such as color) for a specific number of series. Beyond that number, the graph repeats series properties. By default, a graph allows up to 30 different series items for which it displays separate properties.

The value in the seriesObjectCount attribute of the graph determines the number of series before properties are repeated. If seriesObjectCount is set to the value 4, then series 5 has the same properties as series 1, series 6 has the same properties as series 2, and so on.

To control the number of different colors used for series items:

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

  2. In the Appearance attributes category, specify a zero-based value for the seriesObjectCount attribute of the graph.

23.5.2 Formatting Numbers in Graphs

Use the dvt:numberFormat tag to specify formatting for numeric values related to any of the following graph tags:

  • dvt:sliceLabel

  • dvt:stockVolumeFormat

  • dvt:x1Axis

  • dvt:x1Format

  • dvt:y1Axis

  • dvt:y1Format

  • dvt:y2Axis

  • dvt:y2Format

  • dvt:zFormat

You can specify number formatting directly in the dvt:numberFormat tag or you can use the af:convertNumber tag as a child tag of dvt:numberFormat. The following sections provide an example of using each approach.

23.5.2.1 How to Format Numbers in the Y1-Axis of a Graph

You can use the af:convertNumber tag within dvt:numberFormat to format numbers in the Y1-Axis of a graph. In this example, the dvt:numberFormat tag is a child of dvt:y1Axis.

To format numbers in the Y1-axis of a graph:

  1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Y1 Axis.

  2. In the Property Inspector, optionally enter values for attributes of dvt:y1Axis.

  3. In the Structure window, right-click the dvt:y1Axis node and select Insert inside dvt:y1Axis, then Number Format.

  4. In the Structure window, right-click the dvt:y1Axis node and select Insert inside dvt:y1Axis, then af:convertNumber.

  5. In the Property Inspector, specify values as needed for the attributes of the af:convertNumber tag.

23.5.2.2 What Happens When You Format the Numbers in the Y1-Axis of a Graph

Example 23-4 shows the XML code that is generated if you format the numbers in the Y1-Axis of a graph to appear as currency, and using the dollar sign symbol.

Example 23-4 Formatting the Numbers in the Y1-Axis of a Graph

<graph>
   <dvt:y1Axis lineColor="#00000" axisMinValue="0.0"   axisMaxValue="60.0">
     <dvt:numberFormat>
         <af:convertNumber type="currency" currencySymbol="$"/>
      </dvt:numberFormat>
   </dvt:y1Axis>
</graph>

23.5.2.3 How to Format Numbers for the Marker Text of a Graph

You can use the dvt:numberFormat tag directly to format numbers in the marker text of a graph. The attributes of this tag let you format percents, scale numbers, control the number of decimal places, placement of signs, and so on.

You can provide different formatting for the marker text of each axis in the graph. In this procedure, the dvt:numberFormat tag is used to format the marker text on dvt:y1-axis.

To format numbers for the marker text in the y1-axis of a graph:

  1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Marker Text.

  2. In the Property Inspector, optionally enter values for attributes of dvt:markerText.

  3. In the Structure window, right-click the dvt:markerText node and select Insert inside dvt:markerText, then Y1 Format.

  4. In the Property Inspector, optionally enter values as needed for the dvt:y1Format attributes.

  5. In the Structure window, right-click the dvt:y1Format node and select Insert inside dvt:y1Format, then Number Format.

  6. In the Property Inspector, specify values as needed for the attributes of the dvt:numberFormat tag.

23.5.2.4 What Happens When You Format Numbers in the Marker Text of a Graph

Example 23-5 shows the XML code that is generated when you format the numbers in the marker text for the y1-axis of a graph. This example specifies that numbers should be followed by a sign and that the text will appear above the markers. For example, in a bar graph, the text will appear above the bars.

Example 23-5 Formatting Numbers in Graph Marker Text

<dvt:barGraph>
   <dvt:markerText visible="true" markerTextPlace="MTP_OUTSIDE_MAX">
      <dvt:y1Format>
         <dvt:numberFormat posNumFmt="POS_NUMFMT_NUM_POS"/>
      </dvt:y1Format>
   </dvt:markerText>
</dvt:barGraph>

23.5.3 Formatting Text in Graphs

You can format text in any of the following subcomponents of a graph:

  • Annotation: Includes only the dvt:annotation tag.

  • Axis title: Includes the dvt:o1Title, dvt:x1Title, dvt:y1Title, and dvt:y2Title tags.

  • Axis tick label: Includes the dvt:o1TickLabel, dvt:x1TickLabel, dvt:y1TickLabel, and dvt:y2TickLabel tags.

  • Graph title: Includes the dvt:graphFootnote, dvt:graphSubtitle, and dvt:graphTitle tags.

  • Legend: Includes only the dvt:legendText tag.

  • Marker: Includes only the dvt:markerText tag.

Use the dvt:graphFont tag as a child of the specific subcomponent for which you want to format text. For an example of formatting text in graph, see Section 23.5.5.2, "How to Specify Titles and Footnotes in a Graph".

23.5.4 Changing Graph Size and Style

You can customize the width and height of a graph and you can allow for dynamic resizing of a graph based on changes to the size of its container. You can also control the style sheet used by a graph. These two aspects of a graph are interrelated in that they share the use of the graph inlineStyle attribute.

23.5.4.1 How to Specify the Size of a Graph at Initial Display

You can specify the initial size of a graph by setting values for attributes of the dvt:<type>Graph tag. If you do not also provide for dynamic resizing of the graph, then the initial size becomes the only display size for the graph.

To specify the size of a graph at its initial display:

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

  2. In the Style attributes category of the Property Inspector, enter a value for the inlineStyle attribute of the graph tag. For example:

    inlineStyle="width:200px;height:200px"
    

23.5.4.2 How to Provide for Dynamic Resizing of a Graph

You must enter values in each of two attributes of the dvt:<type>Graph tag to allow for a graph to resize when its container in a JSF page changes in size. The values that you specify for this capability also are useful for creating a graph component that fills an area across different browser window sizes.

To allow dynamic resizing of a graph:

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

  2. In the Behavior attributes category of the Property Inspector for the DynamicResize attribute, select the value DYNAMIC_SIZE.

  3. In the Style attributes category of the Property Inspector for theInlineStyle attribute, enter a fixed number of pixels or a relative percent for both width and height.

    For example, to create a graph that fills its container's width and has a height of 200 pixels, use the following setting for the inlineStyle attribute: "width:100%;height:200px;".

23.5.4.3 How to Use a Specific Style Sheet for a Graph

You have the option of selecting any of the standard styles available for the dvt:<type>Graph tag. You can also specify a custom style sheet for use with a graph.

To select a specific style sheet for a graph:

  1. If you want to use one of the standard style sheets provided with the graph, do the following:

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

    2. In the Appearance attributes category, select the desired style sheet from the style attribute dropdown list.

  2. If you want to use a custom style sheet, then set the following attributes in the Style attributes category of the Property Inspector:

    1. For the StyleClass attribute, select Edit from the Property menu choices, and select the CSS style class to use for this gauge.

    2. In the InlineStyle attribute, enter a fixed number of pixels or a relative percent for both width and height.

      For example, to create a graph that fills its container's width and has a height of 200 pixels, use the following setting for the inlineStyle attribute: "width:100%;height:200px;"

23.5.5 Changing Graph Background, Plot Area, and Title

The graph automatically provides default settings for its background and plot area based on the style it is using. You can customize these settings using child tags of the graph.

The graph also provides title, subtitle, and footnote options that you can specify. By default, no text is provided for titles and footnotes. When you enter this information, you can also specify the font and font characteristics that you want to use for the text.

23.5.5.1 How to Customize the Background and Plot Area of a Graph

You can customize the following parts of graphs related to background and plot area:

  • Background: The area on which the graph is plotted.

  • Plot area: A frame in which data is plotted for all graphs other than pie graphs. Axes are displayed on at least two borders of the plot area.

  • Pie frame: A frame in which pie graphs are plotted without the use of axes.

To customize the background and plot area of a graph:

  1. If you want to customize the background of a graph, then do the following:

    1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Background.

    2. Use the Property Inspector to enter colors in the attributes that you want to customize in the dvt:background tag.

  2. If you want to customize the plot area of any graph other than a pie graph, then do the following:

    1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Plot Area.

    2. Use the Property Inspector to enter colors in the attributes that you want to customize in the dvt:graphPlotArea tag.

  3. If you want to customize the plot area of a pie graph, then do the following:

    1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Pie Frame.

    2. Use the Property Inspector to enter colors in the attributes that you want to customize in the dvt:graphPieFrame tag.

Note:

You can also customize the colors of the background and plot area in a graph by adding gradient special effects. For more information, see Section 23.7.2, "Using Gradient Special Effects in Graphs".

23.5.5.2 How to Specify Titles and Footnotes in a Graph

You have the option of specifying a title, subtitle, and footnote for a graph. You use a separate child tag of the graph for each of these text entries. The attributes of each of these child tags let you define the horizontal alignment of the text field, the text content, and whether or not the text should be rendered.

The tags for title, subtitle, and footnote support the use of a child graph font tag to let you identify the exact font characteristics to be used for each text field.

To specify titles and a footnote for a graph:

  1. If you want to enter a graph title, then do the following:

    1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Graph Title.

    2. Use the Property Inspector to specify values in the attributes of the dvt:graphTitle tag.

    3. If you want to provide specific font characteristics for the text, then in the Structure window, right-click the dvt:graphTitle node and select Insert inside dvt:graphTitle, then Font.

    4. Use the Property Inspector to specify values for the attributes of the dvt:graphFont tag.

  2. If you want to enter a graph subtitle, then do the following:

    1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Subtitle.

    2. Use the Property Inspector to specify values in the attributes of the dvt:graphSubtitle tag.

    3. If you want to provide specific font characteristics for the text, then in the Structure window, right-click the dvt:graphSubtitle node and select Insert inside dvt:graphSubtitle, then Font.

    4. Use the Property Inspector to specify values for the attributes of the dvt:graphFont tag.

  3. If you want to enter a graph footnote, then do the following:

    1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Footnote.

    2. Use the Property Inspector to specify values in the attributes of the dvt:graphFootnote tag.

    3. If you want to provide specific font characteristics for the text, then in the Structure window, right-click the dvt:graphFootnote node and select Insert inside dvt:graphFootnote, then Font.

    4. Use the Property Inspector to specify values for the attributes of the dvt:graphFont tag.

23.5.6 Customizing Graph Axes and Labels

Graphs can have the following axes:

  • Ordinal axis (also known as the o1-axis): The ordinal (or category) axis of a graph shows ordered data, such as ratings or stages, or shows nominal data, such as different cities or different products. The ordinal axis appears on bar, line, area, combination, or radar graphs. When the ordinal axis is horizontal and contains time data, it is called a time axis.

    An example of an ordinal axis is the horizontal line across the bottom of the plot area of a vertical bar graph. The values along this axis do not identify the extent of the data shown. Instead, they identify the different groups to which the data belongs.

  • x1-axis: The x1-axis shows the values that appear along the horizontal axis in a graph. This axis has regular intervals of numbers instead of group labels. It is referred to as the x-axis.

  • y1-axis: The y1-axis is the primary y-axis. It is usually the vertical value axis along the left side of the plot area. It has regular intervals of numbers.

  • y2-axis: The y2-axis is the secondary y-axis. It is usually the vertical axis along the right side of the plot area. It has regular intervals of numbers.

For each axis, there are several graph child tags that support customization. The following sections discuss the options available for various kinds of customization of an axis.

23.5.6.1 How to Specify the Title, Appearance, and Scaling of an Axis

The following graph child tags support customization of the title, and appearance of an axis:

  • Title: Specifies the text and alignment for an axis title. Includes the following tags: dvt:o1Title, dvt:x1Title, dvt:y1Title, and dvt:y2Title. An axis does not show a title unless you use the appropriate title tag.

  • Axis: Controls the color, line width, scaling, increment between tick marks, and visibility of the axis. Includes the following tags: dvt:o1Axis, dvt:x1Axis, dvt:y1Axis, dvt:y2Axis.

    Note:

    Scaling attributes are not present on the dvt:o1Axis tag because the ordinal axis does not display numeric values.

To specify the title and appearance of an x1-axis:

  1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then X1 Title.

  2. In the Property Inspector, enter the text for the axis title and optionally specify values for other attributes of this tag.

  3. If you want to specify font characteristics for the title, then do the following:

    1. In the Structure window, right-click the dvt:x1Title node and select Insert inside dvt:x1Title, then Font.

    2. In the Property Inspector, enter the desired values for the characteristics of the font.

  4. Optionally, in the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then X1 Axis.

  5. In the Property Inspector, enter the desired values for the attributes of this tag.

The procedure for controlling the title and appearance of any graph axis is similar to the procedure for the x-axis. However, insert the title and axis tags related to the specific axis that you want to customize.

23.5.6.2 How to Control the Appearance of Tick Marks and Labels on an Axis

Tick marks are used to indicate specific values along a scale on a graph. The following graph child tags support customization of the tick marks and their labels on an axis:

  • Major tick: Controls the color, width, and style of tick marks on the axis. Includes the following tags: dvt:o1MajorTick, dvt:x1MajorTick, dvt:y1MajorTick, and dvt:y2MajorTick.

  • Tick label: Controls the rotation of tick label text and lets you specify font characteristics for the label. Includes the following tags: dvt:o1TickLabel, dvt:x1TickLabel, dvt:y1TickLabel, and dvt:y2TickLabel. These tags can also have a dvt:graphFont child tag to change font characteristics of the label.

To control the appearance of tick marks and tick labels on an x-axis:

  1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then X1 Major Tick.

  2. In the Property Inspector, enter desired values for the attributes of this tag.

  3. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then X1 Tick Label.

  4. In the Property Inspector, enter desired values for the attributes of tick label.

  5. If you want to specify font characteristics for the tick label, do the following:

    1. In the Structure window, right-click the dvt:x1TickLabel node and select Insert inside dvt:x1TickLabel, then Font.

    2. In the Property Inspector, enter desired values for the characteristics of the font.

The procedure for controlling the appearance of tick marks on any graph axis is similar to the procedure for the x-axis. However, you insert the major tick and tick label tags related to the specific axis that you want to customize.

23.5.6.3 How to Format Numbers on an Axis

The dvt:markerText tag lets you to control the format of numbers on an axis. The following dvt:markerText child tags wrap the number format for specific axes: dvt:x1Format, dvt:y1Format, and dvt:y2Format.

Note:

There is no format for the ordinal axis because that axis does not contain numeric values.

To format numbers on these axes, insert child tags for the appropriate axis as shown in Section 23.5.2, "Formatting Numbers in Graphs".

23.5.6.4 How to Set the Starting Value of a Y-Axis

The y-axes have the following graph child tags to support the starting value of the axis: dvt:y1BaseLine, and dvt:y2BaseLine. You have the option of specifying different scaling on each y-axis in a dual y-axis graph. For example, the y1-axis might represent units (in hundreds) while the y2-axis might represent sales (in thousands of dollars).

To specify the starting value on a y2-axis:

  1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Y2 Base Line.

  2. In the Property Inspector, for the Axis Min Value attribute, enter the starting value for the y2-axis.

To establish the starting value on a y-axis, use a similar procedure, but insert the dvt:y1BaseLine tag as a child of the graph.

23.5.7 Customizing Graph Legends

ADF Graph components provide child tags for the following kinds of customization for the legend:

  • Specifying the color, border, visibility, and positioning of the legend area relative to the graph, dvt:legendArea tag.

  • Specifying the font characteristics and positioning of the text that is related to each colored entry in the legend, dvt:legendText tag.

  • Specifying an optional title and font characteristics for the legend area, dvt:legendTitle tag.

To customize the legend area, legend text, and title:

  1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Legend Area.

  2. Use the Property Inspector to specify values for the attributes of this tag.

  3. If you want to customize the legend text, then do the following:

    1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Legend Text.

    2. Use the Property Inspector to enter values for the attributes of this tag.

    3. Right-click the dvt:legendText node and select Insert inside dvt:legendText, then Font.

    4. Use the Property Inspector to specify values for the attributes of the font tag.

  4. If you want to enter a title for the legend, then do the following:

    1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Legend Title.

    2. Use the Property Inspector to enter values for the attributes of this tag.

    3. Right-click the dvt:legendTitle node and select Insert inside dvt:legendTitle, then Font.

    4. Use the Property Inspector to specify values for the attributes of the font tag.

23.5.8 Customizing Tooltips in Graphs

The following graph attributes are available for customizing graph tooltips:

  • markerTooltipType: Specifies if tooltips are displayed for markers (such as bars) and identifies the kind of information that appears in the tooltips. You have the option to display the following information: text only, values only, or text and values. For specific graph types, options include displaying cumulative data value for each stacked graph marker or displaying percentage data value for each pie slice marker.

  • seriesTooltipType: Specifies if tooltips are displayed for each set of values that appear in a legend. This attribute also controls the kind of information that appears in a series tooltip. For example, you could choose to display text that identifies a general term for the entire series (such as Product) or a specific term for a given member of the series (such as a specific Product name).

    Note:

    The graph displays series tooltip labels only if the graph's markerTooltipType attribute has a setting that includes text.
  • groupLabelType: Specifies if tooltip labels are displayed for data groups along an axis. For example, sales for specific products might be grouped by years or quarters. You can choose to display text that identifies a general term for the entire group (such as Time) or specific terms for each member of the group (such as Q1, Q2, Q3, or Q4 for quarters).

In most graphs, if you hover the cursor over a data marker, then a tooltip is displayed. In a line graph, you must hover the cursor over a data marker in the line graph and not merely over the line.

23.6 Customizing the Appearance of Specific Graph Types

The ADF graph components supports more than 50 graph types. Some of the graph attributes and several child tags relate only to specific graph types.

23.6.1 Changing the Type of ADF Graphs

When you insert a graph using the Data Controls Panel, the Component Gallery displays available graph categories, types, and quick-start layout options from which to choose. Selecting a graph type sets the subType attribute for that graph. You can change the type for all graphs except the funnel and radar graphs.

To change the type of a graph:

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

  2. In the Common attributes category of the Property Inspector, for the subType attribute, select the desired type from the attribute dropdown menu. The valid values will vary depending on the graph.

    For example the valid values for a bar graph are:

    • BAR_VERT_CLUST: Clustered bar graph that has a vertical orientation.

    • BAR_VERT_CLUST_SPLIT2Y: Clustered, vertical, split dual-Y bar graph.

    • BAR_VERT_CLUST2Y: Clustered, vertical, dual-Y bar graph.

    • BAR_VERT_FLOAT_STACK: Floating, vertical, stacked bar graph.

    • BAR_VERT_PERCENT: Percent, vertical bar graph.

    • BAR_VERT_STACK: Stacked, vertical bar graph.

    • BAR_VERT_STACK_SPLIT2Y: Stacked, vertical, split dual-Y bar graph.

    • BAR_VERT_STACK2Y: Stacked, vertical, dual-Y bar graph.

23.6.2 Changing the Appearance of Pie Graphs

You can customize the appearance of pie graphs and you can specify that you want one slice of a pie to be separated from the other slices in the pie.

23.6.2.1 How to Customize the Overall Appearance of Pie Graphs

You can customize the appearance of a pie graph by inserting any of the following child tags within the graph tag:

  • dvt:pieFeeler tag: Specifies the color of an optional line (called a pie feeler) that extends from a pie slice to a slice label. If you do not specify this tag, then there will not be a line from a pie slice to a slice label.

  • dvt:slice tag: Specifies the location of a label for a pie slice.

  • dvt:sliceLabel tag: Specifies the characteristics of the labels that describe each slice of a pie or ring graph. Each slice represents a data value. Use the textType attribute of this tag to indicate whether the slice label should show text only, value only, percent only, or text and percent. If you want to format numbers or specify font characteristics, you can add the following tags within the dvt:sliceLabel tag: dvt:graphFont and dvt:numberFormat.

23.6.2.2 How to Specify an Exploding Pie Slice

When one slice is separated from the other slices in a pie, this display is referred to as an exploding pie slice. The reason for separating one slice is to highlight that slice possibly as having the highest value of the quantity being measured in the graph.

The slices of a pie graph are the sets of data that are represented in the graph legend. As such, the slices are the series items of a pie graph.

To separate one slice from a pie graph:

  1. Follow the procedure in Section 23.5.1.1, "How to Specify the Color and Style for Individual Series Items" to create a series set that wraps individual series items.

  2. In the Property Inspector, for the series tag that represents the pie slice that you want to separate from the pie, set the PieSliceExplode attribute between 0 to 100, where 100 is the maximum exploded distance available.

23.6.3 Changing the Appearance of Line Graphs

You can use attributes of the graph tag and attributes of the series tag to change the appearance of lines in a line graph.

23.6.3.1 How to Display Either Data Lines or Markers in a Line Graph

You have the option of displaying data lines or data markers in a line graph. If you display markers rather than data lines, then the markers appear in the legend automatically. The following attributes of the dvt:lineGraph tag relate to this option:

  • lineDataLineDisplayed: Specifies if data lines appear in a line graph. The following values apply:

    • True indicates that data lines are displayed in the graph.

    • False indicates that markers are displayed in a line graph rather than data lines.

  • markerDisplayed: Specifies whether markers or data lines appear in a line graph. The following values apply:

    • True indicates that markers are displayed in a line graph.

    • False indicates that data lines are displayed in a line graph.

Note:

For a line graph, do not set both the lineDataLineDisplayed attribute and the markerDisplayed attribute to False.

23.6.3.2 How to Change the Appearance of Lines in a Graph Series

You can customize the appearance of lines by using the dvt:seriesSet tag and the dvt:series tag as described in the following list:

  • On the dvt:seriesSet tag, you can affect all the dvt:series tags within that set by specifying values for the following attributes:

    • defaultMarkerShape: Used only for line, scatter, and combination graphs. Identifies a default marker shape for all the series in the series set.

    • defaultMarkerType: Used only for combination graphs. Valid values include MT_AREA, MT_BAR, MT_MARKER, and MT_DEFAULT.

  • On the dvt:series tag, you can specify settings for each individual series using the following line attributes:

    • lineWidth: Specifies the width of a line in pixels

    • lineStyle: Specifies whether you want the graph to use solid lines, dotted lines, dashed lines, or dash-dot combination lines.

See the procedures in Section 23.5.1.1, "How to Specify the Color and Style for Individual Series Items" for more information about using the dvt:seriesSet tag and the dvt:series tag.

23.6.4 Customizing Pareto Graphs

A Pareto graph identifies the sources of defects using a series of bars. The bars are arranged by value, from the greatest to the lowest number. The Pareto line shows the percentage of cumulative values of the bars, to the total values of all the bars in the graph. The line always ends at 100 percent.

You can customize the Pareto line and the Pareto marker by using the following graph child tags:

  • dvt:ParetoLine tag: Lets you specify the color, line width, and line style (such as solid, dashed, dotted, or a combination of dash-dot).

  • dvt:paretoMarker tag: Lets you specify the shape of the Pareto markers.

To customize a Pareto graph:

  1. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Pareto Line.

  2. In the Property Inspector, specify values for the attributes of this tag.

  3. In the Structure window, right-click the graph node and select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Pareto Marker.

  4. In the Property Inspector, select a value for the markerShape attribute.

23.7 Adding Specialized Features to Graphs

The focus of this section is graph customization that takes advantage of special features that are not used as frequently as the common features described in Section 23.5.

The special features include the ability to define series-related reference lines and axis-related reference areas, the option of adding gradient special effects to several parts of a graph, the option of setting some parts of a graph to transparent colors, and the use of alerts and annotations in graphs. These special features also let you use interactive capabilities of the graph.

23.7.1 Adding Reference Lines or Areas to Graphs

You can create reference lines that are associated with a series (that is a set of data values that appears as a single color in the graph legend). If there are multiple series with reference lines, then the reference lines show only when you move the cursor over a series marker or the corresponding series legend item. This is because multiple reference lines can be confusing to users.

You can also create reference areas that are associated with an axis. Typically, these areas are associated with a y-axis. If there are multiple reference areas, then these areas are also displayed when you move the cursor over the related axis.

If your application does not know how many reference lines or areas it will need until it is running, then you can create reference lines or areas dynamically at runtime.

23.7.1.1 How to Create Reference Lines or Areas During Design

Both reference lines and reference areas are created by the use of the following tags:

  • dvt:referenceObjectSet: Wraps all the reference object tags for reference lines or reference areas for this graph.

  • dvt:referenceObject: Identifies whether the tag represents a reference line or a reference area and specifies characteristics for the tag.

To add reference lines or areas to a graph during design:

  1. In the Structure window, right-click the graph node, then select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Reference Object Set.

  2. If you are creating reference objects during design, then you do not set attributes for the dvt:referenceObjectSet tag.

  3. In the Structure window, right-click the dvt:referenceObjectSet node and select Insert inside dvt:referenceObjectSet, then Reference Object.

  4. In the Property Inspector, do the following:

    1. In the Common attributes category, specify values for the index attribute of the reference object, the type attribute of the reference object (RO_LINE or RO_AREA), the associated object in the association attribute (a series for a reference line or a specific axis for a reference area). Also specify if the object should be displayed in the legend using the displayedInLegend attribute, and specify the text, if any, to display in the legend.

    2. If you are creating a reference line, then specify values for the attributes related to the line. This includes specifying the series number of the series to which the line is related. The series number refers to the sequence in which the series appear in the Graph data binding dialog.

    3. If you are creating a reference area, then specify the low value and the high value that represent the reference area on the specified axis.

  5. In the Structure window, right-click the graph node and select Go To Properties.

  6. In the Property Inspector, select the Appearance attributes category and do the following to control the display of reference lines and reference areas:

    1. If you have defined reference lines (which must be related to a series), then expand the dvt:series node and specify a value for the behavior of the seriesReferenceObjectDisplay attribute.

      The value RO_DISPLAY_AUTOMATIC enables the display of a reference line only when the cursor moves over a series item (such as a bar) or over the corresponding series entry in the graph legend. This choice prevents the confusion that might occur if multiple series reference lines were displayed all the time.

    2. If you have defined reference areas (which must be related to specific axes), then specify a value for the appropriate axis or axes attributes: X1ReferenceObjectDisplay, Y1ReferenceObjectDisplay, or Y2ReferenceObjectDisplay.

      The value RO_DISPLAY_AUTOMATIC enables the display of a reference area only when the mouse moves over the related axis. This choice prevents the confusion that might occur if multiple reference areas were displayed all the time.

23.7.1.2 What Happens When You Create Reference Lines or Areas During Design

When you create reference lines or areas during design, XML code is generated within the graph XML on the JSF page. The reference objects (both lines and areas) are wrapped by the dvt:referenceObjectSet tags. Example 23-6 shows the code for three reference areas associated with the y1-axis, one reference area associated with the y2-axis, and four reference lines associated with different series.

Example 23-6 XML Code for Reference Lines and Areas in a Graph

<dvt:barGraph value ="#{sampleGraph.graphDataModel}" graphType="BAR_VERT_CLUST2Y"
     imageFormat="FLASH"
     y1ReferenceObjectDisplay="RO_DISPLAY_AUTOMATIC" 
     y2ReferenceObjectDisplay="RO_DISPLAY_AUTOMATIC" 
     seriesReferenceObjectDisplay="RO_DISPLAY_AUTOMATIC">
 <dvt:referenceObjectSet>
   <dvt:referenceObject index="1" type="RO_AREA" association="Y1AXIS" 
     location="RO_BACK" color="#55FF0000" lowValue="0" highValue="4000"/>
    <dvt:referenceObject index="2" type="RO_AREA" association="Y1AXIS" 
      location="RO_BACK" color="#55FFFF00"  lowValue="4000" highValue="10000"/>
    <dvt:referenceObject index="3" type="RO_AREA" association="Y1AXIS" 
      location="RO_BACK" color="#5500FF00"  lowValue="10000" highValue="18000"/>
    <dvt:referenceObject index="4" type="RO_AREA" association="Y2AXIS" 
      location="RO_FRONT" color="#550000FF" lowValue="300" highValue="700"/>
    <dvt:referenceObject index="5" type="RO_LINE" association="SERIES" series="0" 
      location="RO_FRONT" color="#ffff66" lineValue="5000" lineWidth="3" 
      lineStyle="LS_SOLID"/>
    <dvt:referenceObject index="6" type="RO_LINE" association="SERIES" series="0" 
      location="RO_FRONT" color="#ffff66" lineValue="16730" lineWidth="3"
      lineStyle="LS_SOLID"/>
    <dvt:referenceObject index="7" type="RO_LINE" association="SERIES" series="1" 
      location="RO_BACK" color="#99cc66" lineValue="500" lineWidth="3"
      lineStyle="LS_SOLID"/>
    <dvt:referenceObject index="8" type="RO_LINE" association="SERIES" series="1" 
      location="RO_BACK" color="#99cc66" lineValue="1711" lineWidth="3"
      lineStyle="LS_SOLID"/>
  </dvt:referenceObjectSet>
</dvt:barGraph>

23.7.1.3 How to Create Reference Lines or Areas Dynamically

If you want to create reference objects dynamically at runtime, then you use only the dvt:referenceObjectSet tag. You set the referenceObjectMap attribute on this tag with a method reference to the code that creates a map of the child component reference objects. The method that creates this map must be stored in a managed bean.

To create reference lines or areas dynamically:

  1. Write a method that creates a map of the child component reference objects that you want to create during runtime.

    Example 23-7 shows sample code for creating this method.

  2. In the Structure window, right-click the graph node, then select Insert inside dvt:<type>Graph, then ADF Data Visualization, then Reference Object Set.

  3. In the Property Inspector, specify in the referenceObjectMap attribute a method reference to the code that creates the map of child component reference objects.

    For example, for the managed bean (sampleGraph) and the method getReferenceObjectMapList, the attribute should be set to the following value: referenceObjectMap="#{sampleGraph.referenceObjectMapList}"

Example 23-7 Code for a Map of Child Reference Objects

Managed bean SampleGraph.java : 
   public Map getReferenceObjectMapList() { 
     HashMap map = new HashMap(); 
     ReferenceObject referenceObject = new ReferenceObject(); 
     referenceObject.setIndex(1); 
     referenceObject.setColor(Color.red); 
     referenceObject.setLineValue(30); 
     referenceObject.setLineWidth(3); 
     map.put(new Integer(1), referenceObject); 
     return map;
    } 

23.7.2 Using Gradient Special Effects in Graphs

A gradient is a special effect in which an object changes color gradually. Each color in a gradient is represented by a stop. The first stop is stop 0, the second is stop 1, and so on. By default, a gradient has three stops. However, you have the option of specifying any number of stops in the special effects for a subcomponent of a graph that supports special effects.

You can define gradient special effects for the following subcomponents of a graph:

  • Graph background: Use the dvt:background tag.

  • Graph plot area: Use the dvt:graphPlotArea tag.

  • Graph pie frame: Use the dvt:graphPieFrame tag.

  • Legend area: Use the dvt:legendArea tag.

  • Series: Use the dvt:series tag.

  • Time selector: Use the dvt:timeSelector tag.

The approach that you use to define gradient special effects is identical for each part of the graph that supports these effects.

23.7.2.1 How to Add Gradient Special Effects to a Graph

For each subcomponent of a graph to which you want to add special effects, you must insert a dvt:specialEffects tag as a child tag of the subcomponent. For example, if you want to add a gradient to the background of a graph, then you would create one dvt:specialEffects tag that is a child of the dvt:background tag.

Then, optionally if you want to control the rate of change for the fill color of the subcomponent, you would insert as many dvt:gradientStopStyle tags as you need to control the color and rate of change for the fill color of the component. These dvt:gradientStopStyle tags then must be inserted as child tags of the single dvt:specialEffects tag.

To add a gradient special effect to the background of a graph:

  1. In the Structure window, right-click the dvt:background node that is a child of the graph node, then select Insert inside dvt:background, then Special Effects.

  2. Use the Property Inspector to enter values for the attributes of the dvt:specialEffects tag:

    1. For the gradientDirection attribute, select the direction of change that you want to use for the gradient fill.

    2. For the numStops attribute, no entry is needed if you use dvt:gradientStopStyle tags to identify each stop.

      If you do not enter a tag for each gradient stop, then three stops are used by default. Enter a value only if you want to use a different number of stops.

  3. Optionally, in the Structure window, right-click the dvt:specialEffects node and select Insert within dvt:specialEffects, then dvt:gradientStopStyle if you want to control the color and rate of change for each gradient stop.

  4. Use the Property Inspector to enter values for the attributes of the dvt:gradientStopStyle tag:

    1. For the stopIndex attribute, enter a zero-based integer as an index within the dvt:gradientStopStyle tags that are included within the specialEffects tag.

    2. For the gradientStopColor attribute, enter the color that you want to use at this specific point along the gradient.

    3. For the gradientStopPosition attribute, enter the proportional distance along a gradient for the identified stop color. The gradient is scaled from 0 to 100. If 0 or 100 is not specified, default positions are used for those points.

  5. Repeat Step 3 and Step 4 for each gradient stop that you want to specify.

23.7.2.2 What Happens When You Add a Gradient Special Effect to a Graph

Example 23-8 shows the XML code that is generated when you add a gradient fill to the background of a graph and specify two stops.

Example 23-8 XML Code Generated for Adding a Gradient to the Background of a Graph

<dvt:graph >
   <dvt:background borderColor="#848284">
     <dvt:specialEffects fillType="FT_GRADIENT" gradientDirection="GD_RADIAL">
         <dvt:gradientStopStyle stopIndex="0" gradientStopPosition="60"
             gradientStopColor="FFFFCC"/>
         <dvt:gradientStopStyle stopIndex="1" gradientStopPosition="90"
             gradientStopColor="FFFF99"/>
     </dvt:specialEffects> 
   </dvt:background>
</dvt:graph>

23.7.3 Specifying Transparent Colors for Parts of a Graph

You can specify that various parts of a graph show transparent colors by setting the borderTransparent and fillTransparent attributes on the graph child tags related to these parts of the graph. The following list identifies the parts of the graph that support transparency:

  • Graph legend area: Use the dvt:legendArea tag.

  • Graph pie frame: Use the dvt:graphPieFrame tag.

  • Graph plot area: Use the dvt:graphPlotArea tag.

23.7.4 Providing Interactive Capability for Graphs

You can add a number of interactive functions to ADF graphs including:

  • Line and legend highlighting

  • Hide and show sets of markers

  • Zoom- and scroll-level changes

23.7.4.1 How to Provide Line and Legend Highlighting

You can force all the data markers for a given set of data to be highlighted when you move the cursor over one data marker in the set or over the corresponding entry in the graph legend. For example, if a bar graph displays sales by month for four products (P1, P2, P3, P4), then when you move the cursor over product P2 in January, all the P2 bars are highlighted.

Because the graph refers to all the data markers in a given set of data (such as all the P2 bars) as a series, then the ability to highlight the data markers in a series is part of the graph's series rollover behavior feature.

You can also force all the similar data markers for a given set of data to be dimmed when you move the cursor over one data marker in the set. For example, if a bar graph displays sales by month for four products (P1, P2, P3, P4), then when you move the cursor over product P2 in January, all the P2 bars are dimmed. This feature is also part of the graph's series rollover behavior feature.

Series rollover behavior is available only in the following graph types: bar, line, area, pie, scatter, polar, radar, and bubble graphs.

To highlight or dim all the data markers in a series:

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

  2. In the Appearance attributes category, expand the dvt:series node.

  3. In the seriesRolloverBehavior attribute, select the type of highlighting or dimming behavior that you desire when the cursor moves over a series data marker or when the cursor moves over the series item in the graph legend.

23.7.4.2 How to Hide or Show Sets of Related Markers

You can cause all the data markers of one or more sets of data values (also referred to as series of data) to be displayed or to be hidden from a time series axis in a graph. Each hidden series continues to be represented in the legend, but the legend icon appears hollow rather than solid. The graph's automatic scaling for the data axis will ignore hidden series. For this reason, hiding and re-showing a series can change the scaling of the data axis.

To hide or show a series on a time axis:

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

  2. In the Appearance attributes category, expand the dvt:series node.

  3. In the attribute, select the

23.7.4.3 How to React to Changes in the Zoom and Scroll Levels

You can provide custom code that will be executed when the zoom and scroll levels change on a graph.

To provide custom behavior in response to zooming and scrolling in a graph:

  1. In a managed bean, write a custom method that performs the desired behavior when a zoom or scroll event is triggered.

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

  3. Select the Behavior attributes category and expand the Advanced node.

  4. In the zoomAndScrollListener attribute, specify a reference to the method that you stored in the managed bean.

    For example, if the method setZoomAndScroll is stored in the managed bean SampleGraph, then the setting becomes: "#{sampleGraph.zoomAndScroll)".

23.7.5 Providing an Interactive Time Axis for Graphs

You can define relative ranges and explicit ranges for the display of time data.

23.7.5.1 How to Define a Relative Range of Time Data for Display

You can define a simple relative range of time data to be displayed, such as the last seven days. This will force old data to scroll off the left edge of the graph as new data points are added to the display of an active data graph. Relative time range specifications are not limited to use in active data graphs.

To specify a relative range of time data for display:

  1. In the Structure window, right click the graph node and select Go to Properties.

  2. In the Appearance attributes category, expand the dvt:timeAxis node and specify values for the following attributes:

    1. In the timeRangeMode attribute, specify the value TRM_RELATIVE_LAST or TRM_RELATIVE_FIRST depending on whether the relative range applies to the end of the time range (such as the last seven days) or to the beginning of the time range (such as the first seven days).

    2. In the relativeTimeRange attribute, specify the relative range in milliseconds.

23.7.5.2 How to Define an Explicit Range of Time Data for Display

You can define an explicit range of time data to be displayed, such as the period between March 15 and March 25. In this example, the year, hour, minute, and second use default values because they were not stated in the start and end values.

To specify an explicit range of time data for display:

  1. In the Structure window, right click the graph node and select Go to Properties.

  2. In the Appearance attributes category, expand the dvt:timeAxis node and specify values for the following attributes:

    1. In the timeRangeMode attribute, specify the value TRM_EXPLICIT.

    2. In the explicitTimeRangeStart attribute, enter the initial date for the time range.

    3. In the explicitTimeRangeEnd attribute, enter the ending date for the time range.