ng2-branchy is a simple Angular 2 component for visualizing data that can be naturally represented as a tree.
Ok, let's start with an installation - all you need to do is:
npm install --save ng2-branchy
Now when you have branchy installed you need to add it to your component's template and to the list of its directives:
// 1 - import required classes and interfaces
import {BranchyComponent, TreeModel} from 'ng2-branchy';
@Component({
selector: 'myComp',
// 2 - add branchy to the template
template: `
<branchy [tree]="tree"></branchy>
`,
// 3 - add branchy to the list of directives
directives: [BranchyComponent]
})
class MyComponent {
...
}As soon as the previous step is done we need to give branchy a model to render - this can be accomplished by populating its [tree] attribute with an object that confirms to TreeModel interface (see API):
// 1 - import required classes and interfaces
import {BranchyComponent, TreeModel} from 'ng2-branchy';
@Component({
selector: 'myComp',
// 2 - set [tree] attribute to tree object
template: `
<branchy [tree]="tree"></branchy>
`,
directives: [BranchyComponent]
})
class MyComponent {
// 3 - make sure tree object confirms to TreeModel interface
private tree: TreeModel = {
value: 'Programming languages by programming paradigm',
children: [
{
value: 'Object-oriented programming',
children: [
{value: 'Java'},
{value: 'C++'},
{value: 'C#'},
]
},
{
value: 'Prototype-based programming',
children: [
{value: 'JavaScript'},
{value: 'CoffeeScript'},
{value: 'Lua'},
]
}
]
};
}Apart from that I suppose you'd want to listen for branchy's events (for a full list of supported events look at API). No problem, this is also easy to do - for example let's add a listener for node was selected events:
// 1 - import required classes and interfaces
import {BranchyComponent, TreeModel, NodeEvent} from 'ng2-branchy';
@Component({
selector: 'myComp',
// 2 - listent for nodeSelected events and handle them
template: `
<branchy [tree]="tree" (nodeSelected)="logEvent($event)"></branchy>
`,
directives: [BranchyComponent]
})
class MyComponent {
private tree: TreeModel = { ... };
// 3 - print caught event to the console
private logEvent(e: NodeEvent): void {
console.log(e);
}
}Voila! That's pretty much it - enjoy 😊
Feel free to examine the demo and its sources to find out how things are wired.
Here is the fully stuffed branchy tag that you can use in your templates:
<branchy
[tree]="tree"
(nodeRemoved)="handleRemoved($event)"
(nodeRenamed)="handleRenamed($event)"
(nodeSelected)="handleSelected($event)"
(nodeMoved)="handleMoved($event)"
(nodeCreated)="handleCreated($event)">
</branchy>Let's go through every element of this structure one by one.
branchy is the selector for BranchyComponent which you can import like shown below:
import {BranchyComponent} from 'ng2-branchy';branchy has [tree] attribute which need to be populated with an object implementing TreeModel interface. You can import this interface as following
import {TreeModel} from 'ng2-branchy';Here is the definition of TreeModel interface:
interface TreeModel {
value: string | RenamableNode;
children?: Array<TreeModel>;
}As you can see it is recursive and can be represented as the following object:
{
value: 'Programming languages by programming paradigm',
children: [
{
value: 'Object-oriented programming',
children: [
{value: 'Java'},
{value: 'C++'},
{value: 'C#'},
]
},
{
value: 'Prototype-based programming',
children: [
{value: 'JavaScript'},
{value: 'CoffeeScript'},
{value: 'Lua'},
]
}
]
}Property value can be of type string or RenamableNode.
RenamableNode gives you additional control over the way node is renamed and rendered (by rendered I mean its text representation). Here is the definition of RenamableNode interface:
interface RenamableNode {
setName(name: string): void;
toString(): string;
}Here is an example of such a node in the TreeModel object:
{
value: 'Programming languages by programming paradigm',
children: [
{
value: 'Object-oriented programming',
children: [
{
value: <RenamableNode>{
name: 'Java',
setName(name: string): void {
this.name = name;
},
toString(): string {
return this.name;
}
}
},
{value: 'C++'},
{value: 'C#'},
]
},
{
value: 'Prototype-based programming',
children: [
{value: 'JavaScript'},
{value: 'CoffeeScript'},
{value: 'TypeScript'},
]
}
]
};Here is the diagram that shows branchy events' hierarchy
NodeEvent is the root of branchy events' hierarchy. It defines property node that contains a receiver of the event's action (node confirms to TreeModel).
NodeDestructiveEvent is the parent for all events that cause changes to a structure of the tree or to a node value.
It defines property 'parent' that contains an object implementing 'TreeModel' interface and gives context to the event's action.
You can subscribe to NodeSelectedEvent by attaching listener to (nodeSelected) attribute
<branchy
[tree]="tree"
(nodeSelected)="handleSelected($event)">
</branchy>NodeSelectedEvent has just one property node which contains TreeModel object of a selected node.
{node: <TreeModel>{...}}NodeSelectedEvent inherits its property directly from NodeEvent.
You can subscribe to NodeMovedEvent by attaching listener to (nodeMoved) attribute
<branchy
[tree]="tree"
(nodeMoved)="handleMoved($event)">
</branchy>NodeMovedEvent has two properties node and parent both of which contain TreeModel objects.
node contains moved node.
parent contains new parent of the moved node.
{node: <TreeModel>{...}, parent: <TreeModel>{...}}NodeMovedEvent inherits its properties from NodeDestructiveEvent.
You can subscribe to NodeRemovedEvent by attaching listener to (nodeRemoved) attribute
<branchy
[tree]="tree"
(nodeRemoved)="handleRemoved($event)">
</branchy>NodeRemovedEvent has two properties node and parent both of which contain TreeModel objects.
node contains removed node.
parent contains parent of the removed node.
{node: <TreeModel>{...}, parent: <TreeModel>{...}}NodeRemovedEvent inherits its properties from NodeDestructiveEvent.
You can subscribe to NodeCreatedEvent by attaching listener to (nodeCreated) attribute
<branchy
[tree]="tree"
(nodeCreated)="handleCreated($event)">
</branchy>NodeCreatedEvent has two properties node and parent both of which contain TreeModel objects.
node contains created node.
parent contains parent of the newly created node.
{node: <TreeModel>{...}, parent: <TreeModel>{...}}NodeCreatedEvent inherits its properties from NodeDestructiveEvent.
You can subscribe to NodeRenamedEvent by attaching listener to (nodeRenamed) attribute
<branchy
[tree]="tree"
(nodeRenamed)="handleRenamed($event)">
</branchy>NodeRenamedEvent has four properties:
nodecontains node that was renamed (implementsTreeModel).parentcontains parent (implementsTreeModel) for the renamed node.oldValuecontains value node used to have (it might bestringorRenamableNode)newValuecontains new value of the node (it might bestringorRenamableNode)
{
node: <TreeModel>{...},
parent: <TreeModel>{...},
oldValue: <string|RenamableNode>{...},
newValue: <string|RenamableNode>{...}
}NodeRenamedEvent inherits its node and parent properties from NodeDestructiveEvent.
Currently I feel really bad because of two things:
- branchy doesn't have tests (yet), so I wouldn't recommend you to use this in a production environment
- branchy doesn't have proper mechanism for customizing its look
I really want to deminish all the Bad parts and extend branchy with a new stuff
I am very appreciate for your ideas, proposals and found bugs which you can leave in github issues. Thanks in advance!
P.S. If you find it hard going through documentation, please, let me know which parts of it was difficult to grasp and I will improve them.