# Yahoo! UI Library

### TreeView Widget 2.6.0

Yahoo! UI Library > treeview > YAHOO.widget.TreeView

Show Private Show Protected Show Deprecated

## Class YAHOO.widget.TreeView - uses YAHOO.util.EventProvider

Contains the tree view state data and the root node.

### Constructor

YAHOO.widget.TreeView `( id , oConfig )`

Parameters:
  `id <string|HTMLElement>` The id of the element, or the element itself that the tree will be inserted into. Existing markup in this element, if valid, will be used to build the tree
  `oConfig <Array|object|string>` (optional) An array containing the definition of the tree. Objects will be converted to arrays of one element. A string will produce a single TextNode

### Properties

#### _animCount `- private int`

The current number of animations that are executing

#### _collapseAnim `- private string`

The animation to use for collapsing children, if any

#### _dblClickTimer `- private window.timer object`

Stores the timer used to check for double clicks

#### _el `- private HTMLelement`

The host element for this tree

#### _expandAnim `- private string`

The animation to use for expanding children, if any

#### _hasDblClickSubscriber `- private boolean`

Whether there is any subscriber to dblClickEvent

#### _nodes `- private Node[]`

Flat collection of all nodes in this tree. This is a sparse array, so the length property can't be relied upon for a node count for the tree.

#### editorData `- static object`

An object to store information used for in-line editing for all Nodes of all TreeViews. It contains:

- active {boolean}, whether there is an active cell editor
- whoHasIt {YAHOO.widget.TreeView} TreeView instance that is currently using the editor
- nodeType {string} value of static Node._type property, allows reuse of input element if node is of the same type.
- editorPanel {HTMLelement (<div>)} element holding the in-line editor
- inputContainer {HTMLelement (<div>)} element which will hold the type-specific input element(s) to be filled by the fillEditorContainer method
- buttonsContainer {HTMLelement (<div>)} element which holds the <button> elements for Ok/Cancel. If you don't want any of the buttons, hide it via CSS styles, don't destroy it
- node {YAHOO.widget.Node} reference to the Node being edited
- saveOnEnter {boolean}, whether the Enter key should be accepted as a Save command (Esc. is always taken as Cancel), disable for multi-line input elements

Editors are free to use this object to store additional data.

#### id `- String`

The id of tree container element

#### locked `- boolean`

We lock the tree control while waiting for the dynamic loader to return

#### maxAnim `- int`

The maximum number of animations to run at one time.

#### TreeView.FOCUS_CLASS_NAME `- static final String`

Class name assigned to elements that have the focus
Default Value: "ygtvfocus"

#### YAHOO.widget.TreeView.nodeCount `- static int`

Running count of all nodes created in all trees. This is used to provide unique identifies for all nodes. Deleting nodes does not change the nodeCount.

#### YAHOO.widget.TreeView.trees `- private static Array`

Global cache of tree instances

#### Properties inherited from YAHOO.util.EventProvider:

`__yui_events, __yui_subscribers`

### Methods

#### _closeEditor

`private void _closeEditor ( save )`
Method to be called when the inline editing is finished and the editor is to be closed

Parameters:
  `save <Boolean>` true if the edited value is to be saved, false if discarded

Returns: `void`

#### _deleteNode

`private void _deleteNode ( )`
Deletes the node and recurses children

Returns: `void`

#### _destroyEditor

`private void _destroyEditor ( )`
Entry point for TreeView's destroy method to destroy whatever the editing plug-in has created

Returns: `void`

#### _nodeEditing

`Boolean _nodeEditing ( node )`
Entry point of the editing plug-in. TreeView will call this method if it exists when a node label is clicked

Parameters:
  `node <YAHOO.widget.Node>` the node to be edited

Returns: `Boolean`
  true to indicate that the node is editable and prevent any further bubbling of the click.

#### _removeChildren_animComplete

`private void _removeChildren_animComplete ( o )`
wait until the animation is complete before deleting to avoid javascript errors

Parameters:
  `o <object>` the custom event payload

Returns: `void`

#### animateCollapse

`boolean animateCollapse ( el , node )`
Perform the collapse animation if configured, or just show the element if not configured or too many animations are in progress

Parameters:
  `el <HTMLElement>` the element to animate
  `node <YAHOO.util.Node>` the node that was expanded

Returns: `boolean`
  true if animation could be invoked, false otherwise

#### animateExpand

`boolean animateExpand ( el , node )`
Perform the expand animation if configured, or just show the element if not configured or too many animations are in progress

Parameters:
  `el <HTMLElement>` the element to animate
  `node <YAHOO.util.Node>` the node that was expanded

Returns: `boolean`
  true if animation could be invoked, false otherwise

#### buildTreeFromMarkup

`void buildTreeFromMarkup ( id )`
Builds the TreeView from existing markup. Markup should consist of <UL> or <OL> elements, possibly nested. Depending what the <LI> elements contain the following will be created:

- plain text: a regular TextNode
- an (un-)ordered list: a nested branch
- anything else: an HTMLNode

Only the first outermost (un-)ordered list in the markup and its children will be parsed. Tree will be fully collapsed. HTMLNodes have hasIcon set to true if the markup for that node has a className called hasIcon.

Parameters:
  `id <string|HTMLElement>` the id of the element that contains the markup or a reference to it.

Returns: `void`

#### buildTreeFromObject

`void buildTreeFromObject ( oConfig )`
Builds the TreeView from an object. This is the method called by the constructor to build the tree when it has a second argument.

Parameters:
  `oConfig <Array>` array containing a full description of the tree

Returns: `void`

#### collapseAll

`void collapseAll ( )`
Collapses all expanded child nodes in the entire tree.

Returns: `void`

#### collapseComplete

`void collapseComplete ( )`
Function executed when the collapse animation completes

Returns: `void`

#### destroy

`void destroy ( )`
Nulls out the entire TreeView instance and related objects, removes attached event listeners, and clears out DOM elements inside the container. After calling this method, the instance reference should be expliclitly nulled by implementer, as in myDataTable = null. Use with caution!

Returns: `void`

#### draw

`void draw ( )`
Renders the tree boilerplate and visible nodes. Alias for render

Returns: `void`

Deprecated Use render instead

#### expandAll

`void expandAll ( )`
Expands all child nodes. Note: this conflicts with the "multiExpand" node property. If expand all is called in a tree with nodes that do not allow multiple siblings to be displayed, only the last sibling will be expanded.

Returns: `void`

#### expandComplete

`void expandComplete ( )`
Function executed when the expand animation completes

Returns: `void`

#### getEl

`HTMLElement getEl ( )`
Returns the tree's host element

Returns: `HTMLElement`
  the host element

#### getNodeByElement

`YAHOO.widget.Node getNodeByElement ( the )`
Returns the treeview node reference for an anscestor element of the node, or null if it is not contained within any node in this tree.

Parameters:
  `the <HTMLElement>` element to test

Returns: `YAHOO.widget.Node`
  a node reference or null

#### getNodeByIndex

`Node getNodeByIndex ( nodeIndex )`
Returns a node in the tree that has the specified index (this index is created internally, so this function probably will only be used in html generated for a given node.)

Parameters:
  `nodeIndex <int>` the index of the node wanted

Returns: `Node`
  the node with index=nodeIndex, null if no match

#### getNodeByProperty

`Node getNodeByProperty ( property , value )`
Returns a node that has a matching property and value in the data object that was passed into its constructor.

Parameters:
  `property <object>` the property to search (usually a string)
  `value <object>` the value we want to find (usuall an int or string)

Returns: `Node`
  the matching node, null if no match

#### getNodeCount

`int getNodeCount ( )`
Count of nodes in tree

Returns: `int`
  number of nodes in the tree

#### getNodesByProperty

`Array getNodesByProperty ( property , value )`
Returns a collection of nodes that have a matching property and value in the data object that was passed into its constructor.

Parameters:
  `property <object>` the property to search (usually a string)
  `value <object>` the value we want to find (usuall an int or string)

Returns: `Array`
  the matching collection of nodes, null if no match

#### getRoot

`Node getRoot ( )`
Returns the root node of this tree

Returns: `Node`
  the root node

#### getTreeDefinition

`Object | false getTreeDefinition ( )`
Returns an object which could be used to rebuild the tree. It can be passed to the tree constructor to reproduce the same tree. It will return false if any node loads dynamically, regardless of whether it is loaded or not.

Returns: `Object | false`
  definition of the tree or false if any node is defined as dynamic

#### init

`private void init ( )`
Initializes the tree

Returns: `void`

#### onCollapse

`void onCollapse ( node )`
Abstract method that is executed when a node is collapsed.

Parameters:
  `node <Node>` the node that was collapsed.

Returns: `void`

Deprecated use treeobj.subscribe("collapse") instead

#### onEventEditNode

`void onEventEditNode ( oArgs )`
Method to be associated with an event (clickEvent, dblClickEvent or enterKeyPressed) to pop up the contents editor It calls the corresponding node editNode method.

Parameters:
  `oArgs <object>` Object passed as arguments to TreeView event listeners

Returns: `void`

#### onExpand

`void onExpand ( node )`
Abstract method that is executed when a node is expanded

Parameters:
  `node <Node>` the node that was expanded

Returns: `void`

Deprecated use treeobj.subscribe("expand") instead

#### popNode

`void popNode ( the )`
Removes the node from the tree, preserving the child collection to make it possible to insert the branch into another part of the tree, or another tree.

Parameters:
  `the <Node>` node to remove

Returns: `void`

#### regNode

`private void regNode ( node )`
Nodes register themselves with the tree instance when they are created.

Parameters:
  `node <Node>` the node to register

Returns: `void`

#### removeChildren

`void removeChildren ( node )`
Deletes this nodes child collection, recursively. Also collapses the node, and resets the dynamic load flag. The primary use for this method is to purge a node and allow it to fetch its data dynamically again.

Parameters:
  `node <Node>` the node to purge

Returns: `void`

#### removeNode

`boolean removeNode ( The , autoRefresh )`
Removes the node and its children, and optionally refreshes the branch of the tree that was affected.

Parameters:
  `The <Node>` node to remove
  `autoRefresh <boolean>` automatically refreshes branch if true

Returns: `boolean`
  False is there was a problem, true otherwise.

#### render

`void render ( )`
Renders the tree boilerplate and visible nodes

Returns: `void`

#### setCollapseAnim

`void setCollapseAnim ( the )`
Sets up the animation for collapsing children

Parameters:
  `the <string>` type of animation (acceptable values defined in YAHOO.widget.TVAnim)

Returns: `void`

#### setDynamicLoad

`void setDynamicLoad ( fnDataLoader , iconMode )`
Configures this tree to dynamically load all child data

Parameters:
  `fnDataLoader <function>` the function that will be called to get the data
  `iconMode <int>` configures the icon that is displayed when a dynamic load node is expanded the first time without children. By default, the "collapse" icon will be used. If set to 1, the leaf node icon will be displayed.

Returns: `void`

#### setExpandAnim

`void setExpandAnim ( type )`
Sets up the animation for expanding children

Parameters:
  `type <string>` the type of animation (acceptable values defined in YAHOO.widget.TVAnim)

Returns: `void`

#### toString

`string toString ( )`
TreeView instance toString

Returns: `string`
  string representation of the tree

#### YAHOO.widget.TreeView.getNode

`static Node YAHOO.widget.TreeView.getNode ( treeId , nodeIndex )`
Global method for getting a node by its id. Used in the generated tree html.

Parameters:
  `treeId <String>` the id of the tree instance
  `nodeIndex <String>` the index of the node to return

Returns: `Node`
  the node instance requested, null if not found

#### YAHOO.widget.TreeView.getTree

`static TreeView YAHOO.widget.TreeView.getTree ( treeId )`
Global method for getting a tree by its id. Used in the generated tree html.

Parameters:
  `treeId <String>` the id of the tree instance

Returns: `TreeView`
  the tree instance requested, null if not found.

#### YAHOO.widget.TreeView.preload

`static void YAHOO.widget.TreeView.preload ( prefix )`
Attempts to preload the images defined in the styles used to draw the tree by rendering off-screen elements that use the styles.

Parameters:
  `prefix <string>` the prefix to use to generate the names of the images to preload, default is ygtv

Returns: `void`

#### Methods inherited from YAHOO.util.EventProvider:

`createEvent, fireEvent, hasEvent, subscribe, unsubscribe, unsubscribeAll`

### Events

#### animComplete

`animComplete ( node )`
When animation is enabled, this event fires when the animation completes

Parameters:
  `node <YAHOO.widget.Node>` the node that is expanding/collapsing

#### animStart

`animStart ( node )`
When animation is enabled, this event fires when the animation starts

Parameters:
  `node <YAHOO.widget.Node>` the node that is expanding/collapsing

#### clickEvent

`clickEvent ( oArgs.event , oArgs.node )`
Fires when the label in a TextNode or MenuNode or content in an HTMLNode receives a Click. The listener may return false to cancel toggling and focusing on the node.

Parameters:
  `oArgs.event <HTMLEvent>` The event object
  `oArgs.node <YAHOO.widget.Node>` node the node that was clicked

#### collapse

`collapse ( node )`
Fires when a node is going to be collapsed. Return false to stop the collapse.

Parameters:
  `node <YAHOO.widget.Node>` the node that is collapsing

#### collapseComplete

`collapseComplete ( node )`
Fires after a node is successfully collapsed. This event will not fire if the "collapse" event was cancelled.

Parameters:
  `node <YAHOO.widget.Node>` the node that was collapsed

#### dblClickEvent

`dblClickEvent ( oArgs.event , oArgs.node )`
Fires when the label in a TextNode or MenuNode or content in an HTMLNode receives a double Click

Parameters:
  `oArgs.event <HTMLEvent>` The event object
  `oArgs.node <YAHOO.widget.Node>` node the node that was clicked

#### enterKeyPressed

`enterKeyPressed ( node )`
Fires when the Enter key is pressed on a node that has the focus

Parameters:
  `node <YAHOO.widget.Node>` the node that has the focus

#### expand

`expand ( node )`
Fires when a node is going to be expanded. Return false to stop the collapse.

Parameters:
  `node <YAHOO.widget.Node>` the node that is expanding

#### expandComplete

`expandComplete ( node )`
Fires after a node is successfully expanded. This event will not fire if the "expand" event was cancelled.

Parameters:
  `node <YAHOO.widget.Node>` the node that was expanded

#### labelClick

`labelClick ( node )`
Custom event that is fired when the text node label is clicked. The node clicked is provided as an argument

Parameters:
  `node <YAHOO.widget.Node>` the node clicked

Deprecated use clickEvent or dblClickEvent

Copyright © 2008 Yahoo! Inc. All rights reserved.