Appendix: Viewing Trees From Application Pages

This appendix is for developers of PeopleSoft applications who want to display a tree from an application page, and enable users to select a node or leaf from the tree. It provides an overview of View Trees and discusses how to invoke View Trees from application pages.

See Also

Introduction to PeopleSoft Tree Manager

Understanding View Trees

Use a secondary ‘Tree Viewer’ page, (PSTREEVIEWER), to display an existing PeopleSoft tree from an application using the same HTML format as PeopleSoft Tree Manager. It enables the user to select a node or a leaf from a tree and return the selected node or leaf back to the application.

The following PeopleTools definitions are used:

• Secondary Page: PSTREEVIEWER

• Work Page: PSTREEVIEWERWRK

• Work Record: PSTREEVIEWWRK

The work record and work page are used as a way to transfer data between an application page and the secondary page. The PSTREEVIEWWRK record contains fields that define which tree to display, whether the user has selected a node or leaf, and control fields that give the application some control over the display options of the tree.

The following fields identify the specific tree to be displayed. These values should be populated by the calling application as discussed in the following table.

Note. If a tree contains branches, they are ignored and shown as regular nodes. However, the root node displays with the branch icon to indicate that the tree does contain branches.

There are two methods of opening the PSTREEVIEWER secondary page from an application:

• Without ‘MultiNode’ Selection (Method A): Enables user to select, and application to receive a single node with level information, or a leaf with parent node information.

• With ‘MultiNode’ Selection (Method B): Enables user to select, and application to receive multiple nodes without level information. If user selects a leaf the parent node is returned.

The following fields indicate whether specific nodes or a leaf has been selected by the application. These fields can be populated by the calling application if it wants the position of a specific node or leaf, identifying it as the currently selected. The fields are also updated or populated on the Tree Viewer secondary page (PSTRREVIEWER), when the user selects a specific node or leaf and clicks the Select button.

If the application specifies the node value and the leaf value, the search tries to find the leaf under the specified node. This is important when a tree contains duplicate leaves. If a tree does have duplicate leaves and no node is specified, the first leaf occurrence is returned.

The following fields (input) can be used to control the appearance and formatting of the Tree Viewer secondary page:

Invoking View Trees From Application Pages

This section outlines the development steps and provides some sample code to view trees from an application page. It provides two methods of how to view trees from application pages:

• Without multi-node selection.

• With multi-node selection.

To view a tree from an application page:

1. Add the PSTREEVIEWERWRK page to your component as a hidden page.

2. Add a field to a work record that will then be used as a Command Button or Hyperlink to your secondary page.

   The user selects this button or link to invoke the Tree Viewer page. You also need to add the following sample code to the FieldChange event for this field.

3. Add the Command Button or Hyperlink to the application page.

4. Add a Secondary Page control to the application page, and set the secondary page to PSTREEVIEWER.

   The Secondary Page control must be placed on the page at a level higher than level 3.

   In addition, the Command button or Hyperlink to invoke the PSTREEVIEWER secondary page must be placed on the same level as a secondary page control.

5. Add the application PeopleCode, which should do the following:

   1. Set the values of the Tree’s key fields on the PSTREEVIEWWRK record.

   2. Determine whether a node has been previously selected, and if so, setting the Tree_Node field to be the ID of the selected node:

      If a leaf has been previously selected, your code should do the following:

      — Populate the Range_From and Range_To fields with the selected leaf values

      — Set the Tree_Node field to the parent node

      — Set the Leaf_Selected field to "Y"

   3. Set any of the display options that you want to use.

   4. Display the Tree Viewer secondary page (PSTREEVIEWER) by calling the DoModal PeopleCode function.

   5. Optionally, check the return code value and storing the ID of the selected node if the user selected a node and clicked the OK or Select button.

/* Note: Keys of Tree are stored in &SetId,&TreeName variables. 
Assume that application has Leaf selected with values stored in variables &Range⇒
From; &RangeTo and has parent node name stored in &TreeNode variable. QE_TREETEST_⇒
WRK Record holds input and received output values. */

/*Tree to open specification */
PSTREEVIEWWRK.SETID = &SETID;
PSTREEVIEWWRK.SETCNTRLVALUE = " ";
PSTREEVIEWWRK.TREE_NAME = &TREENAME;
PSTREEVIEWWRK.TREE_BRANCH = " ";
PSTREEVIEWWRK.EFFDT = %DATE; /* Get Latest Tree as of Today */

/* Tree appearance specification */
PSTREEVIEWWRK.PAGE_SIZE = 60;
PSTREEVIEWWRK.SHOW_LEAVES = "Y";
PSTREEVIEWWRK.SHOW_LEVELS = "Y";
PSTREEVIEWWRK.MULTINODESELECTION = "N";

/* Leaf input specification */
/* (Assuming QE_TREETEST_WK.LEAF_SELECTED ="Y"; */
PSTREEVIEWWRK.LEAF_SELECTED = QE_TREETEST_WRK.LEAF_SELECTED;
PSTREEVIEWWRK.TREE_NODE = &TreeNode;
PSTREEVIEWWRK.RANGE_FROM = &RangeFrom;
PSTREEVIEWWRK.RANGE_TO = &RangeTo;

/* Opening the PSTREEVIEWER secondary page */
&rslt = DoModal(Page.PSTREEVIEWER, " ", - 1, - 1);

/* populating the application Record (QE_TREETEST_WRK) with output values from⇒
 user selection in Tree */
If &rslt = 1 Then
​   QE_TREETEST_WRK.TREE_NODE = PSTREEVIEWWRK.TREE_NODE;
   QE_TREETEST_WRK.TREE_LEVEL_NUM = PSTREEVIEWWRK.TREE_LEVEL_NUM;
   QE_TREETEST_WRK.TREE_LEVEL = PSTREEVIEWWRK.TREE_LEVEL;
   QE_TREETEST_WRK.TREE_LEVEL_DESCR = PSTREEVIEWWRK.TREE_LEVEL_DESCR;
   QE_TREETEST_WRK.RANGE_FROM = PSTREEVIEWWRK.RANGE_FROM;
   QE_TREETEST_WRK.RANGE_TO = PSTREEVIEWWRK.RANGE_TO;
   QE_TREETEST_WRK.DYNAMIC_FLAG = PSTREEVIEWWRK.DYNAMIC_FLAG;
   QE_TREETEST_WRK.MESSAGE_SET_NBR = PSTREEVIEWWRK.MESSAGE_SET_NBR;
   QE_TREETEST_WRK.MESSAGE_NBR = PSTREEVIEWWRK.MESSAGE_NBR;
End-If;

The following is the sample PeopleCode (Method A), which would be part of the FieldChange event triggered from a Command Button or Hyperlink command on the application page:

In some cases, you may need to use the Component Level Record variable &cPSTREEVIEWWRK to set values for the tree. For example, if the application added the Tree Viewer secondary page to the application’s secondary page and cannot reach the record from the component buffer. The following is the sample PeopleCode illustrating the use of the variable:

Component Record &cPSTREEVIEWWRK;
Component boolean &gbShowTreeLeaves;
Local number &rslt;

/* opening the Tree Viewer secondary page */

&cPSTREEVIEWWRK = CreateRecord(Record.PSTREEVIEWWRK);

&cPSTREEVIEWWRK.SETID.Value = &SETID;
&cPSTREEVIEWWRK.SETCNTRLVALUE.Value = " ";
&cPSTREEVIEWWRK.TREE_NAME.Value = &TREENAME;
&cPSTREEVIEWWRK.TREE_BRANCH.Value = " ";
&cPSTREEVIEWWRK.EFFDT.Value = %DATE; /* Get Latest Tree as of Today */;
&cPSTREEVIEWWRK.PAGE_SIZE.Value = 60;
&cPSTREEVIEWWRK.SHOW_LEVELS.Value = "Y";
&cPSTREEVIEWWRK.MULTINODESELECTION.Value = "N";

If &gbShowTreeLeaves Then
   &cPSTREEVIEWWRK.SHOW_LEAVES.Value = "Y";
Else
   &cPSTREEVIEWWRK.SHOW_LEAVES.Value = "N";
End-If;

&rslt = DoModal(Page.PSTREEVIEWER, "", - 1, - 1);

/* reading output value in a case when Component Level Record variable &c⇒
PSTREEVIEWERWRK is used. */

If &rslt = 1 Then
​   QE_TREETEST_WRK.TREE_NODE = &cPSTREEVIEWWRK.TREE_NODE.value;
   QE_TREETEST_WRK.TREE_LEVEL_NUM = &cPSTREEVIEWWRK.TREE_LEVEL_NUM.value;
   QE_TREETEST_WRK.TREE_LEVEL = &cPSTREEVIEWWRK.TREE_LEVEL.value;
   QE_TREETEST_WRK.TREE_LEVEL_DESCR = &cPSTREEVIEWWRK.TREE_LEVEL_DESCR.value;
   QE_TREETEST_WRK.RANGE_FROM = &cPSTREEVIEWWRK.RANGE_FROM.value;
   QE_TREETEST_WRK.RANGE_TO = &cPSTREEVIEWWRK.RANGE_TO.value;
   QE_TREETEST_WRK.DYNAMIC_FLAG = &cPSTREEVIEWWRK.DYNAMIC_FLAG.value;
   QE_TREETEST_WRK.MESSAGE_SET_NBR = &cPSTREEVIEWWRK.MESSAGE_SET_NBR.value;
   QE_TREETEST_WRK.MESSAGE_NBR = &cPSTREEVIEWWRK.MESSAGE_NBR.value;
​   
   EndModal(1);
   
Else
   EndModal(0);
   
End-If;

Note. The name of the variable &cPSTREEVIEWWRK is hard-coded and should not be changed.

The segment of code in italics reads the results that came from the tree. (Node or leaf selected).

View Trees From Application Example−Without Multi-Node Selection (Method A)

An example of an application that uses the Tree Viewer secondary page (PSTREEVIEWER), with the Multinodeselection flag set to "N", is the Using Copy/Delete Tree (PSTREEMAINT) component. Navigate to the component, select any tree and click the View button.

See Maintaining Trees.

Understanding the Tree Viewer page

View Trees From Application Example−With Multi-Node Selection (Method B)

An example of an application that uses the PSTREEVIEWER secondary page, with the Multinodeselection flag set to "Y", is the Using Query Manager component. Navigate to the Query Manager component, select any query and click the Add Criteria Image. The Edit Criteria Properties page opens. Select field as the first expression then select in tree as the condition type. Click the New Node List link to display the Select Tree page. Click the name of the desired tree.

See Maintaining Trees.

Understanding the Display and Select TreeNodes Page

The Tree Viewer secondary page (PSTREEVIEWER) in Method B has a frame that holds the Selected Nodes List with action buttons associated with each selected node.

This page is used to select the set of nodes, get them back to the calling application, (Query Manager), and use the list of nodes as Query criteria.

To select tree nodes:

1. Highlight the desired tree node and click the Add Node icon.

2. If you know the name of the desired node you can use the manual selection option. Enter the name of the desired node or use the Lookup button to select from a list of available nodes. Click on the Add to List button to add the node to the list.

3. The nodes you entered or selected from the list appear in the Selected Nodes drop-down list box.

4. Delete nodes from the list by clicking the Remove Node From List icon.

5. Display the selected node in the Tree by clicking the Find icon.

6. Click OK when the list is complete to close the Display and Select TreeNodes (PSTREEVIEWER secondary page).

   The selected tree setID, tree name, effective date, and selected nodes display in the Select Tree Node List dialog box.

   The list of selected nodes can be read from the Multinode field of the PSTREEVIEWWRK work record as a comma-separated string. The string can be parsed to get the node names.