Element: <oj-c-area-chart>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
16.0.0
F83701-01

Since:
  • 16.0.0
Module:
  • area-chart

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

Other Topics


JET Area Chart

An area chart displays information graphically using lines and filled areas, making relationships among the data easier to understand.


<oj-c-area-chart
  data="[[dataProvider]]">
</oj-c-area-chart>

Accessibility

To make your component accessible, the application is required to include contextual information for screender readers using one or more the following methods as appropriate:
  • aria-describedby
  • aria-labelledby
  • aria-label
  • short-desc property of your items

If your application has custom keyboard and touch shortcuts implemented for the component, these shortcuts can conflict with those of the component. It is the application's responsibility to disclose these custom shortcuts, possibly via a datatip or help popup.

When setting color, applications are responsible for making sure that the color meets the minimum contrast requirements.

Keyboard End User Information

Key Action
Tab Move focus to next element.
Shift + Tab Move focus to previous element.
UpArrow Move focus and selection to previous data item.
DownArrow Move focus and selection to next data item.
LeftArrow Move focus and selection to previous data item.
RightArrow Move focus and selection to next data item.
Shift + UpArrow Move focus and multi-select previous data item.
Shift + DownArrow Move focus and multi-select next data item.
Shift + LeftArrow Move focus and multi-select previous data item.
Shift + RightArrow Move focus and multi-select next data item.
Ctrl + UpArrow Move focus to previous data item, without changing the current selection.
Ctrl + DownArrow Move focus to next data item, without changing the current selection.
Ctrl + LeftArrow Move focus to previous data item, without changing the current selection.
Ctrl + RightArrow Move focus to next data item, without changing the current selection.
Ctrl + Spacebar Multi-select data item with focus.
= or + Zoom in one level if zooming is enabled.
- or _ Zoom out one level if zooming is enabled.
PageUp Pan up if scrolling is enabled.
PageDown Pan down if scrolling is enabled.
Shift + PageUp Pan left in left-to-right locales. Pan right in right-to-left locales.
Shift + PageDown Pan right in left-to-right locales. Pan left in right-to-left locales.
Enter Drill on data item, categorical axis label, or legend item when drilling is enabled.

Performance

Data Set Size

As a rule of thumb, it's recommended that applications only set usable data densities on the chart. For example, it's not recommended to show more than 500 area series on a 500 pixel wide chart, since the areas will be unusably thin. While there are several optimizations within the chart to deal with large data sets, it's always more efficient to reduce the data set size as early as possible. Future optimizations will focus on improving end user experience as well as developer productivity for common use cases.

Styling

Use the highest level property available. For example, consider setting styling properties on styleDefaults or series, instead of styling properties on the individual data items. The chart can take advantage of these higher level properties to apply the style properties on containers, saving expensive DOM calls.

Touch End User Information

Target Gesture Action
Data Item Tap Select when selectionMode is enabled.
Drill when drilling is enabled and selectionMode is none.
Double Tap Drill when drilling is enabled and selectionMode is enabled.
Press & Hold Display tooltip.
Display context menu on release.
Categorical Axis Item Tap Drill when drilling is enabled.
Legend Item Tap Drill when drilling is enabled.
Filter when hideAndShowBehavior is enabled.
Plot Area Drag Pan when panning is enabled and toggled into that mode.
Marquee select when selectionMode is multiple and toggled into that mode.
Pinch-close Zoom out when zooming is enabled.
Spread-open Zoom in when zooming is enabled.


Usage

Signature:

interface CAreaChartElement<K extends string | number,D extends oj-c.AreaChart.AreaItem<K> | any>

Typescript Import Format
//To typecheck the element APIs, import as below.
import { CAreaChartElement } from "oj-c/area-chart";

//For the transpiled javascript to load the element's module, import as below
import "oj-c/area-chart";

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.


Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

groupTemplate

The groupTemplate slot is used to specify the template for generating the group properties of the chart. The slot content must be a single <template> element. The content of the template should only be one <oj-c-area-chart-group> element. See the oj-c-area-chart-group doc for more details.

When the template is executed for each group, it will have access to the chart's binding context containing the following properties:

  • $current - an object that contains information for the current item. (See the table below for a list of properties available on $current)
  • alias - if as attribute was specified, the value will be used to provide an application-named alias for $current.
Properties of $current:
Name Type Description
depth number The depth of the group. The depth of the outermost group under the invisible root is 1.
ids Array<string> The key of the current item.
index number The group index
items Array.<oj-c.AreaChart.ChartItemTemplateContext> The array of objects which are chart items that belong to this series. The objects will have the following properties

itemTemplate

The itemTemplate slot is used to specify the template for creating each item of the chart. The slot content must be a <template> element. The content of the template should only be one <oj-c-area-chart-item> element. See the oj-c-area-chart-item doc for more details. A series-id and group-id must be specified.

When the template is executed for each item, it will have access to the chart's binding context containing the following properties:

  • $current - an object that contains information for the current item. (See the table below for a list of properties available on $current)
  • alias - if as attribute was specified, the value will be used to provide an application-named alias for $current.
Properties of $current:
Name Type Description
data D The data object of the current item.
index number The zero-based index of the current item.
key K The key of the current item.

seriesTemplate

The seriesTemplate slot is used to specify the template for generating the series properties of the chart. The slot content must be a single <template> element. The content of the template should only be one <oj-c-area-chart-series> element.See the oj-c-area-chart-series doc for more details.

When the template is executed for each series, it will have access to the chart's binding context containing the following properties:

  • $current - an object that contains information for the current item. (See the table below for a list of properties available on $current)
  • alias - if as attribute was specified, the value will be used to provide an application-named alias for $current.
Properties of $current:
Name Type Description
id string The series id
index number The series index
items Array.<oj-c.AreaChart.ChartItemTemplateContext> The array of objects which are chart items that belong to this series. The objects will have the following properties

Attributes

data :(DataProvider.<K, D>|null)

Specifies the DataProvider for the sections and items of the area-chart.
Names
Item Name
Property data
Property change event dataChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-data-changed

drilling :"on"|"off"

Whether drilling is enabled. Drillable objects will show a pointer cursor on hover and fire an ojItemDrill, ojSeriesDrill and ojGroupDrill event on click (double click if selection is enabled). Use "on" to enable drilling for all series objects (legend items), group objects (x-axis labels), and data items. To enable or disable drilling on individual series, group, or data item, use the drilling attribute in each series, group, or data item.
Supported Values:
Value Description
off Drilling is not enabled.
on Drilling is enabled on data items, axis labels and legend items.
Default Value:
  • "off"
Names
Item Name
Property drilling
Property change event drillingChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-drilling-changed

group-comparator :(context1: oj-c.AreaChart.ChartGroupTemplateContext<K, D>, context2: ChartGroupTemplateContext<K, D>) => number

A comparator function that determines the ordering of the chart groups when using a DataProvider. If undefined, the group will follow the order in which they are found in the data. The group objects will have the same properties as the context for groupTemplate's $current. If groupComparator(a, b) is less than 0, chart group a comes before chart group b. If groupComparator(a, b) is 0, the original order is preserved. If groupComparator(a, b) is greater than 0, chart group b comes before chart group a.
Names
Item Name
Property groupComparator
Property change event groupComparatorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-group-comparator-changed

hidden-categories :Array<string>

Default Value:
  • []
Supports writeback:
  • true
Names
Item Name
Property hiddenCategories
Property change event hiddenCategoriesChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-hidden-categories-changed

hide-and-show-behavior :"none"|"withoutRescale"|"withRescale"

Defines the hide and show behavior that is performed when clicking on a legend item. When data items are hidden, the y axes can be optionally rescaled to fit to the remaining data.
Default Value:
  • "none"
Names
Item Name
Property hideAndShowBehavior
Property change event hideAndShowBehaviorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-hide-and-show-behavior-changed

highlight-match :"all"|"any"

The matching condition for the highlightedCategories property. By default, highlightMatch is 'all' and only items whose categories match all of the values specified in the highlightedCategories array will be highlighted. If highlightMatch is 'any', then items that match at least one of the highlightedCategories values will be highlighted.
Default Value:
  • "any"
Names
Item Name
Property highlightMatch
Property change event highlightMatchChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-highlight-match-changed

highlighted-categories :Array<string>

An array of category strings used for highlighting. Series or data items matching categories in this array will be highlighted.
Default Value:
  • []
Supports writeback:
  • true
Names
Item Name
Property highlightedCategories
Property change event highlightedCategoriesChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-highlighted-categories-changed

hover-behavior :"none"|"dim"

Defines the behavior applied when hovering over data items.
Default Value:
  • "none"
Names
Item Name
Property hoverBehavior
Property change event hoverBehaviorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-hover-behavior-changed

legend :oj-c.AreaChart.ChartLegend

An object defining the style, positioning, and behavior of the legend.
Names
Item Name
Property legend
Property change event legendChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-legend-changed

orientation :"horizontal"|"vertical"

The orientation of the chart.
Supported Values:
Value Description
horizontal Chart will be horizontally oriented.
vertical Chart will be vertically oriented.
Default Value:
  • "vertical"
Names
Item Name
Property orientation
Property change event orientationChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-orientation-changed

plot-area :oj-c.AreaChart.PlotArea

An object defining the style of the plot area.
Names
Item Name
Property plotArea
Property change event plotAreaChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-plot-area-changed

selection :Array<K>

An array containing the ids of the initially selected data items.
Default Value:
  • []
Supports writeback:
  • true
Names
Item Name
Property selection
Property change event selectionChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-selection-changed

selection-mode :"none"|"multiple"|"single"

The type of selection behavior that is enabled on the tag cloud. This attribute controls the number of selections that can be made via selection gestures at any given time.
Default Value:
  • "none"
Names
Item Name
Property selectionMode
Property change event selectionModeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-selection-mode-changed

series-comparator :(context1: oj-c.AreaChart.ChartSeriesTemplateContext<K, D>, context2: ChartSeriesTemplateContext<K, D>) => number

A comparator function that determines the ordering of the chart series when using a DataProvider. If undefined, the series will follow the order in which they are found in the data. The series objects will have the same properties as the context for seriesTemplate's $current. If seriesComparator(a, b) is less than 0, chart series a comes before chart series b. If seriesComparator(a, b) is 0, the original order is preserved. If seriesComparator(a, b) is greater than 0, chart series b comes before chart series a.
Names
Item Name
Property seriesComparator
Property change event seriesComparatorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-series-comparator-changed

stack :"on"|"off"

Defines whether the data items are stacked.
Supported Values:
Value Description
off Data items will not be stacked.
on Data items belonging to same group will be stacked.
Default Value:
  • "off"
Names
Item Name
Property stack
Property change event stackChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-stack-changed

value-formats :oj-c.AreaChart.ValueFormats

An object specifying value formatting and tooltip behavior, whose keys generally correspond to the attribute names on the data items.
Names
Item Name
Property valueFormats
Property change event valueFormatsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-value-formats-changed

x-axis :oj-c.AreaChart.XAxis

An object defining properties for the x axis, tick marks, tick labels, and axis titles.
Names
Item Name
Property xAxis
Property change event xAxisChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-x-axis-changed

y-axis :oj-c.AreaChart.YAxis

An object defining properties for the y axis, tick marks, tick labels, and axis titles.
Names
Item Name
Property yAxis
Property change event yAxisChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-y-axis-changed

zoom-and-scroll :"off"|"live"

Specifies the zoom and scroll behavior of the chart. "Live" behavior means that the chart will be updated continuously as it is being manipulated. While "live" zoom and scroll provides the best end user experience, no guarantess are made about the rendering performance or usability for large data sets or slow client environments.
Names
Item Name
Property zoomAndScroll
Property change event zoomAndScrollChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-zoom-and-scroll-changed

Events

ojGroupDrill

Triggered on a chart group drill gesture (double click if selection is enabled, single click otherwise).
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
group K The group id of the drilled object.
groupData oj-c.AreaChart.Group An array of data for the group the drilled object belongs to.
id K The id of the drilled object.
items Array.<oj-c.AreaChart.AreaItem> An array containing objects describing the data items belonging to the drilled group.

ojItemDrill

Triggered on a chart item (double click if selection is enabled, single click otherwise).
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
data oj-c.AreaChart.AreaItem The data object of the drilled item.
group K The group id of the drilled object.
groupData oj-c.AreaChart.Group An array of data for the group the drilled object belongs to.
id K The id of the drilled object.
itemData D The row data object of the drilled item. This will only be set if a DataProvider is being used.
series K The series id of the drilled object.
seriesData oj-c.AreaChart.LineChartSeries The data for the series of the drilled object.

ojSeriesDrill

Triggered on a chart series drill gesture (double click if selection is enabled, single click otherwise).
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
id K The id of the drilled object.
items Array.<oj-c.AreaChart.AreaItem> An array containing objects describing the data items belonging to the drilled group.
series K The series id of the drilled object.
seriesData oj-c.AreaChart.LineChartSeries The data for the series of the drilled object.

ojViewportChange

Triggered after the viewport is changed due to a zoom or scroll operation.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
endGroup string The end group of the new viewport on a chart with categorical axis.
startGroup string The start group of the new viewport on a chart with categorical axis.
xMax number The maximum x value of the new viewport.
xMin number The minimum x value of the new viewport.
yMax number The maximum y value of the new viewport.
yMin number The minimum y value of the new viewport.

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description
property The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a corresponding event.
Parameters:
Name Type Description
property The property name to set. Supports dot notation for subproperty access.
value The new value to set the property to.
Returns:
Type
void

Type Definitions

AreaItem<K>

Properties:
Name Type Argument Description
categories Array<string> <optional>
 An optional array of category strings corresponding to this data item. This enables highlighting and filtering of individual data items through interactions with the legend or other visualization elements. If not defined, series categories are used.
color string <optional>
 The color of the data item. This color value is not inherited by chart legend. See chart series color and display-in-legend for more details.
drilling "inherit" | "off" | "on" <optional>
 Whether drilling is enabled for the data item. Drillable objects will show a pointer cursor on hover and fire an ojDrill event on click (double click if selection is enabled). To enable drilling for all data items at once, use the drilling attribute in the top level.
groupId Array<string> The array of id(s) for the group(s) the item belongs to. For hierarchical groups, it will be an array of outermost to innermost group ids. This is also used to specify the date for non mixed frequency time axes. The specified date for non mixed frequency time axes must be an ISO string.
id K The item id should be set by the application if the DataProvider is not being used. The row key will be used as id in the DataProvider case.
markerDisplayed "auto" | "off" | "on" <optional>
 Defines whether the data marker is displayed. Only applies to line, area, scatter, and bubble series. If auto, the markers will be displayed whenever the data points are not connected by a line.
markerShape "auto" | "square" | "circle" | "diamond" | "human" | "plus" | "star" | "triangleDown" | "triangleUp" <optional>
 The shape of the data markers. Only applies to line, area, scatter, and bubble series. In addition to the built-in shapes, it may also take SVG path commands to specify a custom shape. The chart will style the custom shapes the same way as built-in shapes, supporting properties like color and borderColor and applying hover and selection effects. Only 'auto' is supported for range series.
markerSize number <optional>
 The size of the data markers. Only applies to line, area, and scatter series. Does not apply to bubble charts, which calculate marker size based on the z values.
seriesId string The id for the series the item belongs to.
shortDesc string <optional>
 TThe description of this object. This is used for accessibility and also for customizing the tooltip text.
value number The value for this data item. Null can be specified to skip a data point.

ChartGroupTemplateContext<K,D>

Properties:
Name Type Description
depth number The depth of the group. The depth of the outermost group under the invisible root is 1.
ids Array<string> The key of the current item.
index number The group index
items Array<object> The array of objects which are chart items that belong to this series. The objects will have the following properties

ChartItemTemplateContext<K,D>

Properties:
Name Type Description
data any The data object of the current item.
index number The zero-based index of the current item.
key any The key of the current item.

ChartLegend

The chart legend type.
Properties:
Name Type Argument Default Description
maxSize (number|string) <optional>
 The max size of the legend in pixels or in percentage.
position "auto" | "end" | "start" | "top" | "bottom" "auto" The position of the legend within the chart. By default, the legend will be placed on the side or bottom of the chart.
rendered "auto" | "off" | "on" "on" Defines whether the legend is rendered. If set to auto, the legend will be hidden for charts with a large bunber of series.
size (number|string) <optional>
 Defines the size of legend in pixel or percent.
symbolHeight number <optional>
 The height of the legend symbol (line or marker) in pixels.
symbolWidth number <optional>
 The width of the legend symbol (line or marker) in pixels.

ChartSeriesTemplateContext<K,D>

Properties:
Name Type Description
id string The series id
index number The series index
items Array<object> The array of objects which are chart items that belong to this series. The objects will have the following properties

Group

Properties:
Name Type Argument Description
accessibleLabel string <optional>
 The description of the group. This is used for the customizing the tooltip text and only applies to a categorical axis.
drilling "inherit" | "off" | "on" <optional>
 Whether drilling is enabled in the group label.
id string The id of the group.
name string <optional>
 The name of the group.

LineChartSeries<K>

Properties:
Name Type Argument Description
categories Array<string> <optional>
 An array of category strings corresponding to the tag cloud items. This allows highlighting and filtering of items.
color string <optional>
 The color of the series. The chart legend item will inherit this color value.
drilling "inherit" | "off" | "on" <optional>
 Whether drilling is enabled on the series item. Drillable objects will show a pointer cursor on hover and fire an ojDrill event on click (double click if selection is enabled). To enable drilling for all series items at once, use the drilling attribute in the top level.
items Array<object>
lineType "curved" | "straight" <optional>
 The line type of the data line or area. Only applies to line, area, scatter, and bubble series. centeredStepped and centeredSegmented are not supported for polar, scatter, and bubble charts.
markerColor string <optional>
 The color of the data markers, if different from the series color.
markerDisplayed string <optional>
 Defines whether the data marker is displayed. Only applies to line, area, scatter, and bubble series. If auto, the markers will be displayed whenever the data points are not connected by a line.
markerShape "auto" | "square" | "circle" | "diamond" | "human" | "plus" | "star" | "triangleDown" | "triangleUp" <optional>
 The shape of the data markers. In addition to the built-in shapes, it may also take SVG path commands to specify a custom shape. The chart will style the custom shapes the same way as built-in shapes, supporting properties like color and borderColor and applying hover and selection effects. Only 'auto' is supported for range series.
markerSize number <optional>
 The size of the data markers.
name string <optional>
 The name of the series, displayed in the legend and tooltips.
shortDesc string <optional>
 The description of this series. This is used for accessibility and for customizing the tooltip text on the corresponding legend item for the series.

PlotArea

Properties:
Name Type Argument Description
backgroundColor string <optional>
 The color of the plot area background.

ValueFormats

Properties:
Name Type Description
group object Object that specifies the value formatting and tooltip behavior for the group.
series object Object that specifies the value formatting and tooltip behavior for the series.
value object Object that specifies the value formatting and tooltip behavior for the item value.

XAxis

Properties:
Name Type Argument
majorTick object <optional>

YAxis

Properties:
Name Type Argument
majorTick object <optional>
minorTick object <optional>