TreeView Web Server Control Overview

Artigo
10/22/2014

The TreeView Web server control is used to display hierarchical data, such as a table of contents or file directory, in a tree structure.

This topic contains:

Features
Background
Code Examples
Class Reference

Features

The TreeView control supports the following features:

Automatic data binding, which allows the nodes of the control to be bound to hierarchical data, such as an XML document.
Site navigation support through integration with the SiteMapDataSource control.
Node text that can be displayed as either selectable text or hyperlinks.
Customizable appearance through themes, user-defined images, and styles.
Programmatic access to the TreeView object model, which allows you to dynamically create trees, populate nodes, set properties, and so on.
Node population through client-side callbacks to the server (on supported browsers).
The ability to display a check box next to each node.

Background

The TreeView control can display several different types of data: static data that is specified declaratively in the control, data that is bound to the control, or data that is added to the TreeView control programmatically, in response to user actions.

Displaying Static Data

You can display static data in the TreeView control by creating a collection of TreeNode elements that are children of the TreeView control. These child elements are also known as child nodes.

The following example shows the markup for a TreeView control that contains three nodes, two of which have child nodes.

<asp:TreeView ID="MyTreeView" Runat="server">
  <Nodes>
    <asp:TreeNode Value="Child1" Expanded="True" Text="1">
      <asp:TreeNode Value="Grandchild1" Text="A" />
      <asp:TreeNode Value="Grandchild2" Text="B" />
    </asp:TreeNode>
    <asp:TreeNode Value="Child2" Text="2" />
    <asp:TreeNode Value="Child3" Expanded="True" Text="3">
      <asp:TreeNode Value="Grandchild1" Text="A" />
    </asp:TreeNode>
  </Nodes>
</asp:TreeView>

Bind Data to the TreeView Control

You can bind a TreeView control to a data source that supports the IHierarchicalDataSource interface, such as the XmlDataSource and SiteMapDataSource controls. Additionally, when binding data, you have complete control over which fields are populated from the data source. For more information, see Binding Data to the TreeView Web Server Control.

Displaying Data Programmatically by Using TreeNodeCollection

You can populate a TreeView control with data programmatically by accessing the Nodes property, which returns a TreeNodeCollection class. TreeNodeCollection is a strongly typed collection of TreeNode objects. Because a TreeNode object contains a property called ChildNodes that can contain TreeNode objects, the TreeNodeCollection class is a hierarchal data structure that represents all of the nodes of the TreeView control.

For an example of how to traverse the Nodes collection, see Nodes.

TreeView Node Types

The TreeView control is made up of one or more nodes. Each entry in the tree is called a node and is represented by a TreeNode object. The following table describes the three different node types.

Node type	Description
Root	A node that has no parent node and one or more child nodes.
Parent	A node that has a parent node and one or more child nodes.
Leaf	A node that has no child nodes.

Although a typical tree has only one root node, the TreeView control allows you to add multiple root nodes to your tree structure. This is useful when you want to display item listings without displaying a single main root node, as in a list of product categories.

Each node has a Text property and a Value property. The value of the Text property is displayed in the TreeView control, while the Value property is used to store any additional data about the node, such as data passed to the postback event that is associated with the node.

When a node of the TreeView control is clicked, it can either raise a selection event (via postback) or navigate to another page. When the NavigateUrl property is not set, clicking a node will raise a SelectedNodeChanged event that can be handled to provide custom functionality. Each node also has a SelectAction property that can be used to determine specific actions that happen when the node is clicked, such as expand or collapse the node. Instead of raising a selection event to navigate to a page when a node is clicked, set the NavigateUrl property of the node to a value other than an empty string ("").

Populating TreeNode Data on Demand

It might not be practical to define your data structure statically, or the data might depend on information that is gathered at run time. To display data dynamically, the TreeView control supports dynamic node population. When the TreeView control is configured to populate on demand, the control raises an event when a user expands the node. The event handler retrieves the appropriate data and then populates the node that the user has clicked. To populate the TreeNode object with data on demand, set the PopulateOnDemand property of a node to true, and create a TreeNodePopulate event handler to populate the TreeNode object with data.

Client-Side TreeView Node Population

Any browser that has the SupportsCallback property set to true in the browser capabilities configuration file supports client-side node population.

Client-side node population enables the TreeView control to populate a node by calling the server's TreeNodePopulate event from client script instead of requiring a full postback to the server. For more information about client-side node population, see PopulateNodesFromClient.

Enabling Client Script

By default, on up-level browsers, the expand-collapse functionality of a node on the TreeView control is performed using client script. Using client script increases the efficiency of the rendering because the control does not have to post back to the server to render the new configuration.

Note

If client script is disabled in the browser or the browser does not support client script, then the TreeView control will revert to down-level mode and post back to the server each time a user clicks the node.

TreeView Postback

By default, the TreeView control handles expand-collapse functionality on the client unless the browser does not support client script or the EnableClientScript property is set to false. If the PopulateNodesFromClient property is set to true and the browser supports client script, then the TreeView control retrieves the data from the server without posting the entire page back.

When the TreeView control is in selection mode, each time a user clicks a node, a postback to the server occurs and the SelectedNodeChanged event is raised.

Typically, you should handle postback events when the TreeView control is in selection mode or the nodes are being dynamically populated. This is because either the PopulateOnDemand or PopulateNodesFromClient property is set to true.

Using the TreeView Control with UpdatePanel Controls

UpdatePanel controls are used to update selected regions of a page instead of updating the whole page with a postback. The TreeView control can be used inside an UpdatePanel control with the following restrictions:

TreeView callbacks must be associated with asynchronous postbacks, or callback event validation will fail. When you set the PopulateOnDemand property of the TreeNode controls to true, callbacks are enabled. You can use one of the following approaches to ensure that TreeView callbacks work with the UpdatePanel control:
- If the TreeView control is not inside an UpdatePanel control, disable callbacks on TreeNode controls that are not part of an asynchronous postback. To do this, set the PopulateOnDemand property to false.
- Programmatically refresh all controls that register callbacks during the asynchronous postback. For example, you can place the TreeView control inside an UpdatePanel control. The TreeView control does not have to be in the UpdatePanel control where the asynchronous postback originates, as long as the UpdatePanel control that contains the TreeView control is refreshed.
You must apply styles by using a reference to a Cascading Style Sheet (CSS) class. For example, instead of setting the NodeStyle property by using a property-subproperty attribute, set the style by using the property-CssClass attribute. Similarly, when you use the NodeStyle template to set the style, use the CssClass attribute of the template.
The EnableClientScript property must be true (the default value). In addition, if callbacks are enabled for the TreeView control, you cannot change the EnableClientScript property between asynchronous postbacks.

For more information about using UpdatePanel controls, see UpdatePanel Control Overview and Partial-Page Rendering Overview.

TreeNode Rendering

Each TreeNode object contains four UI elements, which are shown in the following image and described in the table below.

TreeNode UI Elements

TreeNode UI Elements

Item	Description
Expand/Collapse image	An optional image that indicates whether the node can be expanded to show child nodes. By default, this is a plus sign [+] if the node can be expanded, or a minus sign [-] if the node can be collapsed.
Check box	Check boxes can be optionally enabled, which allows users to select a particular node.
Node image	You can specify a node image to display next to the node text.
Node text	Node text is the actual text that displays on the TreeNode object. Node text can behave like a hyperlink in navigation mode, or like a button in selection mode.

In addition to its own properties, the TreeView control supports properties of the TreeNodeStyle control for each node type. These style properties override the NodeStyle property, which applies to all node types.

The TreeView also has a NodeIndent property that specifies the indentation level for all nodes. Nodes are indented from the side on which the TreeView control is rendered. This is the left side for locales that render from left to right, and it is the right side for locales that render from right to left.

A node can also have a different style applied when it is selected or when the mouse hovers over the node. When the Selected property of a node is set to true, the SelectedNodeStyle property is applied, which overrides any unselected style properties for the selected node. When the mouse hovers over a node, the HoverNodeStyle property is applied. The following image and table describe the TreeNodeStyle properties.

TreeNodeStyle Properties

TreeView Node style graphic

Node Property	Description
NodeSpacing	Specifies the amount of vertical spacing between the entire current node and adjacent nodes above and below.
VerticalPadding	Specifies the amount of space rendered on the top and bottom of the TreeNode text.
HorizontalPadding	Specifies the amount space rendered on the left and right of the TreeNode text.
ChildNodesPadding	Specifies the amount of space above and below the child nodes of the TreeNode.
ImageUrl	Specifies the path to the image that displays next to the TreeNode.

For more information, see Customizing the Look and Feel of the TreeView Web Server Control.

Displaying a Check Box Next to a TreeView Node

Another custom rendering feature of the TreeView control is its ability to render check boxes between the node text and image by using the ShowCheckBoxes property. Showing check boxes allows the user to select multiple nodes at once, which is especially useful for interfaces like a newsgroup tree, where users can select and subscribe to multiple newsgroups at once. For more information about using check boxes, see Selection, Navigation, and Check Boxes in the TreeView Web Server Control.

Using the ExpandDepth Property

By default, the TreeView control displays all of the nodes of the tree expanded. You can configure the TreeView control to initially display to any depth. To do so, you can set the ExpandDepth property to a number reflecting the node level that you want to display. For example, if you set the ExpandDepth property to 2, then two levels of the node, or two child nodes, will display when the site initially renders on the client.