Element: <oj-c-legend>

CORE PACK

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

Since:
  • 15.0.0
Module:
  • legend

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

Other Topics


JET Legend

A legend displays an interactive description of symbols, colors, etc used in graphical information representations. 
<oj-c-legend orientation='vertical' data='[[dataProvider]]'></oj-c-legend>

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

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

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.

In the case of the text truncating, applications should provide the untruncated string or contextual text to the datatip to make the component accessible.

Performance

Shaped Data

As a rule of thumb, it's recommended that applications use shaped data if possible for performance gains.

Keyboard

Key Action
Tab Move focus to next element.
Shift + Tab Move focus to previous element.
UpArrow Move focus to previous item.
DownArrow Move focus to next item.
LeftArrow Move focus to previous item (on left).
RightArrow Move focus to next item (on right).
Enter or Space Hides or unhides the data associated with the current item.

Touch End User Information

Target Gesture Action
Legend Item Tap Filter when hideAndShowBehavior is enabled.


Usage

Signature:

interface CLegendElement<K extends string | number,D extends oj-c.Legend.Item<K> | oj-c.Legend.Section<K> | any>

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

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

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.

itemTemplate

The itemTemplate slot is used to specify the template for creating items of the legend. The slot content must be wrapped in a <template> element. The content of the template should be a single <oj-c-legend-item> element. See the oj-c-legend-item doc for more details.

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

  • $current - an object that contains information for the current node. (See 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.
Properties of $current:
Name Type Argument Description
data D The data object of the current item.
index number The zero-based index of the current item relative to the parent.
key K The key of the current item.
parentData Array<D> <optional>
 An array of data objects of the outermost to innermost parents of the node
parentKey K <optional>
 The key of the parent node

sectionTemplate

The sectionTemplate slot is used to specify the template for creating sections of the legend. The slot content must be wrapped in a <template> element. The content of the template should be a single <oj-c-legend-section> element. See the oj-c-legend-section doc for more details.

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

  • $current - an object that contains information for the current node. (See 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.
Properties of $current:
Name Type Description
data D The data object of the current section.
index number The zero-based index of the current section.
key K The key of the current section.

Attributes

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

The DataProvider for the sections and items of the legend. It should provide a data tree where each node in the data tree corresponds to a section or item in the legend. Nodes that are leaves will be treated as items. The row key will be used as the id for legend sections and items. The DataProvider can either have data shape specified by oj-c-legend-item (or oj-c-legend-section) as its data shape, in which case no template is required or it can have an arbitrary data shape, in which case an oj-c-legend-item element (and oj-c-legend-section element for hierarchical data) must be specified in the itemTemplate (and sectionTemplate) slot
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

drilling :"on"|"off"

Whether drilling is enabled on all legend items. Drillable objects will show a background opacity, a pointer cursor on hover, and fire ojDrill event on click.
Supported Values:
Value Description
off Legend items will not be drillable
on Legend items will be drillable
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

halign :"center"|"end"|"start"

Defines the horizontal alignment of the legend contents.
Supported Values:
Value Description
center Legend contents will be center aligned
end Legend contents will be end aligned
start Legend contents will be start aligned
Default Value:
  • "start"
Names
Item Name
Property halign
Property change event halignChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-halign-changed

hidden-categories :Array.<string>

An array of categories that will be hidden.
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 :"on"|"off"

Defines whether the legend can be used to initiate hide and show behavior on referenced data items.
Supported Values:
Value Description
off legend cannot be used to initiate hide and show behavior on referenced data items.
on Legend can be used to initiate hide and show behavior on referenced data items.
Default Value:
  • "off"
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

highlighted-categories :Array.<string>

An array of categories that 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 :"dim"|"none"

Defines the behavior applied when hovering over a legend item.
Supported Values:
Value Description
dim Dimming hover behavior is applied.
none No hover behavior will be applied.
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

orientation :"horizontal"|"vertical"

Defines the orientation of the legend, which determines the direction in which the legend items are laid out.
Supported Values:
Value Description
horizontal Legend items will be horizontally placed in available space.
vertical Legend items will be vertically stacked.
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

section-title-halign :"center"|"end"|"start"

The horizontal alignment of the section titles.
Supported Values:
Value Description
center The section title will be center aligned.
end The section title will be end aligned.
start The section title will be start aligned.
Default Value:
  • "start"
Names
Item Name
Property sectionTitleHalign
Property change event sectionTitleHalignChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-section-title-halign-changed

section-title-style :Partial<Pick<CSSStyleDeclaration, "color" | "fontFamily" | "fontSize" | "fontStyle" | "fontWeight" | "textDecoration">>

The CSS style object defining the style of the section titles' text. The following style properties are supported: color, fontFamily, fontSize, fontStyle, fontWeight, textDecoration
Names
Item Name
Property sectionTitleStyle
Property change event sectionTitleStyleChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-section-title-style-changed

section-title-style.color :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/color)
Names
Item Name
Property sectionTitleStyle.color

section-title-style.font-family :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-family)
Names
Item Name
Property sectionTitleStyle.fontFamily

section-title-style.font-size :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-size)
Names
Item Name
Property sectionTitleStyle.fontSize

section-title-style.font-style :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-style)
Names
Item Name
Property sectionTitleStyle.fontStyle

section-title-style.font-weight :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-weight)
Names
Item Name
Property sectionTitleStyle.fontWeight

section-title-style.text-decoration :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/text-decoration)
Names
Item Name
Property sectionTitleStyle.textDecoration

symbol-height :number

The height of the legend symbol in pixels. If the value is 0, it will take the same value as symbolWidth. If both symbolWidth and symbolHeight are 0, then it will use a default value that may vary based on theme.
Default Value:
  • 0
Names
Item Name
Property symbolHeight
Property change event symbolHeightChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-symbol-height-changed

symbol-width :number

The width of the legend symbol in pixels. If the value is 0, it will take the same value as symbolHeight. If both symbolWidth and symbolHeight are 0, then it will use a default value that may vary based on theme
Default Value:
  • 0
Names
Item Name
Property symbolWidth
Property change event symbolWidthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-symbol-width-changed

text-style :Partial<Pick<CSSStyleDeclaration, "color" | "fontFamily" | "fontSize" | "fontStyle" | "fontWeight" | "textDecoration">>

The CSS style object defining the style of the legend item text.
Names
Item Name
Property textStyle
Property change event textStyleChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-text-style-changed

text-style.color :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/color)
Names
Item Name
Property textStyle.color

text-style.font-family :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-family)
Names
Item Name
Property textStyle.fontFamily

text-style.font-size :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-size)
Names
Item Name
Property textStyle.fontSize

text-style.font-style :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-style)
Names
Item Name
Property textStyle.fontStyle

text-style.font-weight :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-weight)
Names
Item Name
Property textStyle.fontWeight

text-style.text-decoration :string

[MDN Reference](https://developer.mozilla.org/docs/Web/CSS/text-decoration)
Names
Item Name
Property textStyle.textDecoration

valign :"middle"|"bottom"|"top"

Defines the vertical alignment of the legend contents.
Supported Values:
Value Description
bottom The legend items will be bottom aligned.
middle The legend items will be middle aligned.
top The legend items will be top aligned.
Default Value:
  • "top"
Names
Item Name
Property valign
Property change event valignChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-valign-changed

Events

ojDrill

Triggered during a drill gesture (single click on the legend item).
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 item

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

Item<K>

Object type that defines a legend data item.
Properties:
Name Type Argument Description
borderColor string <optional>
 The border color of the marker. Only applies if symbolType is "marker" or "lineWithMarker
categories Array<string> <optional>
 An array of categories for the legend item. Legend items currently only support a single category.
color string <optional>
 The color of the legend symbol (line or marker). When symbolType is "lineWithMarker", this attribute defines the line color and the markerColor attribute defines the marker color.
drilling "inherit" | "off" | "on" <optional>
 Whether drilling is enabled on the legend item. Drillable objects will show a pointer cursor on hover and fire ojDrill event on click. To enable drilling for all legend items at once, use the drilling attribute in the top level.
id K The id of the legend item.
lineStyle "dashed" | "solid" | "dotted" <optional>
 The line style. Only applies when the symbolType is "line" or "lineWithMarker".
lineWidth number <optional>
 The line width in pixels. Only applies when the symbolType is "line" or "lineWithMarker.
markerColor string <optional>
 The color of the marker, if different than the line color. Only applies if the symbolType is "lineWithMarker".
markerShape "square" | "circle" | "ellipse" | "diamond" | "human" | "plus" | "star" | "triangleDown" | "triangleUp" | "rectangle" <optional>
 The shape of the marker. Only applies if symbolType is "marker" or "lineWithMarker". Does not apply if a custom image is specified.
shortDesc string <optional>
 The description of this legend item. This is used for accessibility and for customizing the tooltip text.
source string <optional>
 The URI of the image of the legend symbol.
symbolType "marker" | "image" | "line" | "lineWithMarker" <optional>
 The type of legend symbol to display.
text string The legend item text. Also used as item aria label if short-desc is not provided.

Section<K>

Object type that defines a section data item.
Properties:
Name Type Description
id K The id of the legend section. For the DataProvider case, the key for the node will be used as the id.
items Array.<oj-c.Legend.Item.<K>> The id of the legend section. For the DataProvider case, the key for the node will be used as the id.
title string The title of the legend section.