Class: cWebTreeView
Properties | Events | Methods | Index of Classes
The Web Framework treeview control
Hierarchy
cObject > cWebBaseObject > cWebObject > cWebBaseUIObject > cWebBaseDEOServer > cWebBaseControl > cWebTreeView
Show full hierarchy and direct subclasses
Library: Web Application Class Library
Package: cWebTreeView.pkg
Description
Use the cWebTreeView class to display a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and folders on a disk. Each item consists of a label and an image, and each item can have a list of sub-items associated with it. By clicking an item, users can expand and collapse the associated list of sub-items.
Sample
This example demonstrates a treeview object that is populated with two root items (labeled "Environment" and "Editor"). Each root item also contains multiple child items.
The OnLoadChildNodes event is used to populate the treeview. This event will pass back an array of tree items. Each member of the array describes a single item in the treeview. See Creating the Tree Items (below) for more information.
Object oCategoryTree is a cWebTreeView
Set pbServerOnSelect to True
Function OnLoadChildNodes String sId String sValue ;
Integer iLevel Returns tWebTreeItem[]
tWebTreeItem[] aItems
// Populate Root Level Items
// ~~~~~~~~~~~~~~~~~~~~~~~~~
If (iLevel = 0) Begin
Move 10 to aItems[1].sId
Move sId to aItems[1].sParentId
Move "Environment" to aItems[1].sName
Move True to aItems[1].bLoadChildren
Move True to aItems[1].bFolder
Move (WebObjectName(oGeneral)) to aItems[1].sValue
Move 20 to aItems[2].sId
Move sId to aItems[2].sParentId
Move "Editor" to aItems[2].sName
Move True to aItems[2].bLoadChildren
Move True to aItems[2].bFolder
Move (WebObjectName(oEditor)) to aItems[2].sValue
End
Else Begin
// Populate Sub-pages
// ~~~~~~~~~~~~~~~~~~
Case Begin
Case (sID = 10)
Move 11 to aItems[0].sId
Move sId to aItems[0].sParentId
Move "General" to aItems[0].sName
Move False to aItems[0].bLoadChildren
Move False to aItems[0].bFolder
Move (WebObjectName(oGeneral)) to aItems[0].sValue
Move 12 to aItems[1].sId
Move sId to aItems[1].sParentId
Move "Layout" to aItems[1].sName
Move False to aItems[1].bLoadChildren
Move False to aItems[1].bFolder
Move (WebObjectName(oLayout)) to aItems[1].sValue
Case Break
Case (sID = 20)
Move 21 to aItems[0].sId
Move sId to aItems[0].sParentId
Move "Editor" to aItems[0].sName
Move False to aItems[0].bLoadChildren
Move False to aItems[0].bFolder
Move (WebObjectName(oEditor)) to aItems[0].sValue
Move 22 to aItems[1].sId
Move sId to aItems[1].sParentId
Move "Misc" to aItems[1].sName
Move False to aItems[1].bLoadChildren
Move False to aItems[1].bFolder
Move (WebObjectName(oMisc)) to aItems[1].sValue
Case Break
Case End
End
Function_Return aItems
End_Function
Procedure OnSelect String sId String sValue Integer iLevel
Handle hoCard
Forward Send OnSelect sId sValue iLevel
If (sValue <> "") Begin
// Show the object pointed to by sValue
Get WebObjectByName sValue to hoCard
If (hoCard <> 0) Begin
Send Show to hoCard
End
End
End_Procedure
End_Object
Object Name
The Web Framework uniquely identifies each web object via a combination of the object hierarchy (object nesting), and object name. This means that web object names must be unique within their parent (i.e. each sibling web object must have a unique name).
Object Placement
Treeview controls must be placed within a web container (e.g. cWebPanel, cWebView or cWebModalDialog).
Treeview controls may not be nested inside other web controls. You may not mix web panels and web controls as sibling objects.
WebContextMenu Support
cWebContextMenu support is provided through the C_WebUIContextTreeviewFolder and C_WebUIContextTreeviewItem Contexts, then the psContextValue property will be filled with a comma separated list of items.
Creating the Tree Items
The OnLoadChildNodes event is used to populate the treeview. This event will pass back an array of tree items. Each member of the array describes a single item in the treeview.
Each item is assigned a unique ID. This can be any value and is used to identify each individual tree item.
The OnLoadChildNodes event works in two phases: - The first phase is when the treeview object is first loaded to the client. The OnLoadChildNodes event is called and will load the treeview's root items. In this phase, the passed iLevel parameter is 0. This value is tested to determine which tree items to send back to the client. - The second phase is called each time a tree item is expanded. In this case the passed iLevel parameter represents tree level that is being expanded and the passed sID value is the item ID of the parent tree item that is being expanded. This information is used at the server to determine which tree items should be passed back to the client when a particular item is expanded.
Each tree item can be assigned the following information: - sID - This can be any string or numeric value that uniquely identifies the tree item. This must be assigned during OnLoadChildNodes. - sParentID - This is the ID of the parent tree item, or 0 if it is a root item. You should set this to the sID parameter passed into OnLoadChildNodes. - sName - This is the label that will be displayed in the treeview for each tree item. - sAltText - This is displayed as a tooltip when the mouse is hovered over a tree item. - sValue - This is an optional piece of data pertaining to the tree item. This can be used to store application specific data. - sCSSClass - This is an optional CSS class that can be applied to the tree item. The CSS class should be defined somewhere in your Web Application CSS (usually in your application.css file). - sIcon - This is the name of an image file that can be displayed for a tree item. If you leave this blank then a pre-defined image will be shown. The pre-defined image is based on the current theme CSS (psTheme) and whether the item represents a folder or not. - bFolder - Set this value to True or False: True indicates that the tree item represents a folder (or branch), False indicates that the tree item represents a leaf. This is used to determine which icon will be used from the current CSS theme to represent the item (assuming the sIcon member is not specified). - bLoadChildren - Set this to True to indicate that the tree item can be expanded to reveal child tree items (i.e. the item is expandable). - bExpanded - Do not set this member directly. This will be assigned by the framework. If True, it indicates that the tree item is currently in the expanded state.
Inserting Tree Items
Send InsertNode to add a new node to a treeview.
Object oTree is a cWebTreeView
{ WebProperty=True }
Property Integer piNextID 100
// ...
End_Object
Object oAddChildBtn is a cWebButton
Set piColumnSpan to 1
Set piColumnIndex to 1
Set psCaption to "Add Child"
Procedure OnClick
tWebTreeItem TreeNode
Integer iID
String sID sParentID
WebGet psSelectedId of oTree to sParentID
WebGet piNextID of oTree to iID
WebSet piNextID of oTree to (iID + 1)
Move iID to sID
Move sID to TreeNode.sId
Move sParentID to TreeNode.sParentId
Move ("Root " + sID) to TreeNode.sName
Move False to TreeNode.bFolder
Send InsertNode of oTree TreeNode
End_Procedure
End_Object
In the above example, the OnClick event of the button object creates a new tree item in the cWebTreeView object as a child of the currently selected tree item. The web property psSelectedID is retrieved to get the item ID of the currently selected tree item. A custom web property (piNextID) has been created to maintain the next sequential ID to use when creating a new item.
Removing Tree Items
Send RemoveNode to remove a tree item and all of its child items.
Object oRemoveBtn is a cWebButton
Set piColumnIndex to 2
Set psCaption to "Remove"
Procedure OnClick
String sID
WebGet psSelectedId of oTree to sID
Send RemoveNode of oTree sID
End_Procedure
End_Object
In the above example the button object's OnClick event has been coded to remove the currently selected item of the tree view object (oTree).
Updating Tree Items
Send UpdateNode to modify a single tree item.
Send UpdateSubNodes to replace all children of a given tree item with a new set of child items.
Send FullRefresh to replace all items in the treeview. This will first remove all tree items, then call the OnLoadChildNodes event to re-populate the root items.
Accessing the Selected Items
Item selection can be handled on the server by writing DataFlex code. Item selection can also be handled on the client (browser) by writing JavaScript code. Writing a server-side DataFlex handler is the simplest way to handle item selection events.
Set pbServerOnSelect to True to enable the OnSelect event at the server. By default, this property is False, which disables the server OnSelect event. Write an OnSelect event handler in your treeview object to perform some action whenever a new tree item is selected. The OnSelect event is passed the ID, value and tree level of the selected item.
To write a client-side button click handler using JavaScript, set the psClientOnSelect property to the name of the JavaScript function that will execute when a new tree item is selected.
Manipulating the Tree Items
Send Expand to expand a single tree item and display its child items (if any).
Send Collapse to collapse a single tree item.
Send CollapseAll to collapse all parent tree items. Only the root items will be shown.
Send Select to programmatically select a tree item.
Size and Location
Web controls are positioned by HTML flow layout (left to right, top to bottom). The relative position of the control in this flow is determined by the location of the object declaration in your code.
In addition to the flow layout, each web container is divided into a fixed number of equal-width columns (piColumnCount). Child controls are aligned to these columns to determine their horizontal position and width.
Set piColumnIndex to position a treeview control in a particular column of the parent container.
Set piColumnSpan to determine the width of the treeview control i.e., the number of columns occupied by the control. The actual width is determined by the number of columns and the width of the parent container.
For more information, see Positioning and Layout of Controls.
Each treeview control has a pre-determined height according to the web application's CSS theme (psTheme). Set piHeight to override the default treeview height. You can also configure a treeview control to occupy all available vertical height in its parent container by setting pbFillHeight to True.
Label Support
By default a portion of the control's width is reserved to display a descriptive label. By default, the label is displayed to the left of the control and consumes approximately 120px of the total width.
Set psLabel to the text string you want to display as a label.
Set peLabelAlign to position the label text to the left, right or center of the space allocated to the control's label (alignLeft, alignRight, alignCenter).
Set peLabelPosition to change the position of the space allocated to the control's label. By default, the label is positioned to the left of the control (lpLeft). The label can also be positioned above or to the right of the control (lpTop, lpRight).
Set piLabelOffset to change the amount of space that is consumed by the control's label. By default, the label consumes approximately 120px.
The label's text color is determined by the web application's CSS theme (psTheme). Set psLabelColor to directly override the label's CSS themed color.
Set pbShowLabel to False to hide the label and remove space used the control's label. By default pbShowLabel is True.
Drag and Drop Support
Drag Support
This control allows parts of itself to be picked up and dragged to other places in your interface. To do this, register it as a drag source in a cWebDragDropHelper.
Supported drag actions for this control are: - C_WebDragTreeviewFolder, C_WebDragTreeviewItem
Drop Support
This control can be used as a valid drop target by registering it as such in a cWebDragDropHelper object.
The supported drop actions for this control are: - C_WebDropOnControl, C_WebDropTreeviewRoot, C_WebDropTreeviewFolder, C_WebDropTreeviewItem
File Drop Support
This allows the control to accept data dragged from elsewhere in the control (if configured that way) and can also be used to accept files when registered within a cWebDragDropFileHelper.
Color and Styling
The color of a treeview control is determined by the web application's CSS theme (psTheme). You can define additional or replacement CSS styles in your web application's application.css file. Set psCSSClass to the CSS class name you would like to be applied to a treeview control. Additionally you can apply an individual CSS style to each item in the treeview (see OnLoadChildNodes).
Set psBackgroundColor to directly override the control's CSS themed color.
You can use pbAllowHtml to apply embedded HTML to the tWebTreeItem.
See Also