#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# Tree.Node Class

Defined in: `tree/js/tree-node.js:11`
Module: tree-node
Parent Module: tree

Represents a tree node in a `Tree` data structure.

## Constructor

### `Tree.Node`

(

- `tree`
- `[config]`

)

Defined in `tree/js/tree-node.js:11`

#### Parameters:

- `tree` Tree

  `Tree` instance with which this node should be associated.

- `[config]` Object optional

  Configuration hash for this node.

  - `[canHaveChildren=false]` Boolean optional

    Whether or not this node can contain child nodes. Will be automatically set to `true` if not specified and `config.children` contains one or more children.

  - `[children]` Tree.Node[] optional

    Array of `Tree.Node` instances for child nodes of this node.

  - `[data]` Object optional

    Implementation-specific data related to this node. You may add arbitrary properties to this hash for your own use.

  - `[id]` String optional

    Unique id for this node. This id must be unique among all tree nodes on the entire page, and will also be used as this node's DOM id when it's rendered by a TreeView. A unique id will be automatically generated unless you specify a custom value.

  - `[state]` Object optional

    State hash for this node. You may add arbitrary state properties to this hash for your own use. See the docs for `Tree.Node`'s `state` property for details on state values used internally by `Tree.Node`.

- Index
- Methods
- Properties

## Item Index

### Methods

- append
- empty
- find
- hasChildren
- index
- indexOf
- insert
- isInTree
- isRoot
- next
- prepend
- previous
- remove
- size
- toJSON
- traverse

### Properties

- _indexMap
- _isIndexStale
- _isYUITreeNode
- _serializable
- canHaveChildren
- children
- data
- id
- parent
- state
- tree

## Methods

### `append`

(

- `node`
- `[options]`

)
Tree.Node | Tree.Node[]

Defined in `tree/js/tree-node.js:177`

Appends the given tree node or array of nodes to the end of this node's children.

#### Parameters:

- `node` Object | Object[] | Tree.Node | Tree.Node[]

  Child node, node config object, array of child nodes, or array of node config objects to append to the given parent. Node config objects will automatically be converted into node instances.

- `[options]` Object optional

  Options.

  - `[silent=false]` Boolean optional

    If `true`, the `add` event will be suppressed.

#### Returns:

Tree.Node | Tree.Node[]: Node or array of nodes that were appended.

### `empty`

(

- `[options]`

)
Tree.Node[]

Defined in `tree/js/tree-node.js:195`

Removes all children from this node. The removed children will still be reusable unless the `destroy` option is truthy.

#### Parameters:

- `[options]` Object optional

  Options.

  - `[destroy=false]` Boolean optional

    If `true`, the children will also be destroyed, which makes them available for garbage collection and means they can't be reused.

  - `[silent=false]` Boolean optional

    If `true`, `remove` events will be suppressed.

  - `[src]` String optional

    Source of the change, to be passed along to the event facade of the resulting event. This can be used to distinguish between changes triggered by a user and changes triggered programmatically, for example.

#### Returns:

Tree.Node[]: Array of removed child nodes.

### `find`

(

- `[options]`
- `callback`
- `[thisObj]`

)
Tree.Node | Null

Defined in `tree/js/tree-node.js:216`

Performs a depth-first traversal of this node, passing it and each of its descendants to the specified callback, and returning the first node for which the callback returns a truthy value.

Traversal will stop as soon as a truthy value is returned from the callback.

See `Tree#traverseNode()` for more details on how depth-first traversal works.

#### Parameters:

- `[options]` Object optional

  Options.

  - `[depth]` Number optional

    Depth limit. If specified, descendants will only be traversed to this depth before backtracking and moving on.

- `callback` Function

  Callback function to call with the traversed node and each of its descendants. If this function returns a truthy value, traversal will be stopped and the current node will be returned.

  - `node` Tree.Node

    Node being traversed.

- `[thisObj]` Object optional

  `this` object to use when executing callback.

#### Returns:

Tree.Node | Null: Returns the first node for which the callback returns a truthy value, or `null` if the callback never returns a truthy value.

### `hasChildren`

() Boolean

Defined in `tree/js/tree-node.js:246`

Returns `true` if this node has one or more child nodes.

#### Returns:

Boolean: `true` if this node has one or more child nodes, `false` otherwise.

### `index`

() Number

Defined in `tree/js/tree-node.js:257`

Returns the numerical index of this node within its parent node, or `-1` if this node doesn't have a parent node.

#### Returns:

Number: Index of this node within its parent node, or `-1` if this node doesn't have a parent node.

### `indexOf`

(

- `node`

)
Number

Defined in `tree/js/tree-node.js:269`

Returns the numerical index of the given child node, or `-1` if the node is not a child of this node.

#### Parameters:

- `node` Tree.Node

  Child node.

#### Returns:

Number: Index of the child, or `-1` if the node is not a child of this node.

### `insert`

(

- `node`
- `[options]`

)
Tree.Node[]

Defined in `tree/js/tree-node.js:290`

Inserts a node or array of nodes at the specified index under this node, or appends them to this node if no index is specified.

If a node being inserted is from another tree, it and all its children will be removed from that tree and moved to this one.

#### Parameters:

- `node` Object | Object[] | Tree.Node | Tree.Node[]

  Child node, node config object, array of child nodes, or array of node config objects to insert under the given parent. Node config objects will automatically be converted into node instances.

- `[options]` Object optional

  Options.

  - `[index]` Number optional

    Index at which to insert the child node. If not specified, the node will be appended as the last child of the parent.

  - `[silent=false]` Boolean optional

    If `true`, the `add` event will be suppressed.

  - `[src='insert']` String optional

    Source of the change, to be passed along to the event facade of the resulting event. This can be used to distinguish between changes triggered by a user and changes triggered programmatically, for example.

#### Returns:

Tree.Node[]: Node or array of nodes that were inserted.

### `isInTree`

() Boolean

Defined in `tree/js/tree-node.js:320`

Returns `true` if this node has been inserted into a tree, `false` if it is merely associated with a tree and has not yet been inserted.

#### Returns:

Boolean: `true` if this node has been inserted into a tree, `false` otherwise.

### `isRoot`

() Boolean

Defined in `tree/js/tree-node.js:336`

Returns `true` if this node is the root of the tree.

#### Returns:

Boolean: `true` if this node is the root of the tree, `false` otherwise.

### `next`

() Tree.Node

Defined in `tree/js/tree-node.js:347`

Returns this node's next sibling, or `undefined` if this node is the last child.

#### Returns:

Tree.Node: This node's next sibling, or `undefined` if this node is the last child.

### `prepend`

(

- `node`
- `[options]`

)
Tree.Node | Tree.Node[]

Defined in `tree/js/tree-node.js:361`

Prepends a node or array of nodes at the beginning of this node's children.

If a node being prepended is from another tree, it and all its children will be removed from that tree and moved to this one.

#### Parameters:

- `node` Object | Object[] | Tree.Node | Tree.Node[]

  Child node, node config object, array of child nodes, or array of node config objects to prepend to this node. Node config objects will automatically be converted into node instances.

- `[options]` Object optional

  Options.

  - `[silent=false]` Boolean optional

    If `true`, the `add` event will be suppressed.

#### Returns:

Tree.Node | Tree.Node[]: Node or array of nodes that were prepended.

### `previous`

() Tree.Node

Defined in `tree/js/tree-node.js:381`

Returns this node's previous sibling, or `undefined` if this node is the first child

#### Returns:

Tree.Node: This node's previous sibling, or `undefined` if this node is the first child.

### `remove`

(

- `[options]`

)
chainable

Defined in `tree/js/tree-node.js:395`

Removes this node from its parent node.

#### Parameters:

- `[options]` Object optional

  Options.

  - `[destroy=false]` Boolean optional

    If `true`, this node and all its children will also be destroyed, which makes them available for garbage collection and means they can't be reused.

  - `[silent=false]` Boolean optional

    If `true`, the `remove` event will be suppressed.

  - `[src]` String optional

    Source of the change, to be passed along to the event facade of the resulting event. This can be used to distinguish between changes triggered by a user and changes triggered programmatically, for example.

### `size`

() Number

Defined in `tree/js/tree-node.js:415`

Returns the total number of nodes contained within this node, including all descendants of this node's children.

#### Returns:

Number: Total number of nodes contained within this node, including all descendants.

### `toJSON`

() Object

Defined in `tree/js/tree-node.js:435`

Serializes this node to an object suitable for use in JSON.

#### Returns:

Object: Serialized node object.

### `traverse`

(

- `[options]`
- `callback`
- `[thisObj]`

)
Mixed

Defined in `tree/js/tree-node.js:472`

Performs a depth-first traversal of this node, passing it and each of its descendants to the specified callback.

If the callback function returns `Tree.STOP_TRAVERSAL`, traversal will be stopped immediately. Otherwise, it will continue until the deepest descendant of node has been traversed, or until each branch has been traversed to the optional maximum depth limit.

Since traversal is depth-first, that means nodes are traversed like this:

            1
          / | \
         2  8  9
        / \     \
       3   7    10
     / | \      / \
    4  5  6    11 12

#### Parameters:

- `[options]` Object optional

  Options.

  - `[depth]` Number optional

    Depth limit. If specified, descendants will only be traversed to this depth before backtracking and moving on.

- `callback` Function

  Callback function to call with the traversed node and each of its descendants.

  - `node` Tree.Node

    Node being traversed.

- `[thisObj]` Object optional

  `this` object to use when executing callback.

#### Returns:

Mixed: Returns `Tree.STOP_TRAVERSAL` if traversal was stopped; otherwise returns `undefined`.

## Properties

### `_indexMap`

Object protected

Defined in `tree/js/tree-node.js:138`

Mapping of child node ids to indices.

### `_isIndexStale`

Boolean protected

Defined in `tree/js/tree-node.js:145`

Flag indicating whether the `_indexMap` is stale and needs to be rebuilt.

Default: true

### `_isYUITreeNode`

Boolean protected

Defined in `tree/js/tree-node.js:154`

Simple way to type-check that this is an instance of Tree.Node.

Default: true

### `_serializable`

String[] protected

Defined in `tree/js/tree-node.js:163`

Array of property names on this node that should be serialized to JSON when `toJSON()` is called.

Note that the `children` property is a special case that is managed separately.

### `canHaveChildren`

Boolean

Defined in `tree/js/tree-node.js:71`

Whether or not this node can contain child nodes.

This value is falsy by default unless child nodes are added at instantiation time, in which case it will be automatically set to `true`. You can also manually set it to `true` to indicate that a node can have children even though it might not currently have any children.

Note that regardless of the value of this property, appending, prepending, or inserting a node into this node will cause `canHaveChildren` to be set to true automatically.

### `children`

Tree.Node[]

Defined in `tree/js/tree-node.js:86`

Child nodes contained within this node.

Default: []

### `data`

Object

Defined in `tree/js/tree-node.js:94`

Arbitrary serializable data related to this node.

Use this property to store any data that should accompany this node when it is serialized to JSON.

Default: {}

### `id`

String

Defined in `tree/js/tree-node.js:104`

Unique id for this node.

### `parent`

Tree.Node

Defined in `tree/js/tree-node.js:111`

Parent node of this node, or `undefined` if this is an unattached node or the root node.

### `state`

Object

Defined in `tree/js/tree-node.js:119`

Current state of this node.

Use this property to store state-specific info -- such as whether this node is "open", "selected", or any other arbitrary state -- that should accompany this node when it is serialized to JSON.

### `tree`

Tree

Defined in `tree/js/tree-node.js:129`

The Tree instance with which this node is associated.