I3HTree – Html Tree + Html Grid Web Control

• Download source files - 26 Kb
• Download demo project - 50 Kb

Latest Update

Release 0.22

This version adds a new control setting (I3HGridSaveStyle) that let you decide if the OnGridItemsValueChange event is fired only when a page submit is invoked or whenever a control value is changed. The latter option allows you to change the value of any cell of the grid when the user edits a cell value (for instance in the MyOrderForm sample the row total cell changes whenever the user edits the quantity text box).

In addition it fixes an annoying bug related to the use of the control inside a C# project. To solve it I had to change the name of the control that now is I3HTreeCtrl.I3HTree.

See History section below for further details.

Introduction

This article presents the new version of I3HTree control; the first version can be found in a previous article:

• http://www.codeproject.com/aspnet/i3htree.asp

I created a new article instead of updating the previous because this new release of the control is completely different from the first one. I consider the first release of I3HTree a kind of experiment, from that I started developing this new version adding new features and changing some of the exiting. I also re-organized (and re-named) the interface methods for cleaning reasons.

Now I feel that the control has a cleaner architecture and I can build up new functions on it without changing the base anymore (or at least without any deep impact on existing interfaces).

One of the biggest improvement was integrating an Html Data Grid with the Html Tree as shown in the next picture.

The main idea of the control is still the same: the data are requested only when the related tree nodes or grid rows have to be shown; the ability of loading the data just when needed makes the I3HTreeCtrl suitable when a very large data tree is present.

The data 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 a set of events depending on the control style he wants to use; for instance the OnShowTreeFolders and the OnShowTreeItems events request respectively the tree folders and the tree items (leaves) node under a specific parent node.

A caching mechanism (optional) is foreseen to avoid requesting the same data more than once.

Tree styles

Standard Tree Style

The Standard Style consists of a standard Html Tree. The Tree is made up by Folders and Tree Items.

A Folder is represented by a key (unique), a caption, images (when the folder is open, close or empty) and css styles (when the folder is selected or not). A folder can be expanded and collapsed. A Tree Item is represented by a key (unique), a caption, an image, a link (url and target) and css styles (when the folder is selected or not).

Check-Box Tree Style

The Check-Box Style consists of an Html Tree with a check-box control associated to each tree item. The check-box is implemented using the Html input tag; this means that the tree items can be checked and/or unchecked without reloading the page. In addition an image can be still associated to each item.

Explorer Style

The Explorer Style consists of an Html Tree control plus an Html Grid control. The format (columns number and style) and the data depend on the selected folder in the tree.

Each time a folder is selected the grid is refreshed. As for the Html Tree the Html Grid has and integrated caching mechanism. The Html Grid supports different column types: normal (any Html code, typically a simple text), link, image, image link, check-box, text-box, combo-box.

I3HTreeCtrl class

It is the class that represents the Html Web Control; it inherits from System.Web.UI.WebControls.WebControl and it implements the IPostBackEventHandler interface.

Properties

I3HTreeStyle	Set the tree style: eTreeNormal eTreeCheckBox The control requires all data the first time it is loaded. eTreeExplorer Html Tree plus Html Grid.
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 displays it 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.
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.
I3HFolderEmptyImage	Set the image file to be shown when a folder contains no items.
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, it no image is specified the default is then used.
I3HCssTableStyle	Css style of the main table that contains both the Html Tree and the Html Grid.
I3HCssTreeTableStyle	Css style of the Html Tree table.
I3HCssGridTableStyle	Css style of the Html Grid table.
I3HCssTDFolderStyle	Default Css style of a Folder table cell.
I3HCssAFolderStyle	Default Css style of a Folder link.
I3HCssAFolderSelectedStyle	Default Css style of a selected Folder link.
I3HCssTDItemStyle	Default Css style of an Item table cell.
I3HCssAItemStyle	Default Css style of an Item link.
I3HCssAItemSelectedStyle	Default Css style of a selected Item link.
I3HRootKey	Key of the root node.
I3HRootCaption	Caption of the root node.

Methods

GetSubmitUrl	Returns the Url that has to call in order to force the saving process of the Html Grid form controls.
GetTreeObject	Returns the I3HTree object.

Events

OnShowTreeFolders	Fires when the tree control needs folders information. The parent node key is provided. The called component has to fill some arrays with children folders keys and captions.
OnShowTreeItems	Fires when the tree control needs items information. The parent node key is provided. The called component has to fill some arrays with children items keys and captions.
OnShowGridItems	Fires when a tree folder is selected in the Explorer style. The parent node key is provided. The called component has to fill the array with the children item keys.
OnShowGridItemValue	Fires when a normal cell has to be filled.
OnShowGridItemLinkValue	Fires when a link cell has to be filled.
OnShowGridItemImageValue	Fires when an image cell has to be filled.
OnShowGridItemImageLinkValue	Fires when an image link cell has to be filled.
OnShowGridItemCheckValue	Fires when a check-box cell has to be filled.
OnShowGridItemTextValue	Fires when a text-box cell has to be filled.
OnShowGridItemComboValue	Fires when a combo-box cell has to be filled.
OnTreeItemsCheckChange	Fires on the page postback providing the list of nodes that have been checked or unchecked.
OnGridItemsValueChange	Fires on the page postback providing the list of node values that have been changed.
OnSelectChange	Fires when the selected node changes.
OnNodeCollaspe	Fires when a node is collapsed.
OnNodeExpand	Fires when a node is expanded.

CI3Tree class

It is the main object where the Html Tree and Html Grid formats and data are stored.

Methods

GetSelectedNodeKey	Returns the current selected node key.
GetSelectedNodeCaption	Returns the current selected node caption.
SelectNode	Select a Node; it causes the tree to expand in order to make the node visible. The methods works only with node that have been already loaded.
GetNodeCaption	Returns the node caption of the requested node.
SetNodeCaption	Change the node caption of the requested node.
IsItemChecked	Returns whether the requested item is checked or not.
CheckItem	Check the requested item.
GetCheckedItemList	Returns an array of all the currently checked items.
ClearCheckItemList	Un-checks all the items.
ClearTreeNodes	Clear all the tree nodes.
AddRoot	Add a root node to the tree.
AddFolder	Add a folder node to the tree.
AddTreeItem	Add a tree item node to the tree.
DeleteNode	Delete a node from the tree.
FindNode	Retrieve a node object giving its key.
AddGridType	Add a grid definition.
FindGridType	Retrieve a grid type giving its key.

CI3Node class

It represents a generic Html Tree node; it is the base class of all other Html Tree classes: CI3Folder, CI3ItemTree, CI3ItemGrid.

Properties

Key	Unique node key.
Caption	Node caption.
Level	Tree hierarchical level (1 is the root, 2 the first level children, and so on).
Parent	Reference to the parent node.
Tree	Reference to CI3Tree object.

Methods

SelectNode	Selects the node.
GetItemData	Returns the internal object related to the tree node.
SetItemData	Sets a data object to be associated with the tree node.

CI3Folder class

It represents an Html Tree folder; a folder contains tree items and can be expanded and collapsed.

Properties

Expanded

Returns the expanded or collapsed state.

Methods

CollapseNode	Collapse the folder.
ExpandNode	Expand the folder.

CI3ItemTree class

It represents an Html Tree item; an item can be configured with an image and/or a link to a Url (href + target).

Properties

Image	Image file associated.
HRef	HRef of the link.
Target	Target of the link.

Methods

IsChecked	Only for Check-Box style. Return true if the item is currently checked.
CheckNode	Only for Check-Box style. Check or uncheck the node.

CI3ItemGrid class

It represents an Html Grid item. The grid item corresponds to a row of the Html Grid; it stores the value for each grid column.

Methods

AddItemValue	Add a new CI3ColValue object that represents the value of a specific grid cell.
GetItemValue	It retrieves a reference to the CI3ColValue object that represents the value of a specific grid cell.

CI3Grid class

It represents an Html Grid. The I3HTree control supports different grid formats, one per each tree folder.

Properties

GridTypeId	String that identifies the grid type.
Cols	Returns the grid columns collection.
Caption	Grid caption.
CSSCaptionStyle	Grid caption Css style.

Methods

AddColumn	Add a column header definition to a specific grid.
ClearColumns	Clear all columns.

CI3ColHeader class

It represents the definition of a column of the Html Grid.

Properties

No	Column index.
HeaderText	Column header text.
ColumnType	Column type: normal, link, image, image link, text-box, combo-box, check-box.
HeaderType	Header type, normal, sort.
TDWidth	Column width.
TDCssStyle	Column Css style.

Methods

AddComboItem	Add a combo-box item to a column (of combo-box type).
EnumComboItem	Initialize the combo-box items enumerator.
GetNextComboItem	Retrieve a combo-box item from the enumerator.
ClearComboItems	Clear the combo-box items.

CI3ColValue class

It represents a data grid cell value.

Properties

ColNo	Index of the related column.
ColHeader	Column type of the related column.

Methods

GetValue	Returns the cell value for any cell type.
GetDisplayValue	Returns the cell display value. The display value can be used for formatting fields like currencies or date.
SetValue	Set the Value and the Display Value of a cell.
GetLink	Returns the cell value for link and image-link styles.
SetLink	Sets the cell value for link and image-link styles.
GetImage	Returns the cell value for image and image-link styles.
SetImage	Sets the cell value for image and image-link styles.
SetStyle	Sets the Css styles.

How to use the I3HTreeCtrl

Setting styles and attributes

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 event handler 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"<br>i3htree.I3HRootKey = "MyRootKey"<br>i3htree.I3HTreeStyle = I3HTreeCtrl.I3HTreeCtrl.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.

Creating the tree

To create the tree you need to put your code in the IH3TreeCtrl two main event handlers: OnShowFolders<CODE> and OnShowTreeItems. The folders are tree nodes that can be expanded and collapsed while the items are the leaves of the tree.

OnShowTreeFolders(ByVal sParentKey As String, _
                  ByRef aKey As System.Collections.ArrayList, _
                  ByRef aCaption As System.Collections.ArrayList, _
                  ByRef aTDClass As System.Collections.ArrayList, _
                  ByRef aAClass As System.Collections.ArrayList, _
                  ByRef aASelectedClass As System.Collections.ArrayList) _
                  Handles i3htree.OnShowTreeFolders

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 call using the root key (by default is ROOT but it can be changed using the I3HRootKey property).

The called application shall fill the aKey, aCaption, aTDClass, aAClass, and aSelectedClass arrays. The aKey values will be used in the subsequent OnShowFolder and OnShowTreeItems events while aCaption values are the displayed tree node descriptions. The aTDClass, aAClass, and aSelectedClass arrays specify the css style to be used for the table cell (<td> tag), the link (<a> tag) and the link when the folder is selected.

OnShowTreeItems(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, _
                ByRef aTDClass As System.Collections.ArrayList, _
                ByRef aAClass As System.Collections.ArrayList, _
                ByRef aASelectedClass As System.Collections.ArrayList) _
                Handles i3htree.OnShowTreeItems

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.

Using the CheckBox Style

The CheckBox style let associated a check-box to each Tree Item. The control stores the checked items, to get the list at any time use the GetCheckedItemList method and to free the list use the ClearCheckedItemList method.

A single item can be checked, unchecked using the CheckItem method.

Defining grid columns

When the Explorer Style is set it is possible to define grid columns as shown in the following code:

Dim col As I3HTreeCtrl.CI3ColHeader
Dim sTypeId As String = "coltypeproducts"
<br>col = New I3HTreeCtrl.CI3ColHeader(sTypeId, _
                0, _
                "", _
                I3HTreeCtrl.CI3Tree.enumColumnType.eColImage, _
                I3HTreeCtrl.CI3Tree.enumHeaderType.eHeaderNormal, _
                "50", _
                "i3hTDHeader")<br>i3htree.GetTreeObject().AddColumn(col)

The first parameter sTypeId allows grouping columns that belong to the same Html Grid. The control allows defining different grids so that it is possible to associate a different grid for different Tree Folder.

Other column attributes are: the position, the header, the type (normal, image, image link, link, text-box, check-box, combo-box), the header style (normal or sort), the width, and the css style.

Creating the grid

The grid is created handling the OnShowGridItems and the OnShowGridItemXValue.

The OnShowGridItems is fired when a folder on the tree is selected.

OnShowGridItems(ByVal sParentKey As String, _
  ByRef sGridTypeId As String, _
  ByRef aKey As System.Collections.ArrayList) _
  Handles i3htree.OnShowGridItems

The application that handles the method provides the grid type (in this way the grid columns are defined) and the array of item keys (in this way the grid rows are defined). Then the control fires the OnShowGridItemXValue for each grid cell depending on the columns type. The complete list of methods is:

• OnShowGridItemValue()
• OnShowGridItemLinkValue()
• OnShowGridItemImageValue()
• OnShowGridItemImageLinkValue()
• OnShowGridItemTextValue()
• OnShowGridItemComboValue()

Saving user edited data

The data that the user may edit using the grid controls (text-box, check-box, combo-box) are automatically saved on each PostBack event (for instance when the tree selection is changed). In addition the saving process can be forced; to this aim the control provides a GetSubmitUrl method. The submit Url can be assigned to an hyperlink control in the following way:

hypUpdate.NavigateUrl = i3htree.GetSubmitUrl

In this way by clicking on the hypUpdate link the user forces the saving process.

MyOrderForm Sample application

The MyOrderForm application is a sample application that shows how to use the I3HTreeCtrl with the Explorer style.

The application shows an Html Tree representing a products catalog; each tree folder represents a product category and by selecting a folder the Html Grid shows the products (image, code, name, price, size, and quantity are provided). To order the user has to set the quantity of the product he wants to order.

In the Page_Load events the control attributes are set and the grid columns are defined. The code has to be executed only once so it has to be skipped when the load event is triggered by a PostBack.

If Not Me.IsPostBack Then

   'just the first time
   'set the tree attributes

   i3htree.I3HRootCaption = "my products"
   i3htree.I3HTreeStyle = I3HTreeCtrl.CI3Tree.enumTreeStyle.eTreeExplorer
   i3htree.I3HTreeSelectStyle =
      I3HTreeCtrl.CI3Tree.enumTreeSelectStyle.eTreeSelectExpand

   'create the grid columns

   Dim sTypeId As String = "coltypeproducts" 'typeId is always the same!
   Dim col As I3HTreeCtrl.CI3ColHeader
       
   col = New I3HTreeCtrl.CI3ColHeader(sTypeId, _
               0, _nbsp;           0, _
               "", _
               I3HTreeCtrl.CI3Tree.enumColumnType.eColImage, _
               I3HTreeCtrl.CI3Tree.enumHeaderType.eHeaderNormal, _
               "50", _
               "i3hTDHeader")
               i3htree.GetTreeObject().AddColumn(col)
   ...
   ...
   ...
   'add combo column
   col = New I3HTreeCtrl.CI3ColHeader(sTypeId, _
               4, _nbsp;           4, _
               "size", _
               I3HTreeCtrl.CI3Tree.enumColumnType.eColComboBox, _
               I3HTreeCtrl.CI3Tree.enumHeaderType.eHeaderNormal, _
               "5%", _
               "i3hTDHeader")
           
   i3htree.GetTreeObject().AddColumn(col)
   col.AddComboItem(1, "small")
   col.AddComboItem(2, "medium")
   col.AddComboItem(3, "large")
End If

Once the tree and grid attributes have been defined the I3HTreeCtrl fires events when data is needed according to the user actions.

The tree is created by handling the OnShowTreeFolders event; note that using the Explorer style the OnShowTreeItems will never be called.

Private Sub i3htree_OnShowTreeFolders(ByVal sParentKey As String, _
  ByRef aKey As System.Collections.ArrayList, _
  ByRef aCaption As System.Collections.ArrayList, _
  ByRef aTDClass As System.Collections.ArrayList, _
  ByRef aAClass As System.Collections.ArrayList, _
  ByRef aASelectedClass As System.Collections.ArrayList) _
  Handles i3htree.OnShowTreeFolders;
 
   Handles i3htree.OnShowTreeFolders

   Dim nParentID As Int32

   If sParentKey = "ROOT" Then
      nParentID = 0
   ElseIf sParentKey.Chars(0) = "C" Then
      nParentID = Convert.ToInt32(sParentKey.Substring(1))
   Elsenbsp; Else
      Return
   End If

   Dim cnt As New OleDb.OleDbConnection
   cnt.ConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0;
     Data Source=" + System.Web.HttpRuntime.AppDomainAppPath +
     "MyOrderForm.mdb"
   cnt.Open()

   Dim ds As Data.DataSet = New Data.DataSet
   Dim adp As OleDb.OleDbDataAdapter = New OleDb.OleDbDataAdapter

   'get topics listopics list
   adp.SelectCommand = New OleDb.OleDbCommand
   adp.SelectCommand.CommandText =
"SELECT * FROM tblTree WHERE ParentID = " & nParentID
   adp.SelectCommand.Connection = cnt
   adp.Fill(ds)

   Dim rows As DataRowCollection = ds.Tables(0).Rows
   Dim row As DataRow

   For Each row In rows
      aKey.Add("C" & Convert.ToString(row("ID")))
      aCaption.Add(row("Category"))
   Next

   cnt.Close()
End Sub

The grid is created by handling the OnShowGridItems event; in the event handler method the grid rows number is set. Then the I3HTreeCtrl fires an event per each grid cell according to the cell type (so for instance it fires the OnShowGridItemValue for standard cells, the OnShowGridItemImageValue for image cells, and so on).

The data edited by the user are saved back to the database by handling the OnGridItemsValueChange method.

Private Sub i3htree_OnGridItemsValueChange(
  ByRef aKey As System.Collections.ArrayList, _
  ByRef aCol As System.Collections.ArrayList, _
  ByRef aNewValue As System.Collections.ArrayList) _
  Handles i3htree.OnGridItemsValueChangesp;                           
 Handles i3htree.OnGridItemsValueChange

   Dim i As Int32

   For i = 0 To aKey.Count - 1
      Dim sKey As String = aKey(i)
      Dim nCol As Int32 = aCol(i)
      Dim oValue As Object = aNewValue(i)

      'save to database;  'save to database
      '...
   Next

End Sub

History

To get the latest version

I will post any major version on CodeProject; if you wish to get the code of latest version of the I3HTree just visit www.intre.it/osp.

Release R0.22 (22-Ago-2004)

NOTE:

The control changes its name from I3HTreeCtrl to I3HTree.For existing projects you shall make the following changes:

• In all .vb files you shall change all the declarations from
  Protected WithEvents i3htree As I3HTreeCtrl.I3HTreeCtrl
  to
  Protected WithEvents i3htree As I3HTreeCtrl.I3HTree
• In all .aspx files you shall change all the declarations from
  <cc1:I3HTreeCtrl id="i3htree" runat="server"></cc1:I3HTreeCtrl>
  to
  <cc1:I3HTree id="i3htree" runat="server"></cc1:I3HTree>

Fixed bugs:

• Fixed compilation error that occured when trying to use the component inside a C# project.

New features:

• Added enumGridSaveStyle style. This allow to have a postback anytime a control value (textbox, combobox, checkbox) is changed without having to wait the page submit. This is useful if a cell modification has to trigger another cell modification.
• Changed OnShowGridItemValue and OnShowGridItemTextValue events to support value and display value for handling formatted field like currencies, date, and so on.

Misc changes:

• Class CI3Node, added Tree public property.
• Class CI3ColValue, GetDisplayValue, GetValue, and SetValue methods.

Release R0.21 (09-Jul-2004)

Fixed bugs:

• Tree node item does not create correctly if target attribute is set.
• If more that one grid type is defined the grid columns headers are wrong; to solve the problem and to simply the columns management a new class (CI3Grid) has been added to group column headers.

New features:

• Added ability to set the Grid caption

Release R0.20 (02-Jul-2004)

First release.