Initializer
$(".selector").treeView(options)
Parameters:
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. |