Tree

Provides an effective method to define and use a tree structure.

Syntax

HTML	<div cordysType="wcp.library.ui.Tree" id=treeID treeData=sData treeSchema=sSchema ></div>

Where treeID denotes the unique identifier of the tree, sData denotes the ID of the data that is to be displayed in the tree, and sSchema denotes the ID of the schema that is defined for the tree.
A tree is constructed by defining a schema that identifies the items that can be contained in the tree. Once a schema is defined, data that is compliant with the tree schema is given as input to the component, which is then displayed in the form of tree.
To dynamically add and initialize this component, you can use the initializeHTMLElements or addType methods of the Application object.
Following are the properties and methods that can be set for the tree.

Table 1.	List of Attributes
Attribute	Property	Description
BusDataIsland	[BusDataIsland	String that points to the unique identifier of the busdataisland from which the data is to be taken for tree.
treeData	N/A	Sets the treeData property, which is a string that points to the unique identifier of an XML object which denotes the Data that is to be displayed in the tree.
treeSchema	N/A	Sets the treeSchema property, which is a string that points to the unique identifier of an XML object which denotes the Schema defined for the tree.

Table 2.	List of Properties
Property	Description
leftFolding	Optional, boolean property that shows the tree left folding. The entire tree is right-aligned and the tree items expand from left to right. The default value is 'false'.

Table 3.	List of Methods
Method	Description
addItem	Adds an item in the tree definition.
addItemBefore	Adds an item before the specified tree Item.
addItems	Adds a collection of items to the root node of the tree.
addSchemaItem	Adds a schema definition to the existing schema dynamically.
getCheckableItems	Returns an array of all (un)checked treeItems in the tree. Only checkable items are returned.
getItem	Searches for the specified item in the tree and returns the first item found.
getItems	Searches for the specified item in the tree and returns all the items as an array.
getRoot	Returns the root element of the tree schema from which tree is defined.
getSelectedItem	Returns the currently selected item in the tree.
getSelectedItems	Returns an array of all the selected items in the tree.
getTreeData	Gets the value of the treeData property.
setTreeData	Sets the treeData property, which is a string that points to the unique identifier of an XML object which denotes the Data that is to be displayed in the tree.
getTreeSchema	Gets the value of the treeSchema property.
setTreeSchema	Sets the treeSchema property, which is a string that points to the unique identifier of an XML object which denotes the Schema defined for the tree.
showItem	Searches for the specified item in the tree, highlights the item, and expands all higher levels till the current tree item. Returns the first item found.

TreeSchema

The schema defined for a tree consists of generic notations which can identify the items that can be present in the tree. In addition to that, it consists of tags which denote properties for an item in a tree. Once the tree schema is defined, the data that is to be displayed in the tree has to be specified (tree Data). The source for tree Data can be an XML document or data obtained from a back-end database. In the latter case, a busdataisland can also be used as a source for tree.
Following are the list of properties defined inside the TreeSchema:

Table 4.	List of Properties used for TreeSchema
Property	Description
background	Optional property that sets the background color of the tree. The value inside this property can be any valid HTML color code. If an invalid value is specified, unexpected errors will occur.
multipleSelect	Optional. Boolean property that defines whether more than one tree nodes can be selected at a time. Multiple items in the tree can be selected by holding the Ctrl key and clicking on the tree nodes. Keyboard navigation is possible after selecting at least one node in the tree. Once selected, multiple selection is possible by holding the Ctrl key and clicking the Down Arrow.
searchPath	Property that denotes the name of the XML Node present in the data that will be assigned to the tree.
updateAllowed	Optional property that defines whether the item descriptions displayed in the tree nodes are editable or not. When set to True, the description is editable and the selected node can be deleted from the tree by pressing the Del key.
useTreeLines	Optional. Boolean property that defines whether the lines connecting the tree Items in the tree can be shown or not.
usePlusIcons	Boolean property that specifies whether the plus/minus icons should be displayed before the tree items. Default value is true, which implies that the icons are displayed by default.

Apart from the above mentioned properties, TreeSchema consists of Root property and one or more TreeItem.

Root (optional)

The Root property of the tree refers to the root element of the tree schema from which tree is defined. This can be accessed from the tree component by using the treeID.getRoot() method. The data property cannot be set for a tree root.
A sample of how the Root can be defined in a TreeSchema is as follows:

<Root>
root description
<description>Certificates</description>
location of the icon to be displayed
<icon>/cordys/wcp/theme/default/icon/authorization/certificates.png</icon>
pointer to the function to be called when the root is selected
<onselect>selectCA</onselect>
</Root>

Here, 'description' is a mandatory property that denotes the description of the root. Once Root is defined in the tree, the following methods are exposed for the root property of the tree.

Table 5.	List of Properties used for Root
Property	Description
checkable	Optional boolean property for which the default value is 'false'. It denotes whether the root can be checked. The value 'true' in the treeschema means that a checkbox is shown.
checkChildren	Optional boolean property for which the default value is 'true'. It denotes whether the child items (and subsequent grand-child items) automatically get the same check status as the root. The value 'true means that the (un)check is passed to all lower levels. Only checkable treeItems get updated. Root or treeItems which are not checkable do support this property. This is applicable when the check-method is applied to a non-checkable root or treeItem. In this case the root or treeItem itself is not checked but its child items can be.
genericDropEnabled	Optional property that allows you to drag any element to the tree. If set to true, it is enabled for all elements in the tree. It is false by default.
ondblclick	Optional property that contains a pointer to the function to be called when the root or a tree item in the tree is double-clicked
onitemchecked	Optional property that contains a pointer to the function to be called when the root or a tree item in the tree is (un)checked.
onselect	Optional property that contains a pointer to the function to be called when the root or a tree item in the tree is selected.

Table 6.	List of Methods used for Root
Method	Description
addItem	Adds an item to the tree node.
addItems	Adds a collection of items to tree node.
changeIcon	Changes the icon of the tree item (Node / Leaf).
changeOpenIcon	Changes the icon of the tree item which has to be displayed when the Node is in the expanded state.
collapse	Collapses the root node of the tree by one level.
collapseAll	Collapses the root node of the tree to all levels recursively.
expand	Expands the root node of the tree by one level.
expandAll	Expands the root node of the tree to all levels recursively.
getChildContainer	Returns the collection of all the child items under the root. It returns NULL if there are no child items. Once getChildContainer method is called, the child nodes under this collection is to be accessed through the childNodes property of the method. The length property of the childNodes will specify the total number of children in the collection.
getTree	Returns the tree definition.
select	selects the specified node in the tree.
showitem	Searches for the specified item in the tree, highlights the item, and expands all higher levels till the current tree item. Returns the first item found.
check( bSelect, <bPassCheck> )	(Un)checks a checkable root. It can also be applied to a non-checkable root to pass the status to the child items. Handles the onitemchecked property. bSelect: Boolean, required. If 'true', the root is checked. If false, the root is unchecked. bPassCheck: Optional boolean, for which the default value is determined by the checkChildren property. The value 'true' means that all the checkable child items are also (un)checked. The value 'false' means that only the root is (un)checked.
getCheckableItems	Returns an array of all (un)checked treeItems and its children. Only checkable items are returned.
isCheckable()	Returns 'true' when the root is checkable (displays a checkbox).
isChecked()	Returns 'true' when the root is checked, 'false' when it is unchecked, and null when it is not checkable.
makeCheckable( bSelect )	Makes the root checkable or removes the checkbox. bSelect: Boolean, required. If 'true', makes it checkable; if 'false', it removes the checkbox.
setClass	Applies a style class to the label of the root.
setLabel( sLabel )	Updates the label of the root.

TreeItem

The TreeItem property denotes the properties that can be defined for each item in the tree. The property defines the way the data is displayed in the tree, and the actions that needs to be performed on clicking on those items.
The TreeItem can be defined for Nodes (tree items with children) and Leaves (tree items with no children).
Below is a sample of how a TreeItem can be defined in a TreeSchema:

<TreeItem id="newItem">
<searchPath>XPath to search</searchPath>
<description>Item description</description>
<caption>Item caption</caption>
</TreeItem>
It is now possible to define multiple icons for a single tree item using the icons property, as shown in the structure below:
<TreeItem id="newItem">
<searchPath>...</searchPath>
<description>...</description>
<icons>
<icon>icon url 1</icon>
<icon>icon url 2</icon>
</icons>
</TreeItem>

The following table lists the Properties and Methods that are exposed for each TreeItem.

Table 7.	List of Properties used for TreeItem
Property	Description
checkable	Optional, boolean property that has the default value as 'false'. It denotes whether a treeItem can be checked. The value 'true' in the treeschema means that a checkbox is shown.
checkChildren	Optional, boolean property that has the default value as 'true'. It denotes whether the child tree items (and subsequent grand-child tree items) automatically get the same check status as the current treeItem. The value 'true' means that the (un)check is passed to all lower levels. Only checkable treeItems get updated. Tree items which are not checkable do support this property. This is applicable when the check-method is applied to a non-checkable root or treeItem. In this case the treeItem itself is not checked but its child tree items can be.
contextMenu	Optional property that defines the unique identifier of the shortcut menu that can be attached to the tree Item. Once a shortcut menu is attached to a tree item, then the shortcut menu can be invoked by right-clicking on the tree Item for which the context menu is defined.
data	Contains the XML associated with the tree Item. The data property is read-only. This cannot be set at run time. However, the value for this property is set automatically when data is assigned to the tree using treeData property.
description	Property that sets the description of the tree Item. The description of the item can be a text that denotes the string that is to be shown, or it can be the name of a node. The latter case is possible, if a treeData is assigned to the tree to display data. The description of the TreeItem can be attribute names also. In such cases, the attribute names are mentioned with an @ as a prefix. For example, id "application" is the node and "class" is the attribute defined in the node, then the searchPath will contain "application" and the description contains "@class".
dragEnabled	Optional property that defines whether the TreeItem can be dragged or not. Once dragging is enabled on a tree Item, the item can be dragged and dropped from one tree node to another node. This can be achieved by selecting the item, and hold the mouse on the item, and move the pointer to another tree node. Once the other node is reached, release the mouse click. However, dragging the node will not update the corresponding data in the tree. It is the responsibility of the users to manually change the treeData.
genericDropEnabled	Optional property that if set to true, allows you to drag any element to the TreeItem. It is false by default.
icon	Optional property that contains the URL of the icon attached to the tree Item.
icons	Optional property that contains the URLs of the icon attached to the tree Item. This property contains a collection of icon items inside it.
onchange	Optional property that contains a pointer to the function to be called when the description of a tree item is changed.
oncollapse	Optional property that contains a pointer to the function to be called when an item in the tree is collapsed.
ondblclick	Optional property that contains a pointer to the function to be called when the root or a tree item in the tree is double-clicked.
ondrag	Optional property that contains a pointer to the function to be called when an item in the tree is dragged.
ondrop	Optional property that contains a pointer to the function to be called when an item in the tree is dropped.
onexpand	Optional property that contains a pointer to the function to be called when an item in the tree is expanded.
onitemchecked	Optional property that contains a pointer to the function to be called when a tree item in the tree is (un)checked.
onselect	Optional property that contains a pointer to the function to be called when an item in the tree is selected.
openIcon	Optional property that contains the URL of the icon attached to the tree Item in open state.
searchPath	Property that denotes the name of the XML Node present in the data that will be assigned to the tree.
updateAllowed	Optional property that defines whether the item descriptions displayed in the tree nodes are editable or not.

Table 8.	List of Methods used for TreeItem
Method	Description
addItem	Adds an item under the root node of the tree.
addItemBefore	Adds an item before the specified tree Item.
addItems	Adds a collection of items to the root node of the tree.
changeIcon	Changes the icon of the tree item (Node / Leaf).
changeOpenIcon	Changes the icon of the tree item which has to be displayed when the Node is in the expanded state.
collapse	Collapses the selected node of the tree by one level.
collapseAll	Collapses the selected node of the tree to all levels recursively.
copy	Copies the specified node and its data from the tree to the clipboard.
cut(bDeep)	Removes the specified node and its data from the tree and copies it to the clipboard. The parameter bDeep is a boolean that denotes whether all the child nodes are to be removed from the specified node. By default, this is false.
expand	Expands the selected node of the tree by one level.
expandAll	Expands the selected node of the tree to all levels recursively.
getChildContainer	Returns the collection of all the child items under the specified node. Once getChildContainer method is called, the child nodes under this collection is to be accessed through the childNodes property of the method. The length property of the childNodes will specify the total number of children in the collection.
getParentItem	Gets the parent tree Item for the specified node. The parent item for a tree node can be retrieved only if the tree node is a tree Item. getTreeItem can be used to get the tree Item for a node.
getItem	Searches for the specified item in the tree and returns the first item found.
getLabel	Returns the label of the item specified, which contains the description of the item. The label returned by the above method is a SPAN tag that contains the text displayed as description of the tree Item. Using the innerHTML property of the label, navigation can be changed based on their values. modifying the description of the label is also possible. However, the user is expected to update the data of the tree Item for which the label is changed.
getTree	Returns the tree definition.
getTreeItem	Gets the tree Item for the specified node. The tree Item will be present for Nodes (tree items with children) and Leaves (tree items with no children).
highlight(bHighlight)	Highlights or de-highlights specified item in the tree. The parameter bHighlight is a boolean that denotes whether the tree item is to be highlighted or de-highlighted.
moveTo(oParent)	Moves an item to the specified tree Item. Errors will be encountered while trying to move an ancestor element to its child nodes. The parameter oParent denotes the parent element to which the selected tree item is to be moved.
paste	Copies the contents of the clipboard into the specified node as a child item. The content that is pasted into the clipboard should be a valid tree Data and should be defined in the schema of the tree. Content that does not adopt this criteria will not be copied into the tree node.
remove	Removes an item from the tree. When a node is remove using remove method, the node is first collapsed and then removed. In this case, the function associated with oncollapse property will also be fired.
rename	Makes the selected item editable so that the description of the selected tree Item can be changed.
select(bSkipselect)	Selects the specified node in the tree. The parameter bSkipselect is a boolean that denotes whether the onselect function handler is to be called while selecting the item. By default, this is false.
showitem	Searches for the specified item in the tree, highlights the item, and expands all higher levels till the current tree item. Returns the first item found.
check( bSelect, <bPassCheck>)	(Un)checks a checkable treeItem. Can also be applied to a non-checkable tree item, to pass the status to its child tree items.* bSelect: Boolean, required. It checks the tree item when set as 'true', and unchecks it when set as 'false'.* bPassCheck: Boolean, optional. It is the default value as determined by the checkChildren property. True means that all checkable child tree items are also (un)checked. False means that only the parent tree item is (un)checked.
getCheckableItems	Returns an array of all (un)checked treeItems and its children. Only checkable items are returned.
isCheckable()	Returns true when treeItem is checkable (has a checkbox).
isChecked()	Returns 'true' when the treeItem is checked, 'false' when it is unchecked, and null when it is not checkable.
makeCheckable( bSelect )	Makes the treeItem checkable or removes the checkbox.* bSelect: Boolean, required. If 'true', it makes the treeItem checkable; if 'false', it removes the checkbox.
setClass	Applies a style class to the label of the tree item.
setLabel( sLabel )	Updates the label of the tree item.

Following are the Events used with the tree component

Table 9.	List of Events
Event	Description
onadditem	Fires when a tree Item is added to the tree.
oncontextregister	Fires when a contextMenu is registered with a tree Item.
onremoveitem	Fires when a tree Item is removed from the tree.
onbeforerename	Fires before a node is renamed.
onafterrename	Fires after a node has been renamed. It has the selectedNode property, which refers to the node whose description has been renamed.

The following keys are supported to provide easy navigation in the tree.

[arrow right]: Expand current node.
[arrow left]: Collapse current node.
[arrow up]: Go to previous tree Item.
[arrow down]: Go to next tree Item.
Esc: Close the input box, if open.
Enter: Expand current node.
Tab: Move focus out of the selected tree item.
Esc: When renaming a tree node and if this key is pressed, then the node will not be renamed and the onafterrename event will not fire.

It is also possible to Cut, Copy and Paste a Tree item in a tree using the following keys:

Ctrl+X: Removes the specified node and its data from the tree and copies it to the clipboard
Ctrl+C: Copies the specified node and its data from the tree to the clipboard
Ctrl+V: Pastes the contents of the clipboard into the specified node as a child item

To enable the above shortcuts, set <updateAllowed/> to 'true' in the tree item schema.
Separate handlers can be defined by specifying <oncut>onCutHandler</oncut>, <oncopy>onCopyHandler</oncopy>, and <onpaste>onPasteHandler</onpaste> in the tree schema.
To skip the cut operation specify treeId.getTreeItem().cut(parameter1,parameter2).

The first parameter (parameter1) takes a Boolean value indicating whether all the child items are to be cut or copied recursively. The default value is 'true' indicating all the child items are copied.
Setting the second parameter (parameter2) to 'true', skips the copy-cut-paste event, that is treeID.getTreeItem().cut(true, true).

The operations for oncopy are also similar.
Process Platform Ajax Toolkit displays the selected tree item within a dotted line border, if the focus is lost for the item. This can be also be achieved by clicking the tab to navigate to any other HTML element in the page.

Example

This sample demonstrates the implementation and use of the tree component.

<\!DOCTYPE HTML PUBLIC"-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
 <html onapplicationready="menutree.root.expand()" >
 <head>
 <title>Tree demo</title>
 <script type="text/javascript" src="/cordys/wcp/application.js" ></script>
 <script type="cordys/xml" id="menuData" >
 <menu>
 <MainNode>
 <caption>Demo Using Menu Node</caption>
 <description>Demo Using Menu Node</description>
 <Continents>
 <caption>Continents</caption>
 <description>Continents</description>
 <Continent>
 <caption>Asia</caption>
 <description>Big continent</description>
 <Country>
 <caption>India</caption>
 <description>India is my Country</description>
 </Country>
 <Country>
 <caption>Japan</caption>
 <description>Japan popular for electronic trends</description>
 </Country>
 </Continent>
 <Continent>
 <caption>Europe</caption>
 <description>Europe</description>
 <Country>
 <caption>The NetherLands</caption>
 <description>The NetherLands</description>
 </Country>
 <Country>
 <caption>UK</caption>
 <description>UK</description>
 </Country>
 </Continent>
 </Continents>
 <Oceans>
 <caption>Oceans</caption>
 <description>Oceans</description>
 <Ocean>
 <caption>The Great Ocean</caption>
 <description>Atlantic</description>
 <id>GeneralInformation</id>
 </Ocean>
 </Oceans>
 </MainNode>
 <MainNode>
 <caption>Available tree Item Tags</caption>
 <description>Available tree Item Tags</description>
 <id>Available tree Item Tags</id>
 <Tags>
 <caption>description</caption>
 <description>Description of the item as it appears in the browser</description>
 <id>GeneralInformation</id>
 </Tags>
 <Tags>
 <caption>dragEnabled</caption>
 <description>Describes whether or not this tree item can be dragged</description>
 <id>dragEnabled</id>
 </Tags>
 <Tags>
 <caption>genericDropEnabled</caption>
 <description>Describes whether any other item can be dragged to this tree item</description>
 <id>genericDropEnabled</id>
 </Tags>
 <Tags>
 <caption>icon</caption>
 <description>Contains the url of the icon to attach to the item</description>
 <id>icon</id>
 </Tags>
 <Tags>
 <caption>oncollapse</caption>
 <description>Contains the java script method to be called when an item is collapsed</description>
 <id>oncollapse</id>
 </Tags>
 <Tags>
 <caption>onchange</caption>
 <description>Contains the java script method to be called when the description of an item is changed</description>
 <id>onchange</id>
 </Tags>
 <Tags>
 <caption>ondrag</caption>
 <description>Contains the java script method to be called when an item is dragged</description>
 <id>ondrag</id>
 </Tags>
 <Tags>
 <caption>opdrop</caption>
 <description>Contains the java script method to be called when an item is dropped</description>
 </Tags>
 <Tags>
 <caption>onexpand</caption>
 <description>Contains the java script method to be called when an item is expanded</description>
 <id>onexpand</id>
 </Tags>
 <Tags>
 <caption>onselect</caption>
 <description>Contains the java script method to be called when an item is selected</description>
 <id>onselect</id>
 </Tags>
 <Tags>
 <caption>openIcon</caption>
 <description>Contains the url of the icon that should be displayed when the item is opened</description>
 <id>openIcon</id>
 </Tags>
 <Tags>
 <caption>searchPath</caption>
 <description>XML node present in the XML document specified in treeData.Node specified in searchPath is transformed into the target tree node
 or element.The user is allowed to define custom tree nodes also.</description>
 <id>searchPath</id>
 </Tags>
 <Tags>
 <caption>updateAllowed</caption>
 <description>Tag used to check if updation is allowed on a node.</description>
 <id>updateAllowed</id>
 </Tags>
 </MainNode>
 </menu>
 </script>
 <script type="cordys/xml" xmlns="" id="MenuTreeSchema" >
 <TreeSchema>
 <searchPath>//menu/</searchPath>
 <Root>
 <description>Root</description>
 <icon>/cordys/wcp/images/application.gif</icon>
 <onselect>showRootDescription</onselect>
 </Root>
 <TreeItem id="MainNodeID" >
 <searchPath>MainNode</searchPath>
 <description>caption</description>
 <contextMenu>Menu</contextMenu>
 <icons>
 <icon>/cordys/wcp/images/wizard/backward.gif</icon>
 <icon>/cordys/wcp/images/admin/administrator.gif</icon>
 </icons>
 <openIcon>/cordys/wcp/images/wizard/forward.gif</openIcon>
 </TreeItem>
 <TreeItem id="ContinentsID" >
 <searchPath>Continents</searchPath>
 <description>caption</description>
 <contextMenu>Menu</contextMenu>
 <icon>/cordys/wcp/images/book.gif</icon>
 <openIcon>/cordys/wcp/images/bookopen.gif</openIcon>
 </TreeItem>
 <TreeItem id="ContinentID" >
 <searchPath>Continent</searchPath>
 <description>caption</description>
 <onexpand>expandContinent</onexpand>
 <contextMenu>Menu</contextMenu>
 <icon>/cordys/wcp/images/book.gif</icon>
 <openIcon>/cordys/wcp/images/bookopen.gif</openIcon>
 </TreeItem>
 <TreeItem id="CountryID" >
 <searchPath>Country</searchPath>
 <description>caption</description>
 <icon>/cordys/wcp/images/style/styleeditor.gif</icon>
 </TreeItem>
 <TreeItem id="OceansID" >
 <searchPath>Oceans</searchPath>
 <description>caption</description>
 <contextMenu>Menu</contextMenu>
 <icon>/cordys/wcp/images/book.gif</icon>
 <openIcon>/cordys/wcp/images/bookopen.gif</openIcon>
 </TreeItem>
 <TreeItem id="OceanID" >
 <searchPath>Ocean</searchPath>
 <description>caption</description>
 <icon>/cordys/wcp/images/style/styleeditor.gif</icon>
 </TreeItem>
 <TreeItem id="TagsID" >
 <searchPath>Tags</searchPath>
 <description>caption</description>
 <onselect>showitemtagDescription</onselect>
 <icon>/cordys/wcp/images/style/styleeditor.gif</icon>
 </TreeItem>
 </TreeSchema>
 </script>
 <script type="text/javascript">
 function expandContinent()
 {
 application.notify ("I'm a continent.");
 
}
 
function showitemtagDescription(selectedNode)
 
 {
 var vars="menu/MainNode/Tags\[caption='" + cordys.getTextContent(selectedNode) + "'\]/description";
 if(cordys.selectXMLNode(menuData.XMLDocument,vars))
 application.notify(cordys.getTextContent(cordys.selectXMLNode(menuData.XMLDocument,vars)));
}
 
 function showRootDescription(selectedNode)
 {
 application.notify(cordys.getTextContent(selectedNode.firstChild));
}
</script>
 </head>
 <body>
 <div cordysType="wcp.library.ui.Tree" id="menutree" treeData='menuData' treeSchema='MenuTreeSchema'> </div>
 </body>
 </html>