Element: <oj-spark-chart>

Oracle® JavaScript Extension Toolkit (JET)
17.1.0
G12196-01

Since:
  • 0.7.0
Module:
  • ojchart

QuickNav

Slots

Attributes

Methods

Type Definitions

Other Topics


JET Spark Chart

Spark Chart component for JET with support for bar, line, area, and floating bar subtypes. Spark Charts are designed to visualize the trend of a data set in a compact form factor.

The SVG DOM that this component generates should be treated as a black box, as it is subject to change.


<oj-spark-chart
  type='line'
  items='[5, 8, 2, 7, 0, 9]'
>
</oj-spark-chart>

Touch End User Information

This element has no touch interaction.

Keyboard End User Information

This element has no keyboard interaction.

Performance

Tracking Resize

By default, the element will track resizes and render at the new size. This functionality adds a small overhead to the initial render for simple elements like gauges or spark charts, which become noticable when using large numbers of these simple elements. To disable resize tracking, set trackResize to off. The application can manually request a re-render at any time by calling the refresh function.

Accessibility

The application is responsible for populating the title attribute on the element with meaningful descriptors as the oj-spark-chart element does not provide a default descriptor.

Reading direction

As with any JET component, in the unusual case that the directionality (LTR or RTL) changes post-init, the component must be refresh()ed.


Usage

Signature:

interface SparkChartElement<K, D extends ojSparkChart.Item|any>

Generic Parameters
ParameterDescription
KType of key of the dataprovider
DType of data from the dataprovider
Typescript Import Format
//To typecheck the element APIs, import as below.
import { SparkChartElement } from "ojs/ojchart";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojchart";

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.

contextMenu

The contextMenu slot is set on the oj-menu within this element. This is used to designate the JET Menu that this component should launch as a context menu on right-click, Shift-F10, Press & Hold, or component-specific gesture. If specified, the browser's native context menu will be replaced by the JET Menu specified in this slot.

The application can register a listener for the Menu's ojBeforeOpen event. The listener can cancel the launch via event.preventDefault(), or it can customize the menu contents by editing the menu DOM directly, and then calling refresh() on the Menu.

To help determine whether it's appropriate to cancel the launch or customize the menu, the ojBeforeOpen listener can use component API's to determine which table cell, chart item, etc., is the target of the context menu. See the JSDoc of the individual components for details.

Keep in mind that any such logic must work whether the context menu was launched via right-click, Shift-F10, Press & Hold, or component-specific touch gesture.

Deprecated:
Since Description
13.0.0 This web component no longer supports launching a context menu.

itemTemplate

The itemTemplate slot is used to specify the template for creating each item of the spark chart when a DataProvider has been specified with the data attribute. The slot content must be a <template> element.

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

  • $current - an object that contains information for the current item. (See oj.ojSparkChart.ItemTemplateContext or the table below for a list of properties available on $current)
  • alias - if data-oj-as attribute was specified, the value will be used to provide an application-named alias for $current.

The content of the template should only be one <oj-spark-chart-item> element. See the oj-spark-chart-item doc for more details.

Properties of $current:
Name Type Description
componentElement Element The <oj-spark-chart> custom element.
data D The data object for the current item.
index number The zero-based index of the current item.
key K The key of the current item.

tooltipTemplate

The tooltipTemplate slot is used to specify custom tooltip content. This slot takes precedence over the tooltip.renderer property if specified.

When the template is executed, the component's binding context is extended with the following properties:

  • $current - an object that contains information for the spark chart. (See oj.ojSparkChart.TooltipContext or the table below for a list of properties available on $current)
Properties of $current:
Name Type Description
color string The color of the chart.
componentElement Element The spark chart element.
parentElement Element The tooltip element. The function can directly modify or append content to this element.

Attributes

(nullable) animation-duration :number

The duration of the animations in milliseconds. The default value comes from the CSS and varies based on theme.
Names
Item Name
Property animationDuration
Property change event animationDurationChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-animation-duration-changed

animation-on-data-change :"auto"|"none"

Defines the animation that is applied on data changes.
Supported Values:
Value Description
auto Animation on data change will be enabled.
none Animation on data change will be disabled.
Default Value:
  • "none"
Names
Item Name
Property animationOnDataChange
Property change event animationOnDataChangeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-animation-on-data-change-changed

animation-on-display :"auto"|"none"

Defines the animation that is shown on initial display.
Supported Values:
Value Description
auto Animation on display will be enabled.
none Animation on display will be disabled.
Default Value:
  • "none"
Names
Item Name
Property animationOnDisplay
Property change event animationOnDisplayChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-animation-on-display-changed

area-color :string

The color of the area in area or lineWithArea spark chart.
Default Value:
  • ""
Names
Item Name
Property areaColor
Property change event areaColorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-area-color-changed

area-svg-class-name :string

The CSS style class to apply if the type is area or lineWithArea. The style class and inline style will override any other styling specified through the properties. For tooltips and hover interactivity, it's recommended to also pass a representative color to the color attribute.
Default Value:
  • ""
Names
Item Name
Property areaSvgClassName
Property change event areaSvgClassNameChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-area-svg-class-name-changed

area-svg-style :Partial<CSSStyleDeclaration>

The inline style to apply if the type is area or lineWithArea. The style class and inline style will override any other styling specified through the properties. For tooltips and hover interactivity, it's recommended to also pass a representative color to the color attribute. Only SVG CSS style properties are supported.
Default Value:
  • {}
Names
Item Name
Property areaSvgStyle
Property change event areaSvgStyleChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-area-svg-style-changed

as :string

An alias for the $current context variable when referenced inside itemTemplate when using a DataProvider.
Deprecated:
Since Description
6.2.0 Set the alias directly on the template element using the data-oj-as attribute instead.
Default Value:
  • ''
Names
Item Name
Property as
Property change event asChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-as-changed

bar-gap-ratio :number

Specifies the width of the bar gap as a ratio of the item width. The valid value is a number from 0 to 1.
Default Value:
  • 0.25
Names
Item Name
Property barGapRatio
Property change event barGapRatioChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-bar-gap-ratio-changed

baseline-scaling :"zero"|"min"

Defines whether the axis baseline starts at the minimum value of the data or at zero.
Supported Values:
Value Description
min Axis baseline will start at the minimum value of the data.
zero Axis baseline will start at zero.
Default Value:
  • "min"
Names
Item Name
Property baselineScaling
Property change event baselineScalingChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-baseline-scaling-changed

color :string

The color of the data items. The default value varies based on theme.
Names
Item Name
Property color
Property change event colorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-color-changed

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

The DataProvider for the spark chart. It should provide rows where each row corresponds to a single spark chart item. The DataProvider can either have an arbitrary data shape, in which case an element must be specified in the itemTemplate slot or it can have oj.ojSparkChart.Item as its data shape, in which case no template is required.
Default Value:
  • null
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

first-color :string

The color of the first data item.
Default Value:
  • ""
Names
Item Name
Property firstColor
Property change event firstColorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-first-color-changed

high-color :string

The color of the data item with the greatest value.
Default Value:
  • ""
Names
Item Name
Property highColor
Property change event highColorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-high-color-changed

items :(Array.<oj.ojSparkChart.Item>|Array.<number>|Promise.<Array.<oj.ojSparkChart.Item>>|Promise.<Array.<number>>|null)

An array of objects with the following properties that define the data for the spark chart. Also accepts a Promise for deferred data rendering.
Type details
Setter Type(Array.<oj.ojSparkChart.Item>|Array.<number>|Promise.<Array.<oj.ojSparkChart.Item>>|Promise.<Array.<number>>|null)
Getter Type(Promise.<Array.<oj.ojSparkChart.Item>>|Promise.<Array.<number>>|null)
Default Value:
  • null
Names
Item Name
Property items
Property change event itemsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-items-changed

last-color :string

The color of the last data item.
Default Value:
  • ""
Names
Item Name
Property lastColor
Property change event lastColorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-last-color-changed

line-style :"dotted"|"dashed"|"solid"

The line style of the data line. Only applies to line spark charts.
Supported Values:
Value Description
dashed Line will have dashed strokes.
dotted Line will have dotted strokes.
solid Line will have a solid stroke.
Default Value:
  • "solid"
Names
Item Name
Property lineStyle
Property change event lineStyleChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-line-style-changed

line-type :"curved"|"stepped"|"centeredStepped"|"segmented"|"centeredSegmented"|"none"|"straight"

The line type of the data line or area. Only applies to line and area spark charts.
Supported Values:
Value Description
centeredSegmented Data points will be connected with a centered segmented line.
centeredStepped Data points will be connected with a centered stepped line.
curved Data points will be connected with a curved line.
none Data points will not be connected.
segmented Data points will be connected with a segmented line.
stepped Data points will be connected with a stepped line.
straight Data points will be connected with a straight line.
Default Value:
  • "straight"
Names
Item Name
Property lineType
Property change event lineTypeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-line-type-changed

line-width :number

The width of the data line in pixels. Only applies to line spark charts.
Default Value:
  • 1
Names
Item Name
Property lineWidth
Property change event lineWidthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-line-width-changed

low-color :string

The color of the data item with the lowest value.
Default Value:
  • ""
Names
Item Name
Property lowColor
Property change event lowColorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-low-color-changed

marker-shape :"auto"|"circle"|"diamond"|"human"|"plus"|"square"|"star"|"triangleDown"|"triangleUp"|string

The shape of the data markers. Can take the name of a built-in shape or the SVG path commands for a custom shape. Only applies to line and area spark charts.
Default Value:
  • "auto"
Names
Item Name
Property markerShape
Property change event markerShapeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-marker-shape-changed

marker-size :number

The size of the data markers in pixels. Only applies to line and area spark charts.
Default Value:
  • 5
Names
Item Name
Property markerSize
Property change event markerSizeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-marker-size-changed

reference-objects :Array.<oj.ojSparkChart.ReferenceObject>

An array of objects with the following properties defining the reference objects associated with the y axis of the spark chart.
Default Value:
  • []
Names
Item Name
Property referenceObjects
Property change event referenceObjectsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-reference-objects-changed

svg-class-name :string

The CSS style class to apply to the data items. For type lineWithArea, this style will only be applied to the line if areaSvgClassName is also specified. The style class and inline style will override any other styling specified through the properties. For tooltips, it's recommended to also pass a representative color to the color attribute.
Default Value:
  • ""
Names
Item Name
Property svgClassName
Property change event svgClassNameChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-svg-class-name-changed

svg-style :Partial<CSSStyleDeclaration>

The inline style to apply to the data items. For type lineWithArea, this style will only be applied to the line if areaSvgStyle is also specified. The style class and inline style will override any other styling specified through the properties. For tooltips, it's recommended to also pass a representative color to the color attribute. Only SVG CSS style properties are supported.
Default Value:
  • {}
Names
Item Name
Property svgStyle
Property change event svgStyleChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-svg-style-changed

tooltip :Object

An object containing an optional callback function for tooltip customization.
Names
Item Name
Property tooltip
Property change event tooltipChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-tooltip-changed

tooltip.renderer :((context: ojSparkChart.TooltipContext) => ({insert: Element|string}|{preventDefault: boolean}))|null

A function that returns a custom tooltip. The function takes a dataContext argument, provided by the chart, with the following properties:
  • parentElement: The tooltip element. The function can directly modify or append content to this element.
  • color: The color of the chart.
  • componentElement: The spark chart element.
The function should return an Object that contains only one of the two properties:
  • insert: HTMLElement | string - An HTML element, which will be appended to the tooltip, or a tooltip string.
  • preventDefault: true - Indicates that the tooltip should not be displayed. It is not necessary to return {preventDefault:false} to display tooltip, since this is a default behavior.
Default Value:
  • null
Names
Item Name
Property tooltip.renderer

track-resize :"on"|"off"

Defines whether the element will automatically render in response to changes in size. If set to off, then the application is responsible for calling refresh to render the element at the new size.
Supported Values:
Value
off
on
Default Value:
  • "on"
Names
Item Name
Property trackResize
Property change event trackResizeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-track-resize-changed

translations :object|null

A collection of translated resources from the translation bundle, or null if this component has no resources. Resources may be accessed and overridden individually or collectively, as seen in the examples.

If the component does not contain any translatable resource, the default value of this attribute will be null. If not, an object containing all resources relevant to the component.

If this component has translations, their documentation immediately follows this doc entry.

Names
Item Name
Property translations
Property change event translationsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-translations-changed

(nullable) translations.accessible-contains-controls :string

Used to describe a container that contains controls.

See the translations attribute for usage examples.

Since:
  • 13.0.0
Names
Item Name
Property translations.accessibleContainsControls

(nullable) translations.component-name :string

Used to describe the data visualization type for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Chart"
Names
Item Name
Property translations.componentName

(nullable) translations.label-and-value :string

Used to display a label and its value.

See the translations attribute for usage examples.

Default Value:
  • "{0}: {1}"
Names
Item Name
Property translations.labelAndValue

(nullable) translations.label-clear-selection :string

Text shown for clearing multiple selection on touch devices.

See the translations attribute for usage examples.

Default Value:
  • "Clear Selection"
Names
Item Name
Property translations.labelClearSelection

(nullable) translations.label-count-with-total :string

Used to display a count out of a total.

See the translations attribute for usage examples.

Default Value:
  • "{0} of {1}"
Names
Item Name
Property translations.labelCountWithTotal

(nullable) translations.label-data-visualization :string

Label for data visualizations used for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Data Visualization"
Names
Item Name
Property translations.labelDataVisualization

(nullable) translations.label-invalid-data :string

Text shown when the component receives invalid data.

See the translations attribute for usage examples.

Default Value:
  • "Invalid data"
Names
Item Name
Property translations.labelInvalidData

(nullable) translations.label-no-data :string

Text shown when the component receives no data.

See the translations attribute for usage examples.

Default Value:
  • "No data to display"
Names
Item Name
Property translations.labelNoData

(nullable) translations.state-collapsed :string

Used to describe the collapsed state for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Collapsed"
Names
Item Name
Property translations.stateCollapsed

(nullable) translations.state-drillable :string

Used to describe a drillable object for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Drillable"
Names
Item Name
Property translations.stateDrillable

(nullable) translations.state-expanded :string

Used to describe the expanded state for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Expanded"
Names
Item Name
Property translations.stateExpanded

(nullable) translations.state-hidden :string

Used to describe the hidden state for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Hidden"
Names
Item Name
Property translations.stateHidden

(nullable) translations.state-isolated :string

Used to describe the isolated state for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Isolated"
Names
Item Name
Property translations.stateIsolated

(nullable) translations.state-maximized :string

Used to describe the maximized state for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Maximized"
Names
Item Name
Property translations.stateMaximized

(nullable) translations.state-minimized :string

Used to describe the minimized state for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Minimized"
Names
Item Name
Property translations.stateMinimized

(nullable) translations.state-selected :string

Used to describe the selected state for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Selected"
Names
Item Name
Property translations.stateSelected

(nullable) translations.state-unselected :string

Used to describe the unselected state for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Unselected"
Names
Item Name
Property translations.stateUnselected

(nullable) translations.state-visible :string

Used to describe the visible state for accessibility.

See the translations attribute for usage examples.

Default Value:
  • "Visible"
Names
Item Name
Property translations.stateVisible

type :"area"|"lineWithArea"|"bar"|"line"

The chart type.
Supported Values:
Value Description
area Series will be represented by an area. Use lineWithArea to prevent values from being obscured.
bar Data items will be represented by bars.
line Series will be represented by a line.
lineWithArea Series will be presented by a line and area.
Default Value:
  • "line"
Names
Item Name
Property type
Property change event typeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-type-changed

visual-effects :"none"|"auto"

Defines whether visual effects such as overlays are applied to the spark chart.
Supported Values:
Value Description
auto Overlays and gradients could be applied to the spark chart.
none No overlays are applied to the spark chart.
Default Value:
  • "auto"
Names
Item Name
Property visualEffects
Property change event visualEffectsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-visual-effects-changed

Methods

getDataItem(itemIndex) : {(oj.ojSparkChart.ItemContext|null)}

Returns an object with the following properties for automation testing verification of the data item with the specified item index.
Parameters:
Name Type Description
itemIndex number The item index
Deprecated:
Since Description
7.0.0 The use of this function is no longer recommended.
Properties:
Name Type Description
borderColor string The border color of the item
color string The color of the item
date Date The date (x value) of the item
high number The high value for a range item
low number The low value for a range item
value number The value of the item
Returns:

An object containing properties for the data item, or null if none exists.

Type
(oj.ojSparkChart.ItemContext|null)

getProperty(property) : {any}

Retrieves the value of a property or a subproperty. The return type will be the same as the type of the property as specified in this API document. If the method is invoked with an incorrect property/subproperty name, it returns undefined.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Since:
  • 4.0.0
Returns:
Type
any
Example

Get a single subproperty of a complex property:

let subpropValue = myComponent.getProperty('complexProperty.subProperty1.subProperty2');

refresh : {void}

Refreshes the component.
Returns:
Type
void

setProperties(properties) : {void}

Performs a batch set of properties. The type of value for each property being set must match the type of the property as specified in this API document.
Parameters:
Name Type Description
properties Object An object containing the property and value pairs to set.
Since:
  • 4.0.0
Returns:
Type
void
Example

Set a batch of properties:

myComponent.setProperties({"prop1": "value1", "prop2.subprop": "value2", "prop3": "value3"});

setProperty(property, value) : {void}

Sets a property or a subproperty (of a complex property) and notifies the component of the change, triggering a [property]Changed event. The value should be of the same type as the type of the attribute mentioned in this API document.
Parameters:
Name Type Description
property string The property name to set. Supports dot notation for subproperty access.
value any The new value to set the property to.
Since:
  • 4.0.0
Returns:
Type
void
Example

Set a single subproperty of a complex property:

myComponent.setProperty('complexProperty.subProperty1.subProperty2', "someValue");

Type Definitions

Item

Properties:
Name Type Argument Default Description
borderColor string <optional>
 The default border color for the data items.
color string <optional>
 The color of the bar or marker for the data item. This override can be used to highlight important values or thresholds.
date Date <optional>
 The date for the data item. The date should only be specified if the interval between data items is irregular.
high number <optional>
 The high value for range bar/area. Define 'low' and 'high' instead of 'value' to create a range bar/area spark chart.
low number <optional>
 The low value for range bar/area. Define 'low' and 'high' instead of 'value' to create a range bar/area spark chart.
markerDisplayed "on" | "off" <optional>
 "off" Defines whether a marker should be displayed for the data item. Only applies to line and area spark charts.
markerShape "square" | "circle" | "diamond" | "plus" | "triangleDown" | "triangleUp" | "human" | "star" | "auto" | string <optional>
 "auto" The shape of the data markers. Can take the name of a built-in shape or the SVG path commands for a custom shape. Only applies to line and area spark charts.
markerSize number <optional>
 The size of the data markers in pixels. Only applies to line and area spark charts.
svgClassName string <optional>
 The CSS style class to apply to the data item. The style class and inline style will override any other styling specified through the properties. For tooltips and hover interactivity, it's recommended to also pass a representative color to the item color attribute.
svgStyle Partial<CSSStyleDeclaration> <optional>
 The inline style to apply to the data item. The style class and inline style will override any other styling specified through the properties. For tooltips and hover interactivity, it's recommended to also pass a representative color to the item color attribute. Only SVG CSS style properties are supported.
value number <optional>
 The value of the data item.

ItemContext

Properties:
Name Type Description
borderColor string The border color of the item
color string The color of the item
date Date The date (x value) of the item
high number The high value for a range item
low number The low value for a range item
value number The value of the item

ItemTemplateContext<K = any,D = any>

Properties:
Name Type Description
componentElement Element The <oj-spark-chart> custom element.
data D The data object for the current item.
index number The zero-based index of the current item.
key K The key of the current item.

ReferenceObject

Properties:
Name Type Argument Default Description
color string <optional>
 The color of the reference object.
high number <optional>
 The high value of a reference area.
lineStyle "dotted" | "dashed" | "solid" <optional>
 "solid" The line style of a reference line.
lineWidth number <optional>
 The width of a reference line.
location "front" | "back" <optional>
 "back" The location of the reference object relative to the data items.
low number <optional>
 The low value of a reference area.
svgClassName string <optional>
 The CSS style class to apply to the reference object. The style class and inline style will override any other styling specified through the properties.
svgStyle Partial<CSSStyleDeclaration> <optional>
 The inline style to apply to the reference object. The style class and inline style will override any other styling specified through the properties. Only SVG CSS style properties are supported.
type "area" | "line" <optional>
 "line" The type of reference object being shown.
value number <optional>
 The value of a reference line.

TooltipContext

Properties:
Name Type Description
color string The color of the chart.
componentElement Element The spark chart element.
parentElement Element The tooltip element. The function can directly modify or append content to this element.