24 Using ADF Graph Components

24.3.13.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 with the except of candle stock graphs. 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.

24.3.13.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.

24.3.13.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.

24.3.13.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.

24.3.13.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.

24.3.13.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.

24.3.13.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.

24.3.13.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.

24.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.

24.4.1.1.3 Example of a List of Data

Figure 24-5 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 24-5 Comparison of Annual Sales

Example 24-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 24-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;
}

24.4.1.2 Creating a Graph Using Tabular Data

Use the tabularData attribute of a graph tag to reference data that is stored in a method in a managed bean.

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

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

2. In the Data attributes category of the Property Inspector, click the TabularData attribute dropdown menu and choose Expression Builder.

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

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

5. 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).

24.6.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 and set attributes for color and style of graph data markers.

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

1. In the Structure window, right-click the dvt:seriesSet child tag in the graph node, and choose Go to Properties.

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 choose Insert inside dvt:seriesSet > 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.

24.6.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 choose Go to Properties.

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

24.6.1.3 How to Enable Hiding and Showing Series Items

For graph types including area, bar, bubble, combination, line, pie, radar, and scatter, you can enable the hiding or showing of the series in a graph at runtime. Although at least one series must be displayed in the graph, users can filter the display of data values by clicking on the corresponding legend item.

To enable hiding and show series items:

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

2. In the Property Inspector, in the Series section of the Appearance attributes category, set the hideAndShowBehavior attribute of the graph. Valid values include:

   • none: Default value, no hide and show series behavior is enabled.

   • withRescale: Rescales the graph to show only the visible series.

   • withoutRescale: Hides the series, but does not rescale the graph.

24.6.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 sample procedure, 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 child dvt:y1Axis tag of the graph tag and choose Go to Properties.

2. In the Property Inspector, click the Configure Y1 Axis button and choose Number Values from the dropdown list.

3. In the Property Inspector for the dvt:formatNumber tag, specify values as needed.

4. In the Structure window, right-click the dvt:y1numberFormat tag and choose Insert inside dvt:numberFormat > af:convertNumber.

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

Example 24-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.

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

24.6.2.2 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:y1axis.

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 choose Insert inside dvt:<type>Graph > ADF Data Visualization > 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 choose Insert inside dvt:markerText > 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 choose Insert inside dvt:y1Format > Number Format.

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

Example 24-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.

<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>

24.6.3.1 How to Globally Set Graph Font Using a Skin

You can set the font attributes of graph components globally across all pages in your application by using a cascading style sheet (CSS) to build a skin, and configuring your application to use the skin. By applying a skin to define the fonts used in graph components, the pages in an application will be smaller and more organized, with a consistent style easily modified by changing the CSS file.

You can use the ADF Data Visualization Tools Skin Selectors to define the font styles for graph components. Graph component skin selectors include the following:

• af|dvt-graphFootnote

• af|dvt-graphSubtitle

• af|dvt-graphTitle

• af|dvt-o1Title

• af|dvt-x1Title

• af|dvt-y1Title

• af|dvt-y2Title

• af|dvt-pieLabel

• af|dvt-legendTitle

• af|dvt-legendText

• af|dvt-markerText

• af|dvt-o1TickLabel

• af|dvt-x1TickLabel

• af|dvt-y1TickLabel

• af|dvt-y2TickLabel

• af|dvt-annotation

• af|dvt-sliceLabel

• af|dvt-tooltips

To use a custom skin to set graph fonts:

1. Add a custom skin to your application containing the defined skin style selectors for the graph subcomponents. You can specify values for the following attributes:

   • -tr-font-family: Specifies the font family (name). It may not contain more than one font. If multiple fonts are specified, the first font will be used.

   • -tr-font-size: Specifies the size of the font.

   • -tr-font-style: Specifies the style of the font. Valid values are normal or italic.

   • -tr-font-weight: Specifies the weight of the font. Valid values are normal or bold.

   • -tr-text-decoration: Specifies whether or not the underline emphasis is rendered. Valid values are none or underline.

   • -tr-color: Specifies the color of the font. Valid values are color names for HTML and CSS, 3 or 6 digits HEX, RGB (or RGBA).

   For example, specify the font family for all graph titles in a mySkin.css file as follows:

   af|dvt-graphTitle,
   {
     -tr-font-family: Comic Sans MS:
   }
   

2. Register the custom skin with the application in the trinidad-skins.xml file. For example, mySkin.css extends the default blafplus-rich.desktop style sheet:

   <?xml version="1.0" encoding="ISO-8859-1"?>
   <skins xmlns="http://myfaces.apache.org/trinidad/skin">
     <skin>
       <id>mySkinExtends.desktop</id>
       <family>mySkinExtends</family>
       <extends>blafplus-rich.desktop</extends>
       <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
       <style-sheet-name>skins/mySkin.css</style-sheet-name>
     </skin>
   </skins>
   

3. Configure the application to use the custom skin in the trinidad-config.xml file. For example:

   <trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
     <skin-family>mySkin</skin-family>
   </trinidad-config>
   

4. Package the custom skin into a jar file to deploy with the application. The trinidad-skins.xml file that defines the skin and that references the CSS file must be within the META-INF directory.

For detailed information about applying a custom skin to applications, see Chapter 20, "Customizing the Appearance Using Styles and Skins."

24.6.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 choose 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"
   

24.6.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 choose 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 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;".

24.6.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 choose 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;"

24.6.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, do the following:

   1. In the Structure window, right-click the graph node and choose Insert inside dvt:<type>Graph > ADF Data Visualization > 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, do the following:

   1. In the Structure window, right-click the graph node and choose Insert inside dvt:<type>Graph > ADF Data Visualization > 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, do the following:

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

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

24.6.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, do the following:

   1. In the Structure window, right-click the graph node and choose Insert inside dvt:<type>Graph > ADF Data Visualization > 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 choose Insert inside dvt:graphTitle > 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, do the following:

   1. In the Structure window, right-click the graph node and choose Insert inside dvt:<type>Graph > ADF Data Visualization > 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, in the Structure window, right-click the dvt:graphSubtitle node and choose Insert inside dvt:graphSubtitle > 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, do the following:

   1. In the Structure window, right-click the graph node and choose Insert inside dvt:<type>Graph > ADF Data Visualization > 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 choose Insert inside dvt:graphFootnote > Font.

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

24.6.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, visibility of the axis, and scrolling in specific graph types. 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 choose Insert inside dvt:<type>Graph > ADF Data Visualization > 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, do the following:

   1. In the Structure window, right-click the dvt:x1Title node and choose Insert inside dvt:x1Title > 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 choose Insert inside dvt:<type>Graph > ADF Data Visualization > 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.

24.6.6.2 How to Specify Scrolling on an Axis

Scrolling on a graph axis can be specified for the following graph types:

• Area, bar, and line graphs for the dvt:o1Axis, dvt:y1Axis, and dvt:y2Axis tags.

• Bubble and scatter graphs for the dvt:x1Axis,dvt:y1Axis, and dvt:y2Axis tags.

By default, a graph axis scrolling attribute is set to off. You can specify these values for the scrolling attribute:

• off: Scrolling is disabled (default).

• on: Scrolling is enabled and the scroll bar is always present.

• asNeeded: Scrolling is enabled, but the scrollbar is not initially present. After zooming on the graph, the scrollbar displays and remains visible for the session.

• hidden: Scrolling is enabled but the scroll bar is always hidden. User may use pan scrolling.

24.6.6.3 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. Major tick increments are calculated automatically by default, or you can specify the tick steps with the majorIncrement attribute.

• Minor tick: Controls the color, width, and style of minor tick marks on the axis. Includes the following tags: dvt:x1MinorTick, dvt:y1MinorTick, and dvt:y2MinorTick. Minor tick increments are one-half of the major tick increment by default, or you can specify the tick steps with the minorIncrement attribute. Minor ticks do not support labels.

• Tick label: Controls the rotation of major 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 the ordinal axis tick labels:

1. In the visual editor, select the o1 Tick Label element on the graph.

   Alternatively, you can select the dvt:o1Axis element in the Structure window, then in the Property Inspector click the Configure o1Axis button and choose Value Labels.

2. In the Property Inspector enter values as needed for the following properties:

   • TextRotation: Use to specify the degree of text rotation to improve readability of the tick labels.

   • TickLabelSkipMode: Use to specify if and how tick labels will be displayed on the ordinal axis. When you set the value at TLS_MANUAL, you can optionally use the tickLabelSkipCount to set the number of tick labels to display between tick labels and tickLabelSkipFirst to set the index of the first tick label to be skipped.

3. Optionally, in the Property Inspector, click the Configure Font button to set properties for the child dvt:graphFont tag.

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

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

2. In the Property Inspector, enter desired values for the attributes of this tag and click the Configure Tick Label button to add an X1 Tick Label tag to the graph.

3. In the Property Inspector, enter desired values for the X1 Tick Label and if desired, click the Configure Font button to specify font characteristics for the tick label.

4. If you want to specify minor ticks in the graph, do the following:

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

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

      Note:

      For the tickStyle attribute you must specify a value other than GS_NONE or GS_AUTOMATIC.

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

24.6.6.4 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.

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

24.6.6.5 How to Set Minimum and Maximum Values on a Data Axis

The Y-axes have the following graph child tags to support the starting value of the axis: dvt:y1Axis, and dvt:y2Axis. 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.

Some graphs, such as scatter and bubble graphs, contain a dvt:x1Axis child tag for which the minimum and maximum values can also be set.

To specify the starting value on a y1-axis:

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

2. In the Property Inspector, for the AxisMinValue field, enter the starting value for the y1-axis.

3. In the AxisMinAutoScaled field, select false from the attribute dropdown list.

   You must set this attribute in order for the minimum value to be honored.

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

24.7.1.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 a line, called a pie feeler, that extends 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.

24.7.1.2 How to Customize 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.

Before you begin:

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

To customize one slice in a pie graph:

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

2. To separate one slice in a pie graph, 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.

3. To animate the slices in a pie graph, in the Property Inspector, set the InteractiveSliceBehavior attribute on the dvt:pieGraph tag. Valid values are any combination of the following:

   • none: No interactive slice behavior enabled.

   • explode: User can click to explode the slices in a pie graph.

   • explodeAll: Add Explode All and Unite All options to a context menu.

   For example, you can specify that users can explode the slices in a pie graph, and use a context menu to explode or collapse all the slices in the graph in the code:

   <dvt:pieGraph interactiveSliceBehavior="explode explodeAll"/>
   

24.7.2.1 How to Display Either Data Lines or Markers in Graphs

You have the option of displaying data lines or data markers in a line, combination, or radar graph. If you display markers rather than data lines, then the markers appear in the legend automatically.

In the Property Inspector, set the following attributes of the dvt:seriesSet tag to display data lines or data markers:

• LineDisplayed: Specifies whether data lines appear in the graph. You can set these values:

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

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

• MarkerDisplayed: Specifies whether markers or data lines appear in graph. You can set these values:

  • True indicates that markers are displayed in a graph.

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

24.7.2.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 24.6.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.

24.8.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 and choose Insert inside dvt:<type>Graph > ADF Data Visualization > Reference Object Set.

2. If you are defining reference areas related to specific axes, then specify a value for the appropriate axis or axes attributes: displayX1, displayY1, or displayY2.

   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.

   Optionally, you can apply a gradient special effect to the reference area. For more information see Section 24.8.2.1, "How to Add Gradient Special Effects to a Graph."

3. In the Structure window, right-click the dvt:referenceObjectSet node and choose Insert inside dvt:referenceObjectSet > 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 choose 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 displaySeries 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 associate the reference object with the appropriate axis or axes.

24.8.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 24-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.

<dvt:barGraph value ="#{sampleGraph.graphDataModel}" graphType="BAR_VERT_CLUST2Y"
     imageFormat="FLASH">
  <dvt:referenceObjectSet
     displayX1="RO_DISPLAY_AUTOMATIC" 
     displayY2="RO_DISPLAY_AUTOMATIC" 
    <dvt:referenceObject index="1" type="RO_AREA" association="Y1AXIS" 
     location="RO_BACK" color="#55FF0000" lowValue="0" highValue="4000"
     displayedInLegend="true" text="Low"/>
    <dvt:referenceObject index="2" type="RO_AREA" association="Y1AXIS" 
      location="RO_BACK" color="#55FFFF00"  lowValue="4000" highValue="10000"
      displayedInLegend="true" text="Medium"/>
    <dvt:referenceObject index="3" type="RO_AREA" association="Y1AXIS" 
      location="RO_BACK" color="#5500FF00"  lowValue="10000" highValue="18000"
      displayedInLegend="true" text="High"/>
    <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>

24.8.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 24-7 shows sample code for creating this method.

2. In the Structure window, right-click the graph node, then choose Insert inside dvt:<type>Graph > ADF Data Visualization > 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}"

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;
    } 

24.8.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 choose 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 fillType attribute, choose FT_GRADIENT.

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

   2. For numStops attribute, enter the number of stops to use for the gradient.

3. Optionally, in the Structure window, right-click the dvt:specialEffects node and choose Insert within dvt:specialEffects > 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.

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

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

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

24.8.4.1 How to Provide Marker and Legend Dimming

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. The highlighting effect is visually achieved by dimming the other data markers in the set. For example, if a bar graph displays sales by month for four products (P1, P2, P3, P4), when you move the cursor over product P2 in January, all the P2 bars are highlighted, and the P1, P3, and P4 bars are dimmed.

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.

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

To dim all the data markers in a series:

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

2. In the Appearance attributes category, in the SeriesRolloverBehavior field, use the dropdown list to select RB_DIM.

24.8.4.2 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. In a managed bean you store methods that takes as input a ZoomEvent or ScrollEvent. With these events, users can determine which axis is zoomed, as well as the current extent of the zoomed axes.

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. Example 24-9 shows sample code for creating this method.

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

3. Select the Behavior attributes category and expand the Advanced node and do one or both of the following:

   • In the zoomlListener field, specify a reference to the method that you stored in the managed bean.

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

   • In the scrollListener field, specify a reference to the method that you stored in the managed bean.

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

Managed bean sampleGraph.java
public void setZoom(ZoomEvent event) {
        System.out.println("Start Group: " + event.getAxisStartGroup(ZoomEvent.O1AXIS));
        System.out.println("Group Count: " + event.getAxisGroupCount(ZoomEvent.O1AXIS));
        System.out.println("Start Group Label: " + event.getAxisStartGroupLabel(ZoomEvent.O1AXIS));
public void setScroll(ScrollEvent event) {
        System.out.println("End Group Label: " + event.getAxisEndGroupLabel(ScrollEvent.O1AXIS));
        System.out.println("Axis Min: " + 
event.getAxisMin(ScrollEvent.O1AXIS));
        System.out.println("Axis Max: " + 
event.getAxisMax(ScrollEvent.O1AXIS));

24.8.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 choose 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 timeRelativeRange attribute, specify the relative range in milliseconds.

24.8.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 choose Go to Properties.

2. In the Appearance attributes category, specify the values for the following attributes:

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

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

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