Source Dropdown Options from a Data Page and Group by a Property in Pega 7.1.9

A Data Page can be used to provide the source for the options of a dropdown user interface control in Pega 7.1.9. The dropdown control can be setup to either show a simple list of items or to aggregate the items with a Group By configuration.

  • The below screen shot shows a Pega drop down UI control, where the options (…here US cities) are grouped by a property (…here US state). This post shows how such a drop down can be quickly created in Pega 7.1.9.

Screen shot of Pega 7 section with Dropdown grouped options


  1. Description of Data Type and Data Page for Storing Cities
  2. Source the City Dropdown with a Data Page and Group By a Given Property

Related Posts

  • In this example, a Data Type named PGX-MyStore-Data-City was created using the Data Explorer.
  • The Records tab of that Data Type shows 14 records that were created:

Pega 7 Data Type - PGX-MyStore-Data-City, Records Tab

  • The Properties of the City Data Type are shown in the Data Explorer in the above screen shot.
  • When the Data Type was created, 2 Data Pages were generated as well.
  • D_CityList is a Page List and contains the 14 instances of PGX-MyStore-Data-City.

  • A section contains a dropdown that allows to select a city based on the D_CityList Data Page.

Pega 7 Dropdown - Select City

  • The dropdown’s properties are shown below. The Data Page D_CityList is used for the List Source.
  • The Name property is used for displaying the options in the dropdown in ascending order.
  • The check box Group Items is checked and the property to group by is set to .State.

Pega 7 Dropdown Configuration - Configure List Source, Group By

  • Running the section shows the dropdown with the city options grouped by US state.

Pega 7 Dropdown - Preview Page with City Dropdown

  • Note that the city names within each group are sorted in ascending order.
  • The order can be changed using the Report Definition DataTableEditorReport that was automatically created when the City Data Type was setup. See Example of How to Create Report Definitions in Pega 7 for details on Pega Report Definitions.
  • The Query tab of the Report Definition is shown below.

Pega 7 Edit Report Definition - City Data Type Edit Columns

  • Here, the City property Population is used to sort the records in descending order using Highest to lowest for the sort type value.

Pega 7 Dropdown - Sort Cities by Population Size

  • When running the section again, the city names within each State group are now sorted im descending order by Population, i.e. New York City comes first within the New York state group (…see screen shot of City records at the beginning of this section for population values).

Using a Page List for a Dropdown and Sorting the Options with a Data Transform in Pega 7.1.9

A Data Transform can be used in Pega 7.1.9 to sort list structures such as a Page List. In this example, a Data Transform is used to show how to sort the entries of a Dropdown control that is backed by a List-type Data Page. In addition, another Data Transform is shown that sorts the Page List based on two properties.


  1. Description of Data Type and Data Page for Storing Cell Phone Models
  2. Using an Activity, Section and HTML Rule to Display a Dropdown of Phones
  3. Using a Data Transform to Sort the Page List

Related Posts

  • Here, a Data Type named PGX-MyStore-Data-Phone was created using the Data Explorer.
  • The Definition tab of the Data Type shows its properties:

Data Type Rule - Definition Tab - Phone

  • The Records tab shows the 13 instances that have been created for this Data Type.

Data Type Rule - Records Tab - Phone

  • The Sources tab shows the 2 Data Pages that have been created automatically.

Data Type Rule - Sources Tab - Phone

  • The data page D_PhoneList is of type List and can be used to retrieve all instances of the PGX-MyStore-Data-Phone Data Type.

Data Page - Definition Tab - ListPhone

  • Use Actions > Run to run the data page and view its XML representation. There will be a node called pxResults that contains the list of phones.

  • A form was created to show a dropdown that allows to select a phone based on the D_PhoneList Data Page.

Section - Runtime - Show Dropdown for Phone Selection - Default no Selection

  • Clicking on the dropdown shows the options provided by the Data Page. Note that the order of the items is the same as shown on Data Type > Phone > Records, i.e. the list is sorted ascending by the ID property of PGX-MyStore-Data-Phone.

Section - Runtime - Show Dropdown for Phone Selection - Display Dropdown Options

  • The following rules were used to create the HTML page with the phone dropdown control:
An Activity rule named ShowPhoneOrderSection
A HTML rule named MyPhoneStore
A Section rule named PhoneOrderForm
  • The ShowPhoneOrderSection Section rule containing the dropdown control is shown below:

Edit Section Rule - PhoneOrderForm - Design Tab

  • The configuration of the Dropdown rule is shown below, note the List source section, which refers to the Data Page:

Phone Selection Dropdown - Dropdown Properties

  • The MyPhoneStore HTML rule uses the <pega:include> tag to include the section rule by name.
<pega:include name='PhoneOrderForm' type='Rule-HTML-Section'></pega:include>

HTML Rule - HTML Tab- MyPhoneStore

  • The ShowPhoneOrderSection Activity rule contains one step that uses the Show-HTML method to render and display the HTML rule.

Activity Rule - Steps Tab - ShowPhoneOrderSection

  • When running the Activity using Actions > Run, it will display the HTML page shown at the beginning of this section.

  • A new Data Transform called SortByPhoneNameASC with an applies-to class of PGX-MyStore-Data-Phone was created. On the Pages & Classes tab, the following entries have to be added:
D_PhoneList with class name Code-Pega-List
D_PhoneList.pxResults with class name PGX-MyStore-Data-Phone

Data Transform Rule - Pages and Classes Tab - SortByPhoneNumberASC

  • On the Definition tab, the first and only step uses the Sort method.

Data Transform Rule - Definition Tab - SortByPhoneNumberASC

  • The gear icon is used to configure the Sort method. Clicking on it opens a new layer.

Data Transform Rule - Definition Tab - Sorting Properties

  • Here, the Sort method is configured to sort the list of phones by the Name property of PGX-MyStore-Data-Phone in ascending order.
  • The ShowPhoneOrderSection Activity was modified and a step was added before displaying the HTML page.
  • The first step in the modified Activity uses the Apply-DataTransform method to use the SortByPhoneNameASC Data Transform for sorting the Data Page.

Activity Rule - Steps Tab - ShowPhoneOrderSection - Apply-DataTransform

  • The step page is referring to a page that is defined on Pages & Classes. This entry is needed because the Data Transform’s applies-to class is different than that of the Activity, which is PGX-MyStore-Work.

Activity Rule - Pages and Classes Tab - ShowPhoneOrderSection

  • When the Activity is run again, the options in the phone dropdown control are now sorted by Name in ascending order.

Section Rule - Runtime - Phone Dropdown Options Sorted by Name in Ascending Order

  • Another Data Transform was created to sort the phone list by Memory (ASC) first and then by ScreenSize (DESC). The configuration is shown below.
  • If two or more phones have the same amount of memory, they will be sorted by screen size in descending order, i.e. the one with the largest screen size will be on top in that subset of the list.

Data Transform Rule - Definition Tab - Sorting Properties - Sort By Two Proerpties, Memory and Screen Size

  • The Data Transform can be run by using Actions > Run.
  • In the Run Data Transform dialog, click on the Trace button first and the on the Run button.

Data Transform - Trace and Run Buttons - SortByPhoneMemoryAndScreenSize

  • In the Tracer, where the event type is Action End click on the cell that lists the Data Page, here D_PhoneList, to view the Data Page after it has been sorted by the Data Transform.

Data Transform Rule - Use Tracer to View Data Transform and Data Page

  • The dialog lists the items of D_PhoneList.pxResults.

Tracer - View Properties on Data Page D_PhoneList

  • The phones are sorted in ascending order by memory first. In addition, the phones with 16GB of memory are sorted in descending order by screen size.

Example of Pega 7 Auto-Complete Control Backed by Data Table

The following example shows how to create a data table and how to use it to populate an auto-complete UI control in Pega 7. The auto-complete control allows a user to type a search term and it will present matching options in a dynamic list as shown in the screen shot below.

Pega 7 Auto Complete Control Example

Related Posts


  1. Creating a new Data Table Using the Data Table Wizard in Pega 7
  2. Populating an Auto-Complete Control from a Data Table in Pega 7

  • Open the data tables view by clicking on Designer Studio > Data Model > Data Tables > Data Tables:

Pega 7 Designer Studio - View Data Tables List

  • The data tables view shows a list of existing data tables:

Pega 7 Data Model List of Available Data Tables

  • Click on the Add a new Data Table button. This will open the Data Table Wizard.
  • In this example, a new data table will be created for storing car makes.
  • The class name should be derived from the organization name, here ABC and the application name, here Insurance and the derived class, here -Data.
  • Therefore, the class name in this example is ABC-Insurance-Data-Make.
  • The class for this data table should derive from the -Data class, so the DERIVES FROM field will be ABC-Insurance-Data.

Pega 7 Data Table Wizard - Generate Data Table

  • The check box CREATE DATA PAGES? must be checked in order to see the LOOKUP DATA PAGE and LIST DATA PAGE fields. Completing these fields will cause the wizard to create data pages that can be used to retrieve a single instance of ABC-Insurance-Data-Make or a list of instances.
  • The check box CREATE DEDICATED DATABASE TABLE? should be checked since this data tables provides reference data and should be included when migrating the application.
  • In this example, the intention is to display an auto-complete UI control that allows a user to select from a list of car makes.
  • The ABC-Insurance-Data-Make class will have 2 properties: ID and pyLabel.
  • The ID will be a unique numeric identifier and the inherited pyLabel property of type text will store the car makes such as Honda and Toyota. After entering the configuration data, click on the Generate button to continue.


  • The wizard generates the data table and Associated Rules such as a default data transform, a validate rule and the lookup data page (D_Make) and list data page (D_Makes) using the names specified in the configuration name.
  • After clicking on the Close button and refreshing the data table view, the new data table appears.
  • At this point, the row count is 0 since no data records have been created yet.

Pega 7 Data Table View - New Data Table Available

  • Click on the cogwheel icon in the EDIT column in order to open a view that allows adding rows to the data table.

Pega 7 Data Table View - Edit Data Table Instances

  • Click on the + icon to insert ABC-Insurance-Data-Make instances into the data table.

Pega 7 Data Table View - Insert Data Table Instance

  • Clicking on the check mark icon to the right of the Label text box will insert a new record into the data table.
  • The data table will enforce the unique constraint for the ID column and display an error icon and a tool tip when the user attempts to insert a row with an existing identifier.

Pega 7 Data Table View - Insert Instance Error - This instance already exists

  • Once the data has been added, the dialog showing the data table instances can be closed.
  • Refreshing the data table’s view shows the new row count:

Pega 7 Data Table View - Showing Row Count

  • Here, we want to set a case instance property from a selected value of an auto-complete control.
  • In the sample application, there is a case type rule called ABC-Insurance-Work-Auto that will be used to encapsulate auto policy work.
  • This case type rule has a property called Make that is a single value property of type text.

Pega 7 Application Explorer - Case Type Property

  • Create a new Section rule for the ABC-Insurance-Work-Auto case type and insert e.g. a Dynamic Layout.
  • Click on the Advanced┬ádrop down control in the Deign tab and drag and drop the Auto-Complete control into the dynamic layout.

Pega 7 Designer Studio - Edit Section - Advanced - Add Auto Complete Control

  • Click on the auto-complete control and then on the cogwheel icon in the upper right hand corner.

Pega 7 Designer Studio - Edit Section - Configure Auto Complete Control

  • This will open a dialog for configuring the auto-complete field. In the Property field, type a . (dot) to see all available properties of the ABC-Insurance-Work-Auto case type and select the Make property as shown below.

Pega 7 Designer Studio - Auto Complete Control - General tab

  • A Placeholder can be used to display a default text in the auto-complete control, when no value is selected.
  • In the LIST SOURCE section, select Data page in the type drop down field and enter the name of the list data page that was created using the Data Table Wizard, in this case: D_Makes.

Pega 7 Designer Studio - Auto Complete Control - General tab - Placeholder and List Source

  • Alternatively, instead of using the data page, the default Report Definition, here named dataTableListReport, which was also created by the Data Table Wizard can be used.

Pega 7 Designer Studio - Auto Complete Control - List Source Configuration

  • Caution: Using a data page has performance advantages since it can be configured to be cached (see Load Management tab of edit data page view), whereas the report definition is run every time the auto-complete is loaded.
  • When using a report definition, the SEARCH RESULTS CONFIGURATION section of the dialog is used to select the data source property that will be used for the search and for displaying the auto-complete suggestions list.
  • In this case, the auto-complete needs to search the pyLabel property of the ABC-Insurance-Data-Make instances in the data table.
  • The Match start of string check box causes the auto-complete search to show suggestions where the entered string matches the beginning of Makes instances.
  • E.g.: When the user enters Me in the auto-complete control, the list of suggestions should show all car makes where the pyLabel value starts with Me.

Pega 7 Designer Studio - Configure Auto Complete Control - Search Results Configuration

  • Click on OK to close the dialog and then click on Save to apply the section changes.
  • The auto-complete can be unit-tested by clicking the Actions button and selecting Preview.

Pega 7 Auto Complete Control Example

  • The section will be rendered and display the auto-complete control. Here, the user entered Me and the list of suggestions shows one item: Mercedes-Benz since it is the only make that starts with Me.
  • When the user click on an item in the suggestions list, that item’s pyLabel value is used to set the value of the Make property of the ABC-Insurance-Work-Auto instance on the Clipboard.