Interactive and Accessible Tree View JS Library – bs-treeview

Category: Javascript | February 2, 2024
Author:jbtronics
Views Total:370 views
Official Page:Go to website
Last Update:February 2, 2024
License:MIT

Preview:

Interactive and Accessible Tree View JS Library – bs-treeview

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:

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

You Might Be Interested In:


Leave a Reply