Another tree web control for ASP.NET applications

• Download source files - 11.9 Kb
• Download demo project - 79.2 Kb

Introduction

Even if there are many similar controls available, this article proposes another tree Web Control implementation to be used in ASP.NET applications. One of the key differences of my tree implementation (I3HTreeCtrl) is the ability of load the data just when needed. This makes the I3HTreeCtrl suitable when a very large data tree is present.

The data is requested only when the related tree nodes have to be shown; the request occurs via an Event fired by the I3HTreeCtrl Web Control. Basically, the ASP.NET application that uses the I3HTreeCtrl control just needs to handle the OnAddFolders and the OnAddItems events that request respectively the folders and the items (leaves) node under a specific parent node. In addition, a caching mechanism (optional) is foreseen to avoid requesting the same data more than once.

I3HTreeCtrl

Properties

I3HLoadStyle	Defines the loading style of the control: eLoadWhenExpand (default) The control requires tree nodes data only when it needs it; that is, the user opens a node and wants to display its children. eLoadAll The control requires all data the first time it is loaded.
I3HCacheStyle	Enable/disable the control cache: eCacheEnabled (default) Each node is requested only once. eNoCache The control fires the node data request each time the node is shown.
I3HTreeStyle	Set the tree style: eTreeNormal eTreeCheckBox With this style, each item can be either in the checked or unchecked state. The checked/ unchecked states are shown using a specific image.
I3HTreeOrderStyle	Set the tree order style: eTreeFoldersItems Folders are displayed before items. eTreeItemsFolders Items are displayed before folders.
I3HTreeSelectStyle	Set the tree selection style: eTreeSelectNormal Clicking on the folder icon causes the sub-tree to expand or collapse, while clicking on the folder name causes the folder to be selected (the selected style applies). eTreeSelectCollaspeExpand With this style, clicking the folder name causes the sub-tree to expand or collapse.
I3HRootOpenImage	Set the image file to be shown when the root node is expanded.
I3HRootCloseImage	Set the image file to be shown when the root node is collapsed.
I3HFolderOpenImage	Set the image file to be shown when any folder node is expanded.
I3HFolderCloseImage	Set the image file to be shown when any folder node is collapsed.
I3HItemDefaultImage	Set the image file to be shown by default when an item node has to be shown; it is possible to specify a different image for each item, if no image is specified, the default is then used.
I3HItemCheckedImage	Only for eTreeCheckBox style. Set the image file to be shown when an item node is checked.
I3HItemUncheckedImage	Only for eTreeCheckBox style. Set the image file to be shown when an item node is unchecked.
I3HRootKey	Key of the root node.
I3HRootCaption	Caption of the root node.

Methods

SelectNode	Select a Node; it causes the tree to expand in order to make the node visible. The methods work only with nodes that have been already loaded.
GetSelectedNodeKey	Returns the currently selected node key.
GetSelectedNodeCaption	Returns the currently selected node caption.
GetNodeCaption	Returns the node caption of the requested node.
SetNodeCaption	Changes the node caption of the requested node.
SetItemImage	Changes the node image of the requested node. It applies only to items.
IsItemChecked	Returns whether the requested item is checked or not.
CheckItem	Checks the requested item.
GetCheckedItemList	Returns an array of all the currently checked items.
ClearCheckItemList	Un-checks all the items.
GetTreeObject	Returns the I3HTree object.

Events

OnAddFolders	Fires when the tree control needs folder information. The parent node key is provided. The called component has to fill some arrays with children folder keys and captions.
OnAddItems	Fires when the tree control needs folder information. The parent node key is provided. The called component has to fill some arrays with children items' keys and captions.
OnSelectChange	Fires when the selected node changes.
OnNodeCollaspe	Fires when a node is collapsed.
OnNodeExpanded	Fires when a node is expanded.
OnNodeChecked	Fires when a node is checked.
OnNodeUnchecked	Fires when a node is unchecked.

How to use the I3HTreeCtrl

Using the I3HTreeCtrl is very simple. You just need to add a reference to the I3HTreeCtrl.dll in your project; then a new icon will be shown in the Web Forms toolbox. Then, you can simply drag & drop the control in a Web Form.

Once you have done, a code line similar to the following shall appear in the "Web Form Designer Generated Code" region.

Protected WithEvents i3htree As I3HTreeCtrl.I3HTreeCtrl

In the Page_Load method, you can set any control property for deciding the tree behavior or for changing default CSS styles or images. For instance:

i3htree.I3HRootCaption = "my products"
i3htree.I3HRootKey = "MyRootKey"
i3htree.I3HTreeStyle = enumTreeStyle.eTreeCheckBox

The layout of the tree can be changed acting on the CSS styles and on the images. The page you are working on shall include a CSS file:

<LINK href="i3htree.css" type="text/css" rel="stylesheet">

The file contains the styles related to the tree objects that are defined in the control properties.

To create the tree, you need to put your code in the IH3TreeCtrl's two main event handlers: OnAddFolders and OnAddItems. The folders are tree nodes that can be expanded and collapsed while the items are the leaves of the tree.

Private Sub i3htree_OnAddFolders( _
              ByVal sParentKey As String, _
              ByRef aKey As System.Collections.ArrayList, _
              ByRef aCaption As System.Collections.ArrayList) _
              Handles i3htree.OnAddFolders

This method is called when the user expands a sub-tree under the node identified by the sParentKey string, the first time the method is called using the root key (by default it is ROOT, but it can be changed using the I3HRootKey property).

The called application shall fill the aKey and aCaption arrays. The aKey values will be used in the subsequent OnAddFolder and OnAddItems events while aCaption values are the displayed tree node descriptions.

Private Sub i3htree_OnAddItems( _
              ByVal sParentKey As String, _
              ByRef aKey As System.Collections.ArrayList, _
              ByRef aCaption As System.Collections.ArrayList, _
              ByRef aImage As System.Collections.ArrayList, _
              ByRef aLink As System.Collections.ArrayList, _
              ByRef aTarget As System.Collections.ArrayList) _
              Handles i3htree.OnAddItems

As the previous one, this method is called when the user expands a sub-tree.

For each item, the called applications can specify the key, the caption, the image (if it differs from the default images specified in the tree properties), the link address, and the link target.

I3HTreeCtrl Sample application

The sample application is the application I used mostly for testing. It shows some of the functionalities of the I3HTreeCtrl.

I3HTreeCtrl Demo1 application

The Demo1 application shows how to use the I3HTreeCtrl control for a simple forum application.

The topics and the message subjects are treated as folders while the message texts are the items.

The I3HTreeCtrl control is setup as follows:

i3htree.I3HTreeOrderStyle = _
               enumTreeOrderStyle.eTreeItemsFolders

i3htree.I3HTreeSelectStyle = _
               enumTreeSelectStyle.eTreeSelectCollaspeExpand

Using the eTreeItemFolders style, the items (that are the message texts) are shown before the folders (that are the replies to the message).

The eTreeSelectCollapseExpand makes the tree expand and collapse either when the user clicks on the folder icon or clicks on the folder name.

The application stores the data into a MS Access database named I3TreeDemo1.mdb.

Private Sub i3htree_OnAddFolders(ByVal sParentKey As String, _
              ByRef aKey As System.Collections.ArrayList, _
              ByRef aCaption As System.Collections.ArrayList) _
              Handles i3htree.OnAddFolders

// Open the database connection
Dim cnt As New OleDb.OleDbConnection
cnt.ConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=" + _
                       System.Web.HttpRuntime.AppDomainAppPath + _
                       "I3HTreeDemo1.mdb"
 
cnt.Open()

Dim ds As Data.DataSet = New Data.DataSet
Dim adp As OleDb.OleDbDataAdapter = New OleDb.OleDbDataAdapter
 
If sParentKey = "ROOT" Then
   ' the parent is the ROOT
   ' under the root there are only folders that correspond
   ' to the topics list
ElseIf sParentKey.Chars(0) = "T" Then
   ' the parent is a topic
   ' under each topic there are messages that are folders
ElseIf sParentKey.Chars(0) = "M" Then
   ' the parent is a message
   ' under a message there are the message replies that
   ' that are represent by folders with the subject as folder name
End If
 
Cnt.Close()
  
End Sub

I3HTreeCtrl Demo2 application

The Demo2 application shows how to use the I3HTreeCtrl control for a simple shopping cart application with multiple products selection. The check box style tree is demonstrated here.

The application stores the data into a MS Access database named I3TreeDemo2.mdb.

The product categories are the folders while the products are the leaves. The tree uses the eTreeCheckBox style, so besides each item, the check box is present.

Clicking the Order button causes all the selected products to be moved in the list box. The list of selected products is obtained using the GetCheckedItemList method; after copying the selected products, the tree selections are cleared using the ClearCheckedItemList method.

Dim aOrder As Collections.ArrayList
i3htree.GetCheckedItemList(aOrder)
lstProducts.Items.Clear()
 
Dim i As Int32
For i = 0 To aOrder.Count - 1
   Dim itm As I3HTreeCtrl.CI3Item
   itm = i3htree.GetTreeObject().FindNode(aOrder(i))
   lstProducts.Items.Add(itm.GetCaption())
Next
 
i3htree.ClearCheckedItemList()

The above code lines show how to get node information from the key. This has to be done in 2 steps: first get the CI3Tree object instance using the GetTreeObject method of the I3HTreeCtrl, then get the CI3Node instance using the FindNode method.