YUI recommends YUI 3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

Yahoo! UI Library

TreeView Widget  2.8.0r4

Yahoo! UI Library > treeview > YAHOO.widget.TreeView
Search:
 
Filters

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.