Class: ArrayTreeDataProvider

Oracle® JavaScript Extension Toolkit (JET)
7.1.0

F18183-01

Signature:

class ArrayTreeDataProvider<K, D> implements TreeDataProvider<K, D>

QuickNav


PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

ArrayTreeDataProvider

Version:
  • 7.1.0
Since:
  • 5.1.0
Module:
  • ojarraytreedataprovider

Module usage

See JET Module Loading for an overview of module usage within JET.

Javascript Import Format
define(['ojs/ojarraytreedataprovider'], function(ArrayTreeDataProvider) {
 // Application should call API on ArrayTreeDataProvider 
})
Typescript Import Format
//This class is exported directly as module. To import it
import ArrayTreeDataProvider= require("ojs/ojarraytreedataprovider");

Generic Parameters
ParameterDescription
KType of Key
DType of Data

JET In Typescript

A detailed description of working with JET elements and classes in your typescript project can be found at: JET Typescript Usage.

Description

This class implements oj.TreeDataProvider and is used to represent hierachical data available from an array.

Each array element represents a tree node, which can contain nested child object array for its subtree. Array elements can be in any shape and form, but is usually an object with a "children" property. The name of the "children" property can optionaly be specified with the "childrenAttribute" option.

For nodes that cannot have children, the "children" property should not be set. For nodes that can but don't have children, the "children" property should be set to an empty array.

Data can be passed as a regular array or a Knockout observableArray. If a Knockout observableArray is used, any mutation must be performed with observableArray methods. The events described below will be dispatched to the ArrayTreeDataProvider with the appropriate event payload.

Events

Consumers can add event listeners to listen for the following event types and respond to data change. Event listeners should be added to the root-level ArrayTreeDataProvider created by the application. The root-level ArrayTreeDataProvider receives events for the entire tree. Child-level ArrayTreeDataProvider returned by getChildDataProvider does not receive events.

mutate

This event is fired when items have been added or removed from the data.

Event payload is found under event.detail, which implements the oj.DataProviderMutationEventDetail interface.

refresh

This event is fired when the data has been refreshed and components need to re-fetch the data.

This event contains no additional event payload.

Example of consumer listening for the "mutate" event type:
var listener = function(event) {
  if (event.detail.remove) {
    var removeDetail = event.detail.remove;
    // Handle removed items
  }
};
dataProvider.addEventListener("mutate", listener);

Constructor

new ArrayTreeDataProvider(data, options)

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Parameters:
Name Type Argument Description
data Array | function():Array data supported by the components

This can be either an Array, or a Knockout observableArray.

options Object <optional>
Options for the ArrayTreeDataProvider
Properties
Name Type Argument Description
sortComparators ArrayDataProvider.SortComparators<D> <optional>
Optional oj.sortComparator to use for sort.
implicitSort Array<SortCriterion<D>> <optional>
Optional array of oj.sortCriterion used to specify sort information when the data loaded into the dataprovider is already sorted.
keyAttributes string | Array.<string> <optional>
Optional attribute name(s) which stores the key in the data. Can be a string denoting a single key attribute or an array of strings for multiple key attributes. Dot notation can be used to specify nested attribute (e.g. 'attr.id').

If specified, caller must ensure that the keyAttributes contains values that are either unique within the entire tree, or unique among the siblings of each node. In the latter case, Caller must also set the keyAttributesScope option to 'siblings'.
If keyAttributes is specified and keyAttributesScope is 'global', the attribute value will be used as the key.
If keyAttributes is specified and keyAttributesScope is 'siblings', a path array of the attribute values, starting from the root node, will be used as the key.
If keyAttributes is not specified, a path array of node index, starting from the root node, will be used as the key.
keyAttributesScope 'global' | 'siblings' <optional>
Optional scope of the key values in the fields specified by keyAttributes. Supported values:
  • 'global': the key values are unique within the entire tree.
  • 'siblings': the key values are unique among the siblings of each node.
Default is 'global'.
childrenAttribute string <optional>
Optional field name which stores the children of nodes in the data. Dot notation can be used to specify nested attribute. If this is not specified, the default is "children".

Methods

addEventListener(eventType: string, listener: EventListener): void

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Add a callback function to listen for a specific event type.
Parameters:
Name Type Description
eventType string The event type to listen for.
listener EventListener The callback function that receives the event notification.

containsKeys(params: FetchByKeysParameters<K>): Promise<ContainsKeysResults<K>>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Check if there are rows containing the specified keys in the entire tree.
Parameters:
Name Type Description
params oj.FetchByKeysParameters Fetch by keys parameters
Returns:
Promise which resolves to oj.ContainsKeysResults
Type
Promise.<oj.ContainsKeysResults>

dispatchEvent(evt: Event): boolean

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Dispatch an event and invoke any registered listeners.
Parameters:
Name Type Description
event Event The event object to dispatch.
Returns:
Return false if a registered listener has cancelled the event. Return true otherwise.
Type
boolean

fetchByKeys(params: FetchByKeysParameters<K>): Promise<FetchByKeysResults<K, D>>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Fetch rows by keys in the entire tree.
Parameters:
Name Type Description
params oj.FetchByKeysParameters Fetch by keys parameters
Returns:
Promise which resolves to oj.FetchByKeysResults
Type
Promise.<oj.FetchByKeysResults>

fetchByOffset(params: FetchByOffsetParameters<D>): Promise<FetchByOffsetResults<K, D>>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Fetch rows by offset at the top level.
Parameters:
Name Type Description
params oj.FetchByOffsetParameters Fetch by offset parameters
Returns:
Promise which resolves to oj.FetchByOffsetResults
Type
Promise.<oj.FetchByOffsetResults>

fetchFirst(params?: FetchListParameters<D>): AsyncIterable<FetchListResult<K, D>>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Fetch the first set of rows at the current level.

If params.sortCriteria is specified, the default sorting algorithm used is natural sort.

Parameters:
Name Type Argument Description
params oj.FetchListParameters <optional>
Fetch parameters
See:
Returns:
AsyncIterable with oj.FetchListResult
Type
AsyncIterable.<oj.FetchListResult>

getCapability(capabilityName?: string): any

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Determines whether this data provider supports certain feature.
Parameters:
Name Type Description
capabilityName string capability name. Supported capability names are: "fetchByKeys", "fetchByOffset", and "sort".
Returns:
capability information or null if unsupported
Type
Object

getChildDataProvider(parentKey: any): ArrayTreeDataProvider<K, D>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Get a data provider for the children of the row identified by parentKey.
Parameters:
Name Type Description
parentKey any key of the row to get child data provider for.
Returns:
An ArrayTreeDataProvider if the row can (but doesn't have to) have children; or null if the row cannot have children. Use the isEmpty method on the returned ArrayTreeDataProvider to determine if it currently has children.
Type
ArrayTreeDataProvider | null

getTotalSize() → {Promise.<number>}

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Return the total number of rows at the top level.
Returns:
Returns a Promise which resolves to the total number of rows. -1 is unknown row count.
Type
Promise.<number>

isEmpty() → {"yes"|"no"|"unknown"}

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Return a string that indicates if this data provider is empty.
Returns:
a string that indicates if this data provider is empty. Valid values are: "yes": this data provider is empty. "no": this data provider is not empty. "unknown": it is not known if this data provider is empty until a fetch is made.
Type
"yes" | "no" | "unknown"

removeEventListener(eventType: string, listener: EventListener): void

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Remove a listener previously registered with addEventListener.
Parameters:
Name Type Description
eventType string The event type that the listener was registered for.
listener EventListener The callback function that was registered.