Class: Fancytree

Fancytree(widget)

The controller behind a fancytree.
This class also contains 'hook methods': see Fancytree_Hooks.

Constructor

new Fancytree(widget)

Construct a new tree object.

Parameters:
Name Type Description
widget Widget
Properties:
Name Type Description
_id string

Automatically generated unique tree instance ID, e.g. "1".
_ns string

Automatically generated unique tree namespace, e.g. ".fancytree-1".
activeNode FancytreeNode

Currently active node or null.
ariaPropName string

Property name of FancytreeNode that contains the element which will receive the aria attributes.
Typically "li", but "tr" for table extension.
$container jQueryObject

Outer <ul> element (or <table> element for ext-table).
$div jQueryObject

A jQuery object containing the element used to instantiate the tree widget (widget.element)
columns object | array

Recommended place to store shared column meta data. @since 2.27
data object

Metadata, i.e. properties that may be passed to source in addition to a children array.
ext object

Hash of all active plugin instances.
focusNode FancytreeNode

Currently focused node or null.
lastSelectedNode FancytreeNode

Used to implement selectMode 1 (single select)
nodeContainerAttrName string

Property name of FancytreeNode that contains the outer element of single nodes.
Typically "li", but "tr" for table extension.
options FancytreeOptions

Current options, i.e. default options + options passed to constructor.
rootNode FancytreeNode

Invisible system root node.
statusClassPropName string

Property name of FancytreeNode that contains the element which will receive the status classes.
Typically "span", but "tr" for table extension.
types object

Map for shared type specific meta data, used with node.type attribute. @since 2.27
viewport object

See ext-vieport. @since v2.31
widget object

Base widget instance.
Source:

Method Summary

Return Type Name and Arguments Details
void activateCell($td, orgEvent=null)

[ext-ariagrid] Set active cell and activate cell-nav or cell-edit mode if needed.
Pass $td=null to enter row-mode.

See also FancytreeNode#setActive(flag, {cell: idx})

 Details
FancytreeNode activateKey(key, opts)

Activate node with a given key and fire focus and activate events.

A previously activated node will be deactivated.
If activeVisible option is set, all parents will be expanded as necessary.
Pass key = false, to deactivate the current node only.

 Details
void addPagingNode(node, mode='append')

(experimental) Add child status nodes that indicate 'More...', ....

 Details
void adjustViewportSize()

[ext-grid] Calculate the viewport count from current scroll wrapper height.

 Details
void applyCommand(cmd, node=active_node, opts)

(experimental) Apply a modification (or navigation) operation.

Valid commands:

  • 'moveUp', 'moveDown'
  • 'indent', 'outdent'
  • 'remove'
  • 'edit', 'addChild', 'addSibling': (reqires ext-edit extension)
  • 'cut', 'copy', 'paste': (use an internal singleton 'clipboard')
  • 'down', 'first', 'last', 'left', 'parent', 'right', 'up': navigate
 Details
$.Promise applyPatch(patchList)

(experimental) Modify existing data model.

 Details
void changeRefKey(oldRefKey, newRefKey)

[ext-clones] Replace a refKey with a new one.

 Details
void clear()

Remove all nodes.

 Details
void clearFilter()

[ext-filter] Reset the filter.

 Details
void clearPersistData()

[ext-persist] Remove persistence data of the given type(s).
Called like
$.ui.fancytree.getTree("#tree").clearCookies("active expanded focus selected");

 Details
integer count()

Return the number of nodes.

 Details
void debug(msg)

Write to browser console if debugLevel >= 4 (prepending tree name)

 Details
void debugTime(label)

Call console.time() when in debug mode (verbose >= 4).

 Details
void debugTimeEnd(label)

Call console.timeEnd() when in debug mode (verbose >= 4).

 Details
void destroy()

Destroy this widget, restore previous markup and cleanup resources.

 Details
void enable(flag=true)

Enable (or disable) the tree control.

 Details
boolean enableUpdate(flag)

Temporarily suppress rendering to improve performance on bulk-updates.

 Details
void error(msg)

Write error to browser console if debugLevel >= 1 (prepending tree info)

 Details
void expandAll(flag=true, opts)

Expand (or collapse) all parent nodes.

This convenience method uses tree.visit() and tree.setExpanded()
internally.

 Details
integer filterBranches(filter, opts={autoExpand: false})

[ext-filter] Dimm or hide whole branches.

 Details
integer filterNodes(filter, opts={autoExpand: false, leavesOnly: false})

[ext-filter] Dimm or hide nodes.

 Details
Array. findAll(match)

Find all nodes that matches condition.

 Details
FancytreeNode findFirst(match)

Find first node that matches condition.

 Details
FancytreeNode findNextNode(match, startNode)

Find the next visible node that starts with match, starting at startNode
and wrap-around at the end.

 Details
FancytreeNode | null findRelatedNode(node, where, includeHidden=false)

Find a node relative to another node.

 Details
void generateFormElements(selected=true, active=true, opts)

Generate INPUT elements that can be submitted with html forms.

In selectMode 3 only the topmost selected nodes are considered, unless
opts.stopOnParents: false is passed.

 Details
FancytreeNode getActiveNode()

Return the currently active node or null.

 Details
FancytreeNode | null getFirstChild()

Return the first top level node if any (not the invisible root node).

 Details
FancytreeNode getFocusNode()

Return node that has keyboard focus or null.

 Details
FancytreeNode | null getNodeByKey(key, searchRoot)

Return node with a given key or null if not found.

 Details
Array. | null getNodesByRef(refKey, rootNode)

[ext-clones] Return all nodes with a given refKey (null if not found).

 Details
any getOption(name)

Return current option value.
(Note: this is the preferred variant of $().fancytree("option", "KEY"))

 Details
void getPersistData()

[ext-persist] Return persistence information from cookies

Called like
$.ui.fancytree.getTree("#tree").getPersistData();

 Details
FancytreeNode getRootNode()

Return the invisible system root node.

 Details
Array. getSelectedNodes(stopOnParents=false)

Return an array of selected nodes.

Note: you cannot send this result via Ajax directly. Instead the
node object need to be converted to plain objects, for example
by using $.map() and node.toDict().

 Details
boolean hasFocus()

Return true if the tree control has keyboard focus

 Details
void info(msg)

Write to browser console if debugLevel >= 3 (prepending tree name)

 Details
FancytreeNode | null isEditing()

[ext-edit] Check if any node in this tree in edit mode.

 Details
Boolean isFilterActive()

[ext-filter] Return true if a filter is currently applied.

 Details
boolean isLoading()

Return true if any node is currently beeing loaded, i.e. a Ajax request is pending.

 Details
void isViewportBottom()

[ext-grid] Return true if viewport cannot be scrolled down any further.

 Details
$.Promise loadKeyPath(keyPathList, optsOrCallback)

Make sure that a node with a given ID is loaded, by traversing - and
loading - its parents. This method is meant for lazy hierarchies.
A callback is executed for every node as we go.

 Details
void reactivate(setFocus=false)

Re-fire beforeActivate, activate, and (optional) focus events.
Calling this method in the init event, will activate the node that
was marked 'active' in the source data, and optionally set the keyboard
focus.

 Details
void redrawViewport(force=false)

[ext-grid] Render all visible nodes into the viweport.

 Details
$.Promise reload(source)

Reload tree from source and return a promise.

 Details
void render(force=false, deep=false)

Render tree (i.e. create DOM elements for all top-level nodes).

 Details
void selectAll(flag=true)

(De)select all nodes.

 Details
void setFocus(flag=true) Details
void setOption(name, new)

Set current option value.
(Note: this is the preferred variant of $().fancytree("option", "KEY", VALUE))

 Details
void setViewport(options)

[ext-grid] Define a subset of rows/columns to display and redraw.

 Details
Array | object toDict(includeRoot=false, callback)

Return all nodes as nested list of NodeData.

 Details
integer updateFilter()

[ext-filter] Re-apply current filter.

 Details
boolean visit(fn)

Call fn(node) for all nodes in hierarchical order (depth-first).

 Details
boolean visitRows(fn, options)

Call fn(node) for all nodes in vertical order, top down (or bottom up).

Stop iteration, if fn() returns false.

Return false if iteration was stopped.

 Details
void warn(msg)

Write warning to browser console if debugLevel >= 2 (prepending tree info)

 Details

Method Details

activateCell($tdopt, orgEventopt)

[ext-ariagrid] Set active cell and activate cell-nav or cell-edit mode if needed.
Pass $td=null to enter row-mode.

See also FancytreeNode#setActive(flag, {cell: idx})

Parameters:
Name Type Attributes Default Description
$td jQuery | Element | integer <optional>
orgEvent Event | null <optional>
 null
Since:
  • 2.23
Source:
Requires:
  • module:jquery.fancytree.ariagrid.js

activateKey(key, optsopt) → {FancytreeNode}

Activate node with a given key and fire focus and activate events.

A previously activated node will be deactivated.
If activeVisible option is set, all parents will be expanded as necessary.
Pass key = false, to deactivate the current node only.

Parameters:
Name Type Attributes Description
key string
opts object <optional>

additional options. Defaults to {noEvents: false, noFocus: false}
Source:
Returns:

activated node (null, if not found)

Type
FancytreeNode

addPagingNode(node, modeopt)

(experimental) Add child status nodes that indicate 'More...', ....

Parameters:
Name Type Attributes Default Description
node boolean | object

optional node definition. Pass false to remove all paging nodes.
mode string <optional>
 'append'

'child'|firstChild'
Since:
  • 2.15
Source:

adjustViewportSize()

[ext-grid] Calculate the viewport count from current scroll wrapper height.

Source:
Requires:
  • module:jquery.fancytree.grid.js

applyCommand(cmd, nodeopt, optsopt)

(experimental) Apply a modification (or navigation) operation.

Valid commands:

  • 'moveUp', 'moveDown'
  • 'indent', 'outdent'
  • 'remove'
  • 'edit', 'addChild', 'addSibling': (reqires ext-edit extension)
  • 'cut', 'copy', 'paste': (use an internal singleton 'clipboard')
  • 'down', 'first', 'last', 'left', 'parent', 'right', 'up': navigate
Parameters:
Name Type Attributes Default Description
cmd string
node FancytreeNode <optional>
 active_node
opts object <optional>

Currently unused
Since:
  • 2.32
Source:

applyPatch(patchList) → {$.Promise}

(experimental) Modify existing data model.

Parameters:
Name Type Description
patchList Array

array of [key, NodePatch] arrays
Source:
See:
Returns:

resolved, when all patches have been applied

Type
$.Promise

changeRefKey(oldRefKey, newRefKey)

[ext-clones] Replace a refKey with a new one.

Parameters:
Name Type Description
oldRefKey string
newRefKey string
Source:
Requires:
  • module:jquery.fancytree.clones.js

clear()

Remove all nodes.

Since:
  • 2.14
Source:

clearFilter()

[ext-filter] Reset the filter.

Source:
Requires:
  • module:jquery.fancytree.filter.js

clearPersistData()

[ext-persist] Remove persistence data of the given type(s).
Called like
$.ui.fancytree.getTree("#tree").clearCookies("active expanded focus selected");

Source:
Requires:
  • module:jquery.fancytree.persist.js

count() → {integer}

Return the number of nodes.

Source:
Returns:
Type
integer

debug(msg)

Write to browser console if debugLevel >= 4 (prepending tree name)

Parameters:
Name Type Description
msg *

string or object or array of such
Source:

debugTime(label)

Call console.time() when in debug mode (verbose >= 4).

Parameters:
Name Type Description
label string
Source:

debugTimeEnd(label)

Call console.timeEnd() when in debug mode (verbose >= 4).

Parameters:
Name Type Description
label string
Source:

destroy()

Destroy this widget, restore previous markup and cleanup resources.

Since:
  • 2.34
Source:

enable(flagopt)

Enable (or disable) the tree control.

Parameters:
Name Type Attributes Default Description
flag boolean <optional>
 true

pass false to disable
Since:
  • 2.30
Source:

enableUpdate(flag) → {boolean}

Temporarily suppress rendering to improve performance on bulk-updates.

Parameters:
Name Type Description
flag boolean
Since:
  • 2.19
Source:
Returns:

previous status

Type
boolean

error(msg)

Write error to browser console if debugLevel >= 1 (prepending tree info)

Parameters:
Name Type Description
msg *

string or object or array of such
Source:

expandAll(flagopt, optsopt)

Expand (or collapse) all parent nodes.

This convenience method uses tree.visit() and tree.setExpanded()
internally.

Parameters:
Name Type Attributes Default Description
flag boolean <optional>
 true

pass false to collapse
opts object <optional>

passed to setExpanded()
Since:
  • 2.30
Source:

filterBranches(filter, optsopt) → {integer}

[ext-filter] Dimm or hide whole branches.

Parameters:
Name Type Attributes Default Description
filter function | string
opts boolean <optional>
 {autoExpand: false}
Source:
Requires:
  • module:jquery.fancytree.filter.js
Returns:

count

Type
integer

filterNodes(filter, optsopt) → {integer}

[ext-filter] Dimm or hide nodes.

Parameters:
Name Type Attributes Default Description
filter function | string
opts boolean <optional>
 {autoExpand: false, leavesOnly: false}
Source:
Requires:
  • module:jquery.fancytree.filter.js
Returns:

count

Type
integer

findAll(match) → {Array.<FancytreeNode>}

Find all nodes that matches condition.

Parameters:
Name Type Description
match string | function

title string to search for, or a
callback function that returns true if a node is matched.
Since:
  • 2.12
Source:
See:
Returns:

array of nodes (may be empty)

Type
Array.<FancytreeNode>

findFirst(match) → {FancytreeNode}

Find first node that matches condition.

Parameters:
Name Type Description
match string | function

title string to search for, or a
callback function that returns true if a node is matched.
Since:
  • 2.12
Source:
See:
Returns:

matching node or null

Type
FancytreeNode

findNextNode(match, startNodeopt) → {FancytreeNode}

Find the next visible node that starts with match, starting at startNode
and wrap-around at the end.

Parameters:
Name Type Attributes Description
match string | function
startNode FancytreeNode <optional>

defaults to first node
Source:
Returns:

matching node or null

Type
FancytreeNode

findRelatedNode(node, where, includeHiddenopt) → {FancytreeNode|null}

Find a node relative to another node.

Parameters:
Name Type Attributes Default Description
node FancytreeNode
where string | number

'down', 'first', 'last', 'left', 'parent', 'right', or 'up'.
(Alternatively the keyCode that would normally trigger this move,
e.g. $.ui.keyCode.LEFT = 'left'.
includeHidden boolean <optional>
 false

Not yet implemented
Since:
  • v2.31
Source:
Returns:
Type
FancytreeNode | null

generateFormElements(selectedopt, activeopt, optsopt)

Generate INPUT elements that can be submitted with html forms.

In selectMode 3 only the topmost selected nodes are considered, unless
opts.stopOnParents: false is passed.

Parameters:
Name Type Attributes Default Description
selected boolean | string <optional>
 true

Pass false to disable, pass a string to override the field name (default: 'ft_ID[]')
active boolean | string <optional>
 true

Pass false to disable, pass a string to override the field name (default: 'ft_ID_active')
opts object <optional>

default { filter: null, stopOnParents: true }
Source:
Example
// Generate input elements for active and selected nodes
tree.generateFormElements();
// Generate input elements selected nodes, using a custom `name` attribute
tree.generateFormElements("cust_sel", false);
// Generate input elements using a custom filter
tree.generateFormElements(true, true, { filter: function(node) {
    return node.isSelected() && node.data.yes;
}});

getActiveNode() → {FancytreeNode}

Return the currently active node or null.

Source:
Returns:
Type
FancytreeNode

getFirstChild() → {FancytreeNode|null}

Return the first top level node if any (not the invisible root node).

Source:
Returns:
Type
FancytreeNode | null

getFocusNode() → {FancytreeNode}

Return node that has keyboard focus or null.

Source:
Returns:
Type
FancytreeNode

getNodeByKey(key, searchRootopt) → {FancytreeNode|null}

Return node with a given key or null if not found.

Parameters:
Name Type Attributes Description
key string
searchRoot FancytreeNode <optional>

only search below this node
Source:
Returns:
Type
FancytreeNode | null

getNodesByRef(refKey, rootNodeopt) → {Array.<FancytreeNode>|null}

[ext-clones] Return all nodes with a given refKey (null if not found).

Parameters:
Name Type Attributes Description
refKey string
rootNode FancytreeNode <optional>

optionally restrict results to descendants of this node
Source:
Requires:
  • module:jquery.fancytree.clones.js
Returns:
Type
Array.<FancytreeNode> | null

getOption(name) → {any}

Return current option value.
(Note: this is the preferred variant of $().fancytree("option", "KEY"))

Parameters:
Name Type Description
name string

option name (may contain '.')
Source:
Returns:
Type
any

getPersistData()

[ext-persist] Return persistence information from cookies

Called like
$.ui.fancytree.getTree("#tree").getPersistData();

Source:
Requires:
  • module:jquery.fancytree.persist.js

getRootNode() → {FancytreeNode}

Return the invisible system root node.

Source:
Returns:
Type
FancytreeNode

getSelectedNodes(stopOnParentsopt) → {Array.<FancytreeNode>}

Return an array of selected nodes.

Note: you cannot send this result via Ajax directly. Instead the
node object need to be converted to plain objects, for example
by using $.map() and node.toDict().

Parameters:
Name Type Attributes Default Description
stopOnParents boolean <optional>
 false

only return the topmost selected
node (useful with selectMode 3)
Source:
Returns:
Type
Array.<FancytreeNode>

hasFocus() → {boolean}

Return true if the tree control has keyboard focus

Source:
Returns:
Type
boolean

info(msg)

Write to browser console if debugLevel >= 3 (prepending tree name)

Parameters:
Name Type Description
msg *

string or object or array of such
Source:

isEditing() → {FancytreeNode|null}

[ext-edit] Check if any node in this tree in edit mode.

Source:
Requires:
  • module:jquery.fancytree.edit.js
Returns:
Type
FancytreeNode | null

isFilterActive() → {Boolean}

[ext-filter] Return true if a filter is currently applied.

Since:
  • 2.13
Source:
Requires:
  • module:jquery.fancytree.filter.js
Returns:
Type
Boolean

isLoading() → {boolean}

Return true if any node is currently beeing loaded, i.e. a Ajax request is pending.

Since:
  • 2.32
Source:
Returns:
Type
boolean

isViewportBottom()

[ext-grid] Return true if viewport cannot be scrolled down any further.

Source:
Requires:
  • module:jquery.fancytree.grid.js

loadKeyPath(keyPathList, optsOrCallback) → {$.Promise}

Make sure that a node with a given ID is loaded, by traversing - and
loading - its parents. This method is meant for lazy hierarchies.
A callback is executed for every node as we go.

Parameters:
Name Type Description
keyPathList string | Array.<string>

one or more key paths (e.g. '/3/2_1/7')
optsOrCallback function | object

callback(node, status) is called for every visited node ('loading', 'loaded', 'ok', 'error').
Pass an object to define custom key matchers for the path segments: {callback: function, matchKey: function}.
Source:
Returns:
Type
$.Promise
Example
// Resolve using node.key:
tree.loadKeyPath("/_3/_23/_26/_27", function(node, status){
  if(status === "loaded") {
    console.log("loaded intermediate node " + node);
  }else if(status === "ok") {
    node.activate();
  }
});
// Use deferred promise:
tree.loadKeyPath("/_3/_23/_26/_27").progress(function(data){
  if(data.status === "loaded") {
    console.log("loaded intermediate node " + data.node);
  }else if(data.status === "ok") {
    node.activate();
  }
}).done(function(){
   ...
});
// Custom path segment resolver:
tree.loadKeyPath("/321/431/21/2", {
  matchKey: function(node, key){
    return node.data.refKey === key;
  },
  callback: function(node, status){
    if(status === "loaded") {
      console.log("loaded intermediate node " + node);
    }else if(status === "ok") {
      node.activate();
    }
  }
});

reactivate(setFocusopt)

Re-fire beforeActivate, activate, and (optional) focus events.
Calling this method in the init event, will activate the node that
was marked 'active' in the source data, and optionally set the keyboard
focus.

Parameters:
Name Type Attributes Default Description
setFocus <optional>
 false
Source:

redrawViewport(forceopt)

[ext-grid] Render all visible nodes into the viweport.

Parameters:
Name Type Attributes Default Description
force bool <optional>
 false
Source:
Requires:
  • module:jquery.fancytree.grid.js

reload(sourceopt) → {$.Promise}

Reload tree from source and return a promise.

Parameters:
Name Type Attributes Description
source <optional>

optional new source (defaults to initial source data)
Source:
Returns:
Type
$.Promise

render(forceopt, deepopt)

Render tree (i.e. create DOM elements for all top-level nodes).

Parameters:
Name Type Attributes Default Description
force boolean <optional>
 false

create DOM elemnts, even if parent is collapsed
deep boolean <optional>
 false
Source:

selectAll(flagopt)

(De)select all nodes.

Parameters:
Name Type Attributes Default Description
flag boolean <optional>
 true
Since:
  • 2.28
Source:

setFocus(flagopt)

Parameters:
Name Type Attributes Default Description
flag boolean <optional>
 true
Source:

setOption(name, new)

Set current option value.
(Note: this is the preferred variant of $().fancytree("option", "KEY", VALUE))

Parameters:
Name Type Description
name string

option name (may contain '.')
new any

value
Source:

setViewport(options)

[ext-grid] Define a subset of rows/columns to display and redraw.

Parameters:
Name Type Description
options object | boolean

viewport boundaries and status.
Source:
Requires:
  • module:jquery.fancytree.grid.js

toDict(includeRootopt, callbackopt) → {Array|object}

Return all nodes as nested list of NodeData.

Parameters:
Name Type Attributes Default Description
includeRoot boolean <optional>
 false

Returns the hidden system root node (and its children)
callback function <optional>

callback(dict, node) is called for every node, in order to allow modifications.
Return false to ignore this node or "skip" to include this node without its children.
Source:
See:
Returns:
Type
Array | object

updateFilter() → {integer}

[ext-filter] Re-apply current filter.

Since:
  • 2.38
Source:
Requires:
  • module:jquery.fancytree.filter.js
Returns:

count

Type
integer

visit(fn) → {boolean}

Call fn(node) for all nodes in hierarchical order (depth-first).

Parameters:
Name Type Description
fn function

the callback function.
Return false to stop iteration, return "skip" to skip this node and children only.
Source:
Returns:

false, if the iterator was stopped.

Type
boolean

visitRows(fn, optionsopt) → {boolean}

Call fn(node) for all nodes in vertical order, top down (or bottom up).

Stop iteration, if fn() returns false.

Return false if iteration was stopped.

Parameters:
Name Type Attributes Description
fn function

the callback function.
Return false to stop iteration, return "skip" to skip this node and children only.
options object <optional>

Defaults:
{start: First top node, reverse: false, includeSelf: true, includeHidden: false}
Since:
  • 2.28
Source:
Returns:

false if iteration was cancelled

Type
boolean

warn(msg)

Write warning to browser console if debugLevel >= 2 (prepending tree info)

Parameters:
Name Type Description
msg *

string or object or array of such
Source:

Fork me on GitHub