new (require("nmodule/webEditors/rc/wb/tree/TreeNode"))(name, display [, kids])
API Status: Development
Represents a single node in a tree.
One node has a number of different properties, as well as a reference to
a backing value this node represents. This backing value could be a
nav node on a station, a file or folder on the file system, etc.
It also maintains a list of children. Note that this list of children will
be lazily, asynchronously requested the first time it is loaded. After
that, the list of children must be kept up to date using the parent
node's mutators (added/removed/etc.).
Please note that any child nodes added to a parent node effectively become
the parent node's "property" and are subject to alteration by the parent.
If the parent node is activated, the child nodes will likewise be
activated, and same for destroying.
Parameters:
Name | Type | Argument | Description |
---|---|---|---|
name |
String | the node name |
|
display |
String | the node display |
|
kids |
Array.<module:nmodule/webEditors/rc/wb/tree/TreeNode> |
<optional> |
an |
- Mixes In:
- tinyevents
Methods
-
<static> BY_NODE_NAME()
-
Pass this to
#reorder
to sort all tree nodes by name. -
<abstract> $loadKids( [params])
-
Performs a one-time, asynchronous load of child nodes. On a vanilla
TreeNode
, this does nothing but resolve the array of child nodes passed
into the constructor. In subclasses, this should be overridden to perform
any network calls or other asynchronous behavior to load child nodes.This method is intended to be overridden by subclasses, but not called
directly. It will automatically be used the first timegetKids()
is
called.After
getKids()
is called for the first time, any updates or changes to
the list of nodes should only be done through theadd()
,remove()
,
and other mutator methods.Do not set the parent of the child nodes created by this method - they
will automatically be parented whengetKids()
is called.Important contractual note: in some cases, the async operation to load
kids can be batched together if loading a number of nodes at once. If$loadKids
receives aBatch
object, it is obligated to ensure that anyprogressCallback
param passed in will be called with acommitReady
progress event to notify the caller that the batch is ready to be committed.Parameters:
Name Type Argument Description params
Object <optional>
Properties
Name Type Argument Description batch
baja.comm.Batch <optional>
optional Batch that may be used
when loading multiple tree nodes. See method description for contract.progressCallback
function <optional>
optional function that will
receive progress notifications during the load process.Returns:
promise to be resolved when all child nodes
have been loaded. It should be resolved with an array ofTreeNode
instances.- Type
- Promise
-
activate()
-
Activates the node and all of its child nodes. This method works very
similarly toWidget#initialize()
in that it delegates the implementation
of the destruction of each individual node todoActivate()
.Note that child nodes will not be activated if they are not yet loaded.
Returns:
promise to be resolved when this node and all
child nodes (if loaded) have been activated- Type
- Promise
-
add(kid)
-
Adds a child node to the end of this parent's list of child nodes. The
child will automatically be parented when it is set. If this node has
been activated, the child node will likewise be activated when it is
added.Parameters:
Name Type Description kid
module:nmodule/webEditors/rc/wb/tree/TreeNode Returns:
promise to be resolved when the child node is
added, or rejected if the child node is already parented, if the list
of children is not yet loaded (getKids()
not yet called), or an existing
child with a duplicate name is found- Type
- Promise
-
destroy()
-
Destroys the node and all of its child nodes. This method works very
similarly toWidget#destroy()
in that it delegates the implementation
of the destruction of each individual node todoDestroy()
.Note that child nodes will not be destroyed if they are not yet loaded.
Returns:
promise to be resolved when this node and all
child nodes (if loaded) have been destroyed- Type
- Promise
-
doActivate()
-
Implementation of
activate()
. This method should acquire any resources
the node needs to function properly - registering event handlers,
subscribing components, etc. Ensure that all resources acquired are
properly released indoDestroy()
. By default, does nothing.Returns:
promise to be resolved when activation is
complete - or return undefined if no asynchronous work needs to be done- Type
- Promise
-
doDestroy()
-
Implementation of
destroy()
. This method should release any resources
acquired by the node duringdoActivate()
. By default, does nothing.Returns:
promise to be resolved when destruction is
complete - or return undefined if no asynchronous work needs to be done- Type
- Promise
-
doDrop(values)
-
A tree node that returned
true
fromisDropTarget
can then take an array
of values to perform the drop action.By default, this function does nothing.
Parameters:
Name Type Description values
Array the values being dropped onto this node
Returns:
promise to be resolved when the drop operation
completes, or rejected if the given array does not hold valid data
to perform a drop operation.- Type
- Promise
-
equals(value)
-
Test to see if this node is equivalent to some value. By default, a node
is equivalent only to itself.Parameters:
Name Type Description value
* Returns:
- Type
- boolean
-
getFullPath()
-
The full path of names leading to this node, beginning from the parent
node. Since names must be unique among siblings, each node in a tree will
therefore have a unique full path.Returns:
an array of node names, with the name of the
root node first and this node last- Type
- Array.<String>
-
getIcon()
-
Return a list of URIs to image files that represent a display icon for this
node. Typically, this will only return zero or one URI, but may return
several if the node's icon should be layered or have a "badge" applied. By
default, this just returns an empty array.Returns:
an array of URIs to image files
- Type
- Array.<String>
-
getKid(name)
-
Retrieves a child node by name. If child nodes are not yet loaded, they
will be upon calling this method.Parameters:
Name Type Description name
String Returns:
promise to be resolved with the child node
with the given name, orundefined
if not found- Type
- Promise
-
getKids( [params])
-
Resolves all child nodes of this node. If they have already been loaded,
they will be resolved immediately, otherwise they will be asynchronously
loaded in a one-time operation. (The children will not be loaded if the
node was destroyed first.)After
getKids()
is called for the first time, any updates or changes to
the list of nodes should only be done through theadd()
,remove()
,
and other mutator methods.Parameters:
Name Type Argument Description params
Object <optional>
params object to be passed to
$loadKids
. This
should be provided if you are callinggetKids
without being sure you have
called$loadKids
first.Returns:
promise to be resolved with an array of child
TreeNode
s- Type
- Promise
-
getName()
-
The name of this node. If this node has siblings, note that names must
be unique among all sibling nodes.Returns:
- Type
- String
-
getParent()
-
The parent node. If the node is unparented, will return
null
.Returns:
-
isDraggable()
-
Return true if this tree node is eligible to begin a drag operation.
Returns:
false by default
- Type
- boolean
-
isDropTarget()
-
A tree node has the option of accepting data from a drag and drop
operation. If a node is to accept drag and drop, this function should be
overridden to examine the currently loaded value (if appropriate) and
determine if it can accept a drop operation.It is up to the
NavTree
that holds this node toreturn false
from the
event handler, apply any CSS styles, etc.Naturally, any node that implements this function should also implement
doDrop
to perform the requested drop operation.Returns:
false
by default- Type
- boolean
-
isSelectable()
-
Override this method to return
false
to prevent this node from being
selected in the tree.Returns:
true
by default.- Type
- Boolean
-
<abstract> mayHaveKids()
-
Return false if you know for a fact that this node has no child nodes.
Why is this different from the
bajaui
implementation which declares agetChildCount()
method? Remember that retrieving child nodes is
asynchronous, so it's not always possible to count them synchronously.
This function will mainly serve as a hint to UI widgets whether to show
an expander for this node, with the understanding thatgetKids()
may
still resolve zero nodes, even if this function returned true.Returns:
- Type
- boolean
-
remove(kid)
-
Removes a child node from this parent's list of child nodes. Note that
child'sdestroy()
will be called when it is removed.Parameters:
Name Type Description kid
module:nmodule/webEditors/rc/wb/tree/TreeNode | String the
node to remove, or the name of the node to removeReturns:
promise to be resolved with the
removed/destroyed child, or rejected if the given node or node name is not
found in the existing list of children, or if the list of children is not
yet loaded (getKids()
not yet called)- Type
- Promise
-
rename(name, newName)
-
Renames one child node.
Parameters:
Name Type Description name
String the name of the existing child node to rename
newName
String the new name of the child node
Returns:
promise to be resolved when the child is renamed,
or rejected if the child was not found, if the node already has a
sibling by the new name, or if the list of children is not
yet loaded (getKids()
not yet called)- Type
- Promise
-
reorder(newKids)
-
Sets the order of this node's children. The input array must contain the
exact same set of children as this node has, but in any order.Parameters:
Name Type Description newKids
Array.<module:nmodule/webEditors/rc/wb/tree/TreeNode> | Array.<String> | function the children of this node, in the desired new order. This can be
an array of the actual nodes rearranged, or an array of node names. It can
also be a sort function that takes two tree nodes; the existing nodes will
be reordered according to this function.Returns:
promise to be resolved when the child nodes are
reordered, or rejected if the input array contains a different number of
nodes than this node has children, if it contains a node that does not
exist as a child node, or if the list of children is not
yet loaded (getKids()
not yet called)- Type
- Promise
-
toDisplay()
-
The display name of this node, to be shown in user interfaces. May make
asynchronous calls to format the display name.Returns:
promise to be resolved with the display name
- Type
- Promise
-
toHyperlinkUri()
-
When activated, many tree nodes will instigate a page change. Override
this function to specify the hyperlink target.Returns:
promise to be resolved with the hyperlink target.
Bu default, resolvesundefined
.- Type
- Promise
-
toString()
-
Returns a string representation of this node. By default, just returns
the name.Returns:
- Type
- String
-
value()
-
Returns the backing value represented by this node. By default, this will
returnundefined
, since a vanillaTreeNode
is really just a
name/display pair. Subclasses ofTreeNode
intended to represent real-life
values should override this method to return the appropriate value.Returns:
- Type
- *