Usage
Signature:
interface TagCloudElement<K, D extends ojTagCloud.Item<K>|any>
Generic Parameters
Parameter Description K Type of key of the dataprovider D Type of data from the dataprovider
Typescript Import Format
//To typecheck the element APIs, import as below.
import { TagCloudElement } from "ojs/ojtagcloud";
//For the transpiled javascript to load the element's module, import as below
import "ojs/ojtagcloud";
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.
-
itemTemplate
-
The
itemTemplate
slot is used to specify the template for creating each item of the tag cloud. The slot content must be a single <template> element.When the template is executed for each item, 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 oj.ojTagCloud.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-tag-cloud-item> element. See the oj-tag-cloud-item doc for more details.
- Deprecated:
-
Since Description 16.0.0
The componentElement property is deprecated. This shouldn't be needed, as the component template with access to this context is unique to the component.
Properties of $current:
Name Type Description componentElement
Element The <oj-tag-cloud> custom element. data
Object 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. The slot content must be a single <template> element. 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 current item. (See oj.ojTagCloud.TooltipContext or the table below for a list of properties available on $current)
- Deprecated:
-
Since Description 16.0.0
The componentElement property is deprecated. This shouldn't be needed, as the component template with access to this context is unique to the component.
Properties of $current:
Name Type Description color
string The color of the hovered item. componentElement
Element The tag cloud element. id
K The id of the hovered item. label
string The data label of the hovered item. parentElement
Element The tooltip element. The function can directly modify or append content to this element. value
number The value of the hovered item.
Attributes
-
animation-on-data-change :"auto"|"none"
-
Specifies the animation that is applied on data changes.
- Default Value:
"none"
Supported Values:
Value auto
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"
-
Specifies the animation that is shown on initial display.
- Default Value:
"none"
Supported Values:
Value auto
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
-
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
-
data :(DataProvider.<K, D>|null)
-
The DataProvider for the tag cloud. It should provide rows where each row corresponds to a single tag cloud 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.ojTagCloud.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
-
hidden-categories :Array.<string>
-
An array of category strings used for category filtering. Data items with a category in hiddenCategories will be filtered.
- 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 :"any"|"all"
-
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"
Supported Values:
Value all
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. 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 :"dim"|"none"
-
Defines the behavior applied when hovering over data items.
- Default Value:
"none"
Supported Values:
Value dim
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
-
items :(Array.<oj.ojTagCloud.Item.<K>>|Promise.<Array.<oj.ojTagCloud.Item.<K>>>|null)
-
An array of objects with the following properties that defines the data items for the tag cloud items. Also accepts a Promise or callback function for deferred data rendering. The function should return one of the following:
- Promise: A Promise that will resolve with an array of data items. No data will be rendered if the Promise is rejected.
- Array: An array of data items.
Type details
Setter Type (Array.<oj.ojTagCloud.Item.<K>>|Promise.<Array.<oj.ojTagCloud.Item.<K>>>|null) Getter Type (Promise.<Array.<oj.ojTagCloud.Item.<K>>>|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
-
layout :"cloud"|"rectangular"
-
The layout to use for tag display.
- Default Value:
"rectangular"
Supported Values:
Value cloud
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"|"single"|"multiple"
-
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.
If
single
ormultiple
is specified, selection gestures will be enabled, and the tag cloud's selection styling will be applied to all items specified by the selection attribute. Ifnone
is specified, selection gestures will be disabled, and the tag cloud's selection styling will not be applied to any items specified by the selection attribute.Changing the value of this attribute will not affect the value of the selection attribute.
- Default Value:
"none"
Supported Values:
Value Description multiple
Multiple items can be selected at the same time. none
Selection is disabled. single
Only a single item can be selected at a time. 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
-
style-defaults :Object
-
Component CSS classes should be used to set component wide styling. This API should be used only for styling a specific instance of the component. Properties specified on this object may be overridden by specifications on the data item. Some property default values come from the CSS and varies based on theme.
Names
Item Name Property styleDefaults
Property change event styleDefaultsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-style-defaults-changed
-
(nullable) style-defaults.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 styleDefaults.animationDuration
-
(nullable) style-defaults.hover-behavior-delay :number
-
Specifies initial hover delay in milliseconds for highlighting data items.
- Deprecated:
-
Since Description 15.0.0
This is not recommended in the Redwood design system. The default theme value will be used.
- Default Value:
200
Names
Item Name Property styleDefaults.hoverBehaviorDelay
-
style-defaults.svg-style :Partial<CSSStyleDeclaration>
-
The CSS style object defining the style of the items. Only SVG CSS style properties are supported.
- Deprecated:
-
Since Description 15.0.0
This is not recommended in the Redwood design system.
- Default Value:
{}
Names
Item Name Property styleDefaults.svgStyle
-
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: ojTagCloud.TooltipRendererContext<K>) => ({insert: Element|string}|{preventDefault: boolean}))
-
A callback function that returns a custom tooltip. The callback function will be called with a TooltipContext object containing information about the item that was clicked.
- Default Value:
null
Names
Item Name Property tooltip.renderer
-
touch-response :"touchStart"|"auto"
-
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.
- Default Value:
"auto"
Supported Values:
Value auto
touchStart
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
-
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 callingrefresh
to render the element at the new size.- Deprecated:
-
Since Description 15.0.0
This is no longer needed due to performance enhancements. The default behaviour will be used.
- Default Value:
"on"
Supported Values:
Value off
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.
- Deprecated:
-
Since Description 15.0.0
This is deprecated because it is not used by the ojTagCloud
- Since:
- 15.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:
"Tag Cloud"
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.
- Deprecated:
-
Since Description 15.0.0
This is deprecated because it is not used by the ojTagCloud
- 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.
- Deprecated:
-
Since Description 15.0.0
This is deprecated because it is not used by the ojTagCloud
- 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.
- Deprecated:
-
Since Description 15.0.0
This is deprecated because it is not used by the ojTagCloud
- 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.
- Deprecated:
-
Since Description 15.0.0
This is deprecated because it is not used by the ojTagCloud
- 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.
- Deprecated:
-
Since Description 15.0.0
This is deprecated because it is not used by the ojTagCloud
- 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.
- Deprecated:
-
Since Description 15.0.0
This is deprecated because it is not used by the ojTagCloud
- 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.
- Deprecated:
-
Since Description 15.0.0
This is deprecated because it is not used by the ojTagCloud
- 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.
- Deprecated:
-
Since Description 15.0.0
This is deprecated because it is not used by the ojTagCloud
- 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.
- Deprecated:
-
Since Description 15.0.0
This is deprecated because it is not used by the ojTagCloud
- 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.
- Deprecated:
-
Since Description 15.0.0
This is deprecated because it is not used by the ojTagCloud
- Default Value:
"Visible"
Names
Item Name Property translations.stateVisible
Context Objects
Each context object contains, at minimum, a subId
property,
whose value is a string that identifies a particular DOM node in this element. It can have additional properties to further specify the desired node. See getContextByNode for more details.
Properties:
Name | Type | Description |
---|---|---|
subId |
string | Sub-id string to identify a particular dom node. |
Following are the valid subIds:
-
oj-tagcloud-item
-
Context for tag cloud items at a specified index.
Properties:
Name Type index
number
Methods
-
getContextByNode(node) : {(oj.ojTagCloud.NodeContext|null)}
-
Returns an object with context for the given child DOM node. This will always contain the subid for the node, defined as the 'subId' property on the context object. Additional component specific information may also be included. For more details on returned objects, see context objects.
Parameters:
Name Type Argument Description node
Element <not nullable>
The child DOM node Returns:
The context for the DOM node, or
null
when none is found.- Type
- (oj.ojTagCloud.NodeContext|null)
-
getItem(index) : {(oj.ojTagCloud.ItemContext|null)}
-
Returns an object with the following properties for automation testing verification of the item at the specified index.
Parameters:
Name Type Description index
number The index. Deprecated:
Since Description 7.0.0
The use of this function is no longer recommended. Returns:
An object containing data for the node at the given index, or null if none exists.
- Type
- (oj.ojTagCloud.ItemContext|null)
-
getItemCount : {number}
-
Returns the number of items in the tag cloud data.
Deprecated:
Since Description 7.0.0
The use of this function is no longer recommended. Returns:
The number of data items
- Type
- number
-
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<K>
-
- Deprecated:
-
Since Description 15.0.0
This is not recommended in the Redwood design system.
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 <optional>
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 | ((context: ojTagCloud.ItemShortDescContext<K>) => string)) <optional>
The description of the item. This is used for customizing the tooltip text. svgClassName
string <optional>
The CSS style class defining the style of the item text. svgStyle
Partial<CSSStyleDeclaration> <optional>
The CSS style object defining the style of the item text. Only SVG CSS style properties are supported. The default value comes from the CSS and varies based on theme. url
string <optional>
The url this item references. value
number The value of this item which will be used to scale its font-size within the tag cloud. -
ItemContext
-
Properties:
Name Type Description color
string The color of the item at the given index. label
string The data label of the item at the given index. selected
boolean True if the item at the given index is currently selected and false otherwise. tooltip
string The tooltip of the item at the given index. value
number The value of the item at the given index. -
ItemShortDescContext<K>
-
Properties:
Name Type Description id
K The id of the hovered item. label
string The data label of the hovered item. value
number The value of the hovered item. -
ItemTemplateContext<K>
-
- Deprecated:
-
Since Description 16.0.0
The componentElement property is deprecated. This shouldn't be needed, as the component template with access to this context is unique to the component.
Properties:
Name Type Description componentElement
Element The <oj-tag-cloud> custom element. data
Object 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. -
NodeContext
-
Properties:
Name Type Description index
number The zero based index of the tag cloud item. subId
string The subId string identify the particular DOM node. -
TooltipContext<K>
-
- Deprecated:
-
Since Description 16.0.0
The componentElement property is deprecated. This shouldn't be needed, as the component template with access to this context is unique to the component.
Properties:
Name Type Description color
string The color of the hovered item. componentElement
Element The tag cloud element. id
K The id of the hovered item. label
string The data label of the hovered item. parentElement
Element The tooltip element. The function can directly modify or append content to this element. value
number The value of the hovered item. -
TooltipRendererContext<K>
-
Properties:
Name Type Description color
string The color of the hovered item. componentElement
Element The tag cloud element. id
K The id of the hovered item. label
string The data label of the hovered item. parentElement
Element The tooltip element. The function can directly modify or append content to this element. value
number The value of the hovered item.