README
util.treeitem
Utility functions for manipulating a treeData structure
This module is a support class for use with the gadgets library Treeview React component. It provides a class and functions for maintaning and manipulating the treeData object structure used to represent the Treeview.
Installation
This module uses yarn to manage dependencies and run scripts for development.
To install as an application dependency with cli:
$ yarn add --dev util.treeitem
To build the app and run all tests:
$ yarn run all
TreeItem/Treedata Structure
The treeData is an array of TreeItem
nodes. A TreeItem
node is a dictionary that contains the following properties:
id {string}
- a unique id/key value for the nodeparent {TreeItem}
- reference to the parent node, where the id of the parent isparent.id
data {any}
- a variable to hold any data associated with the node (can hold any type of data)title {string}
- a string that represents the title displayed on the Treeview componentsubtitle {string}
- sub string below the main title.expanded {boolean}
- a boolean flag that determines if the children of this node are displayedchildren {TreeItem[]}
- an array ofTreeItem
nodes attached to this node.
An example of this data structure is:
[
{title: "string", subtitle: "string", expanded: "boolean", children: ["treeData"]},
{title: "string", subtitle: "string", expanded: "boolean", children: [
{title: "string", subtitle: "string", expanded: "boolean", children: ["treeData"]},
{title: "string", subtitle: "string", expanded: "boolean", children: ["treeData"]}
]}
...
]
This is the structure of a general tree, where each node can have an arbitrary number of children.
Usage
Create an instance of the TreeData
class, where the constructor is an array of TreeItem
nodes (shown above). The resulting instance is then used to interact with the data. To create a simple instance:
import {TreeData, TreeItem} from "util.treeitem";
const data: TreeItem[] = [
{id: 0, title: "1.0", children: [{id: 3, title: "1.1", children[]}]}
{id: 1, title: "2.0", children: []}
{id: 2, title: "3.0", children: []}
];
const td = new TreeData(data);
Once the instance is created the tree can be searched by id
values using the find
function:
let it: TreeItem = td.find(1);
// it -> {id: 1, title: "2.0", children: []}
The tree can also be traversed in order with the walk
function:
td.walk((node: TreeItem) => {
log.info('node: %O', node);
});
The walk
function will visit each node in the tree in order invoking a callback function as each node is encountered. The callback receives a reference to each node. If the useindex
property is set when the class is created, which it is by default, then an id-to-node index is created. The treeIndex
property can be used to quickly find a node by its index:
let it: TreeItem = td.treeIndex[2];
// it -> {id: 2, title: "3.0", children: []}
API
properties
defaultTitle {string} ('default')
- the default string loaded into the TreeItem.title field when a new node is created or sanitized (when the title is empty).sequence {number} (0)
- the starting sequence number in key generation when the class is under testtesting {boolean} (false)
- set to true when this class is under test. This is needed to generate predicatble keys instead of UUID values.treeData {TreeItem[]}
- the data that represents the current general treetreeIndex {TreeIndex}
- a key/node value pair used to quickly look up a node by its unique id value.useindex {boolean} (true)
- turns on node indexing when walking the tree or finding nodesusesanitize {boolean} (true)
- if true, then run sanitization on nodes when walking the tree. This ensures that all of the parent/child key relationships are in place and that all valid TreeItem fields are in the objects (with default values if they are missing).