Tree.js
Tree.js is a JavaScript library to build and manipulate hookable trees.
Install / Use
/learn @marmelab/Tree.jsREADME
Tree.js 
Tree.js is a JavaScript library to build and manipulate hookable trees.
Installation
It is available with bower:
bower install tree.js
Then add the retrieved files to your HTML layout:
<script type="text/javascript" src="/path/to/bower_components/tree.js/tree.min.js"></script>
<!-- If you want to build hookable tree (see below) -->
<script type="text/javascript" src="/path/to/bower_components/q/q.js"></script>
You can also use it with RequireJS as an AMD module.
Usage
Simple tree
Create a tree
var myTree = Tree.tree({
children: [
{
name: 'dupuis',
children: [
{
name: 'prunelle',
children: [
{
name: 'lebrac',
job: 'designer'
},
{
name: 'lagaffe',
firstname: 'gaston',
job: 'sleeper'
},
]
}
]
}
]
});
Find a node
var lebrac = myTree.find('/dupuis/prunelle/lebrac');
// or
var lebrac = myTree.find('/dupuis').find('/prunelle/lebrac');
// or
var lebrac = myTree.find('/dupuis').find('/prunelle').find('/lebrac');
Get the raw data of a node
lebrac.data() // { name: 'lebrac', job: 'designer' }
Get an attribute
lebrac.attr('job'); // designer
Set an attribute
lebrac.attr('job', 'director');
lebrac
.attr('location', 'here')
.attr('hobby', 'design');
Get the path of a node
lebrac.path(); // /dupuis/prunelle/lebrac
Get the parent of a node
var dupuis = lebrac.parent();
dupuis.name(); // dupuis
dupuis.parent(); // undefined
Append a child node
lebrac.append(Tree.tree({
name: 'paper',
children: [{ name: 'pen' }]
}));
lebrac.find('/paper/pen');
lebrac.find('/paper').parent().parent().parent().name(); // dupuis
Remove a node
lebrac.remove();
myTree.find('/dupuis/prunelle/lebrac'); // undefined
Move a node
var lagaffe = myTree.find('/dupuis/prunelle/lagaffe').moveTo(myTree.find('/dupuis'));
lagaffe.path(); // /dupuis/lagaffe
Get the children of a node
var children = myTree.find('/dupuis').children();
children[0].name(); // prunelle
Get a node visitor
In order to execute a callback on each node of the tree, you can use a visitor:
var visitor = myTree.visitor();
visitor(function(node) {
// you can now interact with each node
});
Stringify a node
On any node you can call stringify to serialize it. Internally it will use JSON.stringify with custom replacer to avoid circular references because of the _parent private property:
myTree.stringify()
Work with hooks
To work with hooks, you first need to add hook capacities to your tree:
var hookableTree = Tree.hookable(myTree);
Everything explained above is still true but the hookable operations will now return promises!
Because of that you need to include into your page Q library. Otherwise you can specify another promises library by calling: hookableTree.promiseFactory(YOUR_FACTORY). It must expose the same API than Q.
You can configure the timeout used for each listener by calling hookableTree.timeout(30000). Set it to 0 to disable it, default to 30000.
Register a hook listener
There are 12 hooks available:
| Hook | Description |
| ----------------: |:-------------------------------------------------------------------|
| HOOK_PRE_APPEND | Triggered when append is called and before applying it on the tree |
| HOOK_POST_APPEND | Triggered when append is called and after applying it on the tree |
| HOOK_ERROR_APPEND | Triggered when append is called and an error occured |
| HOOK_PRE_REMOVE | Triggered when remove is called and before applying it on the tree |
| HOOK_POST_REMOVE | Triggered when remove is called and after applying it on the tree |
| HOOK_ERROR_REMOVE | Triggered when remove is called and an error occured |
| HOOK_PRE_MOVE | Triggered when moveTo is called and before applying it on the tree |
| HOOK_POST_MOVE | Triggered when moveTo is called and after applying it on the tree |
| HOOK_ERROR_MOVE | Triggered when moveTo is called and an error occured |
| HOOK_PRE_CLONE | Triggered when clone is called and before applying it on the tree |
| HOOK_POST_CLONE | Triggered when clone is called and after applying it on the tree |
| HOOK_ERROR_CLONE | Triggered when clone is called and an error occured |
To register a hook you need to call registerListener(string hook, function listener):
hookableTree.registerListener(hookableTree.HOOK_PRE_APPEND, function(newNode) {
// I am a hook listener, I will be triggered before any append operation.
// The arguments are not always the same depending on the hook.
// Hook context is the tree.
this; // will be our tree
// If you need to perform asynchronous operation, just return a promise.
});
Because of hooks, append, remove, move, clone will return promise, as show in this example:
hookableTree.append(Tree.tree({ name: 'spirou'})).then(function(childNode) {
// Everything is ok, it worked!
// When you append a node, you can either give as argument a tree or hookable tree.
// If it is a hookable tree, its hook listeners will added to the parent tree.
}, function(err) {
// An error occured or a hook listener failed
});
hookableTree.find('/dupuis').remove().then(function(dupuisParent) {
// Everything is ok, it worked!
}, function(err) {
// An error occured or a hook listener failed
});
hookableTree.find('/dupuis/prunelle').moveTo(hookableTree).then(function(prunelle) {
// Everything is ok, it worked!
}, function(err) {
// An error occured or a hook listener failed
});
hookableTree.find('/dupuis/prunelle').clone().then(function(clonedPrunelle) {
// Everything is ok, it worked!
}, function(err) {
// An error occured or a hook listener failed
});
Build
To rebuild the minified JavaScript you must run: make build.
Tests
Install dependencies and run the unit tests:
make install
make test-spec
Contributing
All contributions are welcome and must pass the tests. If you add a new feature, please write tests for it.
License
This application is available under the MIT License, courtesy of marmelab.
