<dvt:horizontalBarGraph>

dvt:horizontalBarGraph horizontalBarGraph horizontal bar graph

UIComponent class: oracle.adf.view.faces.bi.component.graph.UIGraph
Component type: oracle.dss.adf.graph.Graph (horizontalBarGraph)

Overview

Use the <dvt:horizontalBarGraph> tag to create an ADF data visualization horizontal bar graph. A bar graph is one in which data is represented as series of bars. There are many types of horizontal bar graphs. Here is a list of subtypes that a <dvt:horizontalBarGraph> tag supports -

The <dvt:horizontalBarGraph> tag provides a complete set of attributes and child tags required to create any horizontal bar graph. Use the Horizontal Bar 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 bar colors, for instance.

The Graph's layout is dominated by five major components: title, subtitle, footnote, legendArea, and plotArea. The plotArea 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 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. Bar graphs can be drawn with just one data point, though such graphs may not be useful. In a stacked bar graph, the values of each data series are added to the previous one, thus the size of the stack represents a cumulative total of all series. A Percent bar graph is a stacked graph that displays the percentage of a given series relative to the cumulative total of all series. This graph cannot have negative values.

Series

The rows in the grid usually appear as the series in a bar 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 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, assignedToY2 (change axis assignment on a Dual-Y graph), markerShape, etc.

Here is an example of a Horizontal Bar graph with a <dvt:seriesSet> tag that defines default color for all series. The <dvt:series> child tag overrides this color for the first series in the graph. -

                <dvt:horizontalBarGraph id="barGraph1" subType="BAR_HORIZ_CLUST">
                  <dvt:seriesSet defaultColor="#336699"">
                    <dvt:series index="0" color="#99ccff"/>
                  </dvt:seriesSet>
                </dvt:horizontalBarGraph>
        

SeriesEffect

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

Series highlighting

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

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.

Legend

The legend displays the marker and associated color of each series. It also displays the legend title and lists any reference objects that are present. 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.

PlotArea and Axes

Horizontal Bar graphs plot the data within the plotArea. The plotArea integrates the axes and the data markers. Generally for horizontal bar graphs the horizontal axis is an ordinal/category axis (o1Axis), which shows categories like cities or products. This axis can be a time axis if a Horizontal Bar graph is displaying dates (instance of java.util.Date). The primary vertical axis is a data axis (y1Axis). Dual-Y graphs typically also display the y2Axis. 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.

Time Axis

The Horizontal Bar graph displays a time axis when dates (object type java.util.Date) are specified for the column labels. Several timeXXX attributes are defined on the graph tag to customize the time axis. The child tag timeAxisDateFormat controls the format in which the time axis labels are displayed.

Time Selector

Use the <dvt:timeSelector> tag to activate the graph's TimeSelector feature, which allows an end user to select a time range on a time axis. This is typically used in master-detail graphs where the selected time range in the master graph drives the content of a detail graph, table, or other component. A backing or managed bean is required to use this feature.

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

Use a <dvt:annotation> tag to provide an annotation for a specific data point. Multiple annotations can be defined for a single data point. Wrap all <dvt:annotation> tags in a <dvt:annotatinSet> tag.

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.

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 horizontal bar graph using a clickListener to display data value :

                <dvt:horizontalBarGraph >
                 <dvt:shapeAttributesSet>
                  <dvt:shapeAttributes component="GRAPH_TWODMARKER" clickable="true" clickListener="#{clickListener.processClick}"/>
                 </dvt:shapeAttributesSet>
                </dvt:horizontalBarGraph>
        

The "processClick" method in the backing bean will look like:

        public void processClick(ClickEvent event) {   
                ComponentHandle handle = event.getComponentHandle();
                if (handle instanceof DataComponentHandle) {
                        DataComponentHandle dhandle = (DataComponentHandle)handle;
                        System.out.println("Data value: " + dhandle.getValue(DataComponentHandle.UNFORMATTED_VALUE).toString());
                }
        }
        

Wrap all <dvt:shapeAttributes> tags in a <dvt:shapeAttributesSet> tag.

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, legendText, and annotations when their text is truncated. There is no option to change this behavior.

Zoom and Scroll

Give end users the ability to zoom in on and scroll through a data set that may be too large or complex to fit comfortably within the area allocated to the graph using the "zoomDirection" attribute. Zoom and scroll may be enabled for horizontal and or vertical axes. The "scrollbarPresenceGroups" attribute provides control over when a scroll bar appears for the group axis: the horizontal axis in Area graphs, for instance. The "scrollbarPresenceX1", "scrollbarPresenceY1", and "scrollbarPresenceY2" attributes control the appearance of scroll bars for the various data axes.

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.

Relationship with other tags

The <dvt:horizontalBarGraph> tag can have the following child tags:

<activeDataProperties>, <alertSet>, <annotationSet>, <background>, <graphFootnote>, <graphPlotArea>, <graphSubtitle>, <graphTitle>, <legendArea>, <legendText>, <legendTitle>, <markerText>, <o1Axis>, <o1MajorTick>, <o1TickLabel>, <o1Title>, <referenceObjectSet>, <seriesSet >, <shapeAttributesSet>, <timeAxisDateFormat>, <timeSelector>, <y1Axis>, <y1BaseLine>, <y1MajorTick>, <y1Title>, <y1TickLabel>, <y2Axis>, <y2BaseLine>, <y2MajorTick>, <y2TickLabel>, <y2Title>

Events

Type Phases Description
oracle.adf.view.faces.bi.event.ClickEvent Apply Request Values

An event which indicates that a click action occurred in a component. A ClickEvent is enabled by adding the ClickListener to the graph.

org.apache.myfaces.trinidad.event.AttributeChangeEvent Invoke Application,
Apply Request Values
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 events might include the width of a column that supported client-side resizing.

Attributes

Name Type Supports EL? Description
advancedPropertiesXML String Yes

Specifies path to an XML file that contains settings for graph properties that are not exposed in the horizontalBarGraph tag.
For example, /myfiles/graph.xml
Path from web application root must be provided.

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
contentDelivery String Yes Specifies whether to fetch content with page load or after page load. Valid values are lazy (default) and immediate.
customLayout String Yes

Specifies custom layout information when the graph automatically places and sizes its components. Valid values are:

  • CL_NONE - Do not use any of the other custom layout attribute values
  • 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.
drillingEnabled boolean Yes Indicates whether drilling is enabled.
dynamicResize String Yes Specifies whether to resize the component based on its container size. Valid values are FIXED_SIZE (default) and DYNAMIC_RESIZE.
flashDefaultFontLoading String 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.
id String No the identifier for the component. The identifier must follow a subset of the syntax allowed in HTML:
  • Must not be a zero-length String.
  • First character must be an ASCII letter (A-Za-z) or an underscore ('_').
  • Subsequent characters must be an ASCII letter or digit (A-Za-z0-9), an underscore ('_'), or a dash ('-').
imageFormat String Yes

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.
  • AUTO - Generates Flash if a supported Flash player is found on the client.
imageHeight int Yes Specifies the height of the graph image in pixels.
imageWidth int Yes Specifies the width of the graph image in pixels.
inlineStyle String Yes Style of the outer element(enclosing div) of the component
o1AxisTitle String Yes Use to specify the text of the vertical axis title.
partialSubmit boolean Yes

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.
rendered boolean Yes Specifies whether the component is rendered
seriesEffect String Yes

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

Specifies the behavior when the mouse rolls over one bar in a series. Valid value 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.
shortDesc String Yes Specifies the short description of the graph. This is particularly useful in the screen reader mode.
style String Yes

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:

  • BAR_HORIZ_CLUST - Clustered bar graph that is horizontal
  • BAR_HORIZ_CLUST_2Y - Clustered, dual-Y bar graph that is horizontal
  • BAR_HORIZ_CLUST_SPLIT2Y - Clustered, split dual-Y bar graph that is horizontal
  • BAR_HORIZ_PERCENT - Horizontal Percent Bars
  • BAR_HORIZ_STACK - Stacked bar graph that is horizontal
  • BAR_HORIZ_STACK_2Y - Stacked , dual-Y bar graph that is horizontal
  • BAR_HORIZ_STACK_SPLIT2Y - Stacked, split dual-Y bar graph that is horizontal
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 value is "false".

title String Yes 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 String Yes

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

  • NONE - Apply no visual effects
  • AUTO (Default) - Apply visual effects automatically based on graph or gauge type.
y1AxisTitle String Yes Use to specify the text of the horizontal axis title.