<dvt:paretoGraph>

Overview

Use the <dvt:paretoGraph> tag to create an ADF data visualization Pareto graph. A pareto graph is one in which the data is represented by bars and a percentage line that indicates the cumulative percentage of bars. The Bars identify different sources of defects and are arranged by value, from the greatest number to the lowest number.

The Graph's layout is dominated by four major components: title, subtitle, footnote, and plotArea. The plotArea plots the data and is always rendered, but the other three 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. The plotArea 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. Pareto graphs require only a single series of data and with minimum two groups (group being a single column in this case). The Bars in the graph identify different sources of defects and are arranged by value, from the greatest number to the lowest number. The line shows the percentage of the cumulative values of the bars to the total values of all the bars in the graph. The graph automatically calculates the cumulative percentage values for the line based on the data series. This graph cannot have negative values.

Series

The rows in the grid usually appear as the series in a bar graph. Use a set of <dvt:series> tags, within a <dvt:seriesSet> tag, to change bar 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, markerShape, etc.

SeriesEffect

Use the graph's "seriesEffect" attribute to add predefined gradient effects on bars.

MarkerText

The markerText tag defines if and where the marker text should appear in relation to bars. Use the attribute "markerTextPlace" to specify the location of the text.

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.

PlotArea and Axes

Pareto graphs are dual-Y graphs that plot the data within the plotArea. The plotArea integrates the axes and the data markers. The horizontal axis is an ordinal axis (o1Axis). The primary vertical axis is a data axis (y1Axis), corresponds to values that the bars represent. The secondary vertical axis is a percentage data axis (y2Axis), corresponds to values that cumulative percentage line represents. Each axis, whether ordinal or data, has tick labels and an axis title associated with it. The y1Axis is associated with y1TickLabel and y1Title, for instance. See related component tags for detail.

Number Formatting

DVT pareto graph supports number formatting on its Y1 and Y2 axis tick labels as well as for marker text that appear on the bars and pareto line markers. Users can customize the number formatting by adding <af:convertNumber> to the <dvt:y1TickLabel>, <dvt:y2TickLabel>,and <dvt:y1Format> tags. The following is an example of how to configure these tags:

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 graph tags that support <af:convertNumber> child tags ( e.g. <dvt:y1TickLabel>, <dvt:y1Format>,...) 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

Pareto graphs require special formatting, since this graph displays a pareto line using calculated cumulative percent values. Pareto line is associated with y2 axis. The values of the y2 axis labels can be displayed as numbers (e.g. 0.25) or percent (e.g. 25%):

Formatting Percent Axis - when <af:convertNumber> is added to the <dvt:y2TickLabel>, the values will be displayed based on what format is specified. For example, if the convertNumber type is number then the values are formatted as numbers (e.g. 0, 0.1, 0.2, etc.). If the convertNumber type is percent then the values are formatted as percent (e.g. 0%, 10%, 20%, etc.). Please note that if <af:convertNumber> is not added to the <dvt:y2TickLabel> then the graph will format the labels as percent. To achieve the same format using <af:convertNumber>, <af:convertNumber type="percent"> must be used.

Formatting Marker Text / Marker Tooltips - On pareto graphs, marker text's <dvt:y1Format> tag is used to specify formatting for both markerText on bars and on the pareto line. The marker text is always displayed as numbers and optionally marker tooltips can either display values as percent or numbers. When markerText tooltip type is set to percent (valid value are MTT_PERCENT_VAL, MTT_PERCENT_VAL_TEXT, MTT_PERCENT_VAL_VALUES and MTT_PERCENT_VAL_VALUES_TEXT), the formatting engine will use the markerText format and will automatically force the convertNumber type to percent. 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.

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.

Alerts

Use a <dvt:alert> tag for the graph to define an additional data point that needs to be highlighted with a separate symbol, such as for an error or warning. Wrap all <dvt:alert> tags in a <dvt:alertSet> tag.

Annotations

ReferenceObject

Use the <dvt:referenceObject> tag to create either a reference line or a reference area. The reference object can be associated with any data axis or series. Multiple reference objects can be associated with a single series or an axis. Use the attribute "location" to specify whether the referenceObject should displayed in the front or the back of the data markers. Use graph's "referenceObjectDisplay" attributes to specify when the referenceObject would be displayed: the value "RO_AUTOMATIC" displays it only when the mouse hovers over the component with which the referenceObject is defined. Wrap all <dvt:referenceObject> tags in a <dvt:referenceObjectSet> tag.

Popups

The af:showPopupBehavior tag can be used within the <dvt:seriesSet> to display popups for data objects within the graph. Only the "click" and "mouseHover" trigger types are supported. When using hover popups, it is recommended that tooltips be disabled, since having multiple types of hover feedback can be confusing to the user.

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.

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 2D marker in a pareto graph using a clickListener to display data value :

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 markerText. Use attributes "markerTooltipType", "seriesTooltipLabelType", and "groupTooltipLabelType" to customize tooltip content. The graph automatically displays tooltips for components like title, subtitle, footnote, and annotations when their text is truncated. There is no option to change this behavior.

Zoom and Scroll

Zoom and scroll attributes are not supported for the pareto graph.

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.

This component does not stretch its children.

Attachment Mode

In attachment mode, the graph will be displayed in HTML5 or PNG, depending on the browser being used. Limited client interactivity, such as tooltips, is available. The following features are not supported in attachment mode:

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.

multiSelectContextMenu

popup component containing the context menu that will be shown on right click when multiple data objects are selected. 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.

animationDuration

int

Yes

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

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 -

Specifies callback for overriding the error message that the Graph displays when it is not provided with enough data to draw a graph. Only EL is supported.

dataSelection

String

Yes

Valid Values: none, single, multiple

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

none: no selection

single: single selection

multiple: multiple selection

drillingEnabled

boolean

Yes

Indicates whether drilling is enabled.

dynamicResize

String

Yes

Valid Values: FIXED_SIZE, DYNAMIC_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

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.

groupTooltipLabelType

int

Yes

Valid Values: TLT_MEMBER, TLT_DIM_MEMBER, TLT_NONE

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.

id

String

Yes

Specifies the identifier for the component

imageFormat

int

Yes

Valid Values: HTML5, FLASH, PNG, PNG_STAMPED, AUTO

The output format of the graph. Valid values are:

HTML5 - Uses HTML5 technologies when they are available. Falls back to FLASH or PNG when HTML5 is not supported by the client.

FLASH - FLASH image format.

PNG - PNG image format.

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

Note: The default image format is selected based on the oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMAT context parameter.

imageHeight

int

Yes

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

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

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.

o1AxisTitle

String

Yes

This attribute is deprecated. Use the child tag o1Title and its text attribute instead. Use to specify the text of the horizontal axis title.

partialSubmit

boolean

Yes

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

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

rendered

boolean

Yes

Specifies whether the component is rendered.

scrollListener

javax.el.MethodExpression

Only EL

The listener interface for receiving scroll events on the graph. The event triggers when an axis of a graph is scrolled. Here is an example of scrollListener implementation that displays the range of the Y1 Axis and the O1 Axis -

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_HIGHLIGHT

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.

Note: this attribute is not supported for funnel graphs.

seriesTooltipLabelType

int

Yes

Valid Values: TLT_MEMBER, TLT_DIM_MEMBER, TLT_NONE

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.

styleRuleBundle

java.util.Vector

Yes

Specifies a vector of oracle.dss.rules.RuleBundle objects that specify different colors based on data values or characteristics. For example, a styleRuleBundle might contain a stoplight rule that sets the following colors:

Green when the data value is less than 1000.

Yellow when the data value is less than 40.

Red when the data value is less than 20.

The following example refers to a style rule bundle called myRuleBundle that is stored in the backing bean SampleGraph: styleRuleBundle="#{sampleGraph.myRuleBundle}"

subType

String

Yes

Specifies the type of graph. Valid values are:

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

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

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

This attribute is deprecated. Use the child tag y1Title and its text attribute instead. Use to specify the text of the vertical axis title.

zoomListener

javax.el.MethodExpression

Only EL

The listener interface for receiving zoom events on the graph. The event triggers when an axis of a graph is zoomed. Here is an example of zoomListener implementation that displays the range of the Y1 Axis and the O1 Axis -