Tree Control

The following image shows a simple Tree control with a root node, an expanded node, and a collapsed node. The Multiple option has also been enabled for the selection type property of the control to allow multiple items to be selectable:

1. Create a SmartObject with properties, and include a property required to be used as the Parent ID. (The Parent ID will be the value that "binds" a node to its parent). See the Creating SmartObjects section for information on creating SmartObjects.
2. Create a View.
3. Drag the Tree control onto the canvas. The control can be found in the Input section of the Controls.
4. Configure the Selection Type property to indicate whether the control should allow single or multiple selections
5. Configure the Data Source property and select the SmartObject created in Step 1.
6. Configure the rest of the control properties as required.
7. Create a rule or rules to interact with the Tree control at runtime.
8. If required, add data to the SmartObject that is used as the data source for the tree view, taking care to populate the Parent ID property as needed.
9. Run the View.

When creating a SmartObject or editing an existing SmartObject for use with the Tree control, the following need to be considered:

• A property is required for use as the node location identifier of the Tree control. This property is referred to as the Parent ID and determines where in the Tree View a specific value will appear.
• It is advised to use a unique name for the property used as the Parent ID for identification purposes. This property does not necessarily have to be called Parent ID.
• The Parent ID property can be added to existing SmartObjects. The hierarchical structure should be updated manually by adding the new property to a View and editing the data if data already exists to ensure the data is linked to the relevant parent node.
• When using a single data source, any record where the Parent ID value is not valid will be displayed as a root node. Consider the example below: suppose a data set has twelve records (with IDs 1-12). When using the value 13 (or any other number greater than 12) for the Parent ID property, those records will appear as root nodes because there is no record with an ID of 13 to act as the parent node. In the sample dataset Type A, B, C and D are all shown as root nodes, because there is no record with ID 13 that will act as a parent node for those items. In short, if the value of the property used for the Parent ID is 0 or the value does not match a valid parent record, that record will be shown as a root node in the tree control.
  
  
• When using multiple data sources, it is not required to define Associations between the SmartObjects but it can be useful. Association id's can be used in the category fields of the Categories and Items sections to ensure correct population of the tree control.

See the following sections for more detail on using single or multiple data sources:
How to use a single data source
How to use multiple data sources

Below is an example of a SmartObject used with the Tree control, followed by a screenshot showing the behavior of the Tree at runtime based on the values entered for the SmartObject. This example is using a single data source. Note the color-coded links between the ID and Parent ID. Since Vehicles has a Parent ID of 0 and it is the only item with Parent ID 0, it is the Root Node of the Tree View. Cars and Motorcycles have a value of 1 for the Parent ID and therefore appear as sub-nodes under Vehicles. Car 1, Car 2 and Car 3 have 2 as the value of their Parent ID, and therefore they will appear under Cars in the tree view.

The Tree control can interact with other controls through rules. Depending on the control properties, there are certain actions where the control surfaces. Following are a few examples:

• Set a control’s properties: The control's settable properties can be configured using this action
• Show/Hide: The Visible property allows for the control to be shown or hidden through rules
• Enable/Disable: The Enabled property allows for the control to be enabled or disabled through rules 
• Data Transfer: Data can be transferred from items listed in the Context Browser to the Tree control
• Execute a control's method: The control's methods can be configured using this action
• Specify edit state: This action allows for the control to be set as Read-Only or Editable

The following Rule events are available when using the Tree control:

• Changed: A rule condition and/or action can be executed when the control is changed, for example selecting an item or transferring a value to the control.
• Changing: A rule condition and/or action can be executed just before the Changed event is executed.
• Collapsed (node): A rule condition and/or action can be executed when a node is collapsed.
• Double-Clicked: A rule condition and/or action can be executed when a node has been double-clicked.
• Expanded (node): A rule condition and/or action can be executed when a node is expanded.
• Initializing: A rule condition and/or action can be executed when the control is initializing.
• Populating: A rule condition and/or action can be executed when the control is populating. The populated event fires when the control is populated on View initialize and also when a node is expanded (on a multi-source tree), except when the Expanded property is enabled (in this case it will only fire on View initialize).

The following Rule methods are available when using the Tree control:

• Clear Selection: Clears the selection made in the control, i.e. all selected nodes are unselected.
• Collapse All: Collapses all nodes so that only first level parent nodes are visible.
• Collapse Node: Collapses the current node to show only its parent node.
• Expand All: Expands all nodes to the lowest level.
• Expand Node: Expands parent node to the lowest level.
• Find Node: Expands, finds and selects a node. Configure the Parameter in mapping destinations. This method only accepts Value, NOT Value Path or Path. The SmartObject's value need to be changed to a Text value, i.e. change the value property to the display field.
• Populate: Populates the Tree control with data from a SmartObject or SmartObjects.
• Refresh Node: Refreshes the state of a specific node. It allows the user to refresh the current selection via the control’s ‘Path’ Value (Value and Value Path are not accepted for this method). Expand the node by configuring the Parameter and setting the Expand property to true.
• Select All Nodes: Selects (Checks) all populated nodes. This method is only applicable to a multi-source tree

• Values can be transferred to the Tree control by using the Transfer Data action mappings screen.
• On a multi-source tree, it is possible that records from different SmartObjects can have the same value for the ID property. To overcome this, transferred values can be tiered. Consider the image below:
  
  In the above image two items on the tree (South Africa and Gauteng) have the same ID value of 1. If an ID is common between multiple items, only the first level with that value will be transferred. In this example, if 1 was transferred, only South Africa would have been selected. For this reason transferred values can be tiered as can be seen in the Text Box: The first value is the ID value, the second is the SmartObject name and the third is the name of the parent SmartObject (labeled NONE if not applicable). If we wanted to select Gauteng in the tree control, the value would be: 1,Province,Country because 1 is the ID of Gauteng, Province is the name of the SmartObject containing the record Gauteng and Country is the name of the parent SmartObject that provinces are bound to. If we wanted to select China, the value would be 4,Country,NONEbecause 4 is the ID value for China, Country is the name of the SmartObject and since Country does not have a parent SmartObject, NONE is specified as the parent SmartObject name.
• The data is a delimited list of values that the control saves and loads. It is important to always have a delimiter specified, preferably a semi-colon (;).
• The Tree control cannot be used on Forms, it can only be used on Views.
• The populate list control with data rule action is not supported in the Tree control as the Tree uses more than one source to load its data, and the populate list control action only supports controls with one data source.
• When using multiple data sources, data associations are not required between the SmartObjects used but can be useful. Association id's can be used in the category fields of the Categories and Items sections to ensure correct population of the tree control. See the How to use multiple data sources section.
• The Expanded property is not selected by default. This means that the lowest level nodes will show the expander (icon) until the user has clicked the expander, then it will disappear.
• When selecting the Expanded property option, data to populate the tree control will be retrieved once the control loads. This may cause a delay and is not recommended when large data sets are used to populate the control.
• When a parent/root node is expanded to expose child nodes, selecting a parent or root node selects child nodes as well. However, if root/parent nodes remains collapsed, selecting that node will NOT select child nodes.
• The OnChange rule event no longer fires when expanding or collapsing a node. If you want to have rules fire when expanding/collapsing, you will need to use the relevant event.
• The Refresh Node rule method is affected by the control’s Expanded property. If expanded is true, using the method will refresh that node but any children’s nodes will remain expanded.
• The Find Node method only accepts Value, NOT Value Path or Path. Thus, it is suggested to change each SmartObject’s Value to that of the display field to avoid duplicate Auto-number IDs not drilling down to child nodes.
• The Load All Nodes property is not selected by default. This means that data will be loaded on demand when expanding a node.
• When using the Single option in the Selection Type property, the control contains the value for the selected node and only a single selection can be made.
• When using Multiple option as the Selection Type property and a parent node is selected via a multi-selection check box, it will only select the parent node. Child nodes will only be selected once the parent is expanded.
  
• When using the Multiple option in the Selection Type property, the category node does not contain the value and selecting a category by default selects all its respective items. This is useful to transfer values for further action. If a parent is collapsed, you can select it as a value.
• When using the Multiple option in the Selection Type property, the Value property can be set to indicate which value should be selected by default at runtime. Multiple values can be set by using a semi-colon as the delimiter. An example where Multiple has been selected and the Value property is set to 2;8 is shown below. Note the hierarchical order of the nodes.
  
• If you have a multi-source tree and any of those SmartObjects' Selectable property is set to false on the Configure Data Source page, none of the values for that SmartObject can be selected, i.e. values for that SmartObject will behave as if for example Read-Only was set to true. If a single source tree has it’s SmartObject Selectable property set as false, none of the values will be interactive. The user can still expand or collapse nodes, just not select them.
• When selecting the Recursive property on the Configure Data Source page, the Parent property can not be set to a type of ID as this will create an infinite loop.
• No data will be displayed in a single source Tree until the Recursive property is set to true.
• The Find Node method only accepts Value, NOT Value Path or Path. It is suggested to change each SmartObject’s Value to that of the display field to avoid duplicate Autonumber IDs not drilling down to child nodes.
  

The Tree control is available in the Input section of the Controls toolbox.

When clicking on the ellipsis next to Data Source, the Configure Data Source screen opens. Configure the data source to be used for the control. A single or multi-source can be configured. When clicking on the ellipsis next to Method on the Configure Data Source screen, the Populate Tree List Control with Data screen opens. The Tree control's input properties can be set by using fields or parameters. Filters and sorting can also be applied to the results that will populate the Tree control. It is advised that a very strict filter is set up to limit the number of items used to populate the Tree control. See the Filter and Sort sections for a detailed description and items that need to be considered when applying these.

Single data source

A single SmartObject can be used to populate the Tree control. An image can be used as an icon to differentiate between the different categories and items. Images can be contained within the SmartObject used as the data source or it can be a separate SmartObject. When using a single SmartObject, it is important to have the data set up correctly for it to display as expected in the Tree control. See the Creating SmartObjects section for specific requirements and an example of what the data should look like.

How to use a single data source

1. Create one SmartObject to be used as the data source. Following is an example of a SmartObject:
   Sales
   ID: Autonumber type property used to identify the type property.
   Type: Text type property used for the name of the item.
   ParentID: Text type property used to identify the property as a root or secondary level category.
   
2. Create an Item and List View of the SmartObject.
3. Create data using the Item View.
4. View the data with the List View.
5. Ensure the data is captured correctly so it will be displayed in the Tree control as expected. Following is an example of how data can be linked to create different levels of data. Note how the value of the ID property is used in the Parent ID property to link the data. The item listed with a zero in the Parent ID field will be used as the root level node, see Creating SmartObjects for more information.
   
6. Create an Item View.
7. On the Layout screen drag the Tree control onto the canvas.
8. Open the Data Source property.
9. In the Configuration tab, select the Sales SmartObject, the Recursive property and None in the Parent SmartObject field. Select the Parent ID in the Parent Property field.
   
10. Click OK.
11. Finish and Run the View.
12. Expand the nodes to view the data you previously created.
    

Configuration Tab

Field	Description
SmartObject	The SmartObject to be used to populate the control. Click the ellipsis next to SmartObject to select the SmartObject.
Method	The method to be used to populate the control. This can only be a list type method.
Display	The display value for the tree node. The display can be customized by clicking on the ellipsis and dragging fields across from the Context Browser.
ID	The identifier of the SmartObject. One can also transfer the Path (which is recorded as ID,SmartObject) to or from the Tree control and the configured ID and SmartObject name would then be used. The ID is by default the Autonumber ID but can be changed to any field in the SmartObject.
Value	The SmartObject property to be used as the value for the control. The Value of the node when selected, will be the value returned from the property selected in the Data Source screen.
Selectable	The option is selected by default. If set to false it will make all values within the chosen SmartObject “unselectable”. If you have a multi-source tree and any of those SmartObjects' Selectable property is set to false, none of the values for that SmartObject can be selected, i.e. values for that SmartObject will behave as if for example Read-Only was set to true. If a single source tree has it’s SmartObject Selectable property set as false, none of the values will be interactive. The user can still expand or collapse nodes, just not select them.
Recursive	This property allows the user to use a SmartObject field to recur data on itself. The Parent property can not be set to a type of ID as this will create an infinite loop. No data will be displayed in a single source Tree until the recursive property is set to true.
Parent SmartObject	The parent SmartObject to be used to build the relationship between the parent and child SmartObjects.
Parent Property	The parent property to be used when linking the child SmartObject to the parent SmartObject.

Icon Tab

Field	Description
None	No icon applied.
Static	Static list of icons available. Select an icon from the list.
Dynamic	The property of type Image that provides the icon to be used.

Multiple data sources

Multiple SmartObjects can be used to populate the Tree control. An image can be used as an icon to differentiate between the different categories and items. Images can be contained within the SmartObject used as the data source or it can be a separate SmartObject. When using multiple SmartObjects as the data source, associations between the SmartObjects can be useful to populate the Tree control. If associations are not used, the subsequent SmartObjects will need a field linking them to their parents (as with cascading controls).

How to use multiple data sources

Following is an example of how the associations will be created for this specific scenario and how it will be displayed in the tree.

1. Create two SmartObjects to be used as the data sources. Following is an example of two SmartObjects:

   Province:
   ID: Autonumber type property used to identify the Province .
   Province: Text type property used for the name of the Province.
   
   City:
   ID: Autonumber type property used to identify the City.
   Province FK: Number type property used to associate the Province and City SmartObjects.
   City: Text type property used for the name of the City.

2. Create an Association between the two SmartObjects that looks like the image below. Although Associations are not required for linking multiple data sources, they are very useful. If Associations are not used, the subsequent SmartObjects will need a field linking them to their parents (as with cascading controls). In this scenario we are using associations for this purpose.
   
3. Perform the mapping as follows:
   
4. Create data for the two SmartObjects.
5. Create an Item View.
6. On the Layout screen drag the Tree control onto the canvas.
7. Open the Data Source property.
8. Click Add.
9. Select the Province SmartObject in the General section.
   
10. Click Add.
11. Select the City SmartObject in the General section and the Province SmartObject in the Parent section. Select the Province FK property next to the Parent Property field.
    
12. Click OK.
13. Finish and Run the View.
14. Expand the nodes to view the data you entered.

Configuration Tab

Field	Description
SmartObject	The SmartObject to be used to populate the control. Click the ellipsis next to SmartObject to select the SmartObject.
Method	The method to be used to populate the control. This should be a list type method.
Display	The display value for the tree node. The display can be customized by clicking on the ellipsis and dragging fields across from the Context Browser.
ID	The identifier of the SmartObject. One can also transfer the Path (which is recorded as ID,SmartObject) to or from the Tree control and the configured ID and SmartObject name would then be used. The ID is by default the Autonumber ID but can be changed to any field in the SmartObject.
Value	The SmartObject property to be used as the value for the control. The Value of the node when selected, will be the value returned from the property selected in the Data Source screen.
Parent SmartObject	The parent SmartObject to be used to build the relationship between the parent and child SmartObjects.
Parent Property	The parent property to be used when linking the child SmartObject to the parent SmartObject.

Icon Tab

Field	Description
None	No icon applied.
Static	Static list of icons available. Select an icon from the list. Per SmartObject, you will only have one icon. A specifically chosen image will be used to display at runtime. (In the background the static icon selected will still be retrieved via selected Icon ID property in the properties grid of the control)
Dynamic	The property of type Image that provides the icon to be used. This contains the properties of the current source. At runtime, the selected property source will be used as lookup value against the Icon ID property that was chosen.

Using Icons

When you drop a Tree control for the first time, the Tree control will attempt to bind to a system defined SmartObject called Tree Icons. (System Name: SourceCode_Forms_SFTreeIcons)

This SmartObject contains the following icons:

Auto-binding will happen when the Tree control is dropped for the first time. If the icon source is removed, the View is closed and opened again, it will not auto-bind the SmartObject again.

Icon Options

None - No icon is displayed.

Static - A specifically chosen image will be used to display at runtime. (In the background the static icon selected will still be retrieved via selected Icon ID property in the properties grid of the control).

Dynamic - This contains the properties of the current source. At runtime, the selected property source will be used as lookup value against the Icon ID property that was chosen.

Icon Selection behavior

• When a user configures a Source with Static as the Icon option, and removes/changes the Icon Source, the Static value will be invalid for a cleared source and unknown for a new source, so the options are RESET to None.
• When a user configures a Source with Dynamic as the Icon option, and removes the Icon Source, no source exist, no link can occur, and the propery is RESET to None.
• When a user configures a Source with Dynamic as the Icon option, and changes the Icon Source, the link is dynamic, and the properties presented in the Dynamic option is the Data Source’s properties, so the option will remain as Dynamic
• When a user changes an already configured data source as shown below
  
• If Static or Dynamic options were selected, they will be RESET to None.

Icons can be applied on the various levels of the categories and items. To do this, open the data source, navigate to the Icon tab and select one of the options. The icon will be applied on the level that is selected on the left hand side of the screen. So if the City is selected in the example below, the icon will be applied on City level.

A custom icon can be used for the different nodes in a Tree control. An image can be used to differentiate between the different categories and items. Images can be contained within the SmartObject used as the data source or it can be a separate SmartObject.

How to use a Custom Icon

• Create a SmartObject (for example Custom Icon) with an Image property.
  
• Create an Item View of the SmartObject and add an image record.
• Create an Item View with a Tree control.
• Specify a data source for the Tree control, then complete the rest of the data source settings as shown below.
  

  Properties	Description
  Icon Source	SmartObject containing the image.
  Icon ID	The property used to identify the ID of the icon contained in the SmartObject.
  Icon Image	The property used to load the image contained in the SmartObject.
  Icon Name	The property representing the name of the image.

• Finish and Run the View.

When using a rule action to set the properties of the Tree control, the following should be noted:

• Value - The Value of the node when selected in the tree, will be the value returned from the property selected in the Data Source screen. The property can be used to set a node. Setting the tree with a Value however cannot guarantee the correct selection.
  
  
• Path - The Path property contains the exact path for each selected node. When setting the same tree with a Path value, nodes will be guaranteed to be selected.
  

  For each node, the Path contains the ID property value, and then the system name of the corresponding source.

  
• Value Path - The Value Path property is each value node concatenated from the root to the selected node using the control property Path Separator. Setting the tree with a Value Path however cannot guarantee the correct selection.