Harness, Section, and Flow Action forms
Adding a Dynamic Select control

A Dynamic Select control is an optional feature you can add to user forms (through flow actions, harnesses, or sections) to speed user input. The user chooses from one list, computed on demand, to determine a (possibly distinct) value to assign to the property. For example, a user may choose a school course name "Introduction to Computers" from a list that shows only courses with unfilled enrollment. Reflecting the user's choice, the Dynamic Select control may assign a corresponding value such as COMP101 to the property.

Don't use a Dynamic Select control if the options for the drop-down list are stable and the list will be short. Consider providing the values on the General tab of the Property rule:

1. Set the Property Mode to Single Value.
2. Set the Property Type to Text.
3. Set the Table Type to Local List. A Table Values form appears. Enter the values for the drop-down list.

Don't use a Dynamic Select control if an ordinary (that is, static) HTML Select box meets the need. See Harness, Section, and Flow Action forms — Adding a Select control.

Use this procedure when the values that users select and the values for the property are both present as columns in a list view rule.

Find or create a list view rule. Enter ALL as the Owner key part. Specify the following in the list view rule:

1. In the Show These Fields area of the Display Fields tab, identify two properties. Identify a property for the report column that is to contain the possible values of the property. Identify a second property as the source of text values to appear in the drop-down list. (If the values to appear in the drop-down list are the same as the internal property values, you can include the property only once.)

   The Dynamic Select feature provides best performance when these two properties that are exposed as columns in the PegaRULES database table that supports the class. If they are not now exposed, update the database schema to expose them if feasible. This is important if the Dynamic Select control is to be used with high frequency.

2. Complete the selection criteria, sorting, and other fields on the List View form. Don't enable report paging, as the Dynamic Select drop-down list then shows only items on the first page.
3. Save and test the new list view rule.

Often, values for the Dynamic Select control are instances of a class that users maintain with the Data Table editor. If so, you can use either of two standard list view rules:

• Data-.ListDataInstances.ALL — To present all instances of a specified class.
• Data-.ListDataInstancesWithFilter.ALL — To present those instances of a specified class for which the pxInsName property starts with a prefix text value. Set the InsNameStartsWith parameter to the desired prefix text.

Use this procedure when the values that users select and the values for the property are both present as columns in a report definition.

Find or create a report definition. Specify the following in the report definition:

1. In the Columns To Include area of the Design tab, identify two columns that specify the two properties for the Dynamic Select feature:
   • One report column that is the source of the possible values of the property associated with the Dynamic Select.
   • One report column that is the source of the text values to appear in the drop-down list. (If the values to appear in the drop-down list are the same as the internal property values, you can include the property only once.)
2. Complete the fields on the Report Definition form. Don't enable report paging, as the Dynamic Select drop-down list then shows only items on the first page.
3. Save and test the new report definition.

Use this procedure when the values that users select and the values for the property are both present on a clipboard page.

Determine the name of the clipboard page (a Page List or class Code-Pega-List) that is to be located at runtime for the source of the properties. For example: when the flow action or user form appears, is that clipboard page already present with the appropriate data for this Dynamic Select? Or do you need to build an activity to construct the clipboard page to ensure it is present at the right point in the process at runtime?

In some cases, your application can't present the needed data using only a list view, report definition, or clipboard page. For example, some data values may be contained in an external system, accessed through a connector. You can create an activity that produces the XML document needed by the Dynamic Select control.

Find or create an activity that produces as output a top-level clipboard page. In simple cases, if the class containing the instances to be listed is derived from the Data- base class, you may use the standard activity Data-.GetClassInstances. The structure of the clipboard page produced by the activity must be similar to that produced by the Obj-Browse method, though you can produce it by any means:

• The page must have a class of Code-Pega-List.
• The value of the pxResultCount property is a non-negative integer indicating the number of rows to display.
• Property values are embedded on pages of the pxResults property, a Page List.
• The order of pxResults() pages determines the order that values appear on the drop-down list.
• Each embedded pxResults() page contains a value to appear on the Dynamic Select control and the corresponding internal value to be assigned to the property.

As the final step of the activity, use the Show-Page method to convert this page to an XML document. Check the May Start? option on the Security tab of the Activity form.

Click the down-arrow () at the right end of the Advanced control group () and select the Dynamic Select control (). Drag the control to the cell or header that is to contain the property value. When the pointer changes shape to indicate that a single cell is selected, release the mouse button to drop the control.

If the cell is not empty, the dropped control replaces the current contents of the cell. Click the magnifying glass ()to display the Cell Properties panel.

Complete top fields of the Cell Properties panel.

Your updates to this panel can update the rule form immediately or upon clicking Apply, depending on the Property Panel settings in your Edit preferences. See Setting your preferences. If the panel is pinned(), the wireframe on the rule form changes immediately to reflect your inputs. If the panel is not pinned(), click Apply to apply your inputs.

Field	Description
Property	Select or type a property reference that identifies a single text value that has a dynamic set of possible values. (Use the default placeholder property @baseclass.pyTemplateDynamicSelect only when prototyping user forms and the actual property is not yet defined.) Click the pencil icon () to review the property (if the reference is to an existing property in the Applies To class of this rule or a parent of that class). If the property is not found, the New dialog box for the property form appears. You can reference properties on any page identified on the Pages & Classes tab, using the normal notation pagename.propertyname for pages other than the page corresponding to the Applies To class of the rule.
Control	Accept the supplied value DynamicSelect. Click the magnifying glass icon () to enter parameters. Parameter Description Method for Generating Dynamic Select Select a radio button to indicate which of the runtime approaches is to be used to derive the contents of the list. The parameter form changes to reflect your selection.     Report Definition Information Complete these fields if you selected the Report Definition radio button. Applies To Select the first key part of a report definition. Report Name Select the second key part — Report Name — of the report definition. At runtime, the system uses these two key parts and rule resolution to locate the report definition to run. List View Information Complete these fields if you selected the List View radio button. Applies To Select the first key part of the list view rule. View Purpose Select the second key part — Purpose — of the list view rule. At runtime, the system uses these two key parts and rule resolution to locate the list view rule to run. Clipboard Page Information Complete these fields if you selected the Clipboard Page radio button. Clipboard Page Specify the clipboard page (a Page List or class Code-Pega-List) that will be available on the clipboard at runtime. Class of Returned Results Optional. Specify the class of the pxResults() pages. (This helps during development, by facilitating SmartPrompt operations.) Activity Information Complete these fields if you selected the Activity radio button. Applies To Select the first key part of an activity. Activity Name Select the second key part of an activity. If the activity requires as an input parameter the value of a property controlled by another Dynamic Select control, you can identify this parameter and its source in the Filter fields. If the activity requires other input parameters, use the Advanced radio button to enter them in URL format. Class of Returned Results Optional. Identify the class of the pxResults() pages. (This helps during development, by facilitating SmartPrompt operations.) Advanced Additional fields appear if you select the Advanced radio button. See Advanced Format Parameters. Common Dynamic Select Information These fields apply to every Dynamic Select control, regardless of which approach you use to build it. Select ID Optional. Enter an alphabetic-only value for the ID=" " element in the <SELECT> control. The ID is required when you need to reference this control in another Dynamic Select control. Default Caption Optional. Enter a text value for the caption value in the control. For example, "Choose a state". Property for Option Display Identify the property that supplies the text values displayed to users at runtime. Property for Option Value Identify the property that is the source of internal values for the field on the Harness, Section, or Flow Action form. This property may be the same as the property in the Property for Option Display field. Enable Cache When set to true, Dynamic Select instructs the user browser to cache the data that it receives for a specific URL. The next time the data is needed (for the exact URL from this user), the activity is not called and the cached information is presented again. The default is true, which is recommended. This feature is especially useful when a single HTML form includes more than one Dynamic Select control that have a common value for the Source. For example, a user may need to select one or more General Ledger codes for debits, and later one or more General Ledger codes for credits. Filter Optional. Complete these parameters to filter the results in this Dynamic Select control based on the value at runtime of another Dynamic Select control on the same user form that users typically complete first. Enter one row if the values to be presented depend on the value selected by users on a single previously completed field controlled by a Dynamic Select control. Enter multiple rows if multiple selections affect the choices to be presented by this row. The SelectID of Dynamic Select control identified in the last row becomes the ParentID for this Dynamic Select control. As a result, the system refreshes the contents of this Dynamic Select only when the value changes in the parent control, not when any other Dynamic Selects control lists change. If your application requires this Dynamic Select control to refresh when a value changes for any of multiple parents, use the TargetID option in the Advanced format for the parent Dynamic Select controls. Field Description Param Name Optional. Enter the name of an input parameter to the activity identified in the Activity Name field, or a parameter affecting the list view rule identified in the View Purpose field. Do not prefix the parameter name with "param:". Select ID Optional. Enter the ID field of the other Dynamic Select control that at runtime has a value for the parameter.
Behavior	Optional. Leave blank if no dynamic form actions to other parts of the form are to occur based on user updates or values for this field. To establish a dynamic form action, click the magnifying glass icon () to open the Client Event Editor in a new dialog window. Complete the Client Event Editor to select an event (OnBlur, OnChange, or OnClick) and the resulting form action. Click the help icon ( ) on the Client Event Editor for assistance. For general information on this capability, see Harness, section, and flow action forms Help — Client Event Editor. Event support is available for harnesses, sections, or flow actions that have Generate for set to JSP on the HTML tab and that use the SmartFrames layout.

The General tab for a Dynamic Select control is identical to the General tab for a Text Input control. See Completing the Layout tab — Adding a Text Input control — General tab.

The Advanced tab for a Dynamic Select control is identical to the Advanced tab for a Text Input control. See Completing the Layout tab — Adding a Text Input control — Advanced tab.

Use the advanced approach described in this section when you require additional control over the function and appearance of a Dynamic Select control and are familiar with URL encoding.

1. Find or create an activity that produces a XML document, structured to match the XML document that corresponds to a clipboard page of class Code-Pega-List.

2. Select the Advanced radio button. Complete these fields.

When testing, clear the browser cache on your workstation frequently. (For Internet Explorer, select Tools > Internet Options > General > Delete Files).

Alternatively, click the Advanced radio button on this form and temporarily set the Enable Cache setting to false. After you complete testing, set the Enable Cache setting to true.

See the PDN articles:

• 26404 How to configure a dynamic select control using a report definition
• 25315 How to configure a dynamic select control V5.4
• 25898 How to configure cascading dynamic select controls.