Displays hierarchical data, such as a table of contents, in a tree structure.
Assembly: System.Web (in System.Web.dll)
The control is used to display hierarchical data, such as a table of contents or file directory, in a tree structure and supports the following features:
Data binding that allows the nodes of the control to be bound to XML, tabular, or relational data.
Site navigation through integration with the SiteMapDataSource control.
Node text that can be displayed as either plain text or hyperlinks.
Programmatic access to the object model to create trees, populate nodes, set properties, and so on dynamically.
Client-side node population (on supported browsers).
The ability to display a check box next to each node.
Customizable appearance through themes, user-defined images, and styles.
The control is designed to be used inside an UpdatePanel control only when EnableClientScript is set to true. UpdatePanel controls are used to update selected regions of a page instead of updating the whole page with a postback. For more information, see UpdatePanel Control Overview and Partial-Page Rendering Overview.
The control is made up of nodes. Each entry in the tree is called a node and is represented by a TreeNode object. Node types are defined as follows:
A node that contains other nodes is called a parent node.
The node that is contained by another node is called a child node.
A node that has no children is called a leaf node.
The node that is not contained by any other node but is the ancestor to all the other nodes is the root node.
A node can be both a parent and a child, but root, parent, and leaf nodes are mutually exclusive. Several visual and behavioral properties of nodes are determined by whether a node is a root, child, or leaf node.
Although a typical tree structure has only one root node, the 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 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 , while the Value property is used to store any additional data about the node, such as data that is passed to the postback event that is associated with the node.
A node can be in one of two modes: selection mode and navigation mode. By default, a node is in selection mode. To put a node into navigation mode, set the NavigateUrl property for the node to a value other than an empty string (""). To put a node into selection mode, set the NavigateUrl property for the node to an empty string ("").
Some Internet browsers have a limitation that can affect the performance of the control. For example, Microsoft Internet Explorer 6.0 has a URL character limit of 2067 characters that it posts. If the number of characters in a URL of a node is larger than that number, expanding that node will fail and no exception is thrown.
The simplest data model of the control is static data. To display static data using declarative syntax, first nest opening and closing <Nodes> tags between the opening and closing tags of the control. Next, create the tree structure by nesting <asp:TreeNode> elements between the opening and closing <Nodes> tags. Each <asp:TreeNode> element represents a node in the tree and maps to a TreeNode object. You can set the properties of each node by setting the attributes of its <asp:TreeNode> element. To create child nodes, nest additional <asp:TreeNode> elements between the opening and closing <asp:TreeNode> tags of the parent node.
Binding to Data
The control can also be bound to data. You can use either of two methods to bind the control to the appropriate data source type:
The control can use any data source control that implements the IHierarchicalDataSource interface, such as an XmlDataSource control or a SiteMapDataSource control. To bind to a data source control, set the DataSourceID property of the control to the ID value of the data source control. The control automatically binds to the specified data source control. This is the preferred method to bind to data.
The control can also be bound to an XmlDocument object or a DataSet object with relations. To bind to one of these data sources, set the DataSource property of the control to the data source, and then call the DataBind method.
When binding to a data source where each data item contains multiple properties (such as an XML element with several attributes), a node displays the value that is returned by the ToString method of the data item, by default. In the case of an XML element, the node displays the element name, which shows the underlying structure of the tree but is not very useful otherwise. You can bind a node to a specific data item property by specifying tree node bindings using the DataBindings collection. The DataBindings collection contains TreeNodeBinding objects that define the relationship between a data item and the node that it is binding to. You can specify the criteria for binding and the data item property to display in the node. For more information on tree node bindings, see TreeNodeBinding.
A malicious user can create a callback request and get data for the nodes of the control that the page developer is not displaying. Therefore, security of the data must be implemented by the data source. Do not use the MaxDataBindDepth property to hide data.
Dynamic Node Population
Sometimes, it is not practical to statically define the tree structure because the data source returns too much data or because the data to display depends on information that you get at run time. Because of this, the control supports dynamic node population. When the PopulateOnDemand property for a node is set to true, that node gets populated at run time when the node is expanded. To populate a node dynamically, you must define an event-handling method that contains the logic to populate a node for the TreeNodePopulate event.
Browsers that support callback scripts can also take advantage of client-side node population. (This includes Internet Explorer 5.5 and later and some other browsers.) Client-side node population enables the control to populate a node using client script when users expand the node, without requiring a round trip to the server. For more information on client-side node population, see PopulateNodesFromClient.
Customizing the User Interface
There are many ways to customize the appearance of the control. First, you can specify a different style (such as font size and color) for each of the node types.
If you use cascading style sheets (CSS) to customize the appearance of the control, use either inline styles or a separate CSS file, but not both. Using both inline styles and a separate CSS file could cause unexpected results. For more information on using style sheets with controls, see ASP.NET Web Server Controls and CSS Styles.
The following table lists the available node styles.
Node style property
The style settings for a node when the mouse pointer is positioned over it.
The style settings for the leaf nodes.
The default style settings for a node.
The style settings for the parent nodes.
The style settings for the root node.
The style settings for a selected node.
You can also control the style of nodes at specific depths within the tree by using the LevelStyles collection. The first style in the collection corresponds to the style of the nodes at the first level in the tree. The second style in the collection corresponds to the style of the nodes at the second level in the tree, and so on. This is most often used to generate table of contents–style navigation menus where nodes at a certain depth should have the same appearance, regardless of whether they have child nodes.
If a style is defined for a certain depth level using the LevelStyles collection, that style overrides any root, parent, or leaf node style settings for the nodes at that depth.
Another way to alter the appearance of the control is to customize the images that are displayed in the control. You can specify your own custom set of images for the different parts of the control by setting the properties shown in the following table.
The URL to an image displayed for the collapsible node indicator. This image is usually a minus sign (-).
The URL to an image displayed for the expandable node indicator. This image is usually a plus sign (+).
The URL to the folder containing the line images used to connect parent nodes to child nodes. The ShowLines property must also be set to true for this property to have an effect.
The URL to an image displayed for the non-expandable node indicator.
You do not need to customize every image property. If an image property is not explicitly set, the built-in default image is used.
The control also allows you to display a check box next to a node. When the ShowCheckBoxes property is set to a value other than TreeNodeTypes.None, check boxes are displayed next to the specified node types.
Each time the page is posted to the server, the CheckedNodes collection is automatically populated with the selected nodes. When check boxes are displayed, you can use the TreeNodeCheckChanged event to run a custom routine whenever the state of a check box changes between posts to the server.
The control provides several events that you can program against. This allows you to run a custom routine whenever an event occurs. The following table lists the events that are supported by the control.
Occurs when the check boxes of the control change state between posts to the server.
Occurs when a node is selected in the control.
Occurs when a node is expanded in the control.
Occurs when a node is collapsed in the control.
Occurs when a node with its PopulateOnDemand property set to true is expanded in the control.
Occurs when a data item is bound to a node in the control.
The markup rendered by default for this control might not conform to accessibility standards such as the Web Content Accessibility Guidelines 1.0 (WCAG) priority 1 guidelines. For details about accessibility support for this control, see ASP.NET Controls and Accessibility.
The control does not have built-in scrolling. To add scrolling, place the control in a Panel control and add scrollbars to the Panel control. For more information, see Panel Web Server Control Overview.
This section contains seven code examples:
The first code example demonstrates how to set up the frames for the second code example.
The second code example demonstrates how to use declarative syntax to display static data in the control.
The third code example demonstrates how to bind the control to an XML data source.
The fourth code example provides sample XML data for the third code example.
The fifth code example demonstrates how to use the control for site navigation by binding it to a SiteMapDataSource control.
The sixth code example provides sample site map data for the fifth code example.
The seventh code example demonstrates how to populate the nodes in the control from the client.
The following code example demonstrates how to set up the frames for the following code example.
The following code example demonstrates how to use declarative syntax to display static data in the control. This example is used within the frame set of the preceding example to display a table of contents.
The following code example demonstrates how to bind the control to an XML data source. For this example to work correctly, you must copy the sample XML data, provided after this code example, to a file named Book.xml.
The following code example provides sample XML data for the preceding example.
<Book Title="Book Title"> <Chapter Heading="Chapter 1"> <Section Heading="Section 1"> </Section> <Section Heading="Section 2"> </Section> </Chapter> <Chapter Heading="Chapter 2"> <Section Heading="Section 1"> </Section> </Chapter> </Book>
The following code example demonstrates how to use the control for site navigation by binding it to a SiteMapDataSource control. For this example to work correctly, you must copy the sample site map data, provided after this code example, to a file named Web.sitemap.
The following code example provides sample site map data for the preceding code example.
<siteMap> <siteMapNode title="Home" description="Home" url="default.aspx"> <siteMapNode title="Products" description="Products" url="Products.aspx"> <siteMapNode title="Computers" url="Computers.aspx"/> <siteMapNode title="Accessories" url="Accessories.aspx"/> </siteMapNode> </siteMapNode> </siteMap>
The following code example demonstrates how to populate the nodes in the control from the client. When client-side node population is enabled, nodes are populated dynamically on the client, without the need to post back to the server.
Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.