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

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

new (require("nmodule/webEditors/rc/wb/tree/TreeNode"))(name, display, kidsopt)

Description:

  • 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.

Source:
Mixes In:
  • tinyevents
Parameters:
Name Type Attributes 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

Methods

(abstract) $loadKids(paramsopt) → {Promise}

Description:

  • 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.

Source:
Parameters:
Name Type Attributes Description
params Object <optional>
Properties
Name Type Attributes 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() → {Promise}

Description:

  • 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.

Source:
Returns:

promise to be resolved when this node and all
child nodes (if loaded) have been activated

Type
Promise

add(kid) → {Promise}

Description:

  • 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.

Source:
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() → {Promise}

Description:

  • 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.

Source:
Returns:

promise to be resolved when this node and all
child nodes (if loaded) have been destroyed

Type
Promise

doActivate() → {Promise}

Description:

  • 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.

Source:
Returns:

promise to be resolved when activation is
complete - or return undefined if no asynchronous work needs to be done

Type
Promise

doDestroy() → {Promise}

Description:

  • Implementation of destroy(). This method should release any resources
    acquired by the node during doActivate(). By default, does nothing.

Source:
Returns:

promise to be resolved when destruction is
complete - or return undefined if no asynchronous work needs to be done

Type
Promise

doDrop(values) → {Promise}

Description:

  • 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.

Source:
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) → {boolean}

Description:

  • Test to see if this node is equivalent to some value. By default, a node
    is equivalent only to itself.

Source:
Parameters:
Name Type Description
value *
Returns:
Type
boolean

getDescendent(names) → {Promise}

Description:

  • Retrieves a child by traversing the tree using the names provided. Each name
    will traverse a level deeper into the tree.

Source:
Parameters:
Name Type Description
names Array.<string>
Returns:

promise to be resolved with the descendent node, or
undefined if not found

Type
Promise

getFullPath() → {Array.<String>}

Description:

  • 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.

Source:
Returns:

an array of node names, with the name of the
root node first and this node last

Type
Array.<String>

getIcon() → {Array.<String>}

Description:

  • 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.

Source:
Returns:

an array of URIs to image files

Type
Array.<String>

getKid(name) → {Promise}

Description:

  • Retrieves a child node by name. If child nodes are not yet loaded, they
    will be upon calling this method.

Source:
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(paramsopt) → {Promise}

Description:

  • 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.

Source:
Parameters:
Name Type Attributes 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() → {String}

Description:

  • The name of this node. If this node has siblings, note that names must
    be unique among all sibling nodes.

Source:
Returns:
Type
String

getParent() → {module:nmodule/webEditors/rc/wb/tree/TreeNode}

Description:

  • The parent node. If the node is unparented, will return null.

Source:
Returns:
Type
module:nmodule/webEditors/rc/wb/tree/TreeNode

isDraggable() → {boolean}

Description:

  • Return true if this tree node is eligible to begin a drag operation.

Source:
Returns:

false by default

Type
boolean

isDropTarget() → {boolean}

Description:

  • 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.

Source:
Returns:

false by default

Type
boolean

isSelectable() → {Boolean}

Description:

  • Override this method to return false to prevent this node from being
    selected in the tree.

Source:
Returns:

true by default.

Type
Boolean

(abstract) mayHaveKids() → {boolean}

Description:

  • 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.

Source:
Returns:
Type
boolean

remove(kid) → {Promise}

Description:

  • Removes a child node from this parent's list of child nodes. Note that
    child's destroy() will be called when it is removed.

Source:
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) → {Promise}

Description:

  • Renames one child node.

Source:
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) → {Promise}

Description:

  • 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.

Source:
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() → {Promise}

Description:

  • The display name of this node, to be shown in user interfaces. May make
    asynchronous calls to format the display name.

Source:
Returns:

promise to be resolved with the display name

Type
Promise

toHyperlinkUri() → {Promise}

Description:

  • When activated, many tree nodes will instigate a page change. Override
    this function to specify the hyperlink target.

Source:
Returns:

promise to be resolved with the hyperlink target.
Bu default, resolves undefined.

Type
Promise

toString() → {String}

Description:

  • Returns a string representation of this node. By default, just returns
    the name.

Source:
Returns:
Type
String

value() → {*}

Description:

  • 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.

Source:
Returns:
Type
*

(static) BY_NODE_NAME()

Description:

  • Pass this to #reorder to sort all tree nodes by name.

Source: