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
The current number of animations that are executing
The animation to use for collapsing children, if any
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
The animation to use for expanding children, if any
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.
A reference to the Node currently having the focus or null if none.
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
We lock the tree control while waiting for the dynamic loader to return
The maximum number of animations to run at one time.
If true, only one Node can be highlighted at a time
Default Value: false
Class name assigned to elements that have the focus
Default Value: "ygtvfocus"
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
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.
Global cache of tree instances
Methods
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
private
void
_deleteNode
(
)
Deletes the node and recurses children
private
void
_destroyEditor
(
)
Entry point for TreeView's destroy method to destroy whatever the editing plug-in has created
private
void
_getEventTargetTdEl
(
)
Returns the TD element where the event has occurred
private
void
_initEditor
(
)
Entry point for initializing the editing plug-in.
TreeView will call this method on initializing if it exists
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.
private
void
_onClickEvent
(
)
Event listener for click events
private
void
_onDblClickEvent
(
)
Event listener for double-click events
private
void
_onKeyDownEvent
(
)
Event listener for key down events
private
void
_onMouseOutEvent
(
)
Event listener for mouse out events
private
void
_onMouseOverEvent
(
)
Event listener for mouse over events
private
void
_removeChildren_animComplete
(
o
)
wait until the animation is complete before deleting
to avoid javascript errors
- Parameters:
-
o
<object>
the custom event payload
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
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
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.
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.
void
collapseAll
(
)
Collapses all expanded child nodes in the entire tree.
void
collapseComplete
(
)
Function executed when the collapse animation completes
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!
void
draw
(
)
Renders the tree boilerplate and visible nodes.
Alias for render
Deprecated Use render instead
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.
void
expandComplete
(
)
Function executed when the expand animation completes
HTMLElement
getEl
(
)
Returns the tree's host element
- Returns:
HTMLElement
- the host element
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
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
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
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
int
getNodeCount
(
)
Count of nodes in tree
- Returns:
int
- number of nodes in the tree
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
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
Node
getRoot
(
)
Returns the root node of this tree
- Returns:
Node
- the root node
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
private
void
init
(
)
Initializes the tree
void
onCollapse
(
node
)
Abstract method that is executed when a node is collapsed.
- Parameters:
-
node
<Node>
the node that was collapsed.
Deprecated use treeobj.subscribe("collapse") instead
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
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
void
onExpand
(
node
)
Abstract method that is executed when a node is expanded
- Parameters:
-
node
<Node>
the node that was expanded
Deprecated use treeobj.subscribe("expand") instead
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
private
void
regNode
(
node
)
Nodes register themselves with the tree instance when they are created.
- Parameters:
-
node
<Node>
the node to register
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
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.
void
render
(
)
Renders the tree boilerplate and visible nodes
void
setCollapseAnim
(
type
)
Sets up the animation for collapsing children
- Parameters:
-
type
<string>
of animation (acceptable values defined in
YAHOO.widget.TVAnim)
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.
void
setExpandAnim
(
type
)
Sets up the animation for expanding children
- Parameters:
-
type
<string>
the type of animation (acceptable values defined
in YAHOO.widget.TVAnim)
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
string
toString
(
)
TreeView instance toString
- Returns:
string
- string representation of the tree
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
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
(
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
(
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
(
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
(
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
(
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
(
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
(
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
(
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
(
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
(
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
(
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
(
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
(
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
(
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