TreeNodeBinding Class

Reference

Definition

Namespace:: System.Web.UI.WebControls

Assembly:: System.Web.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Defines the relationship between a data item and the node it is binding to in a TreeView control.

public ref class TreeNodeBinding sealed : ICloneable, System::Web::UI::IDataSourceViewSchemaAccessor, System::Web::UI::IStateManager

public sealed class TreeNodeBinding : ICloneable, System.Web.UI.IDataSourceViewSchemaAccessor, System.Web.UI.IStateManager

type TreeNodeBinding = class
    interface IStateManager
    interface ICloneable
    interface IDataSourceViewSchemaAccessor

Public NotInheritable Class TreeNodeBinding
Implements ICloneable, IDataSourceViewSchemaAccessor, IStateManager

Inheritance: Object
TreeNodeBinding

Implements: ICloneable IDataSourceViewSchemaAccessor IStateManager

Examples

The following table shows some example tree node binding declarations.

Example binding	Description
`<asp:TreeNodeBinding TextField="Title" ValueField= "ID"/>`	Binds the Text and Value properties of all nodes in the tree to the `Title` and `ID` fields of the data source, respectively. All nodes use this tree node binding declaration because the DataMember and Depth properties are not set.
`<asp:TreeNodeBinding DataMember= "Book" TextField= "Title" ValueField= "ID"/>`	Binds the Text and Value properties of all nodes in the tree to the `Title` and `ID` fields of the `Book` data item in the data source, respectively.
`<asp:TreeNodeBinding Depth="2" TextField= "Title" ValueField= "ID"/>`	Binds the Text and Value properties of all nodes with a depth of 2 in the tree to the `Title` and `ID` fields of the data item in the data source, respectively.
`<asp:TreeNodeBinding DataMember="Book" Depth= "2" TextField= "Title" ValueField= "ID" ImageUrl= "Image.jpg">`	Binds the Text and Value properties of all nodes with a depth of 2 in the tree to the `Title` and `ID` fields of the `Book` data item in the data source, respectively. Also binds the ImageUrl property of the nodes to a static value.

This section contains three code examples. The first code example demonstrates how to use TreeNodeBinding objects declaratively to define the relationship between a node and a data item. The second code example demonstrates how to use TreeNodeBinding objects programmatically to define the relationship between a node and a data item. The third code example provides sample XML data for the first and second code examples.

The following code example demonstrates how to use TreeNodeBinding objects declaratively to define the relationship between a node and a data item. For this example to work correctly, you must copy the sample XML data, provided after this code example, to a file named Book.xml.


<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
  <head runat="server">
    <title>TreeView XML Data Binding Example</title>
</head>
<body>
    <form id="form1" runat="server">
    
      <h3>TreeView XML Data Binding Example</h3>
    
      <asp:TreeView id="BookTreeView" 
        DataSourceID="BookXmlDataSource"
        runat="server">
         
        <DataBindings>
          <asp:TreeNodeBinding DataMember="Book" TextField="Title"/>
          <asp:TreeNodeBinding DataMember="Chapter" TextField="Heading"/>
          <asp:TreeNodeBinding DataMember="Section" TextField="Heading"/>
        </DataBindings>
         
      </asp:TreeView>

      <asp:XmlDataSource id="BookXmlDataSource"  
        DataFile="Book.xml"
        runat="server">
      </asp:XmlDataSource>
    
    </form>
  </body>
</html>


<%@ Page Language="VB" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
  <head runat="server">
    <title>TreeView XML Data Binding Example</title>
</head>
<body>
    <form id="form1" runat="server">
    
      <h3>TreeView XML Data Binding Example</h3>
    
      <asp:TreeView id="BookTreeView" 
        DataSourceID="BookXmlDataSource"
        runat="server">
         
        <DataBindings>
          <asp:TreeNodeBinding DataMember="Book" TextField="Title"/>
          <asp:TreeNodeBinding DataMember="Chapter" TextField="Heading"/>
          <asp:TreeNodeBinding DataMember="Section" TextField="Heading"/>
        </DataBindings>
         
      </asp:TreeView>

      <asp:XmlDataSource id="BookXmlDataSource"  
        DataFile="Book.xml"
        runat="server">
      </asp:XmlDataSource>
    
    </form>
  </body>
</html>

The following code example demonstrates how to use TreeNodeBinding objects programmatically to define the relationship between a node and a data item. For this example to work correctly, you must copy the sample XML data that is provided in the next code example to a file named Book.xml.


<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">

  void Page_Load(Object sender, EventArgs e)
  {

    // Create a new TreeView control.
    TreeView NewTree = new TreeView();

    // Set the properties of the TreeView control.
    NewTree.ID = "BookTreeView";
    NewTree.DataSourceID = "BookXmlDataSource";

    // Create the tree node binding relationship.

    // Create the root node binding.
    TreeNodeBinding RootBinding = new TreeNodeBinding();
    RootBinding.DataMember = "Book";
    RootBinding.TextField = "Title";

    // Create the parent node binding.
    TreeNodeBinding ParentBinding = new TreeNodeBinding();
    ParentBinding.DataMember = "Chapter";
    ParentBinding.TextField = "Heading";

    // Create the leaf node binding.
    TreeNodeBinding LeafBinding = new TreeNodeBinding();
    LeafBinding.DataMember = "Section";
    LeafBinding.TextField = "Heading";

    // Add bindings to the DataBindings collection.
    NewTree.DataBindings.Add(RootBinding);
    NewTree.DataBindings.Add(ParentBinding); 
    NewTree.DataBindings.Add(LeafBinding);

    // Manually register the event handler for the SelectedNodeChanged event.
    NewTree.SelectedNodeChanged += new EventHandler(this.Node_Change);

    // Add the TreeView control to the Controls collection of the PlaceHolder control.
    ControlPlaceHolder.Controls.Add(NewTree);

  }

  void Node_Change(Object sender, EventArgs e)
  {

    // Retrieve the TreeView control from the Controls collection of the PlaceHolder control.
    TreeView LocalTree = (TreeView)ControlPlaceHolder.FindControl("BookTreeView");

    // Display the selected node.
    Message.Text = "You selected: " + LocalTree.SelectedNode.Text;

  }

</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
  <head runat="server">
    <title>TreeView Constructor Example</title>
</head>
<body>
    <form id="form1" runat="server">
    
      <h3>TreeView Constructor Example</h3>
      
      <asp:PlaceHolder id="ControlPlaceHolder" runat="server">
      </asp:PlaceHolder>
   
      <asp:XmlDataSource id="BookXmlDataSource"  
        DataFile="Book.xml"
        runat="server">
      </asp:XmlDataSource>
      
      <br /><br />
      
      <asp:Label id="Message" runat="server"/>
    
    </form>
  </body>
</html>


<%@ Page Language="VB" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">

  Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)

    ' Create a new TreeView control.
    Dim NewTree As New TreeView

    ' Set the properties of the TreeView control.
    NewTree.ID = "BookTreeView"
    NewTree.DataSourceID = "BookXmlDataSource"

    ' Create the tree node binding relationship.

    ' Create the root node binding.
    Dim RootBinding As New TreeNodeBinding
    RootBinding.DataMember = "Book"
    RootBinding.TextField = "Title"

    ' Create the parent node binding.
    Dim ParentBinding As New TreeNodeBinding
    ParentBinding.DataMember = "Chapter"
    ParentBinding.TextField = "Heading"

    ' Create the leaf node binding.
    Dim LeafBinding As New TreeNodeBinding
    LeafBinding.DataMember = "Section"
    LeafBinding.TextField = "Heading"

    ' Add bindings to the DataBindings collection.
    NewTree.DataBindings.Add(RootBinding)
    NewTree.DataBindings.Add(ParentBinding)
    NewTree.DataBindings.Add(LeafBinding)

    ' Manually register the event handler for the SelectedNodeChanged event.
    AddHandler NewTree.SelectedNodeChanged, AddressOf Node_Change

    ' Add the TreeView control to the Controls collection of the PlaceHolder control.
    ControlPlaceHolder.Controls.Add(NewTree)

  End Sub

  Sub Node_Change(ByVal sender As Object, ByVal e As EventArgs)

    ' Retrieve the TreeView control from the Controls collection of the PlaceHolder control.
    Dim LocalTree As TreeView = CType(ControlPlaceHolder.FindControl("BookTreeView"), TreeView)

    ' Display the selected node.
    Message.Text = "You selected: " & LocalTree.SelectedNode.Text

  End Sub

</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
  <head runat="server">
    <title>TreeView Constructor Example</title>
</head>
<body>
    <form id="form1" runat="server">
    
      <h3>TreeView Constructor Example</h3>
      
      <asp:PlaceHolder id="ControlPlaceHolder" runat="server">
      </asp:PlaceHolder>
   
      <asp:XmlDataSource id="BookXmlDataSource"  
        DataFile="Book.xml"
        runat="server">
      </asp:XmlDataSource>
      
      <br /><br />
      
      <asp:Label id="Message" runat="server"/>
    
    </form>
  </body>
</html>

The following code example provides sample XML data for the preceding code examples.

<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>

Remarks

When the TreeView control is bound to a data source where each data item contains multiple fields (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 the properties of a node to a specific field by specifying tree node bindings. A TreeNodeBinding object defines the relationship between each data item and the node that it is binding to.

The TreeView control stores its TreeNodeBinding objects in the DataBindings property and applies the bindings to the data source to create a one-to-one relationship between the tree hierarchy and the data source hierarchy. For each data item in the data source, the TreeView control attempts to match the data item to a TreeNodeBinding object in order to create the corresponding TreeNode object.

When creating a TreeNodeBinding object, you must specify the criteria for binding. The criteria indicates when a data item should be bound to a node. You can specify the Depth or DataMember property, or both properties. There is a slight performance gain by specifying both. A node depth specifies the node level that gets bound. For example, the following TreeNodeBinding declaration binds the Name and ID fields of the data source to the Text and Value properties, respectively, of all nodes with a depth of 0:

<asp:TreeNodeBinding Depth="0" TextField="Name" ValueField="ID">

A data member specifies the type of the data item in the underlying data source, but can represent different information depending on the data source. Each data item in a hierarchical data source (represented by a System.Web.UI.IHierarchyData interface) exposes a IHierarchyData.Type property, which specifies the type of the data item. For example, the data member for an XML element specifies the name of the element. When a data source contains multiple data item types, the data member specifies which data item type to use. The following TreeNodeBinding declaration binds the <Book> elements of an XmlDataSource control to all the nodes in the tree, regardless of the location in the hierarchy:

<asp:TreeNodeBinding DataMember="Book" TextField="Title" ValueField= "ISBN">

Once the binding criteria is established, you can then bind a property of a TreeNode object that can be bound to a value. You can bind to a field of a data item or to a static value. When bound to a static value, all TreeNode objects to which the TreeNodeBinding object is applied share the same value.

Note

You can selectively override a bound property in a TreeNode object by setting the corresponding property directly in the node.

The following table lists the properties of the TreeNodeBinding class that allow you to bind a property of the TreeNode object to a field of a data item.

Property	Description
ImageUrlField	The field to bind to the ImageUrl property of a TreeNode object.
ImageToolTipField	The field to bind to the ImageToolTip property of a TreeNode object.
NavigateUrlField	The field to bind to the NavigateUrl property of a TreeNode object.
TextField	The field to bind to the Text property of a TreeNode object.
ToolTipField	The field to bind to the ToolTip property of a TreeNode object.
ValueField	The field to bind to the Value property of a TreeNode object.

The following table lists the properties of the TreeNodeBinding class that allow you to bind a property of the TreeNode object to a static value.

Property	Description
ImageUrl	The static value to bind to the ImageUrl property of a TreeNode object.
ImageToolTip	The static value to bind to the ImageToolTip property of a TreeNode object.
NavigateUrl	The static value to bind to the NavigateUrl property of a TreeNode object.
PopulateOnDemand	The static value to bind to the PopulateOnDemand property of a TreeNode object.
SelectAction	The static value to bind to the SelectAction property of a TreeNode object.
ShowCheckBox	The static value to bind to the ShowCheckBox property of a TreeNode object.
Target	The static value to bind to the Target property of a TreeNode object.
Text	The static value to bind to the Text property of a TreeNode object.
ToolTip	The static value to bind to the ToolTip property of a TreeNode object.
Value	The static value to bind to the Value property of a TreeNode object.

If conflicting TreeNodeBinding objects are defined, the TreeView control applies the tree node bindings in the following order of precedence:

The TreeNodeBinding object that defines and matches both a depth and a data member.
The TreeNodeBinding object that defines and matches the data member only.
The TreeNodeBinding object that defines and matches the depth only.
The TreeNodeBinding object that defines neither the depth nor the data member. (This type of tree node binding is applied to all nodes in the tree.)
The TreeNodeBinding object that does not have a match in the data source. In this case, the value that is returned by the ToString method of the data item is then bound to the Text and Value properties of the nodes to which the TreeNodeBinding object is applied.

The TreeNodeBinding class also allows you to format the text that is displayed in a node by setting the FormatString property.

Constructors

TreeNodeBinding()

Initializes a new instance of the TreeNodeBinding class.

Properties

DataMember	Gets or sets the value to match against a Type property for a data item to determine whether to apply the tree node binding.
Depth	Gets or sets the node depth at which the TreeNodeBinding object is applied.
FormatString	Gets or sets the string that specifies the display format for the text of a node to which the TreeNodeBinding object is applied.
ImageToolTip	Gets or sets the ToolTip text for the image that is displayed next to a node to which the TreeNodeBinding object is applied.
ImageToolTipField	Gets or sets the name of the field from the data source to bind to the ImageToolTip property of a TreeNode object to which the TreeNodeBinding object is applied.
ImageUrl	Gets or sets the URL to an image that is displayed next to a node to which the TreeNodeBinding object is applied.
ImageUrlField	Gets or sets the name of the field from the data source to bind to the ImageUrl property of a TreeNode object to which the TreeNodeBinding object is applied.
NavigateUrl	Gets or sets the URL to link to when a node to which the TreeNodeBinding object is applied is clicked.
NavigateUrlField	Gets or sets the name of the field from the data source to bind to the NavigateUrl property of a TreeNode object to which the TreeNodeBinding object is applied.
PopulateOnDemand	Gets or sets a value indicating whether the node to which the TreeNodeBinding object is applied is populated dynamically.
SelectAction	Gets or sets the event or events to raise when a node to which the TreeNodeBinding object is applied is selected.
ShowCheckBox	Gets or sets a value indicating whether a check box is displayed next to a node to which the TreeNodeBinding object is applied.
Target	Gets or sets the target window or frame in which to display the Web page content that is associated with a node to which the TreeNodeBinding object is applied.
TargetField	Gets or sets the name of the field from the data source to bind to the Target property of a TreeNode object to which the TreeNodeBinding object is applied.
Text	Gets or sets the text that is displayed for the node to which the TreeNodeBinding object is applied.
TextField	Gets or sets the name of the field from the data source to bind to the Text property of a TreeNode object to which the TreeNodeBinding object is applied.
ToolTip	Gets or sets the ToolTip text for a node to which the TreeNodeBinding object is applied.
ToolTipField	Gets or sets the name of the field from the data source to bind to the ToolTip property of a TreeNode object to which the TreeNodeBinding object is applied.
Value	Gets or sets a displayed value that is not displayed but is used to store any additional data about a node to which the TreeNodeBinding object is applied, such as data used for handling postback events.
ValueField	Gets or sets the name of the field from the data source to bind to the Value property of a TreeNode object to which the TreeNodeBinding object is applied.

Methods

Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToString()	Returns the DataMember property.

Explicit Interface Implementations

ICloneable.Clone()	Creates a copy of the TreeNodeBinding object.
IDataSourceViewSchemaAccessor.DataSourceViewSchema	For a description of this member, see DataSourceViewSchema.
IStateManager.IsTrackingViewState	For a description of this member, see IsTrackingViewState.
IStateManager.LoadViewState(Object)	Loads the previously saved view state for the node.
IStateManager.SaveViewState()	Saves the view state changes to an object.
IStateManager.TrackViewState()	Instructs the TreeNode object to track changes to its view state.

Applies to

Jaa