Element: <oj-c-legend>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
19.0.0
G25385-01

Since:
  • 15.0.0
Module:
  • legend

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

Documentation-only Types

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.
Shift+F10 Launch the context menu if there is one associated with the current item.

Touch End User Information

Target Gesture Action
Legend Item Tap Filter when hideAndShowBehavior is enabled.
Press & Hold Display context menu on release.
Background Press & Hold Display context menu on release.


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

context-menu-config :oj-c.Legend.LegendContextMenuConfig.<K, D>

Specifies a context menu configuration. It takes the keys `accessibleLabel` and `items`, where `accessibleLabel` is optional and items required .`items` function returns an array of menu item object representations that indicates what menu items are going to be part of menu based on some specific context menu context.
Context Menu Item TypeDef
ContextMenuSeparator{ type: 'separator'}
MenuItem{ type?: 'item'; label: string; key: string; disabled?: boolean; onAction?: () => void; startIcon?: MenuIcon; endIcon?: MenuIcon; variant?: 'standard' | 'destructive'; };
ContextMenuSubMenu{ type: 'submenu'; label?: string; disabled?: boolean; startIcon?: string; items?: Array<ContextMenuItems>; };
ContextMenuSelectSingle{ type: 'selectsingle'; key?: string; items?: Array<MenuSelectItem>; selection?: string; onSelection?: (detail: { value: string }) => void; };
ContextMenuSelectMultiple{ type: 'selectmultiple'; key?: string; items?: Array<MenuSelectItem>; selection?: Array<string>; onSelection?: (detail: { value: Array<string> }) => void; };
MenuIcon{ type?: 'class'; class: string; } | { type: 'img'; src: string; };
MenuSelectItem{ label: string; disabled?: boolean; endIcon?: MenuIcon; value: string; }
Names
Item Name
Property contextMenuConfig
Property change event contextMenuConfigChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-context-menu-config-changed

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

ojContextMenuAction

Triggered when a menu item is clicked, whether by keyboard, mouse, or touch events.
Properties:

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

Name Type
contextMenuContext { type: 'background'; } | { data?: oj-c.Legend.Item<K>; itemData?: D; itemIndexPath: Array<number>; type: 'item'; }
menuItemKey string

ojContextMenuSelection

Triggered when a select menu item is clicked, whether by keyboard, mouse, or touch events.
Properties:

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

Name Type
contextMenuContext { type: 'background'; } | { data?: oj-c.Legend.Item<K>; itemData?: D; itemIndexPath: Array<number>; type: 'item'; }
menuSelectionGroupKey string
value string|Array<string>

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 string 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 object 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 string The property name to set. Supports dot notation for subproperty access.
value any The new value to set the property to.
Returns:
Type
void

Type Definitions

Documentation-only Types

Note: Type definitions in this section have been provided for documentation purposes and cannot be imported into application code.

ContextMenuItems :(oj-c.Legend.MenuItem|oj-c.Legend.ContextMenuSeparator|oj-c.Legend.ContextMenuSubMenu|oj-c.Legend.ContextMenuSelectSingle|oj-c.Legend.ContextMenuSelectMultiple)

ContextMenuSelectMultiple

Properties:
Name Type Argument Description
items Array.<oj-c.Legend.MenuSelectItem> <optional>
 Specifies the array of select items that make up the select multiple.
key string A unique key associated with the select multiple.
onSelection (detail: oj-c.Legend.SelectMenuItemDetail<string[]>) => void <optional>
selection Array<string> <optional>
type "selectmultiple" Specifies a select multiple menu item.

ContextMenuSelectSingle

Properties:
Name Type Argument Description
items Array.<oj-c.Legend.MenuSelectItem> <optional>
 Specifies the array of select items that make up the select single.
key string A unique key associated with the select single.
onSelection (detail: oj-c.Legend.SelectMenuItemDetail<string>) => void <optional>
selection string <optional>
type "selectsingle" Specifies a select single menu item.

ContextMenuSeparator

Properties:
Name Type
type "separator"

ContextMenuSubMenu

Properties:
Name Type Argument Description
disabled boolean <optional>
 Specifies if the submenu is disabled (enabled by default).
items Array<string | oj-c.Legend.MenuItem | oj-c.Legend.ContextMenuSeparator | oj-c.Legend.ContextMenuSubMenu | oj-c.Legend.ContextMenuSelectSingle | oj-c.Legend.ContextMenuSelectMultiple> <optional>
key string <optional>
 A unique key associated with the submenu menu item.
label string <optional>
 The submenu label.
startIcon string <optional>
 Optional icon to render at the start of the submenu.
type "submenu" Specifies a submenu menu item.

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.

LegendContextMenuConfig<K,D>

Properties:
Name Type Argument
accessibleLabel string <optional>
items (context: LegendContextMenuContext<K, D>) => Array<oj-c.Legend.ContextMenuItems>
Specifies a standard menu item.
Properties:
Name Type Argument Description
disabled boolean <optional>
 Specifies if the menu item is disabled (enabled by default).
endIcon { type?: 'class'; class: string; } | { type: 'img'; src: string; } <optional>
 Optional icon to render at the end of the menu item.
key string A unique key associated with the menu item.
label string The menu item label.
onAction function <optional>
 Optional callback function associated with the menu item.
startIcon { type?: 'class'; class: string; } | { type: 'img'; src: string; } <optional>
 Optional icon to render at the start of the menu item.
type "item" <optional>
 Specifies a standard menu item.
variant "standard" | "destructive" <optional>
 Specifies the menu item behavior.
Properties:
Name Type Description
at (index: number) => string | undefined Takes an integer value and returns the item at that index, allowing for positive and negative integers. Negative integers count back from the last item in the array.
Specifies a selectable item in a menu item.
Properties:
Name Type Argument Description
disabled boolean <optional>
 Specifies if the selectable item is disabled (enabled by default).
endIcon { type?: 'class'; class: string; } | { type: 'img'; src: string; } <optional>
 Optional icon to render at the end of the selectable item.
label string The selectable item label.
value string The value associated with the selectable item.

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.

SelectMenuItemDetail<T extends oj-c.Legend.MenuSelection>

Properties:
Name Type
menuSelectionGroupKey string
value T