Back Forward Harness, Section, and Flow Action forms
Adding an Autocomplete field

 About Harness rules

 zzz Show all 

Use an AutoComplete control to allow the user to select a value from a possibly large set of searched text values, based on a partial string match. The system dynamically assembles and displays a list of candidate matching values after the user types one or a few characters of input.

Unlike a static list (such as produced by a Local List on the Table Type fields of a Property form), the drop-down values presented by an Autocomplete control may vary from user to user and from time to time. Unlike a Dynamic Select control, the user must type at least one or a few characters to activate the control.

For example, when searching for an employee by first name, the user can type two characters such as "AL". An autocomplete control can run an activity to create a list of employees in a Page List structure, one page per employee, and match on the embedded FirstName field, presenting matching candidates Alan, Allan, Albert, and so on.

The autocomplete icon at the right of a field indicates that autocomplete is available.

AutoCompleteThe standard section rule Data-Party.PartyAddress includes an Autocomplete example, for the property pyStateCode. The standard activity Data-Party.getStateList assembles the list of state codes from field value rules. Parameters to the AutoComplete HTML property rule identify the Display Field as pyLabel, the Text Box Size and Listing Width as 2 characters, and the Only match... option enabled. At runtime, the drop-down list appears after the user types a single letter.

 zzz 1. Plan and prepare

Confirm that user requirements for the text box field are best met by an AutoComplete control rather than alternatives.

Determine the name of the clipboard page (a Page List or class Code-Pega-List) that is to be searched. When the flow action or work object form appears, is that page already present with appropriate data, or do you need to build an activity to construct it?

NoteWhen building an activity, it is often useful to review and copy (using a new name) the standard activity named LookupList for the class containing the objects, if the objects are rows of a table in the PegaRULES database. Design the activity to:

  1. Create a Page Group page of class Code-Pega-List, with each embedded page containing the values of the pyLabel property and of the property containing the text values to be displayed (the display field).
  2. Set the value of an OUT activity parameter named pyDataSourcePageName containing the fully qualified name of the Page Group page (or include a Show-Page method step for that page).

 zzz 2. Drag and drop the AutoComplete control

Click the down-arrow (Arrow) at the right end of the Advanced control group (Layout group) and select the Autocomplete control (Layout). Drag the control. When the pointer changes shape to indicate that you can drop the layout, release the mouse button.

 zzz 3. Complete the Cell Properties panel — Top fields

Complete Cell Properties panel, starting with the top fields.

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 preferences. If the panel is pinned(pin), the wireframe on the rule form changes immediately to reflect your inputs. If the panel is not pinned(pin), click Apply to apply your inputs.

Field

Description
Property

SmartPromptSelect 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.pyTemplateAutoComplete only when prototyping work object forms and the actual property is not yet defined.)

Click the pencil icon (Pencil) to review the property rule (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.
Display As

SmartPrompt Accept the supplied value AutoComplete. Click the magnifying glass icon (magnifying glass) to enter parameters.

Click the magnifying glass icon (Magnifying glass ) to the right of the Format field to enter parameters for the Autocomplete HTML property.

Complete the Parameter fields; then click Save.

Parameter Description
DataSource Type

Select a radio button to indicate whether the values to appear are present in a clipboard page, or the clipboard page is constructed by an activity.
Basic Information  
Activity Class Name

SmartPromptIdentify the Applies To class of the activity. This field appears only when you select the Activity radio button. If omitted, the system uses the class of the primary page to find the activity.
Activity Name

SmartPromptIdentify the Activity Name of the activity. If the activity requires input parameters, click the Params button and enter parameter values. This field appears only when you select the Activity radio button.
ClipboardPage Name

Enter the fully-qualified name of the clipboard page containing the candidates to be matched. This field appears only when you select the Clipboard Page radio button. This can be a Declare_ clipboard page.

Additional Information  
Search Property Applies To

SmartPromptOptional. Identify the Applies To class of the Page List property containing the candidate matches.
Display Field

Identify a scalar embedded property within each page of the Page List that contains the text value to be matched.
additional Field

Optional. Identify a second property within each page of the Page List that can be displayed to assist user selection. (This property is not text-matched). For example, if the displayField property is FirstName, presenting an additionalField of LastName may help the user make a choice.
Category Field

Optional. Identify a second property within each page of the Page List for grouping results. This operates similar to a Group By field in a summary view display.

Search Property Name

Optional. Identify the name of the Page List property containing the candidate matches. If omitted, the system assumes the property name is pxResults.

NoteEnter the property name only, not a fully qualified property reference. The system determines the property reference from this value and the value in the Clipboard Page Name or the pyDataSourcePageName activity parameter.
Maximum Results

Optional. Enter an integer that defines a maximum number of matches to display. If omitted, up to 10 matches appear.
Text Box Size

Optional. Enter an integer that determines the width of the text box, in characters. If omitted, 50 characters is the default value.
Minimum Search Characters

Optional. Enter a positive integer determining the minimum number of input characters a user types before AutoComplete processing begins. If omitted, the default is one character.
Listing Width

Optional. Enter a maximum width for the drop-down display in characters.
Highlight

Select to cause the text that matches user input to be highlighted in bold text.

Only match the start of string

Select to cause matching to occur only on the initial portion of the string, so that user input of 'AL" matches Alabama, Alaska, and Alan.

Clear to allow a wildcard match anywhere within the candidate text values, so that user input of 'AL' matches Paloma and Musical.
Client Cache

Select to cause listed results to be cached temporarily on the client workstation, for faster access upon a second similar request. Leave cleared if the listed results are highly dynamic.
Send Search Term

AdvancedSelect to cause the user's typed value to be sent to the server as a parameter named searchTerm.

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 (Magnifying glass) 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 ( Help) on the Client Event Editor for assistance. For general information on this capability, see Implementing dynamic form actions and the Client Event Editor.

Event support is available for harness, section, or flow action rules that have Generate for set to JSP on the HTML tab and that use the SmartFrames layout.

 zzz 4. Complete the Cell Properties panel — General tab

The General tab for an AutoComplete control is identical to the General tab for an Input Box control. See Completing the Layout tab — Adding a Input Box — General tab.

 zzz 5. Complete the Cell Properties panel — Advanced tab

The Advanced tab for an AutoComplete control is identical to the Advanced tab for an Input Box control. See Completing the Layout tab — Adding a Input Box — Advanced tab.

 zzz Notes

The standard HTML Property rule Autocomplete accepts the parameters described above. This HTML Property rule is based on the autoComplete JSP tag, which offers additional advanced options including control over timing. See autoComplete JSP tag.

This feature depends on AJAX technology.

zzz About Flow Action rules

zzz About Harness rules

zzz About Section rules