ahmedalatawi / ngx-treant-js

A simple Angular2+ component used as a wrapper for TreantJS library for visualization of tree (chart) diagrams, with additional functionality.

NgxTreantJS 🌳

A simple Angular2+ component used as a wrapper for TreantJS library for visualization of tree (chart) diagrams, with additional functionality. 🔥🔥🔥

Demo 🎥

⬇️ Installation

npm install @ahmed757/ngx-treant-js --save

🔧 Configuration

Add required dependencies to angular.json as follows:

...

"styles": [
    "node_modules/treant-js/Treant.css",
    "node_modules/treant-js/vendor/perfect-scrollbar/perfect-scrollbar.css",
    "src/styles.css"
],
"scripts": [
    "node_modules/jquery/dist/jquery.min.js",
    "node_modules/popper.js/dist/umd/popper.js",
    "node_modules/treant-js/vendor/jquery.easing.js",
    "node_modules/treant-js/vendor/jquery.mousewheel.js",
    "node_modules/treant-js/vendor/perfect-scrollbar/perfect-scrollbar.js",
    "node_modules/treant-js/vendor/raphael.js",
    "node_modules/treant-js/Treant.js"
]
...

See full example here.

✏️ Key Goals

• Easy to integrate and use in any Angular applications
• Provide callback functions to react to user's actions, e.g. single-click, double-click, drag-drop, hover, etc
• provide drag-drop feature for swapping (re-positioning) Tree nodes
• Support adding & removing Tree nodes
• Support editting Node's content, e.g. name, title, etc

Quick start 🚀

employess-chart.component.html

<ngx-treant-chart
    [chartId]="employeesChartId"
    [chartClass]="employeesChartClass"
    [data]="employeesData">
</ngx-treant-chart>

employess-chart.component.ts

export class EmployeesChartComponent {
    employeesChartId = 'employessChart-commpany';
    employeesChartClass = 'employess-chart';

    employeesData = {
        chart: {
            container: "#employessChart-commpany",
            
            connectors: {
                type: 'step'
            },
            node: {
                HTMLclass: 'employessNode'
            }
        },
        nodeStructure: {
            text: {
                name: "Paul Young",
                title: "Chief executive officer",
                contact: "Cel: 01 213 123 134",
            },
            image: "assets/images/img1.jpg",
            children: [
                {
                    text:{
                        name: "John Doe",
                        title: "Chief Technology Officer",
                    },
                    stackChildren: true,
                    image: "assets/images/img2.jpg",
                    children: [ ... ]
                }
            ]
        }
    }
}

styles.css

...
.employess-chart {
  height: 600px;
  margin: 5px;
  width: 900px;
}

.Treant> p {
  font-family: "HelveticaNeue-Light", "Helvetica Neue Light", "Helvetica Neue", Helvetica, Arial, "Lucida Grande", sans-serif;
  font-weight: bold;
  font-size: 12px;
}

.node-name {
  font-weight: bold;
}

.employessNode {
  padding: 2px;
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  border-radius: 3px;
  background-color: #ffffff;
  border: 1px solid #000;
  width: 200px;
  font-family: Tahoma;
  font-size: 12px;
}
...

See full example here.

Note: 💡 In a real world application, the data would most likely come from a server or remote place, which means that we would need to initialize NgxTreantChart only when data arrives. Therefore, *ngIf can be used as a workaround as follows:

<ngx-treant-chart
    ...

    *ngIf="isDataLoaded">
</ngx-treant-chart>

Bootstrap Popover Example

📄 NgxTreantChart component API

Attributes	Description
[chartId]	The chart uniqe ID (required)
[chartClass]	The chart CSS class uniqe name (optional)
[data]	The data used for visualization of chart diagrams (required)
[popoverSettings]	The settings used for customizing a popover (optional - see example)
[mouseleaveMilliseconds]	The mouseleaveMilliseconds delay used prior to a popover being hidden (optional)
[isDraggable]	A boolean flag used to enable drag & drop support (optional)
(clicked)	A callback function invoked when a TreeNode is clicked
(hovered)	A callback function invoked when a TreeNode is mouse hovered
(dragged)	A callback function invoked when a TreeNode is dragged
(dropped)	A callback function invoked when a TreeNode is dropped
(updated)	A callback function invoked when TreeNode's content is updated on dblclick event
(loadedNodes)	A callback function invoked when TreeNodes are loaded
(loadedTree)	A callback function invoked when the Tree is loaded
(loadedTreant)	A callback function invoked when the Treant is loaded

Notes: 💡

1. The callback functions: clicked, hovered, and updated return a value of Object type, which consists of two properties:

• Node: instance of TreeNode type for the node that was modified
• $: jQuery instance, which can be used to perform any additional desired functionality that requires jQuery

Example 📌

<ngx-treant-chart
    ...

    (clicked)="onClick($event)">
</ngx-treant-chart>

onClick(event: any): void {
/* 
event: {
  node: {
    X: 106
    Y: 259.5
    children: (3) [1, 4, 19]
    collapsable: undefined
    collapsed: undefined
    connStyle: {type: "step", style: {…}, 
    stackIndent: 15}
    drawLineThrough: undefined
    height: 30
    id: 0
    image: undefined,
    ...
  },

  $: ƒ (e,t)
}
*/
}

2. The callback function dragged returns an object which contains an instance of TreeNode type as well as jQuery as follows:

{
    draggedNode: {
        X: 106
        Y: 259.5
        children: (3) [1, 4, 19]
        collapsable: undefined,
        ...
    },

    $: ƒ (e,t)
}

3. The callback function dropped returns the following:

• draggedNode: the dragged node of TreeNode type
• droppedNode: the dropped node of TreeNode type
• $: jQuery instance

4. The callback function loadedNodes returns all Tree (chart) nodes.

5. The callback function loadedTree returns an instance of Tree (chart) type. The instance provides useful properties and functions, such as nodeDB and positionTree(), which can be used to update tree (chart) nodes:

...

onLoadTree(tree: any): void {
    const nodes = tree.nodeDB;

    // do something with nodes

    tree.positionTree(); // apply changes
}

6. The callback function loadedTreant returns an instance of Treant type. The instance consists of container_id and tree_id:

...

onLoadTreant(treant: any): void {
    console.log(treant);
    /* example
      {
        container_id: "employessChart-commpany",
        tree_id: 0
      }
    */

    treant.destroy(); // destroy tree
}

Reference 🎯

• TreantJS

Author 📚

Ahmed Alatawi