Interactive and Accessible Tree View JS Library – bs-treeview

Preview:

Description:

The bs-treeview JavaScript library is a modern rewrite of the jQuery BOOTSTRAP TREE VIEW plugin.

It utilizes Bootstrap styling and Font Awesome icons to render a highly customizable and accessible tree view component, which can be useful in displaying hierarchical data in your web app.

Key features include node search, expand/collapse, select/deselect, accessible ARIA tags, and more.

Table Of Contents:

• Data Structure
• Options
• Events
• Methods

How to use it:

1. Install and import the bs-treeview component. Ensure you first have Bootstrap framework and FontAwesome iconic font installed in your project.

# Yarn
$ yarn add @jbtronics/bs-treeview
# NPM
$ npm install @jbtronics/bs-treeview

import {BSTreeView, BS5Theme, FAIconTheme, EVENT_NAME} from "@jbtronics/bs-treeview";
// required stylesheet
import "@jbtronics/bs-treeview/styles/bs-treeview.css";

2. Create an empty DIV to hold the BS treeview.

<div id="treeview"></div>

3. Define the hierarchical structure for the tree.

const treeData = [
  {
    text: "Full Node Spec", // required
    icon: "glyphicon glyphicon-stop",
    image: "something.png",
    selectedIcon: "glyphicon glyphicon-stop",
    color: "#000000",
    backColor: "#FFFFFF",
    iconColor: "#FFFFFF",
    iconBackground: "#000000",
    selectable: true,
    checkable: true,
    state: {
    checked: true,
    disabled: true,
    expanded: true,
    selected: true
    },
    tags: [
      'available',
      {text:'not available', class:'disabled'}
    ],
      dataAttr: {
      target: '#tree'
    }
    id: 'something',
      class: 'special extraordinary',
      hideCheckbox: true,
      nodes: [
      {},
    ]
  },
  {
    // more nodes here
  }
];

4. Render the treeview.

const treeElement = document.getElementById("treeview");
const myTree = new BSTreeView(treeElement, {
  data: treeData
  // more options
},
  // themes
  [BS5Theme, FAIconTheme]
);

5. All possible options and callback functions.

injectStyle: true,
/** Sets the number of hierarchical levels deep the tree will be expanded to by default. */
levels: 1,
/** The data to be displayed on the treeView. Can be either passed as array of nodes / partial node data or a JSON string of the same. Takes presence of ajaxURL */
data: null,
/** The URL to fetch the data from. fetch() is used to get the data from this url */
ajaxURL: null,
/** The options to be passed to the fetch() function, when data is fetched from ajaxURL */
ajaxConfig: {
  method: 'GET',
},
/** Sets the class name of the icon to be used on an expandable tree node. */
expandIcon: 'glyphicon glyphicon-plus',
/** Sets the class name of the icon to be used on a collapsible tree node. */
collapseIcon: 'glyphicon glyphicon-minus',
/** Sets the icon to be used on an a lazyLoad node before its content gets loaded. */
loadingIcon: 'glyphicon glyphicon-hourglass',
/** Sets the class name of icon to be used on a tree node with no child nodes. */
emptyIcon: 'glyphicon',
/** Sets the default icon to be used on all nodes, except when overridden on a per node basis in data. */
nodeIcon: '',
/** Sets the default icon to be used on all selected nodes, except when overridden on a per node basis in data. */
selectedIcon: '',
/** Sets the class name of the icon to be as a checked checkbox, used in conjunction with showCheckbox. */
checkedIcon: 'glyphicon glyphicon-check',
/** Sets the class name of icon to be as a partially checked checkbox, used in conjunction with showCheckbox and hierarchicalCheck. */
partiallyCheckedIcon: 'glyphicon glyphicon-expand',
/** Sets the icon to be as an unchecked checkbox, used in conjunction with showCheckbox. */
uncheckedIcon: 'glyphicon glyphicon-unchecked',
/** Sets the class of tags to be used on a node. Defaults to 'badge' */
tagsClass: 'badge',
/** Sets the default foreground color used by all nodes, except when overridden on a per node basis in data. Can be any valid color value */
color: undefined,
/** Sets the default background color used by all nodes, except when overridden on a per node basis in data. Can be any valid color value */
backColor: undefined,
/** Sets the border color for the component, set showBorder to false if you don't want a visible border. Can be any valid color value */
borderColor: undefined,
/** Sets the text color for a node with a changed checkbox. */
changedNodeColor: '#39A5DC',
/** Sets the default background color activated when the users cursor hovers over a node. */
onhoverColor: '#F5F5F5',
/** Sets the foreground color of a selected node. Defaults to black */
selectedColor: '#FFFFFF',
/** Sets the background color of the selected node. */
selectedBackColor: '#428bca',
/** Sets the foreground color of a node found during a search result */
searchResultColor: '#D9534F',
/** Sets the background color of a node found during a search result */
searchResultBackColor: undefined,
/** Whether or not to highlight the selected node. Default true */
highlightSelected: true,
/** Whether or not to highlight search results. Default false */
highlightSearchResults: true,
/** Whether or not to display a border around nodes. */
showBorder: true,
/** Whether or not to display a nodes icon. Default: true */
showIcon: true,
/** Whether or not to display a nodes image instead of the icon. */
showImage: false,
/** Whether or not to display checkboxes on nodes. */
showCheckbox: false,
/** Swaps the node icon with the checkbox, used in conjunction with showCheckbox. Default false */
checkboxFirst: false,
/** Highlights the nodes with changed checkbox state, used in conjunction with showCheckbox. Default: false */
highlightChanges: false,
/** Whether or not to display tags to the right of each node. The values of which must be provided in the data structure on a per node basis. Default false */
showTags: false,
/** Whether or not multiple nodes can be selected at the same time. Default false */
multiSelect: false,
/** Whether or not a node can be unselected without another node first being selected. Default: false */
preventUnselect: false,
/** Whether or not a node can be reselected when its already selected, used in conjunction with preventUnselect. Default: false */
allowReselect: false,
/** Whether or not to enable hierarchical checking/unchecking of checkboxes. Default false */
hierarchicalCheck: false,
/** Whether or not to propagate nodeChecked and nodeUnchecked events to the parent/child nodes, used in conjunction with hierarchicalCheck. Default false. */
propagateCheckEvent: false,
/** Whether or not to surround the text of the node with a <span class='text'> tag. */
wrapNodeText: true,
// Event handlers
onLoading: undefined,
onLoadingFailed: undefined,
onInitialized: undefined,
onNodeRendered: undefined,
onRendered: undefined,
onDestroyed: undefined,
onNodeChecked: undefined,
onNodeCollapsed: undefined,
onNodeDisabled: undefined,
onNodeEnabled: undefined,
onNodeExpanded: undefined,
onNodeSelected: undefined,
onNodeUnchecked: undefined,
onNodeUnselected: undefined,
onSearchComplete: undefined,
onSearchCleared: undefined,
/** This function is called when a lazily-loadable node is being expanded for the first time.
* The node is available as the first argument, while the second argument is a function responsible for passing the loaded data to the renderer.
* The data needs to be in the same JSON format as specified above. */
lazyLoad: undefined,

6. Events.

• EVENT_DESTROYED
• EVENT_INITIALIZED
• EVENT_LOADING
• EVENT_LOADING_FAILED
• EVENT_NODE_CHECKED
• EVENT_NODE_COLLAPSED
• EVENT_NODE_DISABLED
• EVENT_NODE_ENABLED
• EVENT_NODE_EXPANDED
• EVENT_NODE_RENDERED
• EVENT_NODE_SELECTED
• EVENT_NODE_UNCHECKED
• EVENT_NODE_UNSELECTED
• EVENT_RENDERED
• EVENT_SEARCH_CLEARED
• EVENT_SEARCH_COMPLETED

treeElement.addEventListener(EVENT_INITIALIZED, (event) => {
  // do something
});

7. API methods.

• addNode(nodes: BSTreeViewNode[] | BSTreeViewNode, parentNode?: BSTreeViewNode | null, index?: number, options?: Partial<BSTreeViewMethodOptions>)
• addNodeAfter(nodes: BSTreeViewNode[] | BSTreeViewNode, node: BSTreeViewNode, options?: Partial<BSTreeViewMethodOptions>)
• addNodeBefore(nodes: BSTreeViewNode[] | BSTreeViewNode, node: BSTreeViewNode, options?: Partial<BSTreeViewMethodOptions>)
• checkAll(options?: Partial<BSTreeViewMethodOptions>)
• checkNodee(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewMethodOptions>)
  clearSearch(options?: Partial<BSTreeSearchOptions>)
• collapseAll(options?: Partial<BSTreeViewExpandOptions>)
• collapseNode(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewExpandOptions>)
  disableAlll(options?: Partial<BSTreeViewDisableOptions>)
• disableNode(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewDisableOptions>)
  enableAll(options?: Partial<BSTreeViewDisableOptions>)
• enableNode(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewDisableOptions>)
  expandAll(options?: Partial<BSTreeViewExpandOptions>)
• expandNode(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewExpandOptions>)
  findNodes(pattern: string, field: string)
• getChecked()
• getCollapsed()
• getConfig()
• getDisabled()
• getEnabled()
• getExpanded()
• getNodes()
• getNodesCount()
• getParents(nodes: BSTreeViewNode[] | BSTreeViewNode)
• getRootNodes()
• getRootNodesCount()
• getSearchResults()
• getSelected()
• getSiblings(nodes: BSTreeViewNode[] | BSTreeViewNode)
• getTreeElement()
• getUnchecked()
• getUnselected()
• remove()
• removeNode(nodes: BSTreeViewNode[] | BSTreeViewNode, _options?: Partial<BSTreeViewMethodOptions>)
• revealNode(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewExpandOptions>)
• search(pattern: string, options?: Partial<BSTreeSearchOptions>)
• selectAll(options?: Partial<BSTreeViewSelectOptions>)
• selectNode(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewSelectOptions>)
• toggleNodeChecked(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewMethodOptions>)
• toggleNodeDisabled(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewDisableOptions>)
• toggleNodeExpanded(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewExpandOptions>)
• toggleNodeSelected(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewSelectOptions>)
• uncheckAll(options?: Partial<BSTreeViewMethodOptions>)
• uncheckNode(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewMethodOptions>)
• unmarkCheckboxChanges()
• unselectAll(options?: Partial<BSTreeViewSelectOptions>)
• unselectNode(nodes: BSTreeViewNode[] | BSTreeViewNode, options?: Partial<BSTreeViewSelectOptions>)
• updateNode(node: BSTreeViewNode, newNode: BSTreeViewNode, _options?: Partial<BSTreeViewMethodOptions>)

Changelog:

v1.0.6 (02/02/2024)

• Bugfixes