API: treeview YAHOO.widget.TreeView (YUI Library)

# Yahoo! UI Library

### TreeView Widget 2.8.0r4

Yahoo! UI Library > treeview > YAHOO.widget.TreeView
Search:
Filters 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) If present, it will be used to build the tree via method buildTreeFromObject

### Properties

#### _animCount - `private int`

The current number of animations that are executing

#### _collapseAnim - `private string`

The animation to use for collapsing children, if any

#### _currentlyHighlighted - `private YAHOO.widget.Node`

A reference to the Node that is currently highlighted. It is only meaningful if singleNodeHighlight is enabled
Default Value: null

#### _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.

#### currentFocus - `YAHOO.widget.Node`

A reference to the Node currently having the focus or null if none.

#### 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
- oldValue {any} value before editing

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.

#### singleNodeHighlight - `boolean`

If true, only one Node can be highlighted at a time
Default Value: false

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

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

#### validator - `function`

Validator function for edited data, called from the TreeView instance scope, receives the arguments (newValue, oldValue, nodeInstance) and returns either the validated (or type-converted) value or undefined. An undefined return will prevent the editor from closing
Default Value: null

#### 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

### 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`

#### _getEventTargetTdEl

`private void _getEventTargetTdEl ( )`
Returns the TD element where the event has occurred

Returns: `void`

#### _initEditor

`private void _initEditor ( )`
Entry point for initializing the editing plug-in. TreeView will call this method on initializing if it exists

Returns: `void`

#### _nodeEditing

`private 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.

#### _onClickEvent

`private void _onClickEvent ( )`
Event listener for click events

Returns: `void`

#### _onDblClickEvent

`private void _onDblClickEvent ( )`
Event listener for double-click events

Returns: `void`

#### _onKeyDownEvent

`private void _onKeyDownEvent ( )`
Event listener for key down events

Returns: `void`

#### _onMouseOutEvent

`private void _onMouseOutEvent ( )`
Event listener for mouse out events

Returns: `void`

#### _onMouseOverEvent

`private void _onMouseOverEvent ( )`
Event listener for mouse over events

Returns: `void`

#### _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 containing <LI> elements. Each <LI> can have one element used as label and a second optional element which is to be a <UL> or <OL> containing nested nodes. Depending on what the first element of the <LI> element is, the following Nodes will be created:

- plain text: a regular TextNode
- anchor <A>: a TextNode with its `href` and `target` taken from the anchor
- anything else: an HTMLNode

Only the first outermost (un-)ordered list in the markup and its children will be parsed. Nodes will be collapsed unless an <LI> tag has a className called 'expanded'. All other className attributes will be copied over to the Node className property. If the <LI> element contains an attribute called `yuiConfig`, its contents should be a JSON-encoded object as the one used in method buildTreeFromObject.

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. A tree can be described by an array of objects, each object corresponding to a node. Node descriptions may contain values for any property of a node plus the following extra properties:

- type: can be one of the following:
  - A shortname for a node type (`'text','menu','html'`)
  - The name of a Node class under YAHOO.widget (`'TextNode', 'MenuNode', 'DateNode'`, etc)
  - a reference to an actual class: `YAHOO.widget.DateNode`
- children: an array containing further node definitions

A string instead of an object will produce a node of type 'text' with the given string as its label.

Parameters:
  `oConfig <Array|Object|String>` array containing a full description of the tree. An object or a string will be turned into an array with the given object or string as its only element.

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

#### getHighlightedNode

`YAHOO.widget.Node getHighlightedNode ( )`
When in singleNodeHighlight it returns the node highlighted or null if none. Returns null if singleNodeHighlight is false.

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

#### getNodeByElement

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

Parameters:
  `el <HTMLElement>` the 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

#### getNodesBy

`Array getNodesBy ( a )`
Returns a collection of nodes that have passed the test function passed as its only argument. The function will receive a reference to each node to be tested.

Parameters:
  `a <function>` boolean function that receives a Node instance and returns true to add the node to the results list

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

#### 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`

#### onEventToggleHighlight

`false onEventToggleHighlight ( oArgs )`
Event listener to toggle node highlight. Can be assigned as listener to clickEvent, dblClickEvent and enterKeyPressed. It returns false to prevent the default action.

Parameters:
  `oArgs <any>` it takes the arguments of any of the events mentioned above

Returns: `false`
  Always cancels the default action for the event

#### 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 ( node )`
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:
  `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 ( node , autoRefresh )`
Removes the node and its children, and optionally refreshes the branch of the tree that was affected.

Parameters:
  `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 ( type )`
Sets up the animation for collapsing children

Parameters:
  `type <string>` 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`

#### setNodesProperty

`void setNodesProperty ( name , value , refresh )`
Sets the value of a property for all loaded nodes in the tree.

Parameters:
  `name <string>` Name of the property to be set
  `value <any>` value to be set
  `refresh <boolean>` if present and true, it does a refresh

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.

### Events

#### animComplete

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

Parameters:
  `oArgs.node <YAHOO.widget.Node>` the node that is expanding/collapsing
  `oArgs.type <String>` the type of animation ("expand" or "collapse")

#### animStart

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

Parameters:
  `oArgs.node <YAHOO.widget.Node>` the node that is expanding/collapsing
  `oArgs.type <String>` the type of animation ("expand" or "collapse")

#### 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

#### editorCancelEvent

`editorCancelEvent ( node )`
Fires when the user clicks on the cancel button of a node editor

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

#### editorSaveEvent

`editorSaveEvent ( oArgs.newValue , oArgs.oldValue , oArgs.node )`
Fires when the user clicks on the ok button of a node editor

Parameters:
  `oArgs.newValue <mixed>` the new value just entered
  `oArgs.oldValue <mixed>` the value originally in the tree
  `oArgs.node <YAHOO.widget.Node>` the node that has the focus

#### 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

#### focusChanged

`focusChanged ( oArgs.oldNode , oArgs.newNode )`
Fires when the focus receives the focus, when it changes from a Node to another Node or when it is completely lost (blurred)

Parameters:
  `oArgs.oldNode <YAHOO.widget.Node>` Node that had the focus or null if none
  `oArgs.newNode <YAHOO.widget.Node>` Node that receives the focus or null if none

#### highlightEvent

`highlightEvent ( node )`
Custom event fired when the highlight of a node changes. The node that triggered the change is provided as an argument: The status of the highlight can be checked in nodeRef.highlightState. Depending on nodeRef.propagateHighlight, other nodes might have changed

Parameters:
  `node <YAHOO.widget.Node>` the node that started the change in highlighting state

#### 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 © 2009 Yahoo! Inc. All rights reserved.