Module: nmodule/webEditors/rc/wb/tree/TreeNode


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
array of child nodes

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 time getKids() is
called.

After getKids() is called for the first time, any updates or changes to
the list of nodes should only be done through the add(), remove(),
and other mutator methods.

Do not set the parent of the child nodes created by this method - they
will automatically be parented when getKids() 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 a Batch object, it is obligated to ensure that any
progressCallback param passed in will be called with a commitReady
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 of TreeNode
instances.

Type
Promise

activate()

Activates the node and all of its child nodes. This method works very
similarly to Widget#initialize() in that it delegates the implementation
of the destruction of each individual node to doActivate().

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 to Widget#destroy() in that it delegates the implementation
of the destruction of each individual node to doDestroy().

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 in doDestroy(). 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 during doActivate(). 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 from isDropTarget 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, or undefined 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 the add(), 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 calling getKids without being sure you have
called $loadKids first.

Returns:

promise to be resolved with an array of child
TreeNodes

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:
Type
module:nmodule/webEditors/rc/wb/tree/TreeNode

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 to return 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 a
getChildCount() 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 that getKids() 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's destroy() 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 remove

Returns:

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, resolves undefined.

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
return undefined, since a vanilla TreeNode is really just a
name/display pair. Subclasses of TreeNode intended to represent real-life
values should override this method to return the appropriate value.

Returns:
Type
*