Element: <oj-c-tag-cloud>

CORE PACK

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

Since:
  • 15.0.0
Module:
  • tag-cloud

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

Documentation-only Types

Other Topics


JET Tag Cloud

*

Tag clouds are used to display text data with the importance of each tag shown with font size or color.


<oj-c-tag-cloud
  data="[[dataProvider]]">
</oj-c-tag-cloud>

When using font colors as a data dimension for tag clouds, the application needs to ensure that they meet minimum contrast requirements. Not all colors in the default value ramp provided by oj.ColorAttributeGroupHandler will meet 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.
Enter Open a link when the url for a data item is set.
Shift+F10 Launch the context menu if there is one associated with the current item.

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 using colors as a data dimension for tag clouds, the application needs to ensure that they meet minimum contrast requirements.

Performance

Shaped Data

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

Layout

Rectangular layouts are faster than cloud layouts and are recommended for larger data sets.

Touch End User Information

Target Gesture Action
Data Item Tap Select when selectionMode is enabled.
Open a link when the url for a data item is set.
Press & Hold Display context menu on release.
Background Press & Hold Display context menu on release.


Usage

Signature:

interface CTagCloudElement<K extends string | number,D extends oj-c.TagCloud.Item<K> | any>

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

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

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. The slot content must be a single <template> element.

When the template is executed for each area, it will have access to the tag cloud's binding context and 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 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-c-tag-cloud-item> element. See the oj-tag-cloud-item doc for more details.

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.

Attributes

context-menu-config :oj-c.TagCloud.TagCloudContextMenuConfig.<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)

Specifies the DataProvider for the sections and items of the tag-cloud.
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

datatip :(context: oj-c.TagCloud.DatatipContext<K>) => string

The tagcloud datatip string.
Names
Item Name
Property datatip
Property change event datatipChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-datatip-changed

hidden-categories :Array<string>

An array of category strings used for highlighting. Data items matching categories in this array will be highlighted.
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

highlight-match :"all"|"any"

The matching condition for the highlightedCategories option. 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:
  • "all"
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 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 tagcloud 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

layout :"cloud"|"rectangular"

The layout to use for tag display.
Supported Values:
Value Description
cloud Items will be horizontally placed in available space.
rectangular Items will be vertically stacked.
Default Value:
  • "rectangular"
Names
Item Name
Property layout
Property change event layoutChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-layout-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

touch-response :"auto"|"touchStart"

Data visualizations require a press and hold delay before triggering tooltips and rollover effects on mobile devices to avoid interfering with page panning, but these hold delays can make applications seem slower and less responsive. For a better user experience, the application can remove the touch and hold \delay when data visualizations are used within a non scrolling container or if there is sufficient space outside of the visualization for panning. If touchResponse is touchStart the element will instantly trigger the touch gesture and consume the page pan events. If touchResponse is auto, the element will behave like touchStart if it determines that it is not rendered within scrolling content and if element panning is not available for those elements that support the feature.
Names
Item Name
Property touchResponse
Property change event touchResponseChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-touch-response-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.TagCloud.Item<K>; itemData?: D; 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.TagCloud.Item<K>; itemData?: D; type: 'item'; }
menuSelectionGroupKey string
value string|Array<string>

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.TagCloud.MenuItem|oj-c.TagCloud.ContextMenuSeparator|oj-c.TagCloud.ContextMenuSubMenu|oj-c.TagCloud.ContextMenuSelectSingle|oj-c.TagCloud.ContextMenuSelectMultiple)

ContextMenuSelectMultiple

Properties:
Name Type Argument Description
items Array.<oj-c.TagCloud.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.TagCloud.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.TagCloud.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.TagCloud.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.TagCloud.MenuItem | oj-c.TagCloud.ContextMenuSeparator | oj-c.TagCloud.ContextMenuSubMenu | oj-c.TagCloud.ContextMenuSelectSingle | oj-c.TagCloud.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.

DatatipContext<K>

Context for datatip function.
Properties:
Name Type Description
id K The id of the currently active tag cloud item.

Item<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 text. Will be overridden by any color defined in the style option. The default value comes from the CSS and varies based on theme.
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.
label string The text of the item.
shortDesc string <optional>
 The description of the item. This is used for customizing the tooltip text.
url string <optional>
 The url this item references.
value (number|null) The value of this item is used to scale its font size within the tag cloud.
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.

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

Properties:
Name Type
menuSelectionGroupKey string
value T

TagCloudContextMenuConfig<K,D>

Properties:
Name Type Argument
accessibleLabel string <optional>
items (context: TagcloudContextMenuContext<K, D>) => Array<oj-c.TagCloud.ContextMenuItems>