User Guide

Tree Overview

Present items in a hierarchical tree structure with the wijtree widget. The wijtree widget control supports expand/collapse animations, stylish themes, and drag-and-drop functionality. You can initialize an undordered list (UL) element or an ordered list (OL) element to create the treeview.

The image below illustrates the main elements of the wijtree widget:

For a full overview of tree's and treenode's markup and scripting, see #Wijtree Full Markup and Scripting.

NOTE: This documentation pertains to the latest Wijmo release. Please check the Version Histories for an outline of new features, improvements, and changes to the Wijmo widgets.

TreeNode Overview

The wijtreenode is an internal widget representing the children of a wijtree widget. The HTML elements to create nodes will be LI elements within either an ordered (OL) or an unordered (UL) list. The following shows the elements that will be used to make the treenode nested within the UL elements:

<ul id="tree">
    <li><a>Tree Node 1</a></li>
    <li><a>Tree Node 2</a></li>
 </ul>

For a full overview of tree and treenode's markup and scripting, see #Wijtree Full Markup and Scripting.

Markup and Scripting

The markup used to create the wijtree widget should resemble the following:

  <ul id="tree">    
    <li><a>Tree Node 1</a></li>    
    <li><a>Tree Node 2</a>
    <ul>
        <li><a>Tree Node 2a</a></li>
        <li><a>Tree Node 2b</a></li>
    </ul>
 </li> 
 </ul>

The following jQuery script will initialize the wijtree:


<script id="scriptInit" type="text/javascript">
        $(document).ready(function () {
            $("#tree").wijtree();
            });
</script>

When you run the the project, you'll have a wijtree widget with two second-level nodes:

Tree Node 1
Tree Node 2
- Tree Node 2a
- Tree Node 2b

Quick Start

In this quick start, you'll learn how to add the TreeView widget to an HTML project and how to customize the widget.

Create an .html page and add links to the dependencies to your project. To do this, just link to the content delivery network (CDN) file for each project:

<!--jQuery References-->
<script src="http://code.jquery.com/jquery-1.9.1.min.js" type="text/javascript"></script>
<script src="http://code.jquery.com/ui/1.10.1/jquery-ui.min.js" type="text/javascript"></script>
 
<!--Theme-->
<link href="http://cdn.wijmo.com/themes/aristo/jquery-wijmo.css" rel="stylesheet" type="text/css" />
 
<!--Wijmo Widgets CSS-->
<link href="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.css" rel="stylesheet" type="text/css" />
 
<!--Wijmo Widgets JavaScript-->
<script src="http://cdn.wijmo.com/jquery.wijmo-open.all.3.20131.1.min.js" type="text/javascript"></script>
<script src="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.js" type="text/javascript"></script>

You can reference the latest dependencies from the CDN at http://wijmo.com/downloads/#wijmo-cdn.

Place the following markup within the body of the .html document:

<ul id="tree">
 	<li><a>Tree Node 1</a>
 	    <ul>
 		<li><a>Tree Node 1a</a></li>
              <li><a>Tree Node 1b</a></li>
          </ul>
 	</li>    
 	<li><a>Tree Node 2</a></li>
 </ul>

To initialize the widget, you need to add some jQuery script under the dependencies and within the <head> tags:

<script id="scriptInit" type="text/javascript">
       $(document).ready(function () {
           $("#tree").wijtree();
       });
    </script>

If you run your application now, the wijtreeview widget will resemble the following image:

How To

You can easily change the appearance of the TreeView widget using CSS styling and jQuery options.

Add Check Boxes

You can add check boxes to the nodes by editing your script to resemble the following:

<script id="scriptInit" type="text/javascript">
       $(document).ready(function () {
           $("#tree").wijtree({
                showCheckBoxes: true
           });
       });
    </script>

This script will create a widget that resembles the following image:

Use CSS Styling

You can also change the appearance properties using CSS styling. Just add a set of <style> tags below your jQuery script:

<style type="text/css">

</style>

Within these tags, you can set any of the CSS selectors available in the | C1TreeView CSS Selectors topic.

As an example, we'll set some of the selectors:

<style type="text/css">
    .wijmo-wijtree
      {
          background-color: #B0DB74;
          color: #5788AB;         
      }
      .wijmo-wijtree-child
      {
          color: #D69FBF;
      }
      .wijmo-wijtree-parent
      {
          color: #2371B0;
      }
      
</style>

The above CSS styling will create an application that resembles the following image:

Now you can set up a Wijmo application, add the appropriate HTML markup and script to your application to create and call your widget, and change the appearance of your widget using both jQuery script and CSS styling.

Concepts

Adaptive for Mobile Use

This widget is an adaptive widget in v3. If you are running v2.3.x, it is not adaptive. You can download v3 2013 1 here: Downloads Page.

An adaptive widget is different from a jQuery UI widget in that you can use it in both mobile and non-mobile web applications. To use it in non-mobile applications, just use the regular help. To use it in mobile applications:

Use jQuery Mobile instead of jQuery UI references
Do not initialize the widget in script (unless you need to for complex widgets like charts)
Use the data-role attribute to create the widget in markup

These steps are demonstrated in the Adaptive Widgets for jQuery Mobile topic.

Tree API

Options

The following options are available for the wijtree widget:

autoCheckNodes

The autoCheckNodes option allows the sub-nodes to be checked when the parent nodes are checked. To use this option, showCheckboxes must be set to "true." You can see the wijtree widget with autoCheckNodes set to "true" in the following image:

Type: Boolean

Default: true

Code Example:

//Set autoCheckNodes and showCheckBoxes to "true."
 $("#tree").wijtree({  
	autoCheckNodes: true,  
    showCheckBoxes: true  
});

autoCollapse

When the autoCollapse option is set to true, the expanded node will be collapsed when another node is expanded.

Type: Boolean

Default: false

Code Example:

$("#tree").wijtree({
      autoCollapse: false,
   });

allowDrag

When the allowDrag option is set to true, the tree nodes can be dragged.

Type: Boolean

Default: false

Code Example:

$("#tree").wijtree({
     autoDrag: false,
   });

allowDrop

When allowDrop is set to true, one tree node can be dropped within another tree node.

Type: Boolean

Default:false

Code Example:

$("#tree").wijtree({
     allowDrop: false,
   });

allowEdit

The allowEdit option allows a user to edit the tree nodes at run time. The following image shows this option in use:

Type: Boolean

Default: false

Code Example:

$("#tree").wijtree({
     allowEdit: true
});

allowSorting

The allowSorting option allows the tree nodes to be sorted at run time when the user presses the "s" key.

Type: Boolean

Default: true

Code Example:

 
$("#tree").wijtree({
	allowSorting: true,
  });

allowTriState

The allowTriState option allows the tree nodes to exhibit triState behavior. This lets the node checkboxes be checked, unchecked, or indeterminate. This option must be used with the showCheckBoxes option. You can see this behavior in the following image:

Type: Boolean

Default:true

Code Example:

$("#tree").wijtree({
    showCheckBoxes: true,
    allowTriState: true
});

collapseAnimation

The collapseAnimation option determines the animation effect, easing, and duration for hiding child nodes when the parent node is collapsed.

Type: Object

Default: null

effect

The animation effect that is used when the wijtree is collapsed. Please see the Animation Effects topic for a list of the available animation effects.

duration

The duration of the animation in milliseconds.

easing

A value that indicates the easing function that will be applied to the animation. For more information, please see the Easing topic.

Code Example:

$("#tree").wijtree({
	collapseAnimation: {
		effect: blind,
		easing: easeOutExpo,
		duration: 200
		}
       });

collapseDelay

This option controls the length of time in milliseconds to delay before the node collapses.

Type: Number

Default:0

Code Example:

 
$("#tree").wijtree({
	collapseDelay: 0
   });

disabled

The disabled option disables or enables the tree. It can be set when initializing the tree. The image below shows how wijtree looks when disabled is set to "true." The project that creates this image uses some CSS styling to change the background color.

Type: Boolean

Default: false

Code Example:

$("#tree").wijtree({
	disabled: true
   });

disabled

If this option is set to true, the select, click, and check operations are disabled too.

Type: Boolean

Default: false

Code Example:

$("#tree").wijtree({
      disabled: true
   });

expandAnimation

The expandAnimation option determines the animation effect, easing, and duration for showing child nodes when the parent node is expanded.

Type: Object

Default: null

effect

The animation effect that is used when the wijtree is expanded. Please see the Animation Effects topic for a list of the available animation effects.

duration

The duration of the animation in milliseconds.

easing

A value that indicates the easing function that will be applied to the animation. For more information, please see the Easing topic.

Code Example:

 $("#tree").wijtree({
	expandAnimation: {
		effect: blind,
		easing: easeOutExpo,
		duration: 200
	}
});

expandCollapseHoverUsed

The expandCollapseHoverUsed option allows the tree to expand or collapse when the mouse hovers over the expand/collapse button. You can see in the following image that the tree expands when the mouse hovers over it:

Type: Boolean

Default: false

Code Example:

$("#tree").wijtree({
	expandCollapseHoverUsed: false
   });

expandDelay

The expandDelay option controls the length of time in milliseconds to delay before the node is expanded.

Type: Number

Default: 0

Code Example:

$("#tree").wijtree({
     expandDelay: 100
   });

showCheckBoxes

The showCheckBoxes option allows the node Check Box to be shown on the tree nodes. The following image shows the wijtree with the showCheckBoxes option set to "true."

Type: Boolean

Default: false

Code Example:

$("#tree").wijtree({
      showCheckBoxes: true,
    });

showExpandCollapse

The showExpandCollapse option determines if the tree is displayed in an expanded or collapsed state. If set to "false," then the wijtree widget will be displayed in the expanded state. The following image shows the wijtree with the showExpandCollapse option set to "false."

Type: Boolean

Default: true

Code Example:

$("#tree").wijtree({
      showExpandCollapse: false,
});

Events

The following events are available for the wijtree widget:

nodeBeforeDropped.wijtree

The nodeBeforeDropped event handler is called before a draggable node is dropped in another position. If the event handler returns false, the drop action will be prevented.

Default: null

Type: Function

Parameters:

data.helper: The current draggable helper element.

data.draggable: The current draggable node.

data.offset: The current absolute position of the draggable helper.

data.position: The current position of the draggable helper.

nodeBlur.wijtree

The nodeBlur event fires when the node loses focus.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The node widget that relates to this event.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ nodeBlur: function (e, data) { } });
// Bind to the event by type: wijtreenodeblur
$("#selector").bind("wijtreenodeblur", function(e, data) { } );

nodeCheckChanged.wijtree

The nodeCheckChanged event fires when a node is checked.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The node widget that relates to this event.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ nodeCheckChanged: function (e, data) { } });
// Bind to the event by type: wijtreenodecheckchanged
$("#selector").bind("wijtreenodecheckchanged", function(e, data) { } );

nodeClick.wijtree

The nodeClick event fires when a tree node is clicked.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The node widget that relates to this event.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ nodeClick: function (e, data) { } });
// Bind to the event by type: wijtreenodeclick
$("#selector").bind("wijtreenodeclick", function(e, data) { } );

nodeCollapsed.wijtree

The nodeCollapsed event fires when a tree node is collapsed.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The node widget that relates to this event.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ nodeCollapsed: function (e, data) { } });
// Bind to the event by type: wijtreenodecollapsed
$("#selector").bind("wijtreenodecollapsed", function(e, data) { } );

nodeCollapsing.wijtree

The nodeCollapsing event fires before a node collapses.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The data that relates to this event.

data.node: The node widget that relates to this event.

data.params: The params that passed from the "params" option of this node.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ nodeCollapsing: function (e, data) { } });
// Bind to the event by type: wijtreenodecollapsing
$("#selector").bind("wijtreenodecollapsing", function(e, data) { } );

nodeDragging.wijtree

The nodeDragging event fires when the mouse is moved during a drag-and-drop operation.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The node widget that relates to this event.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ nodeDragging: function (e, data) { } });
// Bind to the event by type: wijtreenodedragging
$("#selector").bind("wijtreenodedragging", function(e, data) { } );

nodeDragStarted.wijtree

The nodeDragStarted event fires when a user starts to drag a node.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The node widget that relates to this event.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ nodeDragStarted: function (e, data) { } });
// Bind to the event by type: wijtreenodedragstarted
$("#selector").bind("wijtreenodedragstarted", function(e, data) { } );

nodeDropped.wijtree

The nodeDropped event is called when an acceptable draggable node is dropped over to another position.

Default: null

Type: Function

jQuery.Event object parameters:

e - jQuery.Event object; a type of Object.

data - The data that relates to this event; a type of Object.

data.sourceParent: The source parent of current draggable node before it be dragged; a jQuery object.

data.sIndex: The Index of dragged node in source parent.

data.targetParent: The target parent of current draggable node after it is dropped; a jQuery object.

data.tIndex: The Index of a dragged node in the target's parent.

data.draggable: The current draggable node.

data.offset: The current absolute position of the draggable helper.

data.position: The current position of the draggable helper.

Code example:

://Supply a function as an option.
$(".selector").wijtree({ nodeDropped: function (e, data) { } });
//Bind to the event by type: wijtreenodedropped
$("#selector").bind("wijtreenodedropped", function(e, data) { } );

nodeExpanded.wijtree

The nodeExpanded event fires when a tree node is expanded.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The node widget that relates to this event.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ nodeexpanded: function (e, data) { } });
// Bind to the event by type: wijtreenodeExpanded
$("#selector").bind("wijtreenodeexpanded", function(e, data) { } );

nodeExpanding.wijtree

The nodeExpanding event fires before a tree node is expanded.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The Data that relates to this event.

data.node: The node widget that relates to this event.

data.params: The params that passed from the "params" option of this node.

Code Example:

// Supply a function as an option. 
$(".selector").wijtree({nodeExpanding: function (e, data) { } });
// Bind to the event by type: wijtreenodeexpanding
$("#selector").bind("wijtreenodeexpanding ", function(e, data) { } );

nodeMouseOut.wijtree

The nodeMouseOut event fires when the user moves the mouse pointer off of a node.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The node widget that relates to this event.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ nodeMouseOut: function (e, data) { } });
// Bind to the event by type: wijtreenodemouseout
$("#selector").bind("wijtreenodemouseout", function(e, data) { } );

nodeMouseOver.wijtree

The nodeMouseOver event fires when a user places the mouse pointer over a node.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The node widget that relates to this event.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ nodeMouseOver: function (e, data) { } });
// Bind to the event by type: wijtreenodemouseover
$("#selector").bind("wijtreenodemouseover", function(e, data) { } );

nodeTextChanged.wijtree

The nodeTextChanged event fires when the text of a node changes.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The node widget that relates to this event.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ nodeTextChanged: function (e, data) { } });
// Bind to the event by type: wijtreenodetextchanged
$("#selector").bind("wijtreenodetextchanged", function(e, data) { } );

selectedNodeChanged.wijtree

The selectedNodeChanged event fires when the selected node changes.

Default: null

Type: Function

Parameters:

e: The jQuery.Event object.

data: The node widget that relates to this event.

Code Example:

// Supply a function as an option.
$(".selector").wijtree({ selectedNodeChanged: function (e, data) { } });
// Bind to the event by type: wijtreeselectednodechanged
$("#selector").bind("wijtreeselectednodechanged", function(e, data) { } );

Methods

The following methods are available for the wijtree widget:

add

The add method adds a node to the tree widget.

Parameters:

node (string) - HTML markup pointing to the node to add, e.g. <li><a>node</a></li>.

index (number) - Zero-based position indicating where to insert the node.

The index parameter is optional.

Code Example:

$("#tree").wijtree ("add", "node 1", 1 );

destroy

The destroy method will remove the rating functionality completely and will return the element to its pre-init state.

Code Example:

$("selector").wijtree ( "destroy" );

disable

The disable method disables the wijtree.

Code Example:

$("selector").wijtree ( "disable" );

enable

The enable method enables the wijtree.

Code Example:

$("selector").wijtree ( "enable " );

findNodeByText

The findNodeByText method finds a node by the specified node text.

Parameter:

text (string) - The text to find.

Code Example:

$("selector").wijtree ("findNodeByText", text);

getCheckedNodes

The getCheckedNodes method gets the nodes which are checked.

Code Example::

$("selector").wijtree ("getCheckedNodes");

getNodes

The getNodes method gets an array that contains the root nodes of the current tree.

Code Example:

$("selector").wijtree ("getNodes");

getSelectedNodes

The getSelectedNodes method gets the selected nodes.

Code Example:

$("selector").wijtree ("getSelectedNodes");

option

The option method gets or sets any wijtree option. If no value is specified, the method will act as a getter.

Code Example:

$("selector").wijtree ("option" , optionName , [value]);

option

The option method allows multiple wijtree options to be set at the same time be providing an options object.

Code Example:

$("selector").wijtree ("option" , options);

remove

The remove method removes the indicated node from the wijtree element.

Parameter:

node (number) - The zero-based index of the node to remove.

Code Example:

$("selector").wijtree ("remove", 1);

widget

The widget method returns the .wijmo-wijtree element.

Code Example:

$("selector").wijtree ("widget");

TreeNode API

Options

The following options are available for the wijtreenode widget:

checked

The checked option checks the tree node checkbox when it is set to true. It will uncheck the tree node checkbox when set to false.

Type: Boolean

Default: false

Code Example:

 $('.selector’).wijtreenode({checked: false});

collapsedIconClass

The collapsedIconClass option sets the collapsed node icon (based on ui-icon) for the specified nodes.

Type: String

Default:false

Code Example:

 $(".selector").wijtreenode(collapsedIconClass: false);

expanded

The expanded option will expand the tree node if set to "true." It will collapse the tree node if set to "false."

Type: Boolean

Default: false

Code Example:

 $('.selector’).wijtreenode({expanded: false});

expandedIconClass

The expandedIconClass option sets the expanded node icon (based on ui-icon) for the specified nodes.

Type: String

Default:

Code Example:

 $(".selector").wijtreenode(expandedIconClass: "ui-icon-folder-open");

itemIconClass

The itemIconClass option sets the node icon (based on ui-icon). It will be displayed on both expanded and collapsed nodes when the expandedIconClass and collapsedIconClass options are not specified.

Type: String

Default:

Code Example:

 $(".selector").wijtreenode(itemIconClass: "ui-icon-file");

hasChildren

The hasChildren option determines whether the specified node has child nodes. It's always used when you're custom adding child nodes, such as in an async load.

Type: Boolean

Default: false

Code Example:

 $('.selector’).wijtreenode({hasChildren: true});

navigateUrl

The navigateUrl option sets the node's navigate url link.

Type: String

Default:

Code Example:

 $('.selector’).wijtreenode({navigateUrl: ‘http://www.componentone.com/graphic.jpg’});

params

The params option sets the parameter needed to pass when the user is custom loading child nodes.

Type: Object

Default: {}

Code Example:

 $('.selector’).wijtreenode({params: {innerHTML:"…"}});

selected

The selected option selects the specified node when set to true, otherwise it unselects the node.

Type: Boolean

Default: false

Code Example:

 $('.selector’).wijtreenode({selected: false});

text

This option sets the node’s text.

Type: String

Default:

Code Example:

 $('.selector’).wijtreenode({text: ‘Hello World!’});

toolTip

The toolTip option sets the node’s tooltip.

Type: String

Default:

Code Example:

 $('.selector’).wijtreenode({toolTip: ‘Hello World!’});

Events

nodeFocus

The nodeFocus event handler is a function called when a node is focused.

Default: null

Type: Function

Code example:

/// Supply a function as an option.        
 $("#selector").wijtree({ nodeFocus: function (e, data) { } });
 /// Bind to the event by type: wijtreenodeBlur 
$("#selector").bind("wijtreenodefocus", function(e, data) { } );

Parameters:

e: jQuery.Event object.

data: The node widget that relates to this event.

nodeFocus: null

Methods

add

The add method adds a child node to the specified tree node.

Parameters:

node (string) - HTML markup pointing to the node to add, e.g. <li><a>node</a></li>.

index (number) - Zero-based position indicating where to insert the node.

The index parameter is optional.

Code Example:

 $('.selector’).wijtreenode("add","Child Node 1", 0);

getNodes

The getNodes method gets an array that contains the root nodes of the current tree node.

Code Example:

 $('.selector’).wijtreenode("getNodes");

getOwner

The getOwner method gets the owner which contains the node.

Code Example:

 $('.selector’).wijtreenode("getOwner");

remove

The remove method removes a child node from a specified node.

Parameter:

index (number) - Zero-based position indicating where to remove the node.

Code Example:

 $('.selector’).wijtreenode("remove", 0);

Tree

Contents

User Guide

Tree Overview

TreeNode Overview

Markup and Scripting

Quick Start

How To

Add Check Boxes

Use CSS Styling

Concepts

Adaptive for Mobile Use

Tree API

Options

autoCheckNodes

autoCollapse

allowDrag

allowDrop

allowEdit

allowSorting

allowTriState

collapseAnimation

effect

duration

easing

collapseDelay

disabled

disabled

expandAnimation

effect

duration

easing

expandCollapseHoverUsed

expandDelay

showCheckBoxes

showExpandCollapse

Events

nodeBeforeDropped.wijtree

nodeBlur.wijtree

nodeCheckChanged.wijtree

nodeClick.wijtree

nodeCollapsed.wijtree

nodeCollapsing.wijtree

nodeDragging.wijtree

nodeDragStarted.wijtree

nodeDropped.wijtree

nodeExpanded.wijtree

nodeExpanding.wijtree

nodeMouseOut.wijtree

nodeMouseOver.wijtree

nodeTextChanged.wijtree

selectedNodeChanged.wijtree

Methods

add

destroy

disable

enable

findNodeByText

getCheckedNodes

getNodes

getSelectedNodes

option

option

remove

widget

TreeNode API

Options

checked

collapsedIconClass

expanded

expandedIconClass

itemIconClass

hasChildren

navigateUrl

params

selected

text

toolTip

Events

nodeFocus