{{>getting-started}}

Using TreeView

Simplest tree can be built as follows: ```

```

`TreeView` uses `Widget Parent` - `Widget child` architecture, where single `TreeView` instance holds nested hierarchy of `TreeNode` objects.

Tree configuration

The following configuration properties are supported:
startCollapsed
By default tree is rendered having all of its nodes expanded. Set this property to `true` to render tree collapsed by default
toggleOnLabelClick
This property determines whether tree node will be collapsed/expanded when click only on a control ("+" sign) or on a node label as well

Skinning

Sam skin is bundled with TreeView. Make sure to enable it by adding `yui3-skin-sam` class to the tree container. More info on YUI skinning is can be found here.

Rendering from markup

Markup pattern ```

```

To build tree from the above markup, simply ``` var treeview = new Y.TreeView({}); treeview.render("#tree"); ```

Changing existing tree

`TreeView` uses YUI widget parent-child to hold the tree hierarchy. This makes adding or removing nodes straight forward.

Adding nodes

Using config - probably the most simplest way ``` treeview.add({ label: "orange" }); treeview.add({ label: "peaches", children: [ {label: "white-flesh"}, {label: "yellow-flesh"} ]); ```

Or using `TreeNode` instance ``` var node = Y.TreeNode({label: "pear"}); treeview.add(node); ```

Removing nodes

Once you have `TreeNode` reference, simple call ``` treeview.remove(node); ```

CheckBox TreeView

Creating tree with check-boxes near each node is as simple as ``` var treeview = new Y.CheckBoxTreeView(); treeview.render("#tree"); ```

`CheckBoxTreeView` supports `checkOnLabelClick` property which is similarly to `toggleOnLabelClick` defines whether node click changes checkbox state.

Node checked state

Tree nodes are unchecked by default.

You can set initial node checked state through `checked` configuration property. It accepts either `unchecked`, `halfchecked`, `checked`, or correspondingly `10`, `20`, `30`. Please note that property getter returns only numeric value. ``` var treeview = new Y.CheckBoxTreeView({ children: [ { label: "peach", checked: "checked"} ] }); ``` Note: Specifying checked state when rendering from markup is currently not supported.

Querying for checked nodes and paths

There are two utility methods that helps querying checkbox tree for currently selected nodes:
`getChecked`
Returns the list of nodes that are roots of checked subtrees
`getCheckedPaths`
Returns list of pathes (breadcrumbs) of nodes that are roots of checked subtrees
Example: ``` treeview.after("check", function(e) { var checked_roots = [], checked_paths = []; Y.Array.each(treeview.getChecked(), function (n) { checked_roots.push(n.get("label")); }); Y.log("Checked roots:\n" + checked_roots.join("\n")); Y.Array.each(treeview.getCheckedPaths(), function (n) { checked_paths.push(n.join(" > ")); }); Y.log("Checked paths:\n" + checked_paths.join("\n")); }); ```

Tree events

Tree supports variety of events signifying that nodes are being clicked, checked, expanded and collapsed. In addition you can listen for regular widget events, for example monitoring nodes being added or removed.

Watching node clicks

``` treeview.on("nodeClick", function(e) { var node = e.treenode; Y.log("Clicked node with label " + node.get("label")); Y.log("Node path is " + node.path().join(" > ")); }); ```

Here we also demonstrate `path` method of the `TreeNode` that returns list of node labels from the root to the node.

`nodeClick` events get fired regardless whether tree state has actually changed. For example when you click on a tree leaf, nothing changes in the tree UI, however `nodeClick` event is still being fired.

Events `nodeToggle`, `nodeExpand` and `nodeCollapse` are however only fired when actual tree node state is changed. That is they will be never fired for tree leaf. They also have `treenode` in the event payload.

For `CheckBoxTreeView` you can monitor for nodes being checked/unchecked by listening for `check` event ``` treeview.on("nodeClick", function(e) { var node = e.treenode, label = node.get("label"), checked = node.get("checked"); Y.log("Intercepted check event for " + label + ", original state was " + checked); }); ```

CSS model

Here is `TreeView`/`TreeNode` CSS model. ```
```

For `CheckBoxTreeView`, there will be another nested span for checkbox control UI ``` peack ```