Dynamic Select controls — Internal operations and advanced features

Definition

The image at right shows the runtime appearance of the Dynamic Select control defined by the standard HTML Property rule named DS_Organization. (This HTML property rule is used in the Application Accelerator to allow the user to pick an organization from a list.)

Don't use the Dynamic Select control to present a static list. Complete the Table Edit tab of the Property form to hold the values using the Local List option, or include the values as a set of field value rules.

Execution sequence

At runtime, a use of a Dynamic Select control has seven steps:

1. The user places focus on an input field on a Process Commander form that contains the Dynamic Select control.
2. A JavaScript function executes on the workstation, sending a short HTTP message to the Process Commander server.
3. After the server receives the message, the server executes an activity to produce an XML document listing both the text values that form the list and a value for each.
4. The server sends the XML document to a user workstation.
5. A JavaScript function on the workstation presents the list, without repainting the entire form.
6. The user selects an item from the drop-down list.
7. The clipboard property associated with the input field is updated to contain a value determined by the user's selection.

Development

Complete three steps to configure a Dynamic Select control. Although you can complete the steps in any order, this order is recommended:

1. Find or create an activity that creates an XML document containing the list of values to appear at runtime.
2. Create an HTML property rule containing the appropriate JavaScript functions. Include a <SELECT> element with extended attributes as defined below.
3. Reference the HTML property rule in a flow action rule, harness rule, section rule, or other HTML rule, identifying a property presented to the user in read-write mode (input mode).

The activity may perform any processing required to assemble values into a clipboard page that meets criteria described in this help topic.

As the final step, the Show-Page method formats information on that page into an XML document sent to the user. When received, Internet Explorer displays the choices identified in the document as part of the Process Commander form.

The structure of the clipboard page must be similar to that produced by the Obj-Browse method, though it can be produced by any means:

• The page has a class of Code-Pega-List.
• The value of the pxResultCount property is a non-negative integer indicating the number of results.
• Property values are embedded on pages of the pxResults property, a Page List.

The sample XML document below contains three pxResults pages. The second and third pages contain values for two properties used in the Dynamic Select control — Company and Account. (The XML document may contain additional elements; they do not affect the processing.)

<?xml version="1.0" ?>
<pagedata>
<pzStatus>valid</pzStatus>
<pxObjClass>Code-Pega-List</pxObjClass>
<pyObjClass>Data-Customer</pyObjClass>
<pxResultCount>3</pxResultCount>

<pxResults REPEATINGTYPE="PageList">
   <rowdata REPEATINGINDEX="1">
     <pxObjClass>Data-Customer</pxObjClass>
   </rowdata>
   <rowdata REPEATINGINDEX="2">
     <Company>MyCo Incorporated</Company>
     <Account>004325</Account>
   </rowdata>
   <rowdata REPEATINGINDEX="3">
      <Company>Micro Small Co.</Company>
      <Account>009142</Account>
   </rowdata>
</pxResults>

</pagedata>

For example, if your application includes a Data Table class containing a set of product codes, a three-step activity can support the display of these codes in a Dynamic Select drop-down box:

• Step 1 uses the Obj-List method on your class to create a page of class Code-Pega-List named ProductCodes.
• Step 2 executes the Show-Page method on the ProductCodes page, returning the XML text for that page to the Dynamic Select control.
• Step 3 uses the Page-Remove method to delete the clipboard page, because the page is no longer needed.

In many cases, the activity queries the PegaRULES database or another database. Use care to limit the number of rows returned and the impact of this query on overall system performance. Users make fast and accurate choices when presented with seven or fewer alternatives. A Dynamic Select control that displays more than a few dozen choices may cause user confusion or errors, and so may benefit from redesign. When appropriate, enable caching (with the optional DSEnableCache attribute) to reduce database traffic.

Complete these steps to construct the control.

You can include the JavaScript functions and calls that support the Dynamic Select control in the HTML code of any type of stream rule. However, when the control is needed only on one or a few work object forms, use the standard HTML Property rule named DynamicSelect and the Formats panel rather than creating new HTML Property rules. See Harness, Section, and Flow Action forms — Defining a Dynamic Select control for a field.

1. Create a new HTML Property rule in your application RuleSet. By convention, the names of such rules start with DS_.

2. In the HTML code of the rule, incorporate the standard Rule-HTML-Fragment rule named DynamicSelect_Script by using a JavaServer Page tag:

If using JSP tags, enter this text:

<pega:include name="DynamicSelect_Script" type="Rule-HTML-Fragment" />

If using directives, enter this text:

{INCLUDE Rule-HTML-Fragment=DynamicSelect_Script}

3. Code the Dynamic Select control using the following syntax:

<SELECT   
     DSSource=  "value1"
     DSCaption= "value2" 
     DSValue=   "value3"
     DSLoadMode="mode"
     DSDefault= "value4"
     id=        "identifier"  
     ... >
</SELECT>

where the five listed DSZzzz attributes are required, and additional optional attributes may appear. The ID attribute is optional. (HTML attributes can appear in any order.)

4. Save the HTML Property rule form.

Required attributes

Include values for these five required attributes within the <SELECT> element:

Initially, the default value appears as selected.

If no DSOnDemandCaption attribute is set, it's also the caption.

These attributes may also appear in the <SELECT > element to refine the appearance and behavior of the control.

Finally, an HTML form presented to the user must include the control.

Typically, the HTML Property rule is referenced in a flow action rule or section rule, to override another HTML Property rule identified in the property rule itself. For example, in the Field panel of a Flow Action form, the optional Format field defines the HTML Property rule used for the field.

In the unusual case that you compose an entire HTML rule using open authoring, include the usual HTML Name attribute to save the value selected by the user into a clipboard property. For example, if the property is JobSelected:

<Select id="JobDropDown"
      Name = "JobSelected"
      DSCaption="JobTitle"
      DSValue = "pyID"      
      DSSource="pyActivity=MyCompany-HR-Recruit-JobApp.GetJobList"       DSRefreshOnLoad="false">
</Select>

In most situations, this is not necessary, as the system adds the Name attribute and the target property name automatically.

Gadget

The standard HTML rule Data-Gadget.myGroupDD uses a Dynamic Select control to list operators in the user's work group and to list workbaskets.

HTML Property rules

Your system includes several HTML property rules named DS_Zzzzz that use a Dynamic Select control. You can use them directly, or copy them using a new name, and modify the copy.

The HTML form listed below includes two cascading Dynamic Select controls. At runtime:

• The first control lists all work groups — all instances of the Data-Admin-WorkGroup class — in the system.
• The second control lists those Operator IDs (pyUserIdentifier property) that belong to the Work Group that the user selected in the first Dynamic Select control.

(Both call the standard LookupList activity, which accepts several parameters.)

<HTML>
 <HEAD>
 <!--set the base of the html to the location
    where Dynamic Select scripts exist.-->
 <base href="{pxRequestor.pxReqScheme  NORMAL}://{pxRequestor.pyHTTPRequestHeaders.pxReqHdrHost  NORMAL}{pxRequestor.pxHomeDirectory NORMAL}/">

 {INCLUDE Rule-HTML-Fragment=DynamicSelect_Script}

</HEAD>

<BODY>
 <TABLE>
  <TR>
   <TD>Select Workgroup</TD>
   <TD>
    <Select id="DSWorkGroups"
         DSCaption="pyWorkGroupName"
         DSValue = "pyWorkGroupName"
         DSSource="pyActivity=Data-Admin-Workgroup.LookupList
          &pyListName=List
          &pyObjClass=Data-Admin-WorkGroup"          DSTargetID="DSOperators"
         DSRefreshOnLoad="true">
    </Select></TD>
  </TR>

  <TR>
   <TD>Select User Name</TD>
   <TD>
    <Select id="DSOperators"
        DSCaption="pyUserName"
        DSValue = "pyUserIdentifier"
        DSSource="pyActivity=Data-Admin-Operator-ID.LookupList
         &pyListName=List
         &pyObjClass=Data-Admin-Operator-ID
         &p1=pyWorkGroup
         &v1="
        DSTargetID=""
        DSRefreshOnLoad="false">
    </Select>
   </TD>
  </TR>
 </TABLE>
</BODY>
</HTML>

These related articles are available in the Pega Developer Network:

• PRKB-5916 How to configure a Dynamic Select control (V4.2) is a primary reference.
• PRKB-16956 How to customize of a LookupList-based Dynamic Select control covers a special case.

If a Dynamic Select control will be used frequently, for best performance make each of the properties that it retrieves exposed columns in the database.

The word ERROR as an element of a drop-down list indicates that the workstation may be disconnected from the server.

The JavaScript DS_loadControl() function loads a Dynamic Select control that it receives as a parameter. This can be useful in dynamic forms. For example, the following call searches the HTML DOM for an element with ID of DSOperators:

DS_loadControl(document.all("DSOperators"));  //DSOperators is an ID of a Dynamic Select control.