Module: ojimmutabletreedatautils

Oracle® JavaScript Extension Toolkit (JET)
15.1.0
F83698-01

QuickNav

Functions

JET Modules

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

Description

This module contains several mutation functions to update/add/remove tree data and return a mutated copy. It also provides a function to find the node's path in the tree data. User need to call fetchByKeys first to get the node's data, then pass the data to findPathByData to get the path. Finially, call the correct mutation function to change the data.

Functions

addNode<K, D>(baseArray, path, newData, childrenAttribute) : {Array<D>}

Utility function that adds node by path and newData. Then returns the mutataed copy. The base array will not be changed.
Parameters:
Name Type Argument Description
baseArray Array<D> The base array that need to be updated.
path Array<number> The path that shows where the newData should be inserted at. Each item in the path indicates the index of the nodes in the path starting with root. The last item in the path is the insertion index within the target parent node. If it is -1, new node will be appended to the target parent node's children array.
newData D The new node's data.
childrenAttribute string <optional>
 Optional. The children attribute name in array. The default value is 'children'.
Since:
  • 13.0.0
Returns:

The mutated array.

Type
Array<D>
Examples

Add a child node to 'Today'

import {
 MutableArrayTreeDataProvider
} from 'ojs/ojmutablearraytreedataprovider';
import {
 addNode,
 findPathByData
} from 'ojs/ojimmutabletreedatautils';
const baseData = [
  {title:"News", id:"news"},
  {title:"Blogs", id:"blogs", "children": [
    {title:"Today", id:"today"},
    {title:"Yesterday", id:"yesterday"},
    {title:"Archive", id:"archive", "children": [
      {title: "Links", id:'links'}
     ]}
  ]}
];
// create a new MutableArrayTreeDataProvider with keyAttribute 'id'
// keyAttribute is unique in baseData
// The default keyAttributeScope is 'global'.
const mutableATDP = new MutableArrayTreeDataProvider(baseData, 'id');

// create a new set and add key 'today' into keySet
let keySet = new Set();
keySet.add('today');

// call fetchByKeys with keySet
const value = await mutableATDP.fetchByKeys({keys: keySet});

// get data of node 'today'
const nodeData = value.results.get('today').data;

// call findPathByData to get path of node 'today'
// path should be [1, 0]
const path = findPathByData(baseData, nodeData);

// indicate the index that the new node shoule be inserted at.
path.push(0);

// create a new node that will be added into baseData
const newNode = {id: 'newNode', title:"new node"};

// use addNode to mutate baseData and update immutableData
let immutableData = addNode(baseData, path, newNode);

// update mutableATDP.data with immutableData
mutableATDP.data = immutableData;

Add a new node before 'Archive' by using -1 in path array

import {
 MutableArrayTreeDataProvider
} from 'ojs/ojmutablearraytreedataprovider';
import {
 addNode,
 findPathByData
} from 'ojs/ojimmutabletreedatautils';
const baseData = [
  {title:"News", id:"news"},
  {title:"Blogs", id:"blogs", "children": [
    {title:"Today", id:"today"},
    {title:"Yesterday", id:"yesterday"},
    {title:"Archive", id:"archive", "children": [
      {title: "Links", id:'links'}
     ]}
  ]}
];
// create a new MutableArrayTreeDataProvider with keyAttribute 'id'
// keyAttribute is unique in baseData
// The default keyAttributeScope is 'global'.
const mutableATDP = new MutableArrayTreeDataProvider(baseData, 'id');

// create a new set and add key 'archive' into keySet
let keySet = new Set();
keySet.add('archive');

// call fetchByKeys with keySet
const value = await mutableATDP.fetchByKeys({keys: keySet});

// get data of node 'archive'
const nodeData = value.results.get('archive').data;

// call findPathByData to get path of node 'archive'
// path should be [1, 2]
const path = findPathByData(baseData, nodeData);

// replace the last item in path with -1
path.pop();
path.push(-1);

// create a new node that will be added into baseData
const newNode = {id: 'newNode', title:"new node"};

// use addNode to mutate baseData and update immutableData
// newNode should be added at index 2. Because Blogs' children array's length is 2 before adding.
// immutableData[1].children[2] is { title: 'new node', id: 'newNode' }
let immutableData = addNode(baseData, path, newNode);

// update mutableATDP.data with immutableData
mutableATDP.data = immutableData;

findPathByData<K, D>(baseArray, data, childrenAttribute) : {Array<number>}

Utility function that find the node's path in base array by node's data.
Parameters:
Name Type Argument Description
baseArray Array.<D> The array that contain the node.
data D The returned node's data from fetchByKeys.
childrenAttribute string <optional>
 Optional. The children attribute name in array. The default value is 'children'.
Since:
  • 13.0.0
Returns:

The path to that node.

Type
Array<number>
Example

Find path of 'Today'

import {
 MutableArrayTreeDataProvider
} from 'ojs/ojmutablearraytreedataprovider';
import {
 findPathByData
} from 'ojs/ojimmutabletreedatautils';
const baseData = [
  {title:"News", id:"news"},
  {title:"Blogs", id:"blogs", "children": [
    {title:"Today", id:"today"},
    {title:"Yesterday", id:"yesterday"},
    {title:"Archive", id:"archive", "children": [
      {title: "Links", id:'links'}
     ]}
  ]}
];
// create a new MutableArrayTreeDataProvider with keyAttribute 'id'
// keyAttribute is unique in baseData
// The default keyAttributeScope is 'global'.
const mutableATDP = new MutableArrayTreeDataProvider(baseData, 'id');

// create a new set and add key 'today' into keySet
let keySet = new Set();
keySet.add('today');

// call fetchByKeys with keySet
const value = await mutableATDP.fetchByKeys({keys: keySet});

// get data of node 'today'
const nodeData = value.results.get('today').data;

// call findPathByData to get path
// path should be [1, 0]
const path = findPathByData(baseData, nodeData);

removeNode<K, D>(baseArray, path, childrenAttribute) : {Array<D>}

Utility function that removes node by path and returns the mutataed copy. The base array will not be changed.
Parameters:
Name Type Argument Description
baseArray Array<D> The base array that need to be updated.
path Array<number> The path that shows where the newData should be inserted at. Each item in the path indicates the index of the nodes in the path starting with root. The last item in the path is the insertion index within the target parent node. If it is -1, last node of the target parent node's children array will be removed.
childrenAttribute string <optional>
 Optional. The children attribute's name in array. The default value is 'children'.
Since:
  • 13.0.0
Returns:

The mutated array.

Type
Array<D>
Example

Remove node 'Today'

import {
 MutableArrayTreeDataProvider
} from 'ojs/ojmutablearraytreedataprovider';
import {
 removeNode,
 findPathByData
} from 'ojs/ojimmutabletreedatautils';
const baseData = [
  {title:"News", id:"news"},
  {title:"Blogs", id:"blogs", "children": [
    {title:"Today", id:"today"},
    {title:"Yesterday", id:"yesterday"},
    {title:"Archive", id:"archive", "children": [
      {title: "Links", id:'links'}
     ]}
  ]}
];
// create a new MutableArrayTreeDataProvider with keyAttribute 'id'
// keyAttribute is unique in baseData.
// The default keyAttributeScope is 'global'.
const mutableATDP = new MutableArrayTreeDataProvider(baseData, 'id');

// create a new set and add key 'today' into keySet
let keySet = new Set();
keySet.add('today');

// call fetchByKeys with keySet
const value = await mutableATDP.fetchByKeys({keys: keySet});

// get data of node 'today'
const nodeData = value.results.get('today').data;

// call findPathByData to get path
// path should be [1, 0]
const path = findPathByData(baseData, nodeData);

// use removeNode to mutate baseData and update immutableData
let immutableData = removeNode(baseData, path);

// update mutableATDP.data with immutableData
mutableATDP.data = immutableData;

replaceNode<K, D>(baseArray, path, newData, childrenAttribute) : {Array<D>}

Utility function that replace node by path and newData. Then returns the mutataed copy. The base array will not be changed.
Parameters:
Name Type Argument Description
baseArray Array<D> The base array that need to be updated.
path Array<number> The path that shows where the newData should be inserted at. Each item in the path indicates the index of the nodes in the path starting with root. The last item in the path is the insertion index within the target parent node. If it is -1, last node of the target parent node's children array will be replaced by new node.
newData D The new node's data.
childrenAttribute string <optional>
 Optional. The children attribute's name in array. The default value is 'children'.
Since:
  • 13.0.0
Returns:

The mutated array.

Type
Array<D>
Example

Update 'Today' title

import {
 MutableArrayTreeDataProvider
} from 'ojs/ojmutablearraytreedataprovider';
import {
 replaceNode,
 findPathByData
} from 'ojs/ojimmutabletreedatautils';
const baseData = [
  {title:"News", id:"news"},
  {title:"Blogs", id:"blogs", "children": [
    {title:"Today", id:"today"},
    {title:"Yesterday", id:"yesterday"},
    {title:"Archive", id:"archive", "children": [
      {title: "Links", id:'links'}
     ]}
  ]}
];
// create a new MutableArrayTreeDataProvider with keyAttribute 'id'
// keyAttribute is unique in baseData
// The default keyAttributeScope is 'global'.
const mutableATDP = new MutableArrayTreeDataProvider(baseData, 'id');

// create a new set and add key 'today' into keySet
let keySet = new Set();
keySet.add('today');

// call fetchByKeys with keySet
const value = await mutableATDP.fetchByKeys({keys: keySet});

// get data of node 'today'
const nodeData = value.results.get('today').data;

// call findPathByData to get path
// path should be [1, 0]
const path = findPathByData(baseData, nodeData);

// create an object that contains the property that will be updated
const newNode = {title:"new Today", id: 'today'};

// use replaceNode to mutate baseData and update immutableData
let immutableData = replaceNode(baseData, path, newNode);

// update mutableATDP.data with immutableData
mutableATDP.data = immutableData;

spliceNode<K, D>(baseArray, path, newData, childrenArrayIndex, deleteCount, childrenAttribute) : {Array<D>}

Utility function that adds/removes/updates node for children mutations by path and returns the mutataed copy. The base array will not be changed. When deleteCount is 1 and doesn't have newData, spliceNode will remove the child node. When deleteCount is 1 and has newData, spliceNode will replace the child node with newData. When deleteCount is 0, spliceNode will add a node according to childrenArrayIndex.
Parameters:
Name Type Argument Description
baseArray Array<D> The base array that need to be updated.
path Array<number> The path should be the path to the Node's parent index. Root manipulations will have a path of [].
newData D <optional>
 The new node's data.
childrenArrayIndex number <optional>
 The index at which to start changing the array. Default value would be 0.
deleteCount number <optional>
 An integer indicating the number of elements in the array to remove from childrenArrayIndex. Default value would be 0. 0 means no elements are removed. Max value will be 1.
childrenAttribute string <optional>
 Optional. The children attribute's name in array. The default value is 'children'.
Since:
  • 13.0.0
Returns:

The mutated array.

Type
Array<D>
Examples

Add node

import {
 MutableArrayTreeDataProvider
} from 'ojs/ojmutablearraytreedataprovider';
import {
 spliceNode
} from 'ojs/ojimmutabletreedatautils';
const oldData = [
      { title: 'News', id: 'news' },
      {
        title: 'Blogs',
        id: 'blogs',
        children: [
          { title: 'Today', id: 'today' },
          { title: 'Yesterday', id: 'yesterday' },
          { title: 'Archive', id: 'archive' }
        ]
      }
    ];
    const newNode = { title: 'new node', id: 'newNode' };
    // should add a child node under blog at index 0
    const newData = spliceNode(oldData, [1], newNode);

remove node

import {
 MutableArrayTreeDataProvider
} from 'ojs/ojmutablearraytreedataprovider';
import {
 spliceNode
} from 'ojs/ojimmutabletreedatautils';
const oldData = [
      { title: 'News', id: 'news' },
      {
        title: 'Blogs',
        id: 'blogs',
        children: [
          { title: 'Today', id: 'today' },
          { title: 'Yesterday', id: 'yesterday' },
          { title: 'Archive', id: 'archive' }
        ]
      }
    ];
   // remove node today
   const newData = spliceNode(oldData, [1], null, 0, 1);

update node

import {
 MutableArrayTreeDataProvider
} from 'ojs/ojmutablearraytreedataprovider';
import {
 spliceNode
} from 'ojs/ojimmutabletreedatautils';
const oldData = [
      { title: 'News', id: 'news' },
      {
        title: 'Blogs',
        id: 'blogs',
        children: [
          { title: 'Today', id: 'today' },
          { title: 'Yesterday', id: 'yesterday' },
          { title: 'Archive', id: 'archive' }
        ]
      }
    ];
    const newNode = { title: 'new today', id: 'today' };
    // should update today with newNode
   const newData = spliceNode(oldData, [1], newNode, 0, 1);