In the Structure window, right-click the graph node and choose Insert inside For fillType attribute, choose FT_GRADIENT.

24-38 Web User Interface Developers Guide for Oracle Application Development Framework – 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.7.3 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 choose Insert inside dvt:typeGraph ADF Data Visualization 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 choose Insert inside

dvt:typeGraph ADF Data Visualization Pareto Marker. Note: Do not set both the lineDisplayed attribute and the markerDisplayed attribute to False. Using ADF Graph Components 24-39 4. In the Property Inspector, select a value for the markerShape attribute.

24.7.4 Customizing Scatter Graph Series Markers

In scatter graphs, related data values in a series are represented by the data marker’s shape and color. You can separate marker shape and color from the series to display the interdependence of data values. For example, Figure 24–8 shows a scatter graph that uses City and Product attributes collectively to determine the series represented by the data marker’s shape and color. Figure 24–8 Scatter Graph with Series Marker The row header attributes can be used to override the default series specification. Figure 24–9 shows a scatter graph that displays the data values for the City attribute mapped to shapes and the Product attribute mapped to colors. Figure 24–9 Scatter Graph with Series Item Markers Use the following attributes to customize the scatter graph series markers: ■ markerShape - Specifies the row header attribute name to use to set the marker color. The graph will display the default index based series marker colors if this attribute is not specified. ■ markerColor - Specifies the row header attribute name to use to set the marker shape. The graph will display the default index based series marker shapes if this attribute is not specified. For example, specify City and Product as separate series item markers using this code: 24-40 Web User Interface Developers Guide for Oracle Application Development Framework dvt:scatterGraph markerColor=Product markerShape=City value={bindings.View1.graphModel}

24.8 Adding Specialized Features to Graphs

There are graph customization features that 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.

24.8.1 Adding Reference Lines or Areas to Graphs

Reference lines and areas can be set to display always, on rollover only, or never, regardless of how many there are and whether they are associated with a series or an axis. 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.

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:typeGraph 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: Using ADF Graph Components 24-41 a. 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. b. 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. c. 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: a. 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. b. 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–8 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 24–8 XML Code for Reference Lines and Areas in a Graph 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 24-42 Web User Interface Developers Guide for Oracle Application Development Framework 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–9 shows sample code for creating this method.

2. In the Structure window, right-click the graph node, then choose Insert inside

dvt:typeGraph 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} Example 24–9 Code for a Map of Child Reference Objects Managed bean SampleGraph.java : public Map getReferenceObjectMapList { HashMap map = new HashMap; ReferenceObject referenceObject = new ReferenceObject; referenceObject.setIndex1; referenceObject.setColorColor.red; referenceObject.setLineValue30; referenceObject.setLineWidth3; map.putnew Integer1, referenceObject; return map; }

24.8.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. You can specify 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: Using ADF Graph Components 24-43 ■ 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. ■ Reference area: Use the dvt:referenceObject tag. The approach that you use to define gradient special effects is identical for each part of the graph that supports these effects.

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:

a. For fillType attribute, choose FT_GRADIENT.

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

b. 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:

a. For the stopIndex attribute, enter a zero-based integer as an index within the

dvt:gradientStopStyle tags that are included within the specialEffects tag. Note: By default, a graph’s series gradient is set in the seriesEffect attribute with a value of SE_AUTO_GRADIENT to make the data markers appear smoother and apply graphic antialiasing. You must set the attribute to SE_NONE in order to specify a custom series gradient. 24-44 Web User Interface Developers Guide for Oracle Application Development Framework b. For the gradientStopColor attribute, enter the color that you want to use at this specific point along the gradient. c. 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–10 shows the XML code that is generated when you add a gradient fill to the background of a graph and specify two stops. Example 24–10 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 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.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 background: Use the dvt:background tag. By default the fillTransparent attribute is set to true. ■ Graph legend area: Use the dvt:legendArea tag. ■ Graph pie frame: Use the dvt:graphPieFrame tag. ■ Graph plot area: Use the dvt:graphPlotArea tag.

24.8.4 Providing Interactive Capability for Graphs

You can add a number of interactive functions to graphs including: ■ Marker and legend dimming Markers include lines, bars, areas, scatter markers, bubbles, and pie slices. ■ Zooming and scrolling ■ Changing zoom and scroll levels

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 Using ADF Graph Components 24-45 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–11 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. Example 24–11 Sample Code to Set Zoom and Scroll Managed bean sampleGraph.java public void setZoomZoomEvent event { System.out.printlnStart Group: + event.getAxisStartGroupZoomEvent.O1AXIS; System.out.printlnGroup Count: + event.getAxisGroupCountZoomEvent.O1AXIS; System.out.printlnStart Group Label: + event.getAxisStartGroupLabelZoomEvent.O1AXIS; public void setScrollScrollEvent event { System.out.printlnEnd Group Label: + event.getAxisEndGroupLabelScrollEvent.O1AXIS; System.out.printlnAxis Min: + event.getAxisMinScrollEvent.O1AXIS; System.out.printlnAxis Max: + 24-46 Web User Interface Developers Guide for Oracle Application Development Framework event.getAxisMaxScrollEvent.O1AXIS;

24.8.5 Providing an Interactive Time Axis for Graphs

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

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:

a. 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. b. 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:

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

b. In the timeRangeStart attribute, enter the initial date for the time range. c. In the timeRangeEnd attribute, enter the ending date for the time range.

24.8.6 Adding Alerts and Annotations to Graphs

Alerts define a data value on a graph that must be highlighted with a separate symbol, such as an error or warning. An icon marks the location of the alert. When the cursor moves over the alert icon, the text of that alert is displayed. An unlimited number of alerts can be defined for a graph using dvt:alert tags. The alerts are wrapped in a dvt:alertSet tag, that is a child of graph tag. Example 24–12 shows a set of alerts for an area graph. Example 24–12 Sample Code for Set of Graph Alerts dvt:areaGraph dvt:alertSet dvt:alert xValue=Boston yValue=3.50 yValueAssignment=Y1AXIS imageSource=myWarning.gif Using ADF Graph Components 24-47 dvt:alert xValue=Boston yValue=5.50 yValueAssignment=Y1AXIS imageSource=myError.gif dvt:alertSet dvt:areaGraph Annotations are associated with a data value on a graph to provide information when the cursor moves over the data value. An unlimited number of annotations can be defined for a graph using dvt:annotation tags and multiple annotations can be associated with a single data value. The annotations are wrapped in a dvt:annotationSet tag that is a child of the graph tag. The data marker associated with the annotation is defined using these attributes of the dvt:annotation tag: ■ series - Specifies the zero-based index of a series in a graph. In most graphs, each series appears as a set of markers that are the same color. For example, in a multiple pie graph, each yellow slice might represent sales of shoes, while each green slice represents the sales of boots. In a bar graph, all of the yellow bars might represent the sales of shoes, and the green bars might represent the sales of boots. ■ group - Specifies the zero-based index of a group in a graph. Groups appear differently in different graph types. In a clustered bar graph, each cluster of bars is a group. In a stacked bar graph, each stack is a group. In a multiple pie graph, each pie is a group. Example 24–13 shows a set of annotations for an area graph. Example 24–13 Sample Code for a Set of Annotations dvt:areaGraph dvt:annotationSet dvt:annotation series=0 group=0 text=annotation 1 dvt:annotation series=0 group=7 fillColor=55FFFF00 borderColor=55FF0000 text=second annotation dvt:annotationSet dvt:areaGraph You can control the position of the annotation in the plot area of a graph using these attributes: ■ position - Specifies the type of positioning to use for the annotation. Valid values are: – dataValue default - Positions the annotation by the data value defined in the series and group attributes. Overlap with other annotations is avoided. – absolute - Positions the annotation at the exact point defined by the xValue and the yValue in graphs with both those axes. Overlap with other annotations is not avoided. – percentage - Positions the annotation at the exact point defined by using the xValue and yValue as a percentage between 0 and 100 of the plot area of graphs with both those axes. Overlap with other annotations is not avoided. ■ xValue - Specifies the X value at which to position the annotation. This setting only applies when the annotation position is absolute or percentage. ■ yValue - Specifies the Y value at which to position the annotation. This setting only applies when the annotation position is absolute or percentage.