util.treeitemdeprecated

Utility functions for working with the Treeview component in the gadgets library

Usage no npm install needed!

<script type="module">
  import utilTreeitem from 'https://cdn.skypack.dev/util.treeitem';
</script>

README

util.treeitem

Utility functions for manipulating a treeData structure

build analysis code style: prettier testing NPM coverage

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 node
  • parent {TreeItem} - reference to the parent node, where the id of the parent is parent.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 component
  • subtitle {string} - sub string below the main title.
  • expanded {boolean} - a boolean flag that determines if the children of this node are displayed
  • children {TreeItem[]} - an array of TreeItem 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 test
  • testing {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 tree
  • treeIndex {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 nodes
  • usesanitize {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).

methods