Merge pull request #122 from valor-software/tree-api

feature(tree-api): create an API to manipulate a node

Author: Georgii Rychko

README.md

@@ -23,6 +23,19 @@
     - [NodeRenamedEvent](#noderenamedevent)
     - [NodeExpandedEvent](#nodeexpandedevent)
     - [NodeCollapsedEvent](#nodecollapsedevent)
+- [:gun: Controller](#gun-controller)
+    - [select - selecting a node](#select---selecting-a-node)
+    - [isSelected - checks whether a node is selected](#isselected---checks-whether-a-node-is-selected)
+    - [collapse - collapses a node](#collapse---collapses-a-node)
+    - [isCollapsed - check whether a node is collapsed](#iscollapsed---check-whether-a-node-is-collapsed)
+    - [expand - expands a node](#expand---expands-a-node)
+    - [isExpanded - checks wheather a node is expanded](#isexpanded---checks-wheather-a-node-is-expanded)
+    - [rename - renames a node (changes its value underneath)](#rename---renames-a-node-changes-its-value-underneath)
+    - [remove - removes a node from the tree](#remove---removes-a-node-from-the-tree)
+    - [addChild - creates a new child node](#addchild---creates-a-new-child-node)
+  - [changeNodeId - changes node's id](#changenodeid---changes-nodes-id)
+  - [reloadChildren - load async children once more](#reloadchildren---load-async-children-once-more)
+  - [setChildren - changes children of a node;](#setchildren---changes-children-of-a-node)
 - [SystemJS](#systemjs)
 - [Changes that should be taken into account in order to migrate from __ng2-tree V1__ to __ng2-tree V2__](#changes-that-should-be-taken-into-account-in-order-to-migrate-from-__ng2-tree-v1__-to-__ng2-tree-v2__)
 - [:bulb: Want to help?](#bulb-want-to-help)
@@ -115,7 +128,7 @@ Voila! That's pretty much it - enjoy :blush:
 
 ## :eyes: Demo
 Feel free to examine the [demo](https://valor-software.github.io/ng2-tree/index.html) and its [sources](src/demo) to find out how things are wired.
-Also there is [another demo built with Angular CLI](https://github.com/rychkog/ng2-tree-demo).
+Also, there is [another demo built with Angular CLI](https://github.com/rychkog/ng2-tree-demo).
 
 ## :wrench: API
 
@@ -161,7 +174,7 @@ interface TreeModel {
 }
 ```
 
-As you can see - object that conforms to this interface has a recursive nature, example can be seen below:
+As you can see - an object that conforms to this interface has a recursive nature, an example can be seen below:
 
 ```typescript
 {
@@ -260,7 +273,7 @@ Another worth noting thing is `loadChildren`. This function on `TreeModel` allow
 }
 ```
 
-Node that defines this function is collapsed by default. At the moment of clicking 'Expand' arrow it starts loading its children by calling given function.
+Node that defines this function is collapsed by default. At the moment of clicking 'Expand' arrow, it starts loading its children by calling given function.
 If `loadChildren` function is given to the node - `children` property is ignored. For more details - have a look at the [Demo](#eyes-demo).
 
 #### Configure node via TreeModelSettings
@@ -309,7 +322,7 @@ Here is an example of its usage:
   * `leaf` - String - It specifies a html template which will be included to the left of the leaf's value.
   * `leftMenu` - String - It specifies a html template to the right of the node's value. This template becomes clickable and shows a menu on node's click.
 
-All options that's defined on a `parent` are automatically applied to children. If you want you can override them by `settings` of the child node.
+All options that are defined on a `parent` are automatically applied to children. If you want you can override them by `settings` of the child node.
 
 ### [settings]
 
@@ -325,7 +338,7 @@ By default `rootIsVisible` equals to `true`
 
 ### `Tree` class
 
-Also in the next section you'll be reading about events generated by the `ng2-tree`. And here [Tree](src/tree.ts) class comes in handy for us, because its instances propagated with event objects. Under the hood `ng2-tree` wraps a `TreeModel` provided by the user in `Tree`. And `Tree` in turn has lots of useful methods and properties (like `parent`, `hasChild()`, `isRoot()` etc.)
+Also in the next section, you'll be reading about events generated by the `ng2-tree`. And here [Tree](src/tree.ts) class comes in handy for us, because its instances propagated with event objects. Under the hood, `ng2-tree` wraps a `TreeModel` provided by the user in `Tree`. And `Tree` in turn has lots of useful methods and properties (like `parent`, `hasChild()`, `isRoot()` etc.)
 
 ### events (nodeMoved, nodeSelected, nodeRenamed, nodeRemoved, nodeCreated, nodeExpanded, nodeCollapsed)
 
@@ -402,10 +415,10 @@ You can subscribe to `NodeCreatedEvent` by attaching listener to `(nodeCreated)`
     </tree>
 ```
 
-`NodeCreatedEvent` has a `node` property of type `Tree`, which contains a created node.
+`NodeCreatedEvent` has a `node` property of type `Tree`, which contains a created node and a `controller` property, which will give you access to node's controller.
 
 ```typescript
-{node: <Tree>{...}}
+{node: <Tree>{...}, controller: <TreeController>{...}}
 ```
 
 #### NodeRenamedEvent
@@ -421,7 +434,7 @@ You can subscribe to `NodeRenamedEvent` by attaching listener to `(nodeRenamed)`
 
 `NodeRenamedEvent` has three properties:
 
-- `node` contains node that was renamed (instance of `Tree`).
+- `node` contains a node that was renamed ( an instance of `Tree`).
 - `oldValue` contains a value, that node used to have (it might be `string` or `RenamableNode`)
 - `newValue` contains a new value of the node (it might be `string` or `RenamableNode`)
 
@@ -467,6 +480,188 @@ You can subscribe to `NodeCollapsedEvent` by attaching listener to `(nodeCollaps
 {node: <Tree>{...}}
 ```
 
+## :gun: Controller
+First of all you should know how to get a controller of a particular node. You can get a controller of a node only if you set an id property of a node. For example, your tree structure should look like:
+
+```typescript
+public tree: TreeModel = {
+    value: 'Programming languages by programming paradigm',
+    id: 1,
+    children: [
+      {
+        value: 'Object-oriented programming',
+        id: 2,
+        children: [
+          {value: 'Java', id: 3},
+          {value: 'C++', id: 4},
+          {value: 'C#', id 5},
+        ]
+      },
+      {
+        value: 'Prototype-based programming',
+        id: 6,
+        children: [
+          {value: 'JavaScript', id: 7},
+          {value: 'CoffeeScript', id: 8},
+          {value: 'Lua', id: 9},
+        ]
+      }
+    ]
+  };
+```
+
+Ids must be unique within a one tree, otherwise, some controllers will be overwritten and you won't be able to acquire them.
+In order to get a node's controller you need to create an Angular local variable out of tree component via hash binding in the template:
+
+```typescript
+@Component({
+  template: '<tree [tree]="tree" #treeComponent></tree>'
+})
+class TheComponent implements AfterViewInit {
+  tree: TreeModel = {
+    value: 'Programming languages by programming paradigm',
+    id: 1,
+    children: [
+      {
+        value: 'Object-oriented programming',
+        id: 2,
+        children: [
+          {value: 'Java', id: 3},
+          {value: 'C++', id: 4},
+          {value: 'C#', id 5},
+        ]
+      },
+      {
+        value: 'Prototype-based programming',
+        id: 6,
+        children: [
+          {value: 'JavaScript', id: 7},
+          {value: 'CoffeeScript', id: 8},
+          {value: 'Lua', id: 9},
+        ]
+      }
+    ]
+  };
+
+  @ViewChild('treeComponent') treeComponent;
+
+  ngAfterViewInit(): void {
+    // ... make use of this.treeComponent ...
+  }
+}
+```
+
+then by executing `this.treeComponent.getControllerByNodeId(PUT_HERE_YOUR_NODE_ID)` you'll get an instance of a TreeController (another couple steps and the world is yours =) )
+
+Below are more detailed explanations of the TreeController and its usage. Let's go method by method:
+
+```typescript
+const oopNodeController = this.treeComponent.getControllerByNodeId(2);
+```
+
+#### select - selects a node
+
+```typescript
+oopNodeController.select();
+```
+
+This method selects the node and unselects all the other nodes, also it fires a select event.
+
+#### isSelected - checks whether a node is selected
+
+```typescript
+oopNodeController.isSelected();
+```
+
+This method returns true if the node is selected and false if it isn't.
+
+#### collapse - collapses a node
+
+```typescript
+oopNodeController.collapse();
+```
+
+This method collapses a node if the node is collapsible (for example we cannot collapse a leaf). If the node gets collapsed successfully - a collapse event gets fired.
+
+#### isCollapsed - check whether a node is collapsed
+
+```typescript
+oopNodeController.isCollapsed();
+```
+
+This method returns true if the node is collapsed and false otherwise.
+
+#### expand - expands a node
+
+```typescript
+oopNodeController.expand();
+```
+
+This method expands the node in case it can be expanded. On successful expanding the expand event is fired.
+
+#### isExpanded - checks whether a node is expanded
+
+```typescript
+oopNodeController.isExpanded();
+```
+
+This method returns true if the node is expanded and false otherwise.
+
+#### rename - renames a node (changes its value underneath)
+
+```typescript
+oopNodeController.rename('new value');
+```
+
+This method accepts a string and sets it as a node's new value, this action also fires rename event.
+
+#### remove - removes a node from the tree
+
+```typescript
+oopNodeController.remove();
+```
+
+This method removes the node and its children and fires remove event.
+
+#### addChild - creates a new child node
+
+```typescript
+let newNode: TreeModel = {
+  value: 'Go',
+  children: []
+};
+oopNodeController.addChild(newNode);
+```
+
+This method accepts a TreeModel and adds it as a child of the parent or as a sibling (depends on which controller this was called - branch controller or a leaf controller).
+
+### changeNodeId - changes node's id
+
+```typescript
+oopNodeController.changeNodeId(10);
+```
+
+This method can change a node's id. When the user creates a node from node's menu you will access the new node after it's created and this method will provide a way to change the node's id.
+
+### reloadChildren - loads async children once more
+
+```typescript
+oopNodeController.reloadChildren();
+```
+
+### setChildren - changes children of a node;
+
+```typescript
+let newChildren: Array<TreeModel> = [
+  {value: 'new children 1'},
+  {value: 'new children 2'},
+  {value: 'new children 3'}
+];
+oopNodeController.setChildren(newChildren);
+```
+
+This method replaces all existing children of the node with new ones.
+
 ## SystemJS
 If you are using SystemJS, then you need
 
@@ -487,10 +682,10 @@ System.config({
   - In V1 all events that were inherited from NodeDestructiveEvent used to have property `parent`. It's not the case anymore. If you need a parent you should get it from `node` in event object like `node.parent`;
   - All events used to have `node` property of type `TreeModel`. Now `node` is of type [Tree](#tree-class) (as well as `node.parent`);
   - `NodeMovedEvent` now has property `previousParent`, which contains tree in which moved node used to be.
-- CSS styles in __ng2-tree V2__ are distributed as separate file which you can find in `node_modules/ng2-tree/styles.css`. That allows you to override ng2-tree styles more easely.
+- CSS styles in __ng2-tree V2__ are distributed as separate file which you can find in `node_modules/ng2-tree/styles.css`. That allows you to override ng2-tree styles more easily.
 
 ## :bulb: Want to help?
 
 I am very appreciate for your ideas, proposals and found bugs which you can put in [github issues](https://github.com/valor-software/ng2-tree/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.
+**P.S.** If you find it hard going through the documentation, please, let me know which parts of it was difficult to grasp and I will improve them.