Final Class: ArrayTreeDataProvider

Oracle® JavaScript Extension Toolkit (JET)
9.0.0

F24343-01

Signature:

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

QuickNav

ArrayTreeDataProvider

Version:
  • 9.0.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.

Final classes in JET

Classes in JET are generally final and do not support subclassing. At the moment, final is not enforced. However, this will likely change in an upcoming JET release.

Description

This class implements 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.

Filtering is supported and, by default, applied only on leaf nodes. Empty tree nodes are not collapsed. The filtering on leaf nodes only works by combining the passed in filter definition with an OR expression of the "children" property to determine if a node is a tree or leaf. Therefore, if users want to customize this to include filtering on tree nodes as well, then a custom filter() function can be specified which excludes tree nodes.

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 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)

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 SortComparator to use for sort.
implicitSort Array.<SortCriterion.<D>> <optional>
Optional array of 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

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(parameters : FetchByKeysParameters<K>) : Promise<ContainsKeysResults<K>>

Check if there are rows containing the specified keys
Parameters:
Name Type Description
parameters FetchByKeysParameters contains by key parameters
Since:
  • 4.2.0
Returns:
Returns Promise which resolves to ContainsKeysResults.
Type
Promise.<ContainsKeysResults>
Example

Check if keys 1001 and 556 are contained

let containsKeys = [1001, 556];
let value = await dataprovider.containsKeys({keys: containsKeys});
let results = value['results'];
if (results.has(1001)) {
  console.log('Has key 1001');
} else if (results.has(556){
  console.log('Has key 556');
}

dispatchEvent(evt: Event): boolean

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(parameters : FetchByKeysParameters<K>) : Promise<FetchByKeysResults<K, D>>

Fetch rows by keys
Parameters:
Name Type Description
parameters FetchByKeysParameters fetch by key parameters
Since:
  • 4.2.0
Returns:
Returns Promise which resolves to FetchByKeysResults.
Type
Promise.<FetchByKeysResults>
Example

Fetch for keys 1001 and 556

let fetchKeys = [1001, 556];
let value = await dataprovider.fetchByKeys({keys: fetchKeys});
// get the data for key 1001
console.log(value.results.get(1001).data);

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

Fetch rows by offset

A generic implementation of this method is available from FetchByOffsetMixin. It is for convenience and may not provide the most efficient implementation for your data provider. Classes that implement the DataProvider interface are encouraged to provide a more efficient implementation.

Parameters:
Name Type Description
parameters FetchByOffsetParameters fetch by offset parameters
Since:
  • 4.2.0
Returns:
Returns Promise which resolves to FetchByOffsetResults.
Type
Promise.<FetchByOffsetResults>
Example

Fetch by offset 5 rows starting at index 2

let result = await dataprovider.fetchByOffset({size: 5, offset: 2});
let results = result['results'];
let data = results.map(function(value) {
  return value['data'];
});
let keys = results.map(function(value) {
  return value['metadata']['key'];
});

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

Get an asyncIterator which can be used to fetch a block of data.
Parameters:
Name Type Argument Description
params FetchListParameters <optional>
fetch parameters
Since:
  • 4.2.0
See:
Returns:
AsyncIterable with FetchListResult
Type
AsyncIterable.<FetchListResult>
Example

Get an asyncIterator and then fetch first block of data by executing next() on the iterator. Subsequent blocks can be fetched by executing next() again.

let asyncIterator = dataprovider.fetchFirst(options)[Symbol.asyncIterator]();
let result = await asyncIterator.next();
let value = result.value;
let data = value.data;
let keys = value.metadata.map(function(val) {
  return val.key;
});

getCapability(capabilityName: string): any

Determines whether this DataProvider defines a certain feature.
Parameters:
Name Type Description
capabilityName string capability name. Defined capability names are: "fetchByKeys", "fetchByOffset", "sort", "fetchCapability" and "filter".
Since:
  • 4.2.0
Returns:
capability information or null if undefined
Type
Object
Example

Check what kind of fetchByKeys is defined.

let capabilityInfo = dataprovider.getCapability('fetchByKeys');
if (capabilityInfo.implementation == 'iteration') {
  // the DataProvider supports iteration for fetchByKeys
  ...

getChildDataProvider(parentKey: K): TreeDataProvider<K, D> | null

Get the 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.
Since:
  • 5.1.0
Returns:
A TreeDataProvider 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 TreeDataProvider to determine if it currently has children.
Type
TreeDataProvider | null

getTotalSize() : {Promise.<number>}

Return the total number of rows in this dataprovider
Returns:
Returns a Promise which resolves to the total number of rows. -1 is unknown row count.
Type
Promise.<number>
Example

Get the total rows

let value = await dataprovider.getTotalSize();
if (value == -1) {
  // we don't know the total row count
} else {
  // the total count
  console.log(value);
}

isEmpty(): 'yes' | 'no' | 'unknown'

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.
Since:
  • 4.2.0
Returns:
string that indicates if this data provider is empty
Type
"yes" | "no" | "unknown"
Example

Check if empty

let isEmpty = dataprovider.isEmpty();
console.log('DataProvider is empty: ' + isEmpty);

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

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.