By Luke Rocco
In this tutorial we provide a step by step guide on how to implement the jsTree control in DotNetMushroom RAD.
One of the myriad of controls available to DNM RAD, as of version 01.50, is the jsTree Control.
Screenshot of a DNM jsTree control displaying sample data
This control provides the functionality to represent a series of items or data elements in a Tree Format. The data presented can be multi-generational and the navigation between the different levels does not cause postbacks. All sorts of data can be represented in this format, such as different Categories, Articles, or File & Folder structures.
In order to implement this control in any DNM RAD Form, you need to make sure that the basic data requirements are met. The DNM RAD jsTree Control needs the following fields to be available:
- The ID field should contain a Unique Identifier to the item being displayed. It is suggested to make use of the default field ‘PK‘ which DNM RAD creates for each table as this will ensure that a Unique field is provided every time.
- The Title field should contain a short description, preferably just a couple of words long, which will be displayed in the control to represent the Item.
- The Parent field should contain a reference to the ID of the item which serves as a ‘Parent’ of the said item. Should the item in question not have a ‘parent’, then it should provide an ‘Invalid ID’ value, such as 0 or a negative number which does not refer to an existing item.
As long as a DNM RAD Table can provide the above mentioned data, it can be represented in the jsTree control.
Once the back-end is ready, we can concentrate on setting up the jsTree control in the Form. This process is the same as the process by which we add other controls. This means that after accessing the DNM RAD Form, switch to the Templates Tab.
Screenshot of highlighted Template Tab Button
Once there, add the jsTree Control on the Form by either manually typing ‘[DNMTREE::ID=control_id]’, replacing ‘control_id’ tag with the ID of your choice, or else by selecting the DNMTREE option from the ‘Control Type’ Dropdown and entering the Id you wish in the ‘Control Name’ textbox and then pressing Add Control. You should end up with something similar to the following:
Remember that the ID value of ‘tr_Articles’ should be replaced by the value which you have chosen. Next, switch to the Properties Tab again and access the Properties of the jsTree control.
Bind Data Source:
Screenshot of DNM jsTree control properties
Begin by selecting a value for the Bind Data Source property. This property chooses which DNM RAD Table or Query is going to be used as the Data Source for the jsTree Control. The data present in the chosen table will be represented on screen by the jsTree control.
Once the ‘Bind Data Source‘ property is chosen, proceed to select the appropriate columns for the ‘ID Field Source’, ‘Title Field Source’ and ‘Parent Field Source’ properties.
ID Field Source:
The ID Field Source Property should refer to a data column which contains a unique identifier which represents the item in the Table. The default ‘PK’ field which is automatically generated by DNM RAD is the ideal candidate for this property as it will always return a Unique Value.
Title Field Source:
The Title Field Source Property should refer to the data column which contains either the Name or a very short description (a maximum of 3 words) of the item being displayed by the jsTree.
Parent Field Source:
The Parent Field Source Property should refer to the data column which contains a reference to another item which is its parent. Should the Item not have a parent, it should contain either a Null value or a value which is not present in the Table. Zero usually does the trick, however any ‘inexistent ID field value’ works.
Remove Parameters & Navigator Filter:
Once the above mentioned properties are set, proceed to setup the Navigator if needed. Click on the ‘Click here to Add Navigator’ link and construct the navigator you requrie. For further details on how to construct a Navigator refer to DNM RAD User Manual.
The Select Theme Property provides a drop down containing a list of available themes which the jsTree can make use of in order to customize the way it is presented to the user.
These Themes can be found at: “\DesktopModules\DotNetMushroom\js\jsTree\themes“
It is possible to either modify existing themes, or create your own theme by making a copy of one of the existing themes and then modifying it as you please. Should you wish to just amend an existing theme, it is suggested that you keep a backup of the original files, just in case the resulting changes invalidate the files.
If you have any problems working with the DNM RAD module you can visit the DotNetMushroom Forums
Note: The DNM RAD jsTree Control is an implementation and integration of the jsTree library