Ngx-bootstrap-treeview

An easy way to integrate a tree widget within your Angular projects

Summary

• Summary
• Quick warning
• Getting Started
  • Installation
  • Setting up in a project
• Usage
  • Simple demo
  • Complete demo with FA Pro styles
• Features
  • Simple singleroot tree
  • Simple multiroot tree
  • Icons customization
• Using mapper
  • Declaring a mapper
  • Understanding the maps
  • Wrap it all together
• Customizing context menu
• API Documentation
  • NgxBootstrapTreeviewComponent
  • NgxBootstrapTreeviewMapper
  • LeafClickedEvent
  • Tree (model)
  • Leaf (model)
  • TreeMap
  • LeafMap
• Todo List
• Things ngx-bootstrap-treeview uses

Quick warning

Hi guys, this plugin is still under development and still lacks some features.

The name might be quite confusing but at the moment, there is not any ngx-bootstrap component involved in this plugin. At first I thought I'd need it, then realised I could do everything, at least until now, without using it and I'll try to keep everything going this way.

PS: I think this readme is quite complete. If you find anything missing, don't hesitate to open an issue, I wrote a mnay things over a short period of time, it's highly probable that I forgot to mention something here 😅.

Getting Started

Installation

1npm install ngx-bootstrap-treeview

Or, if you're using an older version of npm:

1npm install ngx-bootstrap-treeview --save

Setting up in a project

In your app.module.ts

1// Import module in your file
2import { NgxBootstrapTreeviewModule } from 'ngx-bootstrap-treeview';
3
4@NgModule({
5    // And then you add it to your array of imports
6    imports: [NgxBootstrapTreeviewModule]
7})

Now in your HTML files, you can use the <ngx-bootstrap-treeview> tag.

Usage

The purpose of this part is to just show some code that you can copy and use straight out of the clipboard. For further documentation refer to the API Documentation part.

Simple demo

1<ngx-bootstrap-treeview [isOpened]="true" (leafClicked)="defaultStyleLeafClickedEventHandler($event)" [tree]="tree">
2</ngx-bootstrap-treeview>

Complete demo with FA Pro styles

1<ngx-bootstrap-treeview
2    [isOpened]="true"
3    (leafClicked)="lightStyleLeafClickedEventHandler($event)"
4    [tree]="tree"
5    [disableLeafSelection]="false"
6    [selectedLeafIcon]="faCheckSquare"
7    [unselectedLeafIcon]="faSquare"
8    [openedFolderIcon]="faFolderOpen"
9    [closedFolderIcon]="faFolder"
10    [anyChildrenSelectedIcon]="faMinus"
11    [allChildrenSelectedIcon]="faCheck"
12>
13</ngx-bootstrap-treeview>

Features

For this section, we'll consider having a Tree[] with the following value:

1const roots = [
2    {
3        label: 'Langages de programmation',
4        value: 1,
5        children: [
6            {
7                label: 'C++',
8                value: 11
9            },
10            {
11                label: 'Angular',
12                value: 12
13            },
14            {
15                label: 'C#',
16                value: 13,
17                children: [
18                    {
19                        label: 'LinQ',
20                        value: 131
21                    },
22                    {
23                        label: 'UWP',
24                        value: 132
25                    },
26                    {
27                        label: 'Sharepoint',
28                        value: 133
29                    },
30                    {
31                        label: 'WPF',
32                        value: 134
33                    }
34                ]
35            },
36            {
37                label: 'Java',
38                value: 14,
39                children: [
40                    {
41                        label: 'J2E',
42                        value: 141
43                    },
44                    {
45                        label: 'Spring Framework',
46                        value: 142
47                    },
48                    {
49                        label: 'Vanilla Java',
50                        value: 143
51                    },
52                    {
53                        label: 'Android',
54                        value: 144
55                    }
56                ]
57            },
58            {
59                label: 'Empty folder test',
60                value: 15,
61                children: []
62            }
63        ]
64    }, {
65        value: 1111,
66        label: 'Customers',
67        children: [
68            {
69                label: 'Norton',
70                value: 156
71            },
72            {
73                label: 'Symantec',
74                value: 116
75            },
76            {
77                label: 'Some company',
78                value: 126
79            },
80            {
81                label: 'Zokelion',
82                value: 196
83            }
84        ]
85    }
86]

The next paragraphs will just show some HTML snippets that rely on these datas. We'll see later how to use custom objects to build our tree

Simple singleroot tree

1<!-- Here, roots[0] is a Tree since roots is a Tree[] -->
2<ngx-bootstrap-treeview
3    [tree]="roots[0]"
4    [mapper]="mapper"
5    [isOpened]="true"
6>
7</ngx-bootstrap-treeview>

Simple multiroot tree

1<ngx-bootstrap-treeview
2    [trees]="roots"
3    [mapper]="mapper"
4    [isOpened]="true"
5>
6</ngx-bootstrap-treeview>

Icons customization

All icons can be customized, as long as you have access to them in your FontAwesome library. As an example, here, we're using FontAwesome light style. First, let's take an eye to what our TS should look like:

1// Import the every IconDefinition you'll want to use
2import { faFolder, faFolderOpen, faSquare, faCheckSquare, faCheck, faMinus } from '@fortawesome/pro-light-svg-icons';
3
4@Component({
5    selector: 'app-root',
6    templateUrl: './app.component.html',
7    styleUrls: ['./app.component.css']
8})
9export class AppComponent {
10    // Register them into your component
11    public faFolder = faFolder;
12    public faFolderOpen = faFolderOpen;
13    public faSquare = faSquare;
14    public faCheckSquare = faCheckSquare;
15    public faMinus = faMinus;
16    public faCheck = faCheck;
17}

And then, back to some HTML:

1<!-- [propertyYouWantToChangeIcon]="nameInComponent" -->
2<ngx-bootstrap-treeview
3    [isOpened]="true"
4    [trees]="trees"
5    [disableLeafSelection]="false"
6    [selectedLeafIcon]="faCheckSquare"
7    [unselectedLeafIcon]="faSquare"
8    [openedFolderIcon]="faFolderOpen"
9    [closedFolderIcon]="faFolder"
10    [anyChildrenSelectedIcon]="faMinus"
11    [allChildrenSelectedIcon]="faCheck"
12>
13</ngx-bootstrap-treeview>

Using mapper

The mapper takes two maps as a params as well as 2 types. For our example, we'll use these 2 classes to generate our treeview:

1class Skill {
2    public id: number;
3    public label: string;
4    public categoryId: number;
5}
6
7class Category {
8    public id: number;
9    public name: string;
10    public children: Category[];
11    public skills: Skill[];
12}

Some properties differ from our Tree and Leaf models and we don't need to have the categoryId inside our leaves. A Category stands for a branch and a Skill stands for a Leaf.

If we want to get a tree from such data, we must first re-organize it. That's what the mapper stands for.

Declaring a mapper

As explained above, a mapper takes two types as arguments. First one is the type that will be converted in branch (Tree object), second one is the type that will be converted in leaves. Here, our declaration would look like so:

1const mapper: NgxBootsrapTreeviewMapper<Category, Skill>;

Note that it's just a declaration. To instanciate it, we'll need to indicate how our data will be mapped. So let's dive a bit further into the maps.

Understanding the maps

We have two types of map: TreeMap and LeafMap which are respectively used for mapping trees and leaves. TreeMap has the exact same properties as Tree and LeafMap has the exact same properties as Leaf except that for the maps, all of the properties are of type string because they must contain the name of the key, in the source objects, that will be converted to the given property.

Maps for a treeview that displays skills by categories would look like this:

1const treeMap = {
2    children: 'children',
3    leavesKey: 'skills',
4    value: 'id',
5    label: 'name'
6};
7
8const leafMap = {
9    value: 'id',
10    label: 'label'
11};

Wrap it all together

So now that we have all of the keys, let's wrap everything we have to get a working mapper:

1const mapper = new NgxBootsrapTreeviewMapper<Category, Skill>(treeMap, leafMap);

And then we just give it to our treeview within the HTML

1<ngx-bootstrap-treeview
2    [items]="skillsByCategories"
3    [mapper]="mapper"
4    [isOpened]="true"
5>
6</ngx-bootstrap-treeview>

Customizing context menu

Version 1.1 introduced a feature that allow user to have a custom context menu when right clicking the tree. This is done by giving an NgxBootstrapTreeviewContextMenus object as an @Input() to the treeview Every interface you may need can be directly imported from ngx-bootstrap-treeview For now, this feature does not support nested menus.

API Documentation

NgxBootstrapTreeviewComponent

Here is a list of all the @Input():

Name	Type	default value	Description
tree	Tree	undefined	Used as datasource for singleroot trees. Equivalent to giving trees with only one item
trees	Tree[]	undefined	Used when giving an array of Tree as the datasource
mapper	NgxBootstrapTreeviewMapper	undefined	This is mandatory when providing the items or item parameter. It is used when building the treeview. Further documentation below.
item	Object	undefined	The object you want to display in the tree. Equivalent to giving items with only one entry.
items	Object[]	undefined	List of objects you want to display in the treeview. The tree will use the mapper and iterate over this to build the view.
isOpened	boolean	false	If true, first level tree(s) is/are opened by default
isAnimationDisabled	boolean	false	Allows the user to disable any animation on branches folding/unfolding
disableLeafSelection	boolean	false	Only branches can be selected
openedFolderIcon	IconDefinition	faFolderOpen	Icon used to represent an opened branch
closedFolderIcon	IconDefinition	faFolder	Icon used to represent a closed branch
unselectedLeafIcon	IconDefinition	faSquare	Icon used on not selected leaves
selectedLeafIcon	IconDefinition	faCheckSquare	Icon used on selected meaves
anyChildrenSelectedIcon	IconDefinition	faMinus	Icon that will be put inside of the folder icon if it contains at least one ticked leaf
allChildrenSelectedIcon	IconDefinition	faCheck	Icon that will be put inside of the folder icon if all of its children are selected
emptyFolderLabel	string	"This folder is empty"	The label to display inside empty branches
contextMenus	NgxBootstrapTreeviewContextMenus	empty menus	An object describing what your context menus on the tree should look like. If this is not specified, context menu will simply be disabled

None of these inputs are mandatory. Just remember that the tree MUST have a datasource. Either by providing tree or trees, or by giving a mapper + item or items.

NgxBootstrapTreeviewMapper

The purpose of this class is to map a given object to a Tree. Its constructor takes 2 params, treeMap which indicates how to map a tree and find its leaves and leafMap which indicates how to map a leaf when we find some. For more informations about all of this, check the Using mapper part.

LeafClickedEvent

This event is emitted whenever a leaf gets selected or unselected. It contains the leaf that was click along with a complete list of all the leaves that are ticked inside the tree.

Here is what it looks like:

1class LeafClickedEvent {
2    public leaf: Leaf;
3    public selectedLeaves?: Leaf[];
4}

Tree (model)

This class and the next one are pretty self-explanatory. Just use them as interfaces if you ever need them.

1class Tree {
2    children?: Tree[];
3    loadChildren?: Function;
4    label: string;
5    value: number | string;
6}

Leaf (model)

1class Leaf {
2    public value: string | number;
3    public label: string;
4}

TreeMap

1interface TreeMap {
2    value: string;
3    label: string;
4
5    // Contains the key that will point to the property of the source object that will contain children of the same type
6    // For a type T being the data source/branch type, this will point to the T[] type property
7    children?: string;
8
9    // Same idea as above, for type U indicating the datasource type, this will point to a U[]
10    leavesKey: string;
11}

LeafMap

1interface LeafMap {
2    value: string;
3    label: string;
4}

Todo List

• Find a way to support custom objects as datasource (See Using Mapper part of the readme)
• Boxes or custom right click to select/unselect an entire branch
• Async loading of children with a loadChildren callback (started working on it, paused right now)
• Possibility to disable animation and maybe add a set of fancy ones when folding/unfolding a branch
• Allow a Tree array as an @Input() so this plugin can support multi-root trees (Done)
• I'll probably have more ideas as this evolves

Things ngx-bootstrap-treeview uses

• Angular FontAwesome when it comes to icons
• Some of the Bootstrap classes