Harness, Section, and Flow Action forms
Adding an Auto Complete control

Use an Auto Complete 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.

Configure styles for the Auto Complete control in the Skin rule. See Skin form — Styles tab — Layouts — Auto Complete.

Basics

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 Auto Complete 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". The 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 control can also use a report definition as the source of values to match.

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

The standard section Data-Party.PartyAddress includes an AutoComplete example, for the property pyWorkState. The standard activity Data-Address.getStateList assembles the list of state codes from field value rules. Parameters to the AutoComplete control 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.

For instructions on an activity-based example, see PDN article 25064 How to add an AutoComplete form to a flow action form.

The UI Gallery landing page contains a working example of this control. To view and interact with this example and review its configuration, select > User Interface > UI Gallery and select Auto Complete in the Controls group. For another use of autocomplete, see PDN article 26458 How to use the Autocomplete control to build a list.

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 report definition or clipboard page (a Page List or class Code-Pega-List) that is to be searched. When using a clipboard page as the source of values, determine whether the clipboard page will be available at runtime when the data is needed. For example, when the flow action or user form appears, is the work item ready present with appropriate data, or do you need to build an activity to construct it?

When 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:

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).
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).

2. Drag and drop the Auto Complete control

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

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 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

SmartPrompt Select or type a property reference that identifies a single text value that has a dynamic set of possible values.

Click the pencil icon ( Pencil ) 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 AutoComplete. Click the magnifying glass icon () to enter parameters.

Click the magnifying glass icon () to the right of the Format field to enter parameters for the AutoComplete Control rule.

Complete the Parameter fields; then click Save.

Parameter	Description
DataSource Type	Select a radio button to indicate whether the values are provided by: A report definition A clipboard page A clipboard page constructed by an activity
Basic Information	The DataSource Type selection determines the available fields in this area.
Applies To	Identify the Applies To class of the report definition. This field appears when you select the `Report Definition` radio button. If omitted, the system uses the class of the primary page to find the report definition.
Report Definition	Identify the Report Name of the report definition. This field appears when you select the `Report Definition` radio button.
Activity Class Name	Identify 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	Identify 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	Optional. 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.
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. Enter 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	Enter a positive integer that defines a maximum number of matches to display. The default value is 10, meaning that 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 positive integer determining the minimum number of input characters a user types before AutoComplete processing begins. If omitted, the default is one character.
First Column Width (%)	Optional. If the drop-down list contains multiple columns, specify the first column's width as a percentage of the total. The second column width is calculated as 100% minus the first column's percentage. Text is wrapped if it exceeds the available width.
Text Alignment in Columns	Select the text alignment settings for left and right columns.
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	Select to cause the user's typed value to be sent to the server as a parameter named searchTerm.
Use Best Bet	For DataSource Type of Activity only. Check to display at the top of the list (under the heading BestBets), the results that application users select most often. The rest of the results are listed under the heading ALL. This option sends an additional parameter named pzMode to the activity selected in the Activity Name field. You can configure it to return results grouped in both modes (BestBets or ALL), or all results grouped in either mode.
Use Category Field	Select to use property reference syntax the same way it is used in a SmartPrompt.
Additional Fields	Optional. Identify one or more second properties 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 Display Field property is `FirstName`, presenting an additional field of `LastName` may help the user make a choice. To specify an additional field, add a row () and enter the scalar embedded property to be matched (see Display Field) and the `PageList` property containing the candidate match (see Search Property Name) Select Show if you want these field values to appear in the drop-down list.
ReadOnly SmartInfo	Optional. When editing is enabled, select the SmartInfo section that contains the information that appears when the user hovers the mouse-pointer over this control.
ReadWrite SmartInfo	Optional. When editing is enabled, select the SmartInfo section that contains the information that appears when the user hovers the mouse-pointer over this control.
SmartInfoHeader	Enter text to appear in the header of the pop-up window. Alternatively, if this control is to be localized, identify a field value rule that contains the header text.

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 based on user updates or values for this field, click the magnifying glass icon () to open the Client Event Editor. 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.

4. Complete the Cell Properties panel — General tab

The General tab for an Auto Complete control is identical to the General tab for a Text Input control. See Adding a Text Input control — Complete the Cell Properties Panel — General tab.

5. Complete the Cell Properties panel — Advanced tab

The Advanced tab for an Auto Complete control is identical to the Advanced tab for a Text Input control. See Adding a Text Input control — Complete the Cell Properties Panel — Advanced tab.

Notes

The standard control AutoComplete accepts the parameters described above. This control 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.

About Flow Actions

About Harnesses

About Sections

Harness, Section, and Flow Action forms Adding an Auto Complete control

Field

Description

Harness, Section, and Flow Action forms
Adding an Auto Complete control