<dvt:pieGraph>

Overview

Use the <dvt:pieGraph> tag to create an ADF data visualization pie graph. In a Pie Graph one group of data is represented as sections of a circle, making the circle look like a sliced pie. There are many types of pie graphs. Here is a list of subtypes that a <dvt:pieGraph> tag supports -

PIE - Pie graph

PIE_BAR - Pie-Bar graph

PIE_MULTI - Multiple pie graph

RING - Ring graph

RING_BAR - Ring-Bar graph

RING_MULTI - Multiple ring graph

The <dvt:pieGraph> tag provides a complete set of attributes and child tags required to create any pie graph. Use the Pie graph's "subType" attribute to specify the graph type. One of the most commonly useful child tags is the <dvt:series> tag. Use a set of <dvt:series> tags, within a <dvt:seriesSet> tag, to change slice colors, for instance.

The Graph's layout is dominated by five major components: title, subtitle, footnote, legendArea, and pieFrame. The pieFrame plots the data and is always rendered, but the other four components are optional, and can be placed in different locations within the graph. Within the area allocated to the whole graph, space is first allocated to the titles, if present. The title and the subtitle are displayed side by side at the top of the graph by default, and the footnote is displayed at the bottom of the graph. Space is next allocated for the legendArea, which displays the marker color and label associated with each series. It can be positioned in one of four locations: left, right, top and bottom. The legend can use as much as 40% of the graph space. The pieFrame and its labels occupy the remaining space.

Data Model

Use the data binding dialogs to bind the simple graph tags to a data control, which is typically based on a rowset (see data binding documentation for details). Another common way to provide data for the graph is to use the "tabularData" attribute to create a grid. This requires use of a backing or managed bean.

The graph requires a simple grid of numeric data points to plot a graph. The grid's row and column labels are used to identify components within the graph. By default, the rows appear as the series and the columns appear as the groups. A Pie or a Ring graph displays one group of data, each slice representing a different series. This graph type requires one column in the grid, with multiple rows, one for each slice. Multiple Pie or multiple Ring graphs show one pie for each group, or column, of data. Pie graphs can be drawn with just one data point, though such graphs may not be useful. In case of Pie Bar or Ring Bar graphs, each slice represents a series total. The data for one such slice is represented in further detail by a percentage stacked bars.

Series

The rows in the grid usually appear as the series in a graph. The graph legend identifies each series in the graph, with a labeled symbol that shows color and other appropriate attributes. Use a set of <dvt:series> tags, within a <dvt:seriesSet> tag, to change slice colors. The <dvt:seriesSet> tag contains attributes that change the default attributes for all series. The <dvt:seriesSet> tag also contains the <dvt:series> tags that override attributes for individual series. Commonly used series attributes are - color, pieSliceExplode (separate a slice away from the rest of a Pie graph), etc.

Here is an example of a Pie graph with a <dvt:seriesSet> tag that defines default border color for all slices. The <dvt:series> child tag with pieSliceExplode attribute is used to separate first slice away from the rest of the Pie. -

SeriesEffect

Use the graph's "seriesEffect" attribute to add predefined gradient effects on slices of the Pie.

Series highlighting

Use the graph's "seriesRolloverBehavior" attribute to turn on highlighting behavior when the cursor moves over a slice or a series-specific legend component.

Number Formatting

DVT pie graph supports number formatting on its slice labels. Users can customize the number formatting by adding <af:convertNumber> to the <dvt:sliceLabel>. The following is an example of how to configure these tag:

Graph automatically determines the scale ( e.g. 4K ) and precision ( e.g. show 2 decimal points - 0.25 ) based on the values that are being displayed. This automatic formatting still occurs when <af:convertNumber> is specified. The <dvt:sliceLabel> and <dvt:y1TickLabel> tags also have scaling and autoPrecision attributes that can be used to control graph's automatic number formatting. By default, scaling="auto" means graph will auto-calculate the scale. For example, 40,000 will be formatted as "40K". By default, autoPrecision="on" means that graph will auto-calculate the precision of the number. For example, 0.230546 will be displayed as "0.23". If the autoPrecision is 'on' then all of the <af:convertNumber> fraction digit settings ( e.g. min/maxFractionDigits or pattern) are ignored.

Percent and Number Formatting

Pie graphs calculate and display percent values by default. An application has the option to have the pie graph display percent values and / or the numbers used to calculate the percentages. To configure what is displayed in the pie's slice label, <dvt:sliceLabel>'s textType attribute can be set and accepts the following values (LD_TEXT, LD_VALUE, LD_PERCENT, LD_TEXT_PERCENT ). To configure what is displayed in the pie slice labels' tooltip, dvt:pieGraph's markerTextType attribute can be set and accepts the following values (MTT_NONE, MTT_VALUES, MTT_CUM_VAL, MTT_PERCENT_VAL, MTT_TEXT, MTT_PERCENT_VAL_VALUES, MTT_PERCENT_VAL_TEXT, MTT_PERCENT_VAL_VALUES_TEXT, MTT_VALUES_TEXT ).

The single <af:convertNumber> tag specified within <dvt:sliceLabel> is used to specify formatting for slice labels and tooltips, regardless of whether the slice label or tooltip is displaying percent values (e.g. 25% ) or numbers ( e.g. 42K ). When an element of the pie graph is configured to show percents ( e.g. <dvt:sliceLabel textType="LD_PERCENT"> ), the pie graph will force the <af:convertNumber> specified into a percent format. When <af:convertNumber> is forced to percent, graph clears <af:convertNumber> pattern, since the pattern will prevent type=percent if specified. This means that patterns are ignored when graph forces percent formatting.

Also, please note that <dvt:sliceLabel>'s autoPrecision attribute applies to both percent formats as well as numbers, while the scaling attribute only applies to numbers and is not used when formatting percents.

Formatting Pie Bar Charts

A pie bar graph displays the values in the graph as stacked bars next to a y1 axis. To specify number formatting for the y1 axis labels, <af:convertNumber> should be specified within <dvt:y1TickLabel>. To specify number formatting for the bar tooltips, <dvt:markerText><dvt:y1format> should be specified. Here is an example of configuring formatting for a pie bar:

Titles

The title and the subtitle, if present, are displayed side by side at the top of the graph by default. Use the graph's "customLayout" attribute to change this default setting. The footnote, if present, is displayed at the bottom of the graph.

Legend

The legend displays the marker and associated color of each series. It also displays the legend title. The legend can be positioned in one of four different locations: left, right, top and bottom. Use the attribute "alongGraphEdge" to attach it to the edge of the graph. The legend can be removed with the "rendered" attribute.

PieFrame

Pie graphs plot the data within the pieFrame. The pieFrame integrates the slice labels, the slices, and the pie label. The PieFrame is divided into multiple sections when displaying Multiple Pie or Multiple ring graph. The number sections in the frame equal to the number groups in the data. In case of Pie Bar or Ring Bar graphs the pie frame also displays bars with vertical data axis (y1Axis). The y1Axis is associated with y1TickLabel and y1Title

Graph Size

The default graph size is 300 pixels tall by 400 pixels wide. Change this using the "inlineStyle" attribute. Set inlineStyle="width:500px; height:350px;", for instance, to change the graph size to 350 pixels tall by 500 pixels wide. The width and the height can also be specified in percent. Use percent for height only when the graph is added to an explicitly sized container or one that manages layout, otherwise graph will behave differently for different browsers. Use the "dynamicResize" attribute to resize the graph based on its container size.

Animation

Several graph types support animation. Animate the graph during initial rendering using the attribute "animationOnDisplay". The graph can also be animated when the data changes using the attribute "animationOnDataChange". Use the attribute "animationDuration" to specify the animation duration. The indicator colors for increase and decrease in the data value are specified by attributes "animationUpColor" and "animationDownColor", respectively.

Interactivity

Use the shapeAttributes tag to specify interactivity on an individual graph component. A backing or managed bean is required to use this feature.

Here is an example of a slice in a pie graph using a clickListener to display data value :

Context Menus

Context menus can be defined by using any of the context menu facets that are defined on the graph. The "bodyContextMenu" facet specifies a context menu that is displayed on any non-selectable object within the component. The "contextMenu" facet specifies a context menu that is displayed on any selectable object within the graph. The "multiSelectContextMenu" facet specifies a context menu that is displayed when multiple objects are selected. Each facet supports only a single child component. Selection must be enabled and supported for the specific graph type in order for an object to be considered selectable. Context Menus are currently only supported in Flash.

Due to technical limitations when using the Flash rendering format, the context menu contents are currently displayed using the Flash Player's context menu. This imposes several limitations defined by the Flash Player:

Flash does not allow for submenus in its context menu.

Flash only allows a maximum of 15 custom menu items. The component's built in menu items, such as the ones for interactiveSliceBehavior, also count towards this limit.

Flash only allows for text-only menu items. Icons or other controls possible in ADF Faces menus are not possible in Flash.

Each caption must contain at least one visible character.

Control characters, newlines, and other white space characters are ignored.

No caption can be more than 100 characters long.

Captions that are identical to another custom item are ignored, whether the matching item is visible or not. Menu captions are compared to built-in captions or existing custom captions without regard to case, punctuation, or white space.

The following captions are not allowed, but the words may be used in conjunction with other words to form a custom caption: "Save","Zoom In", "Zoom Out", "100%", "Show All", "Quality", "Play", "Loop", "Rewind", "Forward", "Back", "Movie not loaded", "About", "Print", "Show Redraw Regions", "Debugger", "Undo", "Cut", "Copy", "Paste", "Delete", "Select All", "Open", "Open in new window", "Copy link"

None of the following words can appear in a custom caption on their own or in conjunction with other words: "Adobe", "Macromedia", "Flash Player", "Settings"

Additionally, since Flash's request for context menu items is a synchronous call, so a server request to evaluate EL is not possible when the context menu is invoked. To provide context menus that vary by selected object, the menus will be pre-fetched if the context menu popup uses contentDelivery="lazyUncached". For context menus that may vary by state, this means that any EL expressions within the menu definition will be called repeatedly at render time, with different selection and currency states. When using these context menus that are pre-fetched, the application must be aware of the following:

Long running or slow code should not be executed in any EL that may be used to determine how the context menu is displayed. This does not apply to af:commandMenuItem attributes that are called after a menu item is selected, such as "actionListener".

In the future, if the Flash limitations are solved, the ADF context menu may be displayed in place of the Flash context menu. To ensure upgrade compatibility, applications developers should code such that their EL will function both in cases where the menu is pre-fetched, and also if the EL is evaluated when the menu is invoked. It is highly recommended that the only component state that applications rely on are selection and currency.

Tooltips

Tooltips are useful to display identification and or detail information for data markers. They can be very useful in smaller graphs without enough space to display labels. Use attributes "markerTooltipType", "seriesTooltipLabelType", and "groupTooltipLabelType" to customize tooltip content. The graph automatically displays tooltips for components like title, subtitle, footnote, and legendText, when their text is truncated. There is no option to change this behavior.

Font

The <dvt:graphFont> tag is used for font formatting. Text color, style, size, and font name can be specified using this tag. This tag is used as a child tag for any of the graph's text component tags. All text component tags have other formatting attributes like horizontal and vertical alignment, text string, and whether or not the text should be rendered.

SpecialEffects

Use the <dvt:specialEffects> tag to specify gradient effects on many graph subcomponents. This tag must be defined as a child tag of the component tag and is not available for any text components. Note that the "seriesEffect" attribute setting always overrides the special effects settings.

Geometry Management

This component can be stretched by a parent layout component that stretches its children, e.g. panelStretchLayout, panelSplitter, if dynamicResize="DYNAMIC_SIZE" is set.

This component does stretch to fill up the browser's viewport when it is the "sole visual root component" in the component tree, if dynamicResize="DYNAMIC_SIZE" is set.

When NOT stretched, this component will be displayed in its default dimensions which are provided by the skin. This can be modified by applying a dimension using the inlineStyle or styleClass attributes.

Event delivered to describe an attribute change. Attribute change events are not delivered for any programmatic change to a property. They are only delivered when a renderer changes a property without the application's specific request. An example of an attribute change event might include the width of a column that supported client-side resizing.

Supported Facets

Name

Description

bodyContextMenu

popup component containing the context menu that will be shown on right click on any non-selectable object within the component. The af:popup must contain an af:menu to display the context menu. This facet supports only a single child component.

contextMenu

popup component containing the context menu that will be shown on right click of any selectable data object within the component. The af:popup must contain an af:menu to display the context menu. This facet supports only a single child component.

Attributes

Name

Type

Supports EL?

Description

advancedPropertiesXML

String

Yes

This attribute is deprecated. The UIComponent APIs should be used instead. Specifies path to an XML file that contains settings for graph properties that are not exposed in the areaGraph tag.
For example, /myfiles/graph.xml
Path from web application root must be provided.

animationDownColor

String

Yes

Specifies the color used to indicate that a data value has decreased. Enter values in RGB hexadecimal. The default color is red (#FF3300).

animationDuration

int

Yes

Default Value: 1000

Specifies the animation duration in milliseconds. The default value is 1000.

Specifies the color used to indicate that a data value has increased. Enter values in RGB hexadecimal. The default color is cyan (#0099FF).

attributeChangeListener

javax.el.MethodExpression

Only EL

a method reference to an attribute change listener. Attribute change events are not delivered for any programmatic change to a property. They are only delivered when a renderer changes a property without the application's specific request. An example of an attribute change events might include the width of a column that supported client-side resizing.

binding

String

Only EL

Specifies a binding reference to store a specific instance of UIGraph from a backing bean. Set this attribute only to access code in a backing bean. For example, to reference a graph component in the SampleGraph class, use the following code: binding="#{sampleGraph.graph}"

clickAction

String

Yes

Refers to a backing bean method that performs navigation processing for the graph and returns an outcome String. Or a static outcome String can be specified. The JSF NavigationHandler selects the page to display next by matching the outcome String against the navigation rules in the application configuration resource file. The application writes the Navigation rules.

clickListener

String

Yes

The listener interface for receiving click events on the graph components. Here is an example of clickListener implementation that displays a component name on a click action -

CL_TITLES_SIDEBYSIDE - Display Title and subtitle side by side instead of the subtitle below the title

CL_TITLE_SEPARATOR - Display title separator under the titles

customizationId

String

Yes

This attribute is deprecated. The 'id' attribute should be used when applying persistent customizations. This attribute will be removed in the next release.

dataSelection

String

Yes

Valid Values: none, single, multipleDefault Value: none

Determines the data selection mode for the graph. Valid values are:

none: no selection

single: single selection

multiple: multiple selection

drillingEnabled

boolean

Yes

Default Value: false

Indicates whether drilling is enabled.

dynamicResize

String

Yes

Valid Values: FIXED_SIZE, DYNAMIC_SIZEDefault Value: FIXED_SIZE

Specifies whether to resize the component based on its container size. Valid values are FIXED_SIZE (default) and DYNAMIC_RESIZE.

emptyText

String

Yes

Specifies error text to display when graph has no data.

flashDefaultFontLoading

int

Yes

Default Value: FLASH_DEFAULT_FONT_LOADING_ALL

Specifies whether default fonts are loaded in FLASH from the middle tier. Valid values are FLASH_DEFAULT_FONT_LOADING_ALL or FLASH_DEFAULT_FONT_LOADING_NONE. The default value is FLASH_DEFAULT_FONT_LOADING_ALL.

Specifies whether group information for a graph appears in tooltips and, if so, identifies the kind of group information that appears in tooltips. Valid values are:

TLT_NONE - No group information appears in tooltips.

TLT_MEMBER - (Default) Only the dimension member for a group appears in tooltips.

TLT_DIM_MEMBER - Both dimension name and dimension member for a group are displayed in tooltips.

hideAndShowBehavior

String

Yes

Valid Values: none, withRescale, withoutRescaleDefault Value: none

Specifies the hide and show behavior in the graph. If the behavior is not "none", clicking on the legendText or legendMarker will hide the corresponding series. Note that the last series will not be hidden. Valid values are:

none (Default) - no hide and show behavior used

withRescale - rescales the graph after hiding a series

withoutRescale - does not rescale the graph after hiding a series

id

String

Yes

Specifies the identifier for the component

imageFormat

int

Yes

Valid Values: FLASH, PNG, PNG_STAMPED, AUTODefault Value: FLASH

Specifies the format of graph image. Valid values are:

PNG - PNG image format.

FLASH - (Default) FLASH image format.

PNG_STAMPED - PNG image with no javascript. This must be used when using graph in ADF table cells via stamping.

This attribute is deprecated. Use inlineStyle attribute to specify the image width and height instead. For examples: inlineStyle = "width:500px; height:350px;".

The default height is 300 pixels.

imageWidth

int

Yes

Default Value: 400

This attribute is deprecated. Use inlineStyle attribute to specify the image width and height instead. For examples: inlineStyle = "width:500px; height:350px;".

The default width is 400 pixels.

inlineStyle

String

Yes

Style of the outer element(enclosing div) of the component

interactiveSliceBehavior

String

Yes

Specifies the interactivity behavior for pie slices. This is only supported in the Flash imageFormat. Valid values are any combination of the following values:

none (Default) - no interactive slice behavior enabled

explode - click to explode slices in a pie graph

explodeAll - add explodeAll and uniteAll options to the context menu

markerTooltipTemplate

String

Yes

Provides a declarative way to customize the tooltips that appear on the graph. By setting the markerTooltipTemplate attribute to a tokenized string, an application can quickly format all the marker tooltips. This feature is a more performant alternative to the customTooltipCallback, since tokens can be sent to the client instead of preconstructed tooltip strings. This reduces the graph payload significantly, especially for large datasets.

The markerTooltipTemplate attribute accepts a String that may contain any number of a set of predefined tokens. When the tooltips are generated, the tokens are replaced with the information corresponding to each marker. Valid tokens are:

Note: To display series tooltip labels for a graph, you must set markerTooltipType to a value that includes text.

partialSubmit

boolean

Yes

Default Value: true

Deprecated. It is not useful anymore.

Indicates whether an action can be performed through a partial page submit. Valid values are:

"true" - (Default) Partial page submit is allowed.

"false" - No partial page submit.

partialTriggers

String[]

Yes

the IDs of the components that should trigger a partial update. This component will listen on the trigger components. If one of the trigger components receives an event that will cause it to update in some way, this component will request to be updated too.

renderImagemap

boolean

Yes

Default Value: true

Indicates whether an image map should be rendered for a PNG image. The default value is true.

Determines the series effect that is used for a graph. Valid values are:

SE_NONE - No series effect is used for the graph. This value causes markers to appear flat and sets the graphicAntialiasing attribute to "false".

SE_GRADIENT - Sets a special gradient on data markers to make them look more polished and sets graphicAntialiasing to "true".

SE_AUTO_GRADIENT - (Default) Works similar to SE_GRADIENT except in the case of a large dataset. If the graph displays a large dataset, then the gradient is not displayed in data markers so that peformance is improved.

seriesRolloverBehavior

int

Yes

Valid Values: RB_NONE, RB_DIM, RB_HIGHLIGHTDefault Value: RB_NONE

Specifies the behavior when the mouse rolls over one bar in a series. Valid values are:

RB_NONE - (Default) No series rollover behavior is enabled.

RB_HIGHLIGHT - Highlights all bars in the series when rollover occurs.

RB_DIM - Dims all bars in the series when rollover occurs

RB_HIGHLIGHT | RB_DIM - Produces both highlighting and dimming of all bars in the series when rollover occurs.

Specifies series information in a tooltip. Valid values are as follows:

TLT_NONE - Displays no series information

TLT_MEMBER - (Default) Displays the member label of the series in a tooltip

TLT_DIM_MEMBER - Displays the dimension member label of a series in a tooltip

Note: The graph displays series tooltip labels only if markerTooltipType is set to a value that includes text.

shortDesc

String

Yes

Specifies the short description of the graph. This is particularly useful in the screen reader mode.

style

String

Yes

This attribute is deprecated. Skinning should be used instead. Applies a style to the graph based on the specified XML file. Valid values are the name of a standard graph style or the path of a custom XML file that you want to set as a style for this graph.

Predefined graph styles are:

April

Autumn

Black and White

Comet

Confetti

Default

Earth

Executive

Financial

Glass

Nautical

Projection

Regatta

Southwest

Transparent

To specify a custom style, enter the entire path to the xml file. For example: /text/myStyle.xml.

styleClass

String

Yes

Sets a CSS style class to use for this component. Note that width and height should be set using the inlineStyle property.

subType

String

Yes

Specifies the type of graph. Valid values are:

PIE - Pie graph

PIE_BAR - Pie-Bar graph

PIE_MULTI - Multiple pie graph

RING - Ring graph

RING_BAR - Ring-Bar graph

RING_MULTI - Multiple ring graph

tabularData

java.util.List

Yes

Specifies a list of data that the graph uses to create a grid and populate itself. The List 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 a Double.

threeDEffect

boolean

Yes

Default Value: false

Indicates whether a graph appears to have depth. Valid values are "true" and "false" (Default).

title

String

Yes

This attribute is deprecated. Use the child tag graphTitle and its text attribute instead. Specifies the text of the title.

value

String

Yes

Specifies the graph's data model. This must be an instance of oracle.adf.view.faces.bi.model.DataModel or oracle.adf.view.faces.bi.model.GraphDataModel

visualEffects

int

Yes

Valid Values: NONE, AUTODefault Value: AUTO

Specifies the type or types of visualEffect to apply. Valid values are: