Back Forward Harness, Section, and Flow Action forms
Adding a list-to-list control

About Harness rules

  Show all 

Use a list-to-list field to allow a user to make multiple selections from a drop-down list. PROJ-806 5.4 For example, a meeting may involve a dozen people from a department that has 100 employees.

 User interactions with a list-to-list control

ListToListExampleIn the example, the source list (on the left) contains car models, and the destination list (on the right) contains car models the user has selected.

By interacting with the icons or captions at the right of each list, you can add to, remove from, and sort the destination list. List elements added to the destination are removed from the source list.

You can continue to make changes to the list contents until the form is submitted.

For another example, see Pega Developer Network articlePDN PRKB-25065 How to add a list-to-list control to a flow action rule.

Five icons and captions control transfers between the two lists:

Icon Caption Description
Move All Move all Add all entries in the source list to the destination list.
Add one Move Add the selected entry or entries in the source list to the destination list.
Remove All Remove all Remove all entries from the destination list.
Remove one Remove Remove the selected entry or entries from the source list.
Sort
Reverse Sort
Sort asc
Sort desc
Sort the source list.
Three icons and captions allow you to reorder the target list:
Icon Caption Description
Up Move up Move up the selected entry in the target list by one position.
Down Move Down Move down the selected entry in the target list by one position

Sort

Reverse Sort

  Sort the target list.

You can use SHIFT+CLICK to make multiple selections in either list. You can also use Windows drag-and-drop operations to move selected items to or from either list. Standard Windows keyboard operations for selection also work.

By default, the target list can contain up to 200 list elements. Through a parameter, a developer can choose a larger or smaller limit.

Buttons and captions are dimmed (gray) when not available. The entire list-to-list control is dimmed when presented in read-only mode.

 1. Create the activity that builds the source list

Create and test an activity that creates a page corresponding to a Page List property to hold the source list.

By convention, the class of the page is Code-Pega-List and in many cases the page is named pxResults. The embedded pages in the Page List can be of any class.

If the pages in the list correspond to persistent instances in a class, the activity can simply consist of a few steps, such as the Obj-Browse method optionally followed by the Obj-Filter method. At least one non-blank embedded text property is required on each page (for example pyLabel). Values for this property need not be unique.

Optionally, the embedded pages of the Page List properties (for both source and target) can contain a TrueFalse property with the reserved name pySelected. At runtime, the initial display of the list-to-list control presents any items for which pySelected has value "true". This property has no other effect.

 2. Add the control

Identify the Page List property that is to hold the selected pages. The embedded pages of this property must belong to the same class as the embedded pages created by the activity.

Alter the flow rule or other application processing so that the activity executes before the user interface element that includes the list-to-list control is rendered. (For example, if the list-to-list control is to be part of a flow action form, you can identify the activity in the Before this Action Run Activity field on the Action tab.)

Click the down-arrow (Arrow) at the right end of the Advanced control group (Layout group) and select the List to List control (Layout).

Drag the control. When the pointer changes shape to indicate that you can drop the layout, release the mouse button. If the cell is not empty, the dropped control replaces the current contents of the cell. Click the magnifying glass icon (Magnifying glass) to display 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(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.GRP-229

 3. Complete the Cell Properties panel — Top fields

Complete the Cell Properties panel that appears. GRP-229

Enter parameters for the ListtoList control rule, to control these runtime elements:

ListToList

Field

Description

Property

Accept the default placeholder value @baseclass. pyTemplateListToList.

Control

Select ListToList. Click the magnifying glass to enter parameters, based on these runtime elements:

Parameter Description
Source Property

A reference to a Page List property that contains the source list items. The source items must be present on the clipboard before the HTML form containing the list-to-list control is displayed.

If you use the pagename.propertyname form of a reference, enclose the reference in double quote characters.

Target Property

A reference to a Page List property to contain the target list items. This property may or may not exist on the clipboard when the HTML form containing the list-to-list control is displayed.

The embedded pages of the target property may be of the same class or a different class than the embedded pages of the source property. Complete the Property Mapping parameters to define which properties appear in the embedded pages of the target property.

Display Property

Name of a Single Mode property, typically of type Text or Identifier, embedded in the pages of the source property. This text appears in the source list display. Typically, values of this property on distinct embedded pages are distinct, so the user can identify the item at runtime.

First Title

Optional. Enter a short text value to label the source list.

Second Title

Optional. Enter a short text value to label the destination list.

Show Actions

Select button, caption, or both to control whether the runtime display presents buttons or text captions (or both) as controls.

Maximum Items in Target

Optional. Enter a positive integer to limit the number of selected items in the target list. If omitted, the default limit of 200 applies.

Display Image Property

Optional. Identify a Single Value property in the embedded pages of the source list or target list, where the text value of the property identifies the relative path to a small JPG, GIF, or PNG image on the server file system. At runtime, the image appears to the left of the display property text.

Width

Optional. Enter an initial width in pixels of the entire <TABLE> element for the list-to-list control. If omitted, the default width is 600 px.

Copy All Items

Optional. Select to cause the entire embedded page (all properties) from the source Page List property to be appended or inserted in the target Page List property.

Leave unselected if you want the embedded pages of the Page List property corresponding to the target list to contain only properties listed in the Property Mapping parameter array.

Property Mapping

ArrayOptional. Complete this parameter array to identify how properties on the embedded pages of the source property are to be copied to create property values on the embedded pages of the target property, for items selected by the user.

If you leave this array blank, select the Copy All Items checkbox. If you complete this array, clear the Copy All Items checkbox.

Typically, a mapping copies a property in the source to the same property name in the target pages. However, you can map any property to any other (of suitable mode and type), for example Child into SelectedChild. To reduce the size of target pages, copy only those properties needed for later processing.

Source

Identify a property on the embedded page of the source property.

Target

Identify a property to hold the Source value, in the embedded pages of the target property.

Behavior

Not used with List-To-List. C-1990 The list-to-list control does not support the OnChange event. VAGUE KARAF 1/14/09

 4. Complete the Cell Properties panel — General tab

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

 5. Complete the Cell Properties panel — Advanced tab

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

 Notes

Although the standard control rule ListToList exists, it supports the capabilities described in this topic only. Because of its non-standard capabilities, do not specify ListToList as the Display Property on the General tab of a Property form.

The generated HTML code for a list-to-list control is a resizable <TABLE > structure.

This control depends on hidden HTML fields (<INPUT TYPE="HIDDEN" ..>).

For advanced cases, you can bypass the steps described in this topic and create a section rule with hand-crafted HTML code containing the <pega:listtolist > JSP control, which offers many additional options beyond the parameters listed in Step 4 above. See ListToList JSP tag.

You can localize this control by overriding selected standard field value rules named @baseclass.pyMessageLabel.zzzzz and @baseclass.pyButtonLabel.zzzzz, where zzzzz is the default English text.

Up About Flow Action rules

Up About Harness rules

Up About Section rules