Telerik Extensions for ASP.NET MVC

This help topic discusses the client-side API and events exposed by Telerik TreeView for ASP.NET MVC.

Important

All Telerik UI components need a ScriptRegistrar component in order to output their JavaScript objects and register their JavaScript files. The ScriptRegistrar component should be defined *after* all other UI components in the page. If you create the components on the client-side and do not use the MVC extensions, you need to manually register all requried JavaScript files. For further information check this help topic (Step 4 - Register Scripts)

How to get treeview client object?

The treeview client object is preserved in the data store for the treeview element.

Here is a code snippet showing how to retrieve the client object of the treeview.

CopyView
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .Items(items =>{/*items definition */})
%>
CopyJavaScript
function getTreeView(){
    // #TreeView is a jQuery selector based on the "id" attribute of the treeview. The id is set using Name()
    var treeview = $("#TreeView").data("tTreeView");
    return treeview;
}

Client events

Telerik TreeView for ASP.NET MVC exposes the following client-side events

  • OnLoad - raised when the treeview is initialized.
  • OnDataBinding - raised when the treeview is binding (ajax or web-service).
  • OnDataBound - raised when the treeview is bound (ajax or web-service).
  • OnError - raised when an error occurs during databinding.
  • OnExpand - raised when a node is expanded.
  • OnCollapse - raised when a node is collapsed.
  • OnSelect - raised when a node is selected.
  • OnChecked - raised when a node is checked.
  • OnNodeDragStart - raised when a node is about to be dragged.
  • OnNodeDragging - raised when a node is being dragged.
  • OnNodeDragCancelled - raised when a node dragging has ben cancelled by the user.
  • OnNodeDrop - raised when a node is about to be dropped.
  • OnNodeDropped - raised when a node has been dropped.

OnLoad

The OnLoad event is raised when the treeview is initialized. Here is a short example showing how to handle that event:
CopySubscribing to the OnLoad event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnLoad("TreeView_onLoad"))
%>
CopyHandling the OnLoad event
function TreeView_onLoad(e) {
    // `this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    // event handling code
}

OnDataBinding

The OnDataBinding event is raised every time the treeview is being databound on the client-side (during Ajax and WebService binding). Here is a short example showing how to handle that event:
CopySubscribing to the OnDataBinding event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnDataBinding("TreeView_onDataBinding"))
%>
CopyHandling the OnDataBinding event
function TreeView_onDataBinding(e) {
    // `this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    // event handling code
}
Important
You can cancel the OnDataBinding event by calling the preventDefault method of the event argument:
CopyCancelling the OnDataBinding event
function TreeView_onDataBinding(e) {
    e.preventDefault();
}
Cancelling the OnDataBinding event will prevent the treeview from binding.

OnDataBound

The OnDataBound event is raised when the treeview is databound on the client side. Here is a short example showing how to handle that event:
CopySubscribing to the OnDataBound event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnDataBound("TreeView_onDataBound"))
%>
CopyHandling the OnDataBound event
function TreeView_onDataBound(e){
    // `this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    // handling code
}

OnError

The OnError event is raised when there is an error during databiding. Here is a short example showing how to handle that event:
CopySubscribing to the OnError event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnError("TreeView_onError"))
%>
CopyHandling the OnError event
function TreeView_onError(e) {
    // `this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    // the current XMLHttpRequest object
    var xhr = e.XMLHttpRequest;

    // the text status of the error - 'timeout', 'error' etc.
    var status = e.textStatus;

    if (status == 'error') {
       // xhr.status is the HTTP code returned by the server
       if (xhr.status == "404") {
           alert("requested url not found")
       }
    }
}
Important
You can cancel the OnError event by calling the preventDefault method of the event argument:
CopyCancelling the OnError event
function TreeView_onError(e) {
    e.preventDefault();
}
Cancelling the OnError event will prevent the treeview from showing a message box with error details.

OnExpand

The OnExpand event is raised when a node is expanded. The event argument exposes one field
  • item - the <li> DOM element of the tree node
Here is a short example showing how to handle that event:
CopySubscribing to the OnExpand event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnExpand("TreeView_onExpand"))
%>
CopyHandling the OnExpand event
function TreeView_onExpand(e) {
    // `this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    var nodeElement = e.item;

    // event handling code
}

OnCollapse

The OnCollapse event is raised when a node is colapsed. The event argument exposes one field
  • item - the <li> DOM element of the tree node
Here is a short example showing how to handle that event:
CopySubscribing to the OnCollapse event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnCollapse("TreeView_onCollapse"))
%>
CopyHandling the OnCollapse event
function TreeView_onCollapse(e) {
    // `this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    var nodeElement = e.item;

    // event handling code
}

OnSelect

The OnSelect event is raised when a node is selected. The event argument exposes one field
  • item - the <li> DOM element of the tree node
Here is a short example showing how to handle that event:
CopySubscribing to the OnSelect event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnSelect("TreeView_onSelect"))
%>
CopyHandling the OnSelect event
function TreeView_onSelect(e) {
    // `this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    var nodeElement = e.item;

    // event handling code
}

OnChecked

The OnChecked event is raised when a node is checked. The event argument exposes one field
  • item - the <li> DOM element of the tree node
Here is a short example showing how to handle that event:
CopySubscribing to the OnChecked event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnChecked("TreeView_onChecked"))
%>
CopyHandling the OnChecked event
function TreeView_onChecked(e) {
    // `this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    var nodeElement = e.item;

    // event handling code
}
Important
You can cancel the OnChecked event by calling the preventDefault method of the event argument:
CopyCancelling the OnChecked event
function TreeView_onChecked(e) {
    e.preventDefault();
}
Cancelling the OnChecked event will prevent the treeview from changing the checked state of the node.

OnNodeDragStart

The OnNodeDragStart event is raised when a node is about to be dragged. The event argument exposes one field
  • item - the <li> DOM element of the tree node
Here is a short example showing how to handle that event:
CopySubscribing to the OnNodeDragStart event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnNodeDragStart("TreeView_onNodeDragStart"))
%>
CopyHandling the OnNodeDragStart event
function TreeView_onNodeDragStart(e) {
    // `this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    var nodeElement = e.item;

    // event handling code
}
Important
You can cancel the OnNodeDragStart event by calling the preventDefault method of the event argument:
CopyCancelling the OnNodeDragStart event
function TreeView_onNodeDragStart(e) {
    e.preventDefault();
}
Cancelling the OnNodeDragStart event will prevent the user from dragging the node.

OnNodeDragging

The OnNodeDragging event is raised when a node is being dragged. The event argument exposes four fields and one method
  • item - the <li> DOM element of the tree node
  • pageY - the Y coordinate of the mouse pointer
  • pageX - the X coordinate of the mouse pointer
  • dropTarget - the DOM element of the potential drop target
  • setStatusClass(value) - a function that takes one or more CSS classes as parameter and applies them to the drag cue
Here is a short example showing how to handle that event:
CopySubscribing to the OnNodeDragging event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnNodeDragging("TreeView_onNodeDragging"))
%>
CopyHandling the OnNodeDragging event
function TreeView_onNodeDragging(e) {
    //`this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    var nodeElement = e.item;

    //event handling code
}

OnNodeDragCancelled

The OnNodeDragCancelled event is raised when the node dragging is cancelled, for example, by pressing Escape. The event argument exposes one field
  • item - the <li> DOM element of the tree node
Here is a short example showing how to handle that event:
CopySubscribing to the OnNodeDragCancelled event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnNodeDragCancelled("TreeView_onNodeDragCancelled"))
%>
CopyHandling the OnNodeDragCancelled event
function TreeView_onNodeDragCancelled(e) {
    //`this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    var nodeElement = e.item;

    //event handling code
}

OnNodeDrop

The OnNodeDrop event is raised when a node is about to be dropped. The event argument exposes five fields
  • item - the <li> DOM element of the tree node
  • destinationItem - the DOM element of the destination treeview item. Available when the item is dropped over a treeview.
  • dropPosition - a string indicating the position of the dropped node relative to the destination item. The possible values are "before", "over" and "after". Available when the item is dropped over a treeview.
  • dropTarget - the DOM element of the drop target
  • isValid - a boolean value indicating if the drop is allowed. For example, it's not valid if the node is dropped on itself or on its child nodes.
Here is a short example showing how to handle that event:
CopySubscribing to the OnNodeDragCancelled event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnNodeDragCancelled("TreeView_onNodeDragCancelled"))
%>
CopyHandling the OnNodeDragCancelled event
function TreeView_onNodeDragCancelled(e) {
    //`this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    var nodeElement = e.item;

    //event handling code
}

OnNodeDropped

The OnNodeDropped event is raised when a node has been dropped. The event argument exposes three fields
  • item - the <li> DOM element of the tree node
  • destinationItem - the DOM element of the destination treeview item. Available when the item is dropped over a treeview.
  • dropPosition - a string indicating the position of the dropped node relative to the destination item. The possible values are "before", "over" and "after". Available when the item is dropped over a treeview.
Here is a short example showing how to handle that event:
CopySubscribing to the OnNodeDropped event
<%= Html.Telerik().TreeView()
        .Name("TreeView")
        .ClientEvents(events => events.OnNodeDropped("TreeView_onNodeDropped"))
%>
CopyHandling the OnNodeDropped event
function TreeView_onNodeDropped(e) {
    //`this` is the DOM element of the treeview
    var treeview = $(this).data('tTreeView');

    var nodeElement = e.item;

    //event handling code
}

Client Methods

Telerik TreeView for ASP.NET MVC exposes the following client-side methods:

ajaxRequest

The ajaxRequest method initiates an Ajax request for a client-side bound treeview. If the method is called with a DOM element of a node, it will rebind that node. If the parameter is omitted, the whole treeview will be rebound.
CopyajaxRequest example
var treeview = $('#ProductsTreeView').data('tTreeView');

treeview.ajaxRequest();
You can change the URL that will be used by the request in the following way:
Copychange the URL that will be requested
var treeview = $('#ProductsTreeView').data('tTreeView');

treeview.ajax.selectUrl = '/Home/Products'; // if you are using AJAX binding

treeview.ws.selectUrl = '/Home/Products'; // if you are using Web Service binding

treeview.ajaxRequest(); // request the new URL
Note
The ajaxRequest method will raise the OnDataBinding client-side event.

append(node, referenceNode)

The append method allows appending of new nodes and moving of existing nodes within the treeview. If the referenceNode parameter is ommited, the nodes are appended to the root of the treeview.
Copyappend example
var treeview = $('#ProductsTreeView').data('tTreeView');

// append a new item to `foo`
treeview.append({ Text: "bar" }, treeview.findByText("foo"));

// append a new item to the root of the treeview
treeview.append({ Text: "baz" });

// move the item `bar` to the root of the treeview
treeview.append(treeview.findByText("bar"));

// append several items to the item `baz`
treeview.append([{ Text: "qux" }, { Text: "cat" }], treeview.findByText("baz"));

insertBefore(node, referenceNode)

The insertBefore method allows inserting of new nodes and moving of existing nodes within the treeview. The nodes are inserted before the referenceNode parameter.
CopyinsertBefore example
var treeview = $('#ProductsTreeView').data('tTreeView');

// insert a new item before `foo`
treeview.insertBefore({ Text: "bar" }, treeview.findByText("foo"));

// insert several items before the item `baz`
treeview.insertBefore([{ Text: "qux" }, { Text: "cat" }], treeview.findByText("baz"));

insertAfter(node, referenceNode)

The insertAfter method allows inserting of new nodes and moving of existing nodes within the treeview. The nodes are inserted after the referenceNode parameter.
CopyinsertAfter example
var treeview = $('#ProductsTreeView').data('tTreeView');

// insert a new item after `foo`
treeview.insertAfter({ Text: "bar" }, treeview.findByText("foo"));

// insert several items after the item `baz`
treeview.insertAfter([{ Text: "qux" }, { Text: "cat" }], treeview.findByText("baz"));

remove(node)

The remove method removes the passed nodes from the treeview.
Copyremove example
var treeview = $('#ProductsTreeView').data('tTreeView');

// get the first li in the TreeView
var node = $('#TreeView li:first')

// remove the node
treeview.remove(node);

dataBind

The dataBind method binds the treeview to a specified array of JavaScript objects.
CopydataBind example
var treeview = $('#ProductsTreeView').data('tTreeView');
var data = [
      { Value: "1", Text: "Product 1", Expanded: true,
        Items: [
            { Value: "4", Text: "Product 4", Expanded: true,
              Items: [
                  { Value: "6", Text: "Product 6" },
                  { Value: "7", Text: "Product 7" }
              ]
            },
            { Value: "5", Text: "Product 5" }
         ]
       },
       { Value: "2", Text: "Product 2 (unavailable)", Enabled: false },
       { Value: "3", Text: "Product 3" }
  ];

treeview.dataBind(data);
The dataBind method can also accept a node to which to bind the data.
CopydataBind example
var firstNodeElement = $("li:first", treeview.element)[0];
treeview.dataBind(firstNodeElement, data);
Note
The Text and Value property must be specified in json object. Otherwise dataBind will fail to bind data.
Note
The dataBind method will not raise the OnDataBinding client-side event.

expand

The expand method expands one or more nodes.
Copyexpanding a single node
var treeview = $('#ProductsTreeView').data('tTreeView');
var firstNodeElement = $("li:first", treeview.element)[0];
treeview.expand(firstNodeElement);

You can expand multiple nodes by passing a jQuery collection

Copyexpanding multiple nodes
var treeview = $('#ProductsTreeView').data('tTreeView');
var allNodes = $("li", treeview.element); // jQuery collection of all node elements
treeview.expand(allNodes);

The expand method can also take a jQuery selector as parameter. In this case the selector is applied in the context of the TreeView and the matching items are expanded.

Copyexpanding nodes matching selector
var treeview = $('#ProductsTreeView').data('tTreeView');
treeview.expand("li:first");

collapse

The collapse method collapses one or more nodes.
Copycollapsing a single node
var treeview = $('#ProductsTreeView').data('tTreeView');
var firstNodeElement = $("li:first", treeview.element)[0];
treeview.collapse(firstNodeElement);

You can collapse multiple nodes by passing a jQuery collection

Copycollapsing multiple nodes
var treeview = $('#ProductsTreeView').data('tTreeView');
var allNodes = $("li", treeview.element); // jQuery collection of all node elements
treeview.collapse(allNodes);

The collapse method can also take a jQuery selector as parameter. In this case the selector is applied in the context of the TreeView and the matching items are collapsed.

Copycollapsing nodes matching selector
var treeview = $('#ProductsTreeView').data('tTreeView');
treeview.collapse("li:first");

enable

The enable method enables one or more nodes.
Copyenabling a single node
var treeview = $('#ProductsTreeView').data('tTreeView');
var firstNodeElement = $("li:first", treeview.element)[0];
treeview.enable(firstNodeElement);

You can enable multiple nodes by passing a jQuery collection

Copyenabling multiple nodes
var treeview = $('#ProductsTreeView').data('tTreeView');
var allNodes = $("li", treeview.element); // jQuery collection of all node elements
treeview.enable(allNodes);

The enable method can also take a jQuery selector as parameter. In this case the selector is applied in the context of the TreeView and the matching items are enabled.

Copyenabling nodes matching selector
var treeview = $('#ProductsTreeView').data('tTreeView');
treeview.enable("li:first");

disable

The disable method disables one or more nodes.
Copydisabling a single node
var treeview = $('#ProductsTreeView').data('tTreeView');
var firstNodeElement = $("li:first", treeview.element)[0];
treeview.disable(firstNodeElement);

You can disable multiple nodes by passing a jQuery collection

Copydisabling multiple nodes
var treeview = $('#ProductsTreeView').data('tTreeView');
var allNodes = $("li", treeview.element); // jQuery collection of all node elements
treeview.disable(allNodes);

The disable method can also take a jQuery selector as parameter. In this case the selector is applied in the context of the TreeView and the matching items are disabled.

Copydisabling nodes matching selector
var treeview = $('#ProductsTreeView').data('tTreeView');
treeview.disable("li:first");

getItemText

The getItemText method returns the text of a treeview item. You can pass a DOM element, jQuery object or a jQuery selector which identify the item.
CopygetItemText example
var treeview = $('#ProductsTreeView').data('tTreeView');
var firstNodeElement = $("li:first", treeview.element)[0];
var text = treeview.getItemText(firstNodeElement);

getItemValue

The getItemValue method returns the value of a treeview item. You can pass a DOM element, jQuery object or a jQuery selector which identify the item.
CopygetItemValue example
var treeview = $('#ProductsTreeView').data('tTreeView');
var firstNodeElement = $("li:first", treeview.element)[0];
var value = treeview.getItemValue(firstNodeElement);

findByText

The findByText method finds the treeview items that have the given text.
CopygetItemValue example
var treeview = $('#ProductsTreeView').data('tTreeView');
var fooElements = treeview.findByText('foo');
// fooElements is a jQuery object that contains all elements that have the text "foo"
fooElements.css('color', 'red');

findByValue

The findByValue method finds the treeview items that have the given value.
CopyfindByValue example
var treeview = $('#ProductsTreeView').data('tTreeView');
var elementsWithValue1 = treeview.findByValue(1);
// elementsWithValue1 is a jQuery object that contains all elements that have the value 1
elementsWithValue1.css('color', 'red');

nodeCheck

The nodeCheck changes the checked state of a treeview item. The function requires two arguments:
  • item - the item DOM element, jQuery object or a jQuery selector
  • checked - true if the item should be checked, false otherwise
CopynodeCheck example
var treeview = $('#ProductsTreeView').data('tTreeView');
var firstNodeElement = $("li:first", treeview.element)[0];
treeview.nodeCheck(firstNodeElement, true);

See Also