Pre-General Availability: 2018-5-8
Widget: treeView
treeView
A jQuery UI widget that implements a tree view used to display and interact with hierarchical data. Implements tree view functionality according to WAI-ARIA authoring practices design patterns and the DHTML Style Guide with minor differences in keyboard handling.
The treeView works with any data model via the treeNodeAdapter interface supplied when the treeView is created. The tree data model must be singly rooted. If the data doesn't have a single root then the adapter must generate one dynamically where the multiple roots are its children. The tree need not display the root. For a multi-rooted tree set the treeView#showRoot option to false. With showRoot false the adapter will never be asked for the label or icon etc. of the root node. The tree can also be created from markup
Context Menus
The treeView has easy integration with the menu widget to provide context menu support. The treeView#contextMenu option is used to provide a menu widget options object. When the contextMenu option is used the menu#event:beforeOpen event/callback ui argument has these additional properties:
- menuElement: The menu jQuery object.
- treeView: This tree jQuery object.
- treeNodeAdapter: The nodeAdapter for this tree.
- selection: A jQuery object with the selected tree nodes at the time the menu was opened.
- selectedNodes: An array of the selected model nodes at the time the menu was opened.
Also the menu#event:afterClose event/callback will automatically focus the tree if the menu action didn't take the focus and the ui argument has these additional properties:
- menuElement: The menu jQuery object.
- treeView: This tree jQuery object.
If using the contextMenu option the treeView#contextMenuId option can be used to give the menu element an ID. This is useful if other code must refer to the menu element or widget.
You can reference an already existing menu widget by specifying the treeView#contextMenuId in place of the treeView#contextMenu option.
If for any reason you don't want to use the menu widget, the treeView#contextMenuAction option allows you to respond to mouse or keyboard interactions that typically result in a context menu. Specifically Right Mouse click (via contextmenu event), Shift-F10 key (via keydown event) and the Windows context menu key (via contextmenu event). The original event is passed to the contextMenuAction function. The event object can be used to position the menu. If you implement your own menu it is best if you put focus back on the treeView using the treeView#focus method when the menu closes (unless the menu action directs focus elsewhere).
Only one of treeView#contextMenuAction and treeView#contextMenu or treeView#contextMenuId can be specified. The contextMenu and contextMenuId options can only be set when the treeView is initialized and it can't be changed. The contextMenuAction cannot be set if the contextMenu or contextMenuId options were given when the tree was created.
Drag and Drop
To enable drag and drop set the treeView#dragAndDrop option to true. The treeView can be a drag source for either a jQuery UI droppable or the same treeView instance and it can be a drop target for either a jQuery UI draggable or the same treeView instance.
To work with a droppable make sure the scope options of the droppable and treeView match and that the droppable accept option allows the treeView node (an element with class a-TreeView-content). On droppable drop you would typically call the treeView#getSelection or treeView#getSelectedNodes of the treeView instance.
To work with a draggable set the draggable connectToTreeView option to a selector for the treeView instance you want to be a drop target. (Note a treeView plugin extends the draggable to add the connectToTreeView option)
The treeView supports dragging single or multiple nodes. In order to drag multiple nodes both the treeView#multiple and treeView#dragMultiple options must be true. Note it is possible for a treeView instance to support multiple selection but single drag. The reverse (single selection and multiple drag) is not possible.
Regardless of the drag source there are two modes of behavior for identifying drop targets. The mode is determined by the treeView#dragReorder option. If false (the default) nodes which can have children of the type(s) being dragged are targets and dropping on the target node results in the dragged node(s) being added as children. This mode is suitable when the children have an implicit order such as files in a file system folder. If dragReorder is true then a placeholder node, which dynamically moves between nodes whose parent can have children of the type(s) being dragged, is the target. Dropping on the placeholder target adds the nodes where the placeholder is. This mode is suitable for when nodes can be explicitly ordered by the user such as with sections in a document outline.
A drag and drop can perform various operations. There is builtin support for move, copy and add operations. Add only works when the drag is from a draggable, move and copy work when the tree is the drag source and target. The nodeAdapter decides what operations are supported with the dragOperations method based on the types of nodes being dragged, or any other context available to the adapter. Different operations are selected with keyboard modifiers: shift, ctrl, alt, and meta (only one modifier is allowed). Operations besides move, copy, and add are handled with custom logic in the beforeStop event handler. See treeNodeAdapter#moveNodes, and treeNodeAdapter#copyNodes for how the nodeAdapter is used for drag and drop move and copy operations.
Tree From Markup
A tree data model can be created from HTML markup inside the treeView element. A tree from markup has much less functionality. The markup is nested lists using ul, li, and a or span for the labels. This is typically used for navigation such as with a site map. The markup is converted to data and a default adapter with no editing capability is created to interface to it. The li element can include attributes: class (value returned by getClasses), data-id (value used by get/setViewId), data-icon (value returned by getIcon), data-type (used by default adapter, only useful if supplying adapterTypesMap), data-current (true value will select that node), data-disabled (value returned by isDisabled). The span or anchor content is the label. The anchor href attribute is the link (getLink) used for navigation. Unless the top level list has a single item treeView#showRoot should be false. Typically treeView#multiple is false and navigation is true. An example below show the basic expected markup.
Keyboard End User Information
Key | Action |
Up Arrow, Down Arrow | Moves focus to the previous or next visible node and selects it. |
Shift+Up Arrow, Shift+Down Arrow | Extends the selection to the previous or next visible node. Only if multiple selection is enabled. |
Ctrl+Up Arrow, Ctrl+Down Arrow | Moves focus to the previous or next visible node without changing the selection. Only if multiple selection is enabled. |
Ctrl+Up Arrow, Ctrl+Down Arrow | Moves focus to the previous or next visible node without changing the selection. Only if multiple selection is enabled. |
Space | Selects the focused node. Only if multiple selection is enabled. |
Ctrl+Space | Toggles selection of the focused node. Only if multiple selection is enabled. |
Right Arrow | On a collapsed node, expands the node. On an expanded node, moves to the first first child of the node. On a leaf node, does nothing. |
Left Arrow | On an expanded node, collapses the node. On a collapsed or leaf node, moves focus to the node's parent. |
Home | Moves focus to the first visible node and selects it. Shift modifier can be used if multiple selection is enabled. |
End | Moves focus to the last visible node and selects it. Shift modifier can be used if multiple selection is enabled. |
Page Up, Page Down | Moves up or down a page of nodes. Shift modifier can be used if multiple selection is enabled. |
printable character(s) | Sets focus to and selects the next node with a label that starts with the character(s). |
Enter | Activates the focused node. The behavior of a node when it is activated is application defined.
If the node has a link then navigate to that link. During in-place editing completes the editing. |
Context Menu, Shift+F10 | Invoke Context Menu if defined on current node. |
F2 | Rename the node. Only if the tree and node allow renaming and keyboard rename is enabled. |
Insert | Insert a new node. Only if the tree and node allow inserting and keyboard insert is enabled. |
Delete | Delete the node. Only if the tree and node allow deleting and keyboard delete is enabled. |
Escape | Cancels in-place node label editing. |
When the direction is right to left (RTL) the behavior of the left and right arrow keys is reversed.
Name | Type | Description |
---|---|---|
options |
Object | A map of option-value pairs to set on the widget. |
- Since:
- 5.0
Examples
Create a simple treeView with 4 nodes using the default node adapter. The page contains an empty div element with id "simpleTree".
var treeData = {
label: "Root",
children: [
{
label: "Child 1",
children: [
{
label: "Grandchild"
}
]
},
{
label: "Child 2",
children: []
}
]
};
var myAdapter = $.apex.treeView.makeDefaultNodeAdapter( treeData );
$( "#simpleTree" ).treeView( {
getNodeAdapter: function() { return myAdapter; },
expandRoot: false
} );
Create a simple treeView from markup. The display:none style is used to keep the markup from being seen before it is turned into a treeView widget.
Markup:
<div id="markupTree">
<ul style="display:none;">
<li><a href="#toc">Table of Contents</a>
<ul>
<li><a href="#chapter1">Chapter 1</a>
<li><a href="#chapter2">Chapter 2</a>
</ul>
</li>
</ul>
</div>
JavaScript:
$( "#markupTree" ).treeView( {
navigation: true
} );
Options
adapterTypesMap :Object
Optional and only used when getNodeAdapter is null (when initializing the treeView from markup) The value is passed to treeView.makeDefaultNodeAdapter as types parameter.
Type:
- Object
allowCopy :boolean
If true the selection can be copied to the clipboard using the browsers copy event.
Type:
- boolean
- Default Value:
- true
autoCollapse :boolean
If true only one sibling node can be expanded at a time.
Type:
- boolean
- Default Value:
- false
clickToRename :boolean
If true allow nodes to be renamed in-place by clicking on a selected node subject to data model approval via treeNodeAdapter#allowRename.
Type:
- boolean
- Default Value:
- false
collapsibleRoot :boolean
If false the root node cannot be collapsed (has no toggle area) otherwise the root can be collapsed.
Type:
- boolean
- Default Value:
- true
contextMenu :Object
A menu widget options object use to create the context menu.
Only specify one of contextMenu or contextMenuId and contextMenuAction. If none of contextMenu, contextMenuId or contextMenuAction are specified there is no context menu.
Type:
- Object
- Default Value:
- null
contextMenuAction :function
A callback function that is called when it is time to display a context menu. function( event ) The function is responsible for showing the context menu. It is given the event that caused this callback to be called.
In most cases it is simpler and more consistent to use the contextMenu option. Only specify one of contextMenu or contextMenuId and contextMenuAction. If none of contextMenu, contextMenuId or contextMenuAction are specified there is no context menu.
Type:
- function
- Default Value:
- null
contextMenuId :string
If option contextMenu is given then this is the element id to give the context menu created. This allows other code to interact with the created context menu widget.
If option contextMenu is not given then this is the element id of an existing menu widget.
Type:
- string
- Default Value:
- null
doubleClick :false|string
Determines the behavior of double clicking on a node. One of:
- false: does nothing.
- "activate": the node is activated.
- "toggle": the node is collapsed if expanded and expanded if collapsed.
Type:
- false | string
- Default Value:
- false
dragAndDrop :boolean
If true drag and drop is supported. The treeNodeAdapter must also support drag and drop.
Type:
- boolean
- Default Value:
- false
dragAppendTo :string
Which element the draggable helper should be appended to while dragging. See jQuery UI draggable appendTo option for details.
Type:
- string
- Default Value:
- "parent"
dragContainment :boolean
Constrains dragging to within the bounds of the specified element or region. See jQuery UI draggable containment option for details.
Type:
- boolean
- Default Value:
- false
dragCursor :string
The CSS cursor during the drag operation. See jQuery UI draggable cursor option for details.
Type:
- string
- Default Value:
- "auto"
dragCursorAt :false|Object
Sets the offset of the dragging helper relative to the mouse cursor. See jQuery UI draggable cursorAt option for details.
Type:
- false | Object
- Default Value:
- false
dragExpandDelay :number
When dragging and hover over a collapsed node how long (in milliseconds) to wait until it expands -1 means don't expand.
Type:
- number
- Default Value:
- 1200
dragHelper :string|function
Allows for a helper element to be used for dragging display. See jQuery UI draggable helper option for details.
Type:
- string | function
- Default Value:
- true
dragMultiple :boolean
This only applies if treeView#multiple and treeView#dragAndDrop options are true.
If this option is true then multiple nodes can be dragged.
Type:
- boolean
- Default Value:
- false
dragOpacity :false|number
Opacity for the helper while being dragged. See jQuery UI draggable opacity option for details.
Type:
- false | number
- Default Value:
- false
dragReorder :boolean
If true the nodes can be reordered using drag and drop. If false drag and drop just moves (or copies) nodes from one parent node to another.
Type:
- boolean
- Default Value:
- false
dragScroll :boolean
If set to true, container auto-scrolls while dragging. See jQuery UI draggable scroll option for details.
Type:
- boolean
- Default Value:
- true
dragScrollSensitivity :number
Distance in pixels from the edge of the viewport after which the viewport should scroll. Distance is relative to pointer, not the draggable. See jQuery UI draggable scrollSensitivity option for details.
Type:
- number
- Default Value:
- 20
dragScrollSpeed :number
The speed at which the window should scroll. See jQuery UI draggable scrollSpeed option for details.
Type:
- number
- Default Value:
- 10
dragZIndex :number
Z-index for the helper while being dragged. See jQuery UI draggable zIndex option for details.
Type:
- number
- Default Value:
- 1000
expandRoot :boolean
If true the root node is initially expanded otherwise it is collapsed.
Type:
- boolean
- Default Value:
- true
getNodeAdapter :function
A no argument function returning an object that implements the treeNodeAdapter interface. The node adapter provides access to the data behind the treeView. This option is required unless the tree data is supplied by markup.
Type:
- function
- Default Value:
- null
iconType :string
Type:
- string
- Default Value:
- a-Icon
idPrefix :boolean
Optional id prefix used to generate unique DOM ids. If not given the prefix is based on the id of the treeView widget root element or if there is no id the prefix is "tree".
Type:
- boolean
keyboardAdd :boolean
If true allow a new child node to be added in-place with Insert key subject to model approval via treeNodeAdapter#allowAdd.
Type:
- boolean
- Default Value:
- false
keyboardDelete :boolean
If true allow nodes to be deleted with the Delete key subject to model approval via treeNodeAdapter#allowDelete.
Type:
- boolean
- Default Value:
- false
keyboardRename :boolean
If true allow nodes to be renamed in-place by pressing the F2 key subject to data model approval via treeNodeAdapter#allowRename.
Type:
- boolean
- Default Value:
- false
labelClass :string
The CSS class name to use on the focusable node content element. This should only be changed if the node adapter implements treeNodeAdapter#renderNodeContent.
Type:
- string
- Default Value:
- "a-TreeView-label"
multiple :boolean
If true multiple nodes can be selected otherwise only single selection is supported.
Type:
- boolean
- Default Value:
- false
navigation :boolean
If true then single click causes activation (unless treeView#doubleClick value is "activate") and if the node adapter supports treeNodeAdapter#getLink and getLink returns a value the default behavior is to navigate to that link.
Type:
- boolean
- Default Value:
- false
nodeSelector :boolean
If true a selector control is added before the node icon and label. The selector is a checkbox if multiple is true and a radio button if multiple is false.
Type:
- boolean
- Default Value:
- false
scope :string
Only used with jQuery UI droppable for drag and drop. Used to group sets of draggable and droppable items. See jQuery UI droppable scope option for details.
Type:
- string
- Default Value:
- "default"
showRoot :boolean
Determines if the tree is shown with a single root or with multiple "roots" which are really the first level nodes in the data model. If false the tree appears like a forest (multi-rooted). If true there is a single root node.
Type:
- boolean
- Default Value:
- true
tooltip :Object
A tooltip options object suitable for the jQuery UI tooltip widget except that the items property is not needed (it is supplied by the treeView) and the content callback function receives a second argument that is the treeNodeAdapter.node the tooltip applies to. If not given there is no tooltip.
See the jQuery UI documentation for details on the tooltip widget.
Type:
- Object
- Default Value:
- null
useLinks :boolean
If true nodes with links are rendered as anchor elements. Nodes that have a link can be navigated to on activation regardless of this option value. By using an anchor element the built in browser behavior for opening links in new windows or tabs is available. Beware if combined with context menu options.
Type:
- boolean
- Default Value:
- true
Events
activateNode
Triggered when when nodes are activated with the Enter key or double click if treeView#doubleClick option set to "activate" or single click if treeView#navigation option is true and treeView#doubleClick is not "activate". Handler can call the event's preventDefault method to stop navigation.
Properties:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
event |
Event | jQuery event object. |
||||||
ui |
Object |
Properties
|
Examples
Initialize the treeView with the activateNode
callback specified:
$( ".selector" ).treeView({
activateNode: function( event, ui ) {}
});
Bind an event listener to the treeviewactivatenode
event:
$( ".selector" ).on( "treeviewactivatenode", function( event, ui ) {} );
beginEdit
Triggered when when in-place add or rename begins.
Properties:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
event |
Event | jQuery event object. |
||||||||||||
ui |
Object |
Properties
|
Examples
Initialize the treeView with the beginEdit
callback specified:
$( ".selector" ).treeView({
beginEdit: function( event, ui ) {}
});
Bind an event listener to the treeviewbeginedit
event:
$( ".selector" ).on( "treeviewbeginedit", function( event, ui ) {} );
endEdit
Triggered when when in-place add or rename ends.
Properties:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
event |
Event | jQuery event object. |
|||||||||
ui |
Object |
Properties
|
Examples
Initialize the treeView with the endEdit
callback specified:
$( ".selector" ).treeView({
endEdit: function( event, ui ) {}
});
Bind an event listener to the treeviewendedit
event:
$( ".selector" ).on( "treeviewendedit", function( event, ui ) {} );
expansionStateChange
Triggered when nodes are expanded or collapsed.
Properties:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
event |
Event | jQuery event object. |
||||||||||||
ui |
Object |
Properties
|
Examples
Initialize the treeView with the expansionStateChange
callback specified:
$( ".selector" ).treeView({
expansionStateChange: function( event, ui ) {}
});
Bind an event listener to the treeviewexpansionstatechange
event:
$( ".selector" ).on( "treeviewexpansionstatechange", function( event, ui ) {} );
selectionChange
Triggered when the selection state changes. It has no additional data. When the selection changes the handler will generally want to get the current selection using the treeView#getSelection or treeView#getSelectedNodes methods.
Properties:
Name | Type | Description |
---|---|---|
event |
Event | jQuery event object. |
Examples
Initialize the treeView with the selectionChange
callback specified:
$( ".selector" ).treeView({
selectionChange: function( event ) {}
});
Bind an event listener to the treeviewselectionchange
event:
$( ".selector" ).on( "treeviewselectionchange", function( event ) {} );
Methods
(static) makeDefaultNodeAdapter(data, typesopt, hasIdentity, initialExpandedNodeIds) → {treeNodeAdapter}
Returns a default node adapter. xxx
This is an adapter for a default data model. Use it if you don't already have a prescribed data model. This supports all the treeView features except for asynchronous loading of child nodes and custom node rendering. Although it supports editing there is no built-in support for persiting the edits. xxx should editing be removed in favor of using the model adapter?Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
treeNodeAdapter.defaultNode | This object is the root node of the tree. | |
types |
treeNodeTypes |
<optional> |
xxx |
hasIdentity |
boolean | xxx | |
initialExpandedNodeIds |
Array | An array of node ids for all the nodes that should be initially expanded. |
Returns:
- Type
- treeNodeAdapter
Examples
xxx
* Call as
$.apex.treeView.makeDefaultNodeAdapter(data, [types], false);
xxx
$.apex.treeView.makeDefaultNodeAdapter(data, [types], [initialExpandedNodeIds]);
(static) makeModelNodeAdapter(modelId, options, data) → {treeNodeAdapter}
Parameters:
Name | Type | Description |
---|---|---|
modelId |
modelId used to create apex model | |
options |
options to create an apex model with these additional options hasIdentity initialExpandedNodeIds labelField - default label iconField - default icon classesField - default classes linkField - default link, disabledField - default isDisabled | |
data |
initial tree data |
Returns:
- Type
- treeNodeAdapter
(static) treeModelListener(modelName, tree$)
Parameters:
Name | Type | Description |
---|---|---|
modelName |
||
tree$ |
addNode(toParentNodeContent$, index, nodeopt)
Adds the given node to the model and the tree view under the given parent tree node and at the given index. If node is null then the model should create whatever its default new node is and add that. The model must allow the node to be added.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
toParentNodeContent$ |
jQuery | The parent tree node to add a child to. If null or an empty jQuery object then the node is added to the root (this can only happen when the root node is not shown in the tree view). | |
index |
integer | The index in the array of children to add the new node. | |
node |
treeNodeAdapter.node |
<optional> |
(optional) New node to add. |
Throws:
addNodeInPlace(parentNodeContent$, initialLabel, contextopt)
Adds a new tree node in the tree view and also adds it to the model via the node adapter treeNodeAdapter#addNode method. First checks if the model allows add for the parent node. The label of the new node is chosen by the user in-place. The tree node label is replaced by a text input field. Escape will cancel the add, blur will complete the add with the initial label, and Enter will complete the add. The order of the new node among its siblings is determined by the model after the node is added.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
parentNodeContent$ |
jQuery | The parent tree node to add the new node under. Must be a jQuery object representing exactly one tree node element. | |
initialLabel |
string | The initial label for the new node which is then edited. | |
context |
Object |
<optional> |
Optional arbitrary object to pass into the adapter allowAdd and addNode methods. This is an object containing information needed by the treeNodeAdapter#addNode method to create the new node. In the typical simple case it is exactly the model node. |
Throws:
collapse(nodeContent$opt)
Collapse the given tree node(s) or if no node is given collapse the root node(s). Collapsing a node makes all of its children hidden.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
nodeContent$ |
jQuery |
<optional> |
One or more tree nodes to collapse or null or omit to collapse the root(s). |
collapseAll(nodeContent$opt)
Collapse the given tree node(s) or if no node is given the root node(s) and recursively collapse all its children.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
nodeContent$ |
jQuery |
<optional> |
One or more tree nodes to collapseALl from or null or omit to collapseAll from the root(s). |
copyNodes(toParentNodeContent$, index, nodeContent$)
Copies the given tree nodes to be children of the given parent tree node starting at the given index. The model must allow each of the nodes to be added to the new parent.
Parameters:
Name | Type | Description |
---|---|---|
toParentNodeContent$ |
jQuery | parent tree node to copy nodes to. If null or an empty jQuery object then the node is copied to the root (this can only happen when the root node is not shown in the tree view). |
index |
integer | The index in the array of children to copy the nodes to. |
nodeContent$ |
jQuery | The tree nodes to be copied. |
Throws:
deleteNodes(nodeContent$)
Deletes nodes from the model and tree view. First checks that the model allows delete then deletes the node from the model (a potentially async operation). If the deletes are allowed and successful then the tree nodes are removed from the tree view UI.
Parameters:
Name | Type | Description |
---|---|---|
nodeContent$ |
jQuery | One or more tree nodes to delete. |
Throws:
deleteTreeNodes(nodeContent$)
Deletes tree nodes that have already been deleted from the model.
Parameters:
Name | Type | Description |
---|---|---|
nodeContent$ |
jQuery | One or more tree nodes to delete. |
expand(nodeContent$opt)
Expand the given tree node(s) or if no node is given expand the root node(s). Expanding a node makes all of its children visible.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
nodeContent$ |
jQuery |
<optional> |
One or more tree nodes to expand or null or omit to expand the root(s). |
expandAll(nodeContent$opt)
Expand the given tree node(s) or if no node is given the root node(s) and recursively expand all its children.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
nodeContent$ |
jQuery |
<optional> |
One or more tree nodes to expand all from or null or omit to expand all from the root(s). |
find(options) → {jQuery}
Search through the tree starting at the root or the given parent tree node for one or more matching nodes (the parent tree node is not included in the search). The set of matched tree nodes is returned as a jQuery object. The match criteria is determined by the match function that is called for each node. The search can be limited to a specified depth (from the starting node). Find can return either all the nodes matched or just the first one.
This is a synchronous API so it can only search tree nodes that have been loaded. If the data model is loaded asynchronously only those tree nodes that have already been loaded into the model can be searched. The tree nodes don't need to be expanded to be searched, but searching will cause them to be rendered to the DOM.
Parameters:
Name | Type | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object | The properties control how the search is done.
Properties
|
Returns:
- Type
- jQuery
focus()
Set focus to the tree node that last had focus.
getExpandedNodeIds()
Get the ids of expanded nodes. The node adapter must implement view state methods.
Throws:
Returns:
getExpandedState() → {Object}
Get a map from node id to Boolean where true = expanded and false = collapsed
Note It is not guaranteed that the map contain all nodes! It may only contain nodes that have been explicitly expanded or collapsed by the user. This is up to the adapter. The node adapter must implement view state methods.
Throws:
Returns:
- Type
- Object
getNodeAdapter() → {treeNodeAdapter}
Returns the node adapter that the treeView is using.
Returns:
- Type
- treeNodeAdapter
getNodes(nodeContent$) → {Array.<treeNodeAdapter.node>}
Given a jQuery object with a set of tree view nodes return an array of model nodes that corresponds to each tree node in the set. The tree nodes passed in must be the ones this treeView instance rendered with class a-TreeView-content.
This is for mapping from DOM elements to model node objects.
Parameters:
Name | Type | Description |
---|---|---|
nodeContent$ |
jQuery | jQuery Object holding a set of tree nodes. |
Returns:
- Type
- Array.<treeNodeAdapter.node>
getSelectedNodes() → {Array.<treeNodeAdapter.node>}
Returns the data model nodes corresponding to the currently selected tree nodes.
Returns:
- Type
- Array.<treeNodeAdapter.node>
getSelection() → {jQuery}
Returns the set of tree nodes currently selected. If there is no selection the empty set is returned. The elements returned have the class a-TreeView-content.
Returns:
- Type
- jQuery
getTreeNode(node) → {jQuery}
Given a node return a jQuery object with the element corresponding to that node. The element returned has the class a-TreeView-content. The node adapter must implement view state methods.
This is for mapping from a model node object to a DOM element.
Parameters:
Name | Type | Description |
---|---|---|
node |
treeNodeAdapter | the model node to get the corresponding tree node DOM element for. |
Throws:
Returns:
- Type
- jQuery
moveNodes(toParentNodeContent$, index, nodeContent$)
Moves the given tree nodes to be children of the given parent tree node starting at the given index. The model must allow each of the nodes to be added to the new parent and must allow all the nodes to be deleted.
Parameters:
Name | Type | Description |
---|---|---|
toParentNodeContent$ |
jQuery | The parent tree node to move node to. If null or an empty jQuery object then the node is moved to the root (this can only happen when the root node is not shown in the tree view) |
index |
integer | The index in the array of children to move the nodes to. |
nodeContent$ |
jQuery | The tree nodes to be moved. |
Throws:
refresh(nodeContent$)
Call to render the whole tree or sub trees whenever the data model changes.
Parameters:
Name | Type | Description |
---|---|---|
nodeContent$ |
jQuery | the tree node(s) to refresh from. If not given or null start from the root of the tree. |
renameNodeInPlace(nodeContent$)
Renames a tree node in the tree view and updates the model via the node adapter treeNodeAdapter#renameNode method. First checks it the model allows the node to be renamed. The rename is done by the user in-place. The tree node label is replaced by a text input field. Escape or blur will cancel, Enter will complete the rename. The order of the renamed node among its siblings is determined by the model after the node is renamed.
Parameters:
Name | Type | Description |
---|---|---|
nodeContent$ |
the tree node to rename. Must be a jQuery object representing exactly one tree node element. |
Throws:
setSelectedNodes(nodes, focus, pNoNotifyopt)
Sets the current tree selection. Given an array of nodes from the node adapter model, find the corresponding tree node elements and set the selection to those nodes. The node adapter must implement view state methods.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
nodes |
Array.<treeNodeAdapter.node> | An array of model nodes. | |
focus |
boolean | If true the tree node corresponding to the first node in nodes will be focused. | |
pNoNotify |
boolean |
<optional> |
If true the selection change event will be suppressed. |
Throws:
setSelection(nodeContent$, focusopt, pNoNotifyopt)
Sets the current tree selection. The tree nodes passed in must be the ones this treeView instance rendered with class a-TreeView-content.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
nodeContent$ |
jQuery | A jQuery object with the tree nodes to select. An empty jQuery set will clear the selection. | |
focus |
boolean |
<optional> |
If true the first tree node in nodeContent$ will be focused. |
pNoNotify |
boolean |
<optional> |
If true the selection change event will be suppressed. |
update(nodeContent$)
Call this method if the model node changes in a way that would affect its display in the tree. For example if the label or icon changes. If a node's children have changed then call refresh instead. If a nodes position has changed then call refresh on the nodes parent node.
Parameters:
Name | Type | Description |
---|---|---|
nodeContent$ |
jQuery | The tree node for which the underlying model node has changed. |