@jbtronics/bs-treeview

bs-treeview

A treeview element for browsers using Javascript. It is based on the bootstrap-treeview libraries of @jonmiles and @patternfly, but is overhauled with typescript and does not use any jQuery.

Screenshots

You can find a real world application using this library here (See the sidebar with three treeviews).

Features

• No dependencies (especially not on jQuery)
• Supports all features of the original libraries (with some minor changes, see below)
• Search function for nodes
• Allows selection of one (or if wanted multiple) nodes, nodes can be checked or unchecked independently
• Methods to control the treeview and nodes states (expand, collapse, select, deselect, check, uncheck, check all, uncheck all)
• Style each node independently (using different classes, colors, icons, etc.)
• Support for different themes, to fit the CSS framework and icon set you are using
• Improved accessibility by setting the correct aria-* tags according specification

Dependencies

• A browser supporting ECMAScript 2017 (which should be any browser of the last years)
• Bootstrap 4 or 5, and Font Awesome: bs-treeview can be configured to use other frontend frameworks, but this is the default configuration
• A bundler like webpack is highly recommended

Usage

1. Import it to your project: yarn add @jbtronics/bs-treeview
2. Import the bs-treeview library and the style file (example code for webpack):

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

3. You need some data source to populate the treeview: This could be an object structure, created in javascript, an static JSON string created by your website, an endpoint serving an JSON encodes tree structure and so on. See below for an description of the datastructures.
4. Create the treeview element in your DOM:

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

5. Initialize the treeview element:

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

//Choose the element on which you want to create the treeview
const treeElement = document.getElementById("treeview");

//The data which will be shown in the treeview. For simplicity we use an object structure, but you can load it from anywhere you want
const data = [
    {
        text: "Parent 1",
        state: {
            expanded: true
        },
        nodes: [
            {
                text: "Child 1",
                nodes: [
                    {
                        text: "Grandchild 1",
                        state: {
                            disabled: true
                        }
                    },
                    {
                        text: "Grandchild 2"
                    }
                ]
            },
            {
                text: "Child 2",
                tags: ["available", "out of stock"]
            }
        ]
    },
    {
        text: "Parent 2"
    }
]



//Create the treeview
const tree = new BSTreeView(treeElement,
    //The options to apply to our treeView
    {
        data: data,
        //You can either use the callback provided in the options element...
        onNodeSelected: (event) => {
            const node = event.detail.node;
            alert("You selected: " + node.text);
        }

    },
    //Themes to use for the BSTreeview. We use Bootstrap5 and FontAwesome5
    [BS5Theme, FAIconTheme]
);

//Or attach an event listener to the tree DOM element (The event is triggered on the node and bubbles upwards)
treeElement.addEventListener(EVENT_INITIALIZED, (event) => {
    console.log("The treeview has been initialized");
    treeView.expandAll()
});

Options

You can pass various options to the treeview as the second argument of the constructor, to control the behavior of the treeview. See the documentation of BSTreeViewOptions to see which options are possible and what they do.

Methods

The treeview nodes and the treeview itself can be controlled using various methods of the treeview. See the documentation of BSTreeView and the documentation of BSTreeViewNode for more information.

Most methods take an second argument with an options object. The options object can be used to pass additional parameters to the method, like preventing the triggering of events. See the respective Options class of the method for more information.

Themes

Themes are presets for the options object, which can be passed as the third argument of the constructor (as an array of themes). Multiple themes are possible, where the last theme in the array overrides the previous themes. The properties in the options object overrides every theme property.

By default, the treeview uses settings which allows it to render on bootstrap 3-5 (with glyphicons). To use a better styling for modern bootstrap versions or other icon packs, you can use the following themes:

• BS5Theme: Use Bootstrap 5's CSS variables to style the treeview
• FA5Theme: Use FontAwesome 5 icons for the treeview

Data Structure

In order to define the hierarchical structure needed for the tree it's necessary to provide a nested array of JavaScript objects.

Example:

var tree = [
    {
        text: "Parent 1",
        nodes: [
            {
                text: "Child 1",
                nodes: [
                    {
                        text: "Grandchild 1"
                    },
                    {
                        text: "Grandchild 2"
                    }
                ]
            },
            {
                text: "Child 2"
            }
        ]
    },
    {
        text: "Parent 2"
    },
    {
        text: "Parent 3"
    },
    {
        text: "Parent 4"
    },
    {
        text: "Parent 5"
    }
];

At the lowest level a tree node is a represented as a simple JavaScript object. This one required property text will build you a tree.

{
    text: "Node 1"
}

If you want to do more, here's the full node specification

{
    text: "Node 1",
        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: [
        {},
        ...
    ]
}

See documentation of the respective properties in the BSTreeViewNode class for more information. Furthermore you can pass any other property to the node, but it will be ignored by the treeview, but passed to the node element, and can for example be accessed inside event handlers.

Events

The treeview fires events when the treeview is initialized, when a node is selected or when a node is expanded or collapsed.

Global events are dispatched on the treeview element, node events on the respective node element. The event bubbles the DOM upwards, so you can attach an event listener to the treeView element to catch all node events of the treeView. You can even attach an event listener to the document, to catch the events of all treeViews on the page.

Every event name has a EVENT_ prefixed, constant which can be imported and used in your code.

Every event passes the treeView object on which the event was triggered in event.detail.treeView.

Every event has a handler parameter in the option object which is initially passed to the constructor of the treeview (e.g. the onNodeSelected property is called when a EVENT_NODE_SELECTED event is triggered).

Global events

Event constant	Event name	Description
EVENT_LOADING	bs-treeview:loading	The tree has initiated data loading
EVENT_LOADING_FAILED	bs-treeview:loadingFailed	The tree failed to load data (ajax error). In event.detail.data the exception is passed
EVENT_LOADED	bs-treeview:loaded	The tree has initialized itself and data ready for rendering. In event.detail.data a flat list of all nodes is passed
EVENT_RENDERED	bs-treeview:rendered	The tree is rendered. In event.detail.data the list of rendered nodes is passed
EVENT_DESTROYED	bs-treeview:destroyed	The tree is being destroyed
EVENT_SEARCH_COMPLETED	bs-treeview:searchCompleted	The search has completed. In event.detail.data the list of found nodes is passed
EVENT_SEARCH_CLEARED	bs-treeview:searchCleared	The search has been cleared

Node events

For every node event you can find the node object in event.detail.node.

Event constant	Event name	Description
EVENT_NODE_RENDERED	bs-treeview:nodeRendered	The node is rendered
EVENT_NODE_CHECKED	bs-treeview:nodeChecked	The node is checked
EVENT_NODE_UNCHECKED	bs-treeview:nodeUnchecked	The node is unchecked
EVENT_NODE_SELECTED	bs-treeview:nodeSelected	The node is selected
EVENT_NODE_UNSELECTED	bs-treeview:nodeUnSelected	The node is deselected
EVENT_NODE_EXPANDED	bs-treeview:nodeExpanded	The node is expanded
EVENT_NODE_COLLAPSED	bs-treeview:nodeCollapsed	The node is collapsed
EVENT_NODE_DISABLED	bs-treeview:nodeDisabled	The node is disabled
EVENT_NODE_ENABLED	bs-treeview:nodeEnabled	The node is enabled

Migrate from bootstrap-treeview

Breaking changes

• Event names are now prefixed with bs-treeview:, so the event nodeSelected becomes bs-treeview:nodeSelected
• Event signatures are changed: We use javascript native events now, which has the signature: (event: Event) => void for the handlers. You can access the data part of the event using event.detail.data
• The default value for the levels option, of how many levels should be expanded automatically, is now 1 instead of 2 (meaning no levels are expanded automatically).
• addNode()/RemoveNode()/UpdateNode() does not dispatch the initialized anymore
• initialized event is now dispatched after all nodes were rendered (therefore afterwards the render event is dispatched)

License

bs-treeview is licensed under Apache 2.0 license. This means you can use it for free and redistribute it, without much restrictions. See LICENSE for more information.

bs-treeview is based on the bootstrap-treeview library of @jonmiles and @patternfly.