Pre-General Availability: 2019-2-1

Interface: treeNodeAdapter

QuickNav

treeNodeAdapter

A treeNodeAdapter is an interface used by the treeView widget for all access to the underlying tree data structure. The treeView has no direct access to the nodes of the tree or any properties of nodes such as label or icon. It is possible to create a treeNodeAdapter interface for any hierarchical data structure. The tree data structure must be singly rooted. If the data doesn't have a single root then the adapter must generate a virtual one where the multiple roots are its children.

The adapter provides the following areas of functionality:

A default treeNodeAdapter implementation is provided by calling treeView.makeDefaultNodeAdapter.

The adapter interface is provided to the treeView with the treeView#getNodeAdapter(1) option.

This interface is used by the treeView. Rarely does a developer need to call these methods. This interface is documented to allow developers to create a custom treeNodeAdapter implementation for their own data.

Methods

addNode(pParent, pIndex, pLabelopt, pContextopt, pCallback)

Adds a new node as a child of the given parent node with the given label (optional) and at the given index.

Parameters:
Name Type Attributes Description
pParent treeNodeAdapter.node The parent node to add the new node to.
pIndex integer The index among the existing children at which to add the new node.
pLabel string <optional>
The label for the new node. If not given the label may have been given a default by the adapter.
pContext Object <optional>
Arbitrary additional information that can be used in creating the new node. It is up to the adapter how to use this parameter. It could be the new node itself.
pCallback function A function to call when the new node has been added. The function takes two parameters. The first is the new child node that was added. If the child node is false the treeView may try again to add a node. If the child node is null then the add failed and the treeView will remove the node. The second parameter is the index the node was actually inserted at which could differ from pIndex.

allowAdd(pNode, pOperation, pChildrenopt) → {boolean}

Check if the node allows adding children to it. Returns true if the node allows children to be added to it. If the children parameter is passed in return true if each of those children (or ones just like them) can be added. Children is an array of nodes. Operation is "add" when adding a new node (treeNodeAdapter#addNode will be called), "move" when the node comes from elsewhere in the tree and is being moved (treeNodeAdapter#moveNodes will be called), and "copy" when the node is a copy of a node from elsewhere in the tree (treeNodeAdapter#copyNodes will be called). Additional operation values are possible if the adapter supports custom drag operations.

Parameters:
Name Type Attributes Description
pNode treeNodeAdapter.node The node to check if adding children is allowed.
pOperation string Specifies how the node would be added. One of "add", "move", "copy" or a custom value.
pChildren Array.<treeNodeAdapter.node> <optional>
The children to be added.
Returns:
true if children can be added and false otherwise.
Type
boolean

allowDelete(pNode) → {boolean}

Return true if the given node can be deleted.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node to check if deleting is allowed.
Returns:
true if the node can be deleted and false otherwise.
Type
boolean

allowDrag(pNode) → {boolean}

Return true if the given node can be dragged.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node to check if dragging is allowed.
Returns:
true if the node can be dragged and false otherwise.
Type
boolean

allowRename(pNode) → {boolean}

Return true if the given node can be renamed.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node to check if renaming is allowed.
Returns:
true if the node can be renamed and false otherwise.
Type
boolean

child(pNode, pIndex) → {treeNodeAdapter.node}

Return the ith child of the given node.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node from which to get the child node.
pIndex integer The index of the child to return.
Returns:
The child node. If the node has no children or no child at index i then undefined is returned.
Type
treeNodeAdapter.node

childCount(pNode) → (nullable) {number}

Returns the number of children that the given node has or null if the answer is not yet known, which can happen for lazy loaded nodes.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node from which to get the number of children.
Returns:
The number of children or null if unknown.
Type
number

clearViewId(pTreeId, pNodeopt)

Remove the view id mapping for node pNode. If the node is null then all previous view id mappings should be removed. See also treeNodeAdapter#setViewId.
Parameters:
Name Type Attributes Description
pTreeId string This is a unique opaque identifier supplied by the treeView.
pNode treeNodeAdapter.node <optional>
The node to clear the view id for.

copyNodes(pParent, pIndex, pNodes, pCallback)

Copies one or more nodes from elsewhere in the tree to be children of the given parent starting at the given index among the existing children of the parent. A copy of each node and all its descendants is made. The copies are the same except for identity and parentage. When the nodes have been copied the callback function is called.

Parameters:
Name Type Description
pParent treeNodeAdapter.node The parent node to copy nodes to. The copied nodes (pNodes) become children of this node.
pIndex integer The index at which to insert the copied nodes.
pNodes Array.<treeNodeAdapter.node> An array of nodes from this tree to copy.
pCallback function This function must be called when the nodes have been copied. The function takes one parameter which is a places array of indexes where the children nodes ended up. If the tree nodes are sorted then even though they were copied starting at the given index they could end up at any position. If the tree nodes are not sorted then places will consist of integers index ... index + n - 1 where n is the number of nodes copied. If the copy fails call with the places parameter equal to false. If some of the nodes can't be copied return -1 for its index in the places array.

deleteNode(pNode, pCallback, pMore)

Deletes the given node. When the node has been deleted the callback is called.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node to delete.
pCallback function The callback function must be called when the node is deleted. It takes one parameter, status, that is true if the delete was successful and false otherwise.
pMore boolean If this is true another deleteNode call will be made right away. This parameter can be ignored or can be used to batch up deletes. In either case each call to pCallback must be made.

dragOperations(pNodes) → {Object}

Determine which operations are allowed while dragging the given array of nodes. Return an object with allowed drag operations. The properties are: "normal", "ctrl", "alt", "shift", "meta". The standard values are "move", "copy" or "add". Other values are allowed. The normal property is required. The default should be:
{ normal: "move", ctrl: "copy" }
or if nodes is null:
{ normal: "add" }

Parameters:
Name Type Description
pNodes Array.<treeNodeAdapter.node> An array of nodes being dragged or null when dragging from an external source.
Returns:
Allowed drag operations as described above.
Type
Object

fetchChildNodes(pNode, pCallback)

Fetch child nodes for the given node from a server (or by any other asynchronous means). This method is optional. This is used for asynchronous/lazy tree construction. The root and first level of nodes should not be lazy loaded. May be called after treeNodeAdapter#childCount returns null.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node for which to fetch children.
pCallback function function(status) This function must be called when the asynchronous operation has completed and nodes have been added to pNode. The status value is:
  • > 0 (or true) if 1 or more children were fetched.
  • 0 if the node has 0 children.
  • false if there was an error fetching the children.

getClasses(pNode) → {string}

Returns one or more CSS classes to add to the node content container or null if none. Multiple classes are separated by a space. This is an optional method. If the method doesn't exist then no nodes will have classes added to the node content container.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node from which to get the CSS classes.
Returns:
The node's CSS Classes.
Type
string

getExpandedNodeIds(pTreeId) → {Array}

Returns an array of each of the expanded node's id. Can be used to persist the expansion state. See treeView#getExpandedNodeIds.
Parameters:
Name Type Description
pTreeId string This is a unique opaque identifier supplied by the treeView.
Returns:
Type
Array

getExpandedState(pTreeId)

Returns map of node id to expansion state. See treeView#getExpandedState.
Parameters:
Name Type Description
pTreeId string This is a unique opaque identifier supplied by the treeView.

getIcon(pNode) → {string}

Returns the icon of the node or null if none. The icon is a CSS class name. The icon is used by node content rendering. This is an optional method. If the method doesn't exist then no nodes will have icons.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node from which to get the icon.
Returns:
The node's icon.
Type
string

getLabel(pNode) → {string}

Returns the label of the given node. The label is used for node content rendering (if treeNodeAdapter#renderNodeContent not implemented) and for editing during rename.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node from which to get the label.
Returns:
The node's label.
Type
string

Returns the URL to navigate to when the node is activated. This is an optional method. It is only needed for navigation trees. If defined it is called during activation if treeView#navigation option is true.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node from which to get the link URL.
Returns:
The node's link URL.
Type
string

getViewId(pTreeId, pNode) → {string}

Return the view id for the given pTreeId and pNode. This is used by the treeView to map from nodes to DOM elements. See also treeNodeAdapter#setViewId.
Parameters:
Name Type Description
pTreeId string This is a unique opaque identifier supplied by the treeView.
pNode treeNodeAdapter.node The node to get the view id for.
Returns:
The view id for this node that was assigned with treeNodeAdapter#setViewId.
Type
string

hasChildren(pNode) → (nullable) {boolean}

Returns true if the node has children, false if it does not and null if not yet known, which can happen for lazy loaded nodes.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node for which to determine if it has children.
Returns:
true if the node has children, false if it does not and null if not yet known.
Type
boolean

isDisabled(pNode) → {boolean}

Returns the disabled state of a node. A disabled node cannot be selected or activated but it can be focused. This is an optional method. If not defined no nodes are ever disabled.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node from which to get the disabled state.
Returns:
true if the node is disabled and false otherwise.
Type
boolean

isExpanded(pTreeId, pNode) → {boolean}

Return true if the given node is or should be expanded and false otherwise.

Parameters:
Name Type Description
pTreeId string This is a unique opaque identifier supplied by the treeView.
pNode treeNodeAdapter.node The node to check if it is expanded.
Returns:
Type
boolean

moveNodes(pParent, pIndex, pNodes, pCallback)

Moves one or more nodes from elsewhere in the tree to be children of the given parent starting at the given index among the existing children of parent. The move includes all the descendants of the moved nodes. Only the parents and/or positions of the moved nodes should change. When the nodes have been moved the callback function is called.

Parameters:
Name Type Description
pParent treeNodeAdapter.node The parent node to move nodes to. The moved nodes (pNodes) become children of this node.
pIndex integer The index at which to insert the moved nodes.
pNodes Array.<treeNodeAdapter.node> An array of nodes from this tree to move.
pCallback function This function must be called when the nodes have been moved. The function takes one parameter which is a places array of indexes where the children nodes ended up. If the tree nodes are sorted then even though they were moved starting at the given index they could end up at any position. If the tree nodes are not sorted then places will consist of integers index ... index + n - 1 where n is the number of nodes moved. If the move fails call with the places parameter equal to false. If some of the nodes can't be moved return -1 for its index in the places array.

renameNode(pNode, pNewLabel, pCallback)

Rename the given node.
Parameters:
Name Type Description
pNode treeNodeAdapter.node The node to rename.
pNewLabel string The new label to rename the node to.
pCallback function This function must be called once the node is renamed. It takes two parameters. The first is node which is likely the same as pNode or false if the rename can be tried again or null if the rename failed. The second parameter is the index of the node after the rename. If the nodes are sorted then renaming the node can change its position.

renderNodeContent(pNode, pOut, pOptions, pState)

This is an optional function used to render the node content. It is used for advanced cases where more control over the node markup is needed.

The content must include an element with tabindex='-1' and that element must have a class that matches the treeView#labelClass option. The custom rendering is responsible for setting the aria-level, aria-disabled, aria-selected, and aria-expanded attributes for proper accessibility.

The options and state arguments provide additional information to determine how to render the node.

Parameters:
Name Type Description
pNode treeNodeAdapter.node The node from which to get the disabled state.
pOut apex.util.htmlBuilder Call methods on this interface to render the node content.
pOptions Object View options.
Properties
Name Type Description
iconType string CSS class used in creating an icon. The treeView#iconType option value.
labelClass string CSS classes to use for the content label. The treeView#labelClass option.
useLinks boolean Used to determine how to render nodes that have a link. The treeView#useLinks option value.
pState Object Node state information.
Properties
Name Type Description
selected boolean If true the node is selected.
level integer This is the level of the node. Used for the aria-level attribute.
disabled boolean This is true if the node is disabled.
hasChildren boolean This is true if the node has children.
expanded boolean This is true if the node is expanded.
Example

See treeView#makeDefaultNodeAdapter for an example.

root() → {treeNodeAdapter.node}

Returns the root node of the tree. All trees must have a single root node even if it is not shown/used.

Returns:
The root node.
Type
treeNodeAdapter.node

setExpanded(pTreeId, pNode, pExpanded)

Called when the expansion state of the tree node changes.

Parameters:
Name Type Description
pTreeId string This is a unique opaque identifier supplied by the treeView.
pNode treeNodeAdapter.node The node that has been expanded or collapsed.
pExpanded boolean true if the node is expanded and false if it is collapsed.

setViewId(pTreeId, pNode, pViewId)

Set the view id for the given pTreeId and pNode. This is used by the treeView to map from nodes to DOM elements.
Parameters:
Name Type Description
pTreeId string This is a unique opaque identifier supplied by the treeView.
pNode treeNodeAdapter.node The node to set the view id for.
pViewId string The view id to associate with the given node.

Type Definitions

defaultNode

This is the specific object structure for nodes used by the default treeNodeAdapter returned by treeView.makeDefaultNodeAdapter. It is possible for nodes to have additional properties. For example the APEX Tree region adds a tooltip property

Type:
Properties:
Name Type Attributes Description
label string The node label returned by treeNodeAdpater#getLabel.
id string <optional>
The unique node identity. This property is required if the hasIdentity argument to treeView.makeDefaultNodeAdapter is true.
type string <optional>
The type name of the node. The node type can determine some default aspects of the node such as CSS classes or icon. For editable treeViews it can determine what edit operations are allowed. See treeView.typeInfo for details.
link string <optional>
The URL returned by treeNodeAdpater#getLink.
children Array.<treeNodeAdapter.defaultNode> <optional>
The nodes children. Empty array means that it could have children but doesn't. Omit for leaf nodes. The treeNodeAdpater#child method is used to access the node's children.
icon string <optional>
The icon CSS class returned by treeNodeAdpater#getIcon. This overrides any icon based on the node type.
classes string <optional>
The classes returned by treeNodeAdpater#getClasses. These are added to any classes based on node type.
isDisabled boolean <optional>
The disabled state returned by treeNodeAdpater#isDisabled. This overrides any disabled state based on node type.
operations object <optional>
Overrides any operations defined for the node type. See treeView.typeInfo for details.
_parent treeNodeAdapter.defaultNode This is a reference to the parent node. This is added automatically when the default adapter is created and should not be present in the initial data.

node

An object that represents a node in a tree data structure. There are no requirements for and no assumptions are made about the specific properties of the object as all access to the node is through the treeNodeAdapter interface.

Type:
  • Object

typeInfo

The default treeNodeAdapter returned by treeView.makeDefaultNodeAdapter uses this type information to provide default settings and control over allowed edit operations for nodes based on their type.

Type:
  • Object
Properties:
Name Type Description
* Object The property names are the type names and the value is information about the type. There is one reserved type name call "default" that provides default settings for any nodes that don't have a type or if there is specific information for that type.
Properties
Name Type Attributes Description
icon string <optional>
The icon to use for nodes of this type.
classes string <optional>
Classes to add for nodes of this type.
isDisabled boolean | function <optional>
If true nodes of this type are disabled by default.
defaultLabel string <optional>
The default label for new nodes.
validChildren true | Array.<string> <optional>
An array of valid children types for this type. If true then children of any type can be added to nodes of this type.
operations Object <optional>
Specifies what edit operations can be done on nodes of this type.
Properties
Name Type Attributes Description
canAdd boolean | function <optional>
If true nodes of this type allow adding.
canDelete boolean | function <optional>
If true nodes of this type allow being deleted.
canRename boolean | function <optional>
If true nodes of this type allow being renamed.
canDrag boolean | function <optional>
If true nodes of this type allow being dragged.
drag Object <optional>
An object that defines the operation to perform during a drop based on the modifier key pressed. The properties are the modifier keys and can containe any one of: "normal", "ctrl", "alt", "shift" and the values are the the operation to perform and can be anyone of "move", "copy", or "add". The value can also be a custom operation that is handled in the beforeStop event.
externalDrag Object <optional>
An object that defines the operation to perform during a drop from an external draggable based on the modifier key pressed. The properties and values are the same as for the operations drag property. This property can only be used on the "default" type.