An In-Depth Look at the Tree View Weblet
The tree view weblet provides a windows-like tree view control for use by your WAM application. Following is a description of how it should be used. This description is rather long, and has been divided into these sections:
The Role of the Tree View Target Weblet
Processing Expanding Tree Items
Accessing Ancestor Information
As with all weblet controls that display a list of information, the Tree View Weblet is primarily driven by a working list in your WAM. Each entry in the working lists represents a tree item. Fields in the working list control the tree view item's appearance and behavior. These include the hidden key information of the tree item, its caption, what to do when the item receives focus and what to do when the tree item is expanded.
Depending on how you wish to utilize the tree view, different techniques are used. These are documented in What You Need to Know.
The Tree View examples supplied are WAMEX50 and WAMEX51.
They are both simple examples of a tree that contains Department branches which, when expanded, show Section branches belonging to the Department, which, in turn, show Employees belonging to the Section.
Both examples use a Vertical Splitter weblet. This allows the Tree View weblet to be displayed on the left of the web page and details for a selected tree item to be displayed, in a Tree View Target weblet, on the right of the web page.
WAM01 is an enquiry-only example, whereas WAMEX51 allows the update of the selected department's description. Due to the updating of the tree, WAMEX51 uses additional Weblets and slightly different coding techniques to those of WAMEX50.
Both examples are intended to give you a good introduction to the Tree View weblet and how it interacts with other, related weblets, as well as the underlying WAM code.
The Tree Working List
In all cases, you will need a working list. Remember that each entry of the working list represents an item in the tree view. The working list should contain fields that will populate the list_* properties of the weblet. Refer to Properties - Tree View for a list of these. As a minimum, however, the working list should contain the following:
- A field to hold a caption for the tree item It can be any free-format text string that describes the tree item In the example WAMs, this is the Department description, the Section description, or the name of an Employee.
- A field to hold the key, or tag, of the tree item In the example WAMs, this field holds either the Department Code, Section Code, or Employee Number Composite keys are derived by querying another working list that holds ancestor items of a given item This is discussed in the Accessing Key Information section.
- A field to hold the name of the Webroutine to be invoked when a tree item is selected When a tree item is selected, you will usually want to perform some action, such as display the details associated with the selected item In the example WAMs, a Webroutine is invoked to display details of Departments, Sections and Employees Refer to the When a Webroutine is Invoked section for more information.
- A Sub-Item Group field This numeric field holds the nesting level of the tree item from its root item In the example WAMs, Departments have a level of 1, sections 2 and employees 3.
- A HasChildren field This is a single-byte field that should contain a Y or N. This denotes whether or not the tree item is a branch that can be expanded in order to display dependant information In the example WAMs, each Department has dependant Sections, so this field is set to Y Likewise, Sections have dependant Employees, so this field is also set to Y Employees, however, do not have any dependant information, so this field is set to N.
The Parent Items Working List
In most, if not all cases, your tree view will have multiple levels and, usually, will contain data that follows a parent/child pattern. In our examples, this is true of the Department/Sections/Employees data.
The Parent Items working list is passed into the WAM, providing a list of ancestors of an item that has been selected or is expanding. As such, it contains just one field, which must match the field used in the Tree View working list to hold a tree item's key information. More information about using this working list can be found later in this document.
When a Tree Item is Selected
The list_onselect_wrname_field property of the tree view points to a field that contains the name of the Webroutine that is to be invoked when the corresponding item in the tree is selected. In the example WAMs, this is set to ShowDepartmentDetail for each Department entry.
When this Webroutine is invoked, certain information is passed into it:
The key information of the selected tree item. This is the field that is specified in the list_tag_field property. This can be used to access additional or related information that is relevant to the tree item. A Web_map to receive this field is required at all times.
The working list that contains the identifiers of the selected tree item's parents or ancestors. This is the list specified in the listname_of_parents_of_selected property. See the Accessing Key Information section for more information.
When a Tree Item is Expanded
The onexpand_wrname property of the Tree View can be used to build the contents of a branch when it is expanded. In the example WAMs, when a Department or Section branch is expanded, the TreeExpanding Webroutine is invoked.
As well as the key information of the expanding tree item, the level of the tree item is passed into this Webroutine, along with the tree list itself and the list of parents of the expanding tree item. Based on the level of the expanding tree item, the appropriate method is invoked to add child items to the tree for the selected parent item.
So, a level of 1 indicates that a Department tree item is being expanded, and so Sections belonging to that Department are added to the tree. A level of 2 indicates that a Section tree item is being expanded, and so Employees are added.
Because a tree item can have parent tree items, a working list to hold this information is required. It should be defined as containing just the field that is specified in the list_tag_field property of the tree.
It must be specified as a Web_map for the Webroutine that is used to display the main tree view working list. In WAMEX50, the ShowPage Webroutine has a Web_map specified for the list.
When passed into the WAM, it will have an entry for each of the selected item's parent items. Each entry contains the key information of the parent item. For tree items that do not have any parents, the list will be empty.
A Web_map to receive this list is only required if you wish to access information in it. This would typically be required for the selection Webroutine and the Tree Expanding Webroutine.
In the example WAMs, when a Section is selected, this list is used to ascertain the key value of the Department to which the Section belongs.
Usually, you will want to display additional information relating to a tree item that has been selected.
In the example WAMS, when a Department is selected, the ShowDepartmentDetail Webroutine is invoked to show additional information for the Department.
There must be an area on the web page for this information to be shown. This is what the Tree View Target weblet is used for. When a tree item is selected, the Tree View Target associated with the tree (via the Tree View Target's treeview_name property) becomes active, or gets focus. The output from the Webroutine invoked when the tree item is selected is thus directed to the Tree View Target.
For more information on the Tree View Target (std_treeview_target)weblet, refer to its documentation.
In WAMEX50, which is a simple enquiry, the Tree View and Tree View Target weblets are displayed by the ShowPage Webroutine. This works fine for enquiry purposes.
It becomes slightly more complex, however, if an update function for the details that are displayed in the Tree View Target weblet is introduced. For example, if the user changes the Department description and presses an update push button, you would expect the Tree View to be updated with the new description.
In order to get this to happen, the Tree View must be displayed in a different way to that shown in WAMEX50. Here, the Tree View is directly placed in the left-hand portion of the Vertical Splitter.
In WAMEX51, the left-hand portion of the Vertical Splitter contains a navigation panel. This panel is set to navigate to the DepartmentTree Webroutine. This is the Webroutine that contains the Tree View weblet. Separating it out like this means the Tree View can be easily refreshed on the web page, as it is, in effect, in its own sub-page of the main web page.
To help reinforce the techniques described, this section contains sections of the WAM code, along with property settings of the Tree View and associated weblets.
The List Definitions
The RDML code below shows the field and list definitions that are used by the Tree View weblet.
The tvDepts working list is the list used to populate the Tree View. The function of its fields is as follows:
- TreeID, used to hold the key information for the tree item.
- TreeCapt, used to hold the caption for the tree item.
- TreeLvl, used to return the selected tree item's level to the WAM.
- HasKids, used to denote whether the tree item has children.
- DetailsWR, used to hold the name of the Webroutine to be invoked when the tree item is selected.
- Selected, used to control whether a tree item should be selected.
The Ancestors list is used to receive parent tree item key information from the Tree View weblet for the selected tree item.
Right-click on the DepartmentTree Webroutine and select the LANSA Editor option. Once the LANSA Editor has opened, click on the tree itself and then select the Details tab. The properties of the tree view will be shown, as follows:
Note the listname property contains the name of the tree view working list, tvDepts. Note also how the list_*, onexpand_wrname and listname_of_parents_of_selected properties relate back to fields in tvDepts.
The entry point of the WAM (that which should used to execute the WAM via a browser URL or from another WAM) is the ViewDepartments Webroutine. It is designed to be the only entry point, to be executed only once. Any initialization logic for the WAM could be placed here. See below:
In this example, the only thing it has to do is set the Session Status to Active. This controls the writing out and reading in of any persistent session data when executing Webroutines in the WAM.
The ShowPage Webroutine is then executed. Again, this is designed to be the only place in the WAM used to display the web page. In this example, no Web_maps specify what is to be displayed – all such information is handled by other Webroutines, as you will see. Non-field and list data has been specified via the LANSA Editor, and so the ShowPage Webroutine shows as being 'empty'.
1. Right-click on the ShowPage Webroutine and select the LANSA Editor option.
2. Click on the left-hand side of the Vertical Splitter and select the Details tab to display the Navigation Panel's properties, as shown below:
Take note of the nav_wrname property. This is the Webroutine that is invoked whenever the Navigation Panel is displayed. In this example, it points to the DepartmentTree Webroutine, which is used to build the tree view.
3. Close the XML editor and look at the DepartmentTree Webroutine in the WAM source, as shown below:
Note the Web_map definitions. Because this Webroutine is used to display the tree view, it has Web_maps for the working list that represents the tree, along with the working list that is used to hold ancestor items for a selected tree item. Wherever the tree view working list is specified as a Web_map, the ancestor list must also be specified as a Web_map. If it isn't, your WAM won't work correctly.
BuildTree is a Boolean field that is used to control the building of the tree view. Its default (in its field definition, at the top of the source) is True, which means that when this Webroutine is invoked for the first time, by the Navigation Panel, the tree view will be built. BuildTree is then set to False, ensuring that the tree is not rebuilt on subsequent invocations.
BuildDepartmentList method:
Note the setting for each entry to be added to the Tree View working list. Refer to List Definitions in A Closer Look at WAMEX51 for a full explanation of these.
The Role of the Tree View Target Weblet
1. Right-click on the ShowPage Webroutine again and select the LANSA Editor option.
2. Click on the right-hand side of the Vertical Splitter and then click the Details tab. The properties for the Tree View Target will be displayed.
Note the treeview_name property points to the name of the Tree View weblet as defined in the DepartmentTree Webroutine. This indicates that the Tree View Target will receive selection events from the tree view. Effectively, it will become the active, target portion of the web page when something is selected in the tree.
This, in combination with the list_onselect_wrname_field property of the tree view, will display details of a selected Department, Section or Employee.
3. Close the LANSA Editor.
DepartmentDetail Webroutine in the WAM source:
This is the Webroutine that is invoked when a Department is selected in the tree view. Note the *input Web_map. This is the field specified against the list_tag_field property of the list view weblet. It contains the identifier, or key, of the selected tree item.
The SelID field is defined as a persistent session field (Web_map with *NONE and *PERSIST) and is used to hold the selected key on multiple invocations of the WAM. This is used when rebuilding the tree.
When the Webroutine ends, because the active portion of the web page is the Tree View Target, the output from the Webroutine is directed to it, so you see the department details in the right-hand portion of the Vertical Splitter.
1. Right-click on the ShowDepartmentDetail Webroutine and select the LANSA Editor option. Note that, as well as the department description, an Update push button is displayed. Click on it and select the Details tab. Its properties will be displayed, as follows:
Note the on_click_wrname and target_window_name properties. The on_click_wrname property contains the name of the Webroutine to invoke when the push button is clicked.
The target_window_name property is used to direct the output of the WAM to a specified window. In effect, this becomes the active portion of the web page. In this example, the Navigation Panel will be the target window.
2. Close the LANSA Editor.
UpdateDepartment Webroutine in the WAM source:
Note that the BuildTree boolean field is set to True, indicating that the tree should be rebuilt. Control is then transferred to the DepartmentTree Webroutine, from where the tree view is rebuilt. Have another look at the AddListEntry method:
Note the If/Else/Endif code. Remember the SelID field? If the entry being added to the tree is the same one that has just been updated, the SELECTED field is set to 'freeze'. SELECTED is a field in the tree view working list which drives the list_is_selected_field property of the tree view. Setting it to freeze does two things: it pre-selects the tree view item and it stops the TreeViewTarget from being reloaded.
Processing Expanding Tree Items
Open the DepartmentTree Webroutine in the LANSA Editor and select the tree view weblet. Click the Details tab to display its properties. Note the onexpand_wrname property is set to TreeExpanding. This is the Webroutine to be invoked when an expander (+) of a tree item is clicked on. Close the LANSA Editor and have a look at the TreeExpanding Webroutine in the WAM source:
Note the *input field Web_maps: the TreeID field, which holds the key information of the expanding tree item, and the TreeLvl field, which indicates the level of the expanding tree item. The tree view working list is also passed in, along with the list of ancestors of the expanding tree item. Note that the tree view working list is specified as *both – it will be passed to the DepartmentTree Webroutine at the end of the TreeExpanding routine. Also, the ANCESTORS list is *input – it is only needed by this routine.
The Case statement determines what should be added to the tree view working list. If the level is 1, it means a Department tree item is being expanded, so Sections need to be added. If it's 2, a Section is being expanded and Employees need to be added. Once entries have been added to the tree working list, control is transferred back to the DepartmentTree Webroutine which displays the tree.
In Accessing Ancestor Information, the focus is on what happens if a Section tree item is being expanded in order to show what you need to do to retrieve parent key information.
Accessing Ancestor Information
Refer back to Processing Expanding Tree Items. When processing level 2, the SECTION field is set to the incoming identifier (this was set when the Sections were added to the tree view working list in the BuildSectionsList method). Of course, a Section has a parent of Department.
In order to determine the Department to which the Section being expanded belongs, the ANCESTORS working list is used. This list contains multiple entries of the TreeID field. A Section only has one parent, so the ancestor working list will contain one entry. In this example, the GetAncestor method is executed to retrieve the key value of the Section's parent.
If the tree contained more levels, the ANCESTOR working list would contain more than one entry for a level three or higher item, and so multiple Get_entrys could be used to build up the full list of parent keys.