Tree

Override defaults with $.fn.tree.defaults.

The tree displays hierarchical data in a tree structure in a web page. It provides users expand, collapse, drag and drop, editing and async loading functionality.

Dependencies

  • draggable
  • droppable

Usage Example

Tree can be definded in <ul> element. The markup can defines leaf and children. The nodes will be <li> elements within ul list. The following shows the elements that will be used to make the tree node nested within the ul elements.

Tree can also be defined in an empty <ul> element and load data using javascript.

Use loadFilter to process the json data from ASP.NET web services.

Tree Data Format

Every node can contains following properties:

  • id: node id, which is important to load remote data
  • text: node text to show
  • state: node state, 'open' or 'closed', default is 'open'. When set to 'closed', the node have children nodes and will load them from remote site
  • checked: Indicate whether the node is checked selected.
  • attributes: custom attributes can be added to a node
  • children: an array nodes defines some children nodes

Some example:

The Async Tree

The tree supports the built-in async loading mode, with which users create an empty tree, then specify a server side that dynamically returns the JSON data to use to populate the tree with asynchronously and on demand. Here is an example:

The tree is loaded with the URL 'get_data.php'. The child nodes to be loaded dependent on the parent node state. When expand a closed node, if the node has no child nodes loaded, it will send node id value as the http request parameter named 'id' to server via the URL defined above to retrieve child nodes.

Looks at the data returned from server:

The node 1 and node 2 are closed, when expand the node 1, it will directly show its child nodes. When expand node 2, it will send the value(2) to server to retrieve child nodes.

This tutorial Create Async Tree shows how to write server code to return the tree data on demand.

Properties

Name Type Description Default
url string a URL to retrieve remote data. null
method string The http method to retrieve data. post
animate boolean Defines if to show animation effect when node expand or collapse. false
checkbox boolean,function Defines if to show the checkbox before every node. If a function is specified, return true to show the checkbox.

Code example:

$('#tt').tree({
	checkbox:function(node){
		if (node.id == 11 || node.id == 122){
			return true;
		}
	}
})
false
cascadeCheck boolean Defines if to cascade check. true
onlyLeafCheck boolean Defines if to show the checkbox only before leaf node. false
lines boolean Defines if to show lines between tree nodes. false
dnd boolean Defines if to enable drag and drop. false
data array The node data to be loaded. 
$('#tt').tree({
	data: [{
		text: 'Item1',
		state: 'closed',
		children: [{
			text: 'Item11'
		},{
			text: 'Item12'
		}]
	},{
		text: 'Item2'
	}]
});
null
queryParams object The additional parameters that will be sent to server when requesting remote data. Available since version 1.4. {}
formatter function(node) Defines how to render the node's text.

Code example:

$('#tt').tree({
	formatter:function(node){
		return node.text;
	}
});
filter function(q,node) Defines how to filter the local tree data, return true to allow the node to be displayed. Available since version 1.4.2.

Code example:

$('#tt').tree({
	filter: function(q, node){
		return node.text.toLowerCase().indexOf(q.toLowerCase()) >= 0;
	}
})
loader function(param,success,error) Defines how to load data from remote server. Return false can abort this action. This function takes the following parameters:
param: the parameter object to pass to remote server.
success(data): the callback function that will be called when retrieve data successfully.
error(): the callback function that will be called when failed to retrieve data. 		json loader
loadFilter function(data,parent) Return the filtered data to display. The returned data is in standard tree format. This function takes the following parameters:
data: the original data to be loaded.
parent: DOM object, indicate the parent node.

Events

Many events callback function can take the 'node' parameter, which contains following properties:

  • id: An identity value bind to the node.
  • text: Text to be showed.
  • iconCls: The css class to display icon.
  • checked: Whether the node is checked.
  • state: The node state, 'open' or 'closed'.
  • attributes: Custom attributes bind to the node.
  • target: Target DOM object.
Name Parameters Description
onClick node Fires when user click a node. Code example: 
$('#tt').tree({
	onClick: function(node){
		alert(node.text);  // alert node text property when clicked
	}
});
onDblClick node Fires when user dblclick a node.
onBeforeLoad node, param Fires before a request is made to load data, return false to cancel this load action.
onLoadSuccess node, data Fires when data loaded successfully.
onLoadError arguments Fires when data loaded fail, the arguments parameter is same as the 'error' function of jQuery.ajax.
onBeforeExpand node Fires before node is expanded, return false to cancel this expand action.
onExpand node Fires when node is expanded.
onBeforeCollapse node Fires before node is collapsed, return false to cancel this collapse action.
onCollapse node Fires when node is collapsed.
onBeforeCheck node, checked Fires before users click the checkbox, return false to cancel this check action. Available since version 1.3.1.
onCheck node, checked Fires when users click the checkbox.
onBeforeSelect node Fires before node is selected, return false to cancel this select action.
onSelect node Fires when node is selected.
onContextMenu e, node Fires when node is right clicked. Code example: 
// right click node and then display the context menu
$('#tt').tree({
	onContextMenu: function(e, node){
		e.preventDefault();
		// select the node
		$('#tt').tree('select', node.target);
		// display context menu
		$('#mm').menu('show', {
			left: e.pageX,
			top: e.pageY
		});
	}
});

// the context menu is defined as below:
<div id="mm" class="easyui-menu" style="width:120px;">
	<div onclick="append()" data-options="iconCls:'icon-add'">Append</div>
	<div onclick="remove()" data-options="iconCls:'icon-remove'">Remove</div>
</div>
onBeforeDrag node Fires when a node's dragging starts, return false to deny drag. Available since version 1.3.2.
onStartDrag node Fires when start dragging a node. Available since version 1.3.2.
onStopDrag node Fires after stop dragging a node. Available since version 1.3.2.
onDragEnter target, source Fires when a node is dragged enter some target node that can be dropped to. return false to deny drop.
target: the target node element to be dropped.
source: the source node being dragged.
Available since version 1.3.2.
onDragOver target, source Fires when a node is dragged over some target node that can be dropped to, return false to deny drop.
target: the target node element to be dropped.
source: the source node being dragged.
Available since version 1.3.2.
onDragLeave target, source Fires when a node is dragged leave some target node that can be dropped to.
target: the target node element to be dropped.
source: the source node being dragged.
Available since version 1.3.2.
onBeforeDrop target,source,point Fires before a node is dropped, return false to deny drop.
target: DOM object, The node being targeted for the drop.
source: the source node.
point: indicate the drop operation, posible values are: 'append','top' or 'bottom'.
Available since version 1.3.3.
onDrop target,source,point Fires when a node is dropped.
target: DOM object, The node being targeted for the drop.
source: the source node.
point: indicate the drop operation, posible values are: 'append','top' or 'bottom'.
onBeforeEdit node Fires before edit node.
onAfterEdit node Fires after edit node.
onCancelEdit node Fires when cancel the editing action.

Methods

Name Parameter Description
options none Return the options of tree.
loadData data Load the tree data.
getNode target get the specified node object.
getData target get the specified node data, including its children.
reload target Reload tree data.
getRoot none Get the root node, return node object
getRoots none Get the root nodes, return node array.
getParent target Get the parent node, the target parameter indicate the node DOM object.
getChildren target Get the children nodes, the target parameter indicate the node DOM object.
getChecked state Get the checked nodes. The state available values are: 'checked','unchecked','indeterminate'. If the state is not assigned, return the 'checked' nodes.

Code example:

var nodes = $('#tt').tree('getChecked');	// get checked nodes
var nodes = $('#tt').tree('getChecked', 'unchecked');	// get unchecked nodes
var nodes = $('#tt').tree('getChecked', 'indeterminate');	// get indeterminate nodes
var nodes = $('#tt').tree('getChecked', ['checked','indeterminate']);	// get checked and indeterminate nodes
getSelected none Get the selected node and return it, if no node selected return null.
isLeaf target Determine the specified node is leaf, the target parameter indicate the node DOM object.
find param Find the specifed node and return the node object. Code example: 
// find a node by id and then select it
var node = $('#tt').tree('find', 12);
$('#tt').tree('select', node.target);
// find a node by 'text' property
var node = $('#tt').tree('find', {text:'node1'});
// find the menu item by customized definitions
var node = $('#tt').tree('find', function(node){
	if (node.text == 'text1'){
		return true;
	} else if (node.age > 12){
		return true;
	} else {
		return false;
	}
})
findBy param Find the specifed node by field. Available since version 1.7.0. 
var node = $('#tt').tree('findBy', {
	field: 'text',
	value: 'text1'
})
select target Select a node, the target parameter indicate the node DOM object.
check target Set the specified node to checked.
uncheck target Set the specified node to unchecked.
collapse target Collapse a node, the target parameter indicate the node DOM object.
expand target Expand a node, the target parameter indicate the node DOM object. When node is closed and has no child nodes, the node id value(named as 'id' parameter) will be sent to server to request child nodes data.
collapseAll target Collapse all nodes.
expandAll target Expand all nodes.
expandTo target Expand from root to specified node.
scrollTo target Scroll to the specified node. Available since version 1.3.4.
append param Append some children nodes to a parent node. param parameter has two properties:
parent: DOM object, the parent node to append to, if not assigned, append as root nodes.
data: array, the nodes data. Code example: 
// append some nodes to the selected node
var selected = $('#tt').tree('getSelected');
$('#tt').tree('append', {
	parent: selected.target,
	data: [{
		id: 23,
		text: 'node23'
	},{
		text: 'node24',
		state: 'closed',
		children: [{
			text: 'node241'
		},{
			text: 'node242'
		}]
	}]
});
toggle target Toggles expanded/collapsed state of the node, the target parameter indicate the node DOM object.
insert param Insert a node to before or after specified node. the 'param' parameter contains following properties:
before: DOM object, the node to insert before.
after: DOM object, the node to insert after.
data: object, the node data.

The code below shows how to insert a new node before the selected node:

var node = $('#tt').tree('getSelected');
if (node){
	$('#tt').tree('insert', {
		before: node.target,
		data: {
			id: 21,
			text: 'node text'
		}
	});
}
remove target Remove a node and it's children nodes, the target parameter indicate the node DOM object.
pop target Pop a node and it's children nodes, the method is same as remove but return the removed node data.
update param Update the specified node. The 'param' parameter has following properties:
target(DOM object, the node to be updated),id,text,iconCls,checked,etc.

Code example:

// update the selected node text
var node = $('#tt').tree('getSelected');
if (node){
	$('#tt').tree('update', {
		target: node.target,
		text: 'new text'
	});
}
enableDnd none Enable drag and drop feature.
disableDnd none Disable drag and drop feature.
beginEdit target Begin editing a node.
endEdit target End editing a node.
cancelEdit target Cancel editing a node.
doFilter text Do the filter action. Available since version 1.4.2.

Code example:

$('#tt').tree('doFilter', 'easyui');
$('#tt').tree('doFilter', '');	// clear the filter

Copyright © 2010-2025 www.jeasyui.com