How to configure a Dynamic Select control (V4.2)
Summary
Updates: V5.2 and later includes a standard HTML Property rule DynamicSelect that accepts parameters corresponding to the HTML attributes below.
Using this HTML Property rule in the Format field of a Field panel is simpler than hand-coded HTML and covers all but very advanced situations.
V5.4 provides direct access to the parameters of the DynamicSelect HTML property rule. See How to configure a Dynamic Select control (V5.4).
Suggested Approach
A Dynamic Select control is an HTML <Select ..> element with additional attributes.
To use a Dynamic Select control in a Rule-Obj-HTML instance you must include the Rule-HTML-Fragment instance DynamicSelect_Script by using
the following syntax:
{INCLUDE Rule-HTML-Fragment=DynamicSelect_Script}
Since SmartFrame-based rules already include this fragment, you do not need to add the {INCLUDE } tag to flow action or section rules that are in the SmartFrames format.
The syntax of a Dynamic Select control is:
<SELECT id="aDSControl"
DSSource="string"
DSCaption="string"
DSValue="string"
DSLoadMode="Auto|Dynamic|OnDemand"
DSRefreshOnLoad*="true|false"
DSDefault="string">
</SELECT>
(Starting with V4.2SP2, the DSRefreshOnLoad attribute is deprecated. Use DSLoadMode instead.)
Please note that the ID attribute of the Select element is required.
Attributes
| Attribute | Description |
|---|---|
| DSSource | A required string that defines the activity and its parameters that is used to populate the Dynamic Select control. The activity must return XML of a page of class Code-Pega-List. Typically it would do this by executing the Show-Page method on a page created by a previous step. For example, suppose you have a data table containing a list of product codes that you wish to display to your user in the dynamic select drop-down box. Step 1 in your activity would use the Obj-List method on your data table class to create a Code-Pega-List page, called ProductCodes perhaps, in the user clipboard. Step 2 executes Show-Page on ProductCodes, returning the xml for that page to the dynamic select control. As of V4.2 SP2, a reference to an HTML element can be used for a parameter value. The ID of the element is enclosed between an opened and a closed bracket. Syntax: pyActivity=ActivityClass.ActivityName&ActivityParamter1= value1&ActivityParameter2=[textBox1] For example, to get a list of classes, use the following DSSource: pyActivity=Rule-Obj-.LookupList&pyListName=List&pyObjClass=Rule-Obj-Class |
| DSCaption | A required semicolon-delimited string of property names that form the text of Option elements in the Dynamic Select. Syntax: propertyName1;propertyName2;... For example. to display the name and the label of a class as the text of the Dynamic Select options elements use the following: DSCaption="pyClassName;pyLabel" |
| DSValue | A required semicolon-delimited string of property names that form the values of the Option Elements in the Dynamic Select. Syntax: propertyName1;propertyName2;... For example, to set the values of a Dynamic Select to the class names in a list use the following: DSValue = "pyClassName" |
| DSRefreshOnLoad | Deprecated starting with V4.2SP2. Use DSLoadMode instead. A boolean attribute. If true then Dynamic Select will be populated when the HTML page is loaded. |
| DSDefault | An optional string value that sets the default value of the Dynamic Select. To preserve the value of a Dynamic Select element when a form a submitted, this attribute must be set to the value of the property it’s bound to. Examples: If a Dynamic Select is used in an HTML Property, then one of the bellow syntaxes could be used: Syntax for HTML directives: DSDefault = “{$THIS-VALUE}” Syntax for JSP tags: DSDefault = “<pega:reference name=”$THIS-VALUE”/>” |
| DSDefaultCaption | An optional string to replace the default caption of Dynamic Select. If this attribute is not specified, Dynamic Select displays "Select...". |
| DSTargetID | An optional* semicolon-delimited string value that sets the IDs of the Dynamic Select(s), whose values depend on the value selected in this Dynamic Select. When a selection is made in this Dynamic Select, its value gets appended to the DSSource of the target Dynamic Select(s). The activity of the latter is then executed to populate it. The DSSource of the target control must end with the following syntax: parameterName=. The value of the selected option in the first Dynamic Select then becomes the value of the parameter in the activity of the target Dynamic Select. For example, to list properties in a certain class in a Dynamic Select, you define two Dynamic Select controls. One gets the list of classes; the other gets the list of properties based on the class a user selects in the first Dynamic Select: <SELECT id="DSClasses" <SELECT id="DSProperties" *The ability to have multiple targets is introduced in V4.2SP2 . |
| New Attributes in V4.1SP3 | |
| DSNoDataCaption | An optional string value that sets the message that Dynamic Select displays when no data is found. Default value is "No results were found.". |
| New Attributes in V4.2SP2 | |
| DSDelimiter | An optional string that defines the delimiter used to concatenate multiple captions or values. The default value is the space character. |
| DSLoadMode | A required string attribute. It can set to one of three values:
Initially, the default value is selected and if no DSOnDemandCaption attribute is set, it's also the caption. |
| DSOnDemandCaption | An optional string to set the caption of the default value when the Dynamic Select control is set to OnDemand mode. The value of this attribute could be one of three:
pyActivity=myClass.myActivity¶m=value.... |
| DSWaitTime | An optional attribute. It instructs Dynamic Select to wait an x number of seconds before it gives up on a request. The default value is 3 seconds. The minimum value is 1 second and the maximum value is 60 seconds. |
| DSEnableCache | An optional boolean with a default value of true. When set to true, Dynamic Select will cache the data that it receives for a URL and will not call that URL again and instead will reuse the cache the next time the data is needed. This is especially useful when one HTML document includes a group of Dynamic Select controls that have the same value for the DSSource attribute. |
Public Functions
| Function | Description |
|---|---|
| DS_loadControl | This function loads a Dynamic Select control which it receives as a parameter. DS_loadControl(document.all("DSOperators")); //DSOperators is an ID of a Dynamic Select control. |
Examples
In this example, three Dynamic Select controls are built. The first lists organizations, the second divisions and the third units. When an organization is selected from the first one, the divisions are loaded into the second one and when a division is selected, the units are loaded into the third one.
The first control is configured to load OnDemand. This is a good practice, because the data is requested from the server only if and when needed.
The second and third controls are configured to load dynamically since their data depends on selections made in other controls.
To get lists of organizations, divisions and units we will use three list view rules. To get the data from the List Views and send it back to the controls, we will create three activities that call the List View rules, read the data from the report pages and send them as XML to the controls. Finally, we create a Rule-Obj-HTML rule that includes the three controls.
The images below show the configurations of the list view rules
List view rule to get a list of organizations
List view to get a list of divisions in an organization.
Notice that the criteria uses a parameter for an organization to filter the list of division. This parameter will be passed to this list view by the activity specified in the DSSource attribute of the second control.
List view to get a list of organization units.
The list is filtered by an organization and a division which are passed as parameters by the Activity in the DSSource attribute of the third control.
The images below show the configuration of the three activities specified in the DSSource attribute of the three Dynamic Select controls. Each activity gets the data from a list view by calling the standard Rule-Obj-ListView.ShowView Activity.
As the last step in building this example, create an HTML rule that has the three Dynamic Select controls. For this example, the HTML rule uses JavaServer Page tags. ( To get this example to work with SmartFrames rules, don't include the DynamicSelect_Script fragment. )
The source code below is an example on how to include the three controls and call the activities created above.
<html>
<pega:include name="DynamicSelect_Script" type="Rule-HTML-Fragment"/>
<body >
Organization
<select id="DSOrganization" DSCaption="pyOrganization" DSValue="pyOrganization"
DSDefaultCaption="Select Organization..." DSTargetID="DSDivision"
DSSource="pyActivity=Data-WBTests-DynamicSelect.getOrganizations" DSLoadMode="OnDemand"> </select>
<p> Division
<select id="DSDivision"
DSCaption="pyOrgDivision"
DSValue="pyOrgDivision"
DSDefaultCaption="Select Division"
DSTargetID="DSUnit" DSSource="pyActivity=Data-WBTests-DynamicSelect.getOrgDivisions&organization=" DSLoadMode="Dynamic">
</select>
<p> Unit
<select id="DSUnit"
DSCaption="pyOrgUnit"
DSValue="pyOrgUnit"
DSDefaultCaption="Select Unit"
DSTargetID=""
DSSource="pyActivity=Data-WBTests-DynamicSelect.getOrgUnits&organization=[DSOrganization]&division="
DSLoadMode="Dynamic">
</select>
</body>
</html>
Note: To submit to the clipboard the value selected in a dynamic select control, use the standard HTML Name attribute:
<Select id="JobDropDown"
Name = "JobSelected"
DSCaption="JobTitle"
DSValue = "pyID"DSSource="pyActivity=MyCompany-HR-Recruit-JobApp.GetJobList"
DSRefreshOnLoad="false">
</Select>
In JSP-based HTML streams, the name attribute must be set to the property name of the Dynamic Select it’s bound to. In an HTML Property rule, you can follow the following example:
<Select id="JobDropDown"
Name = "<pega:reference name="$THIS-NAME"/>"
DSCaption="JobTitle"
DSValue = "<pega:reference name="$THIS-VALUE" />"
DSSource="pyActivity=MyCompany-HR-Recruit-JobApp.GetJobList"
DSLoadMode="Auto">
</Select>