Grid layout - General tab

Select either a Property (default), list-type Data Page, or a Report Definition as the data source for the repeating grid. You cannot select a summary-type Report Definition.

If you select Report Definition as data source, you can configure a dynamic grid.

If you specified Report Definition as the Source, press the down arrow to select the report that you want to use as the source of the grid.

If the report definition has parameters, you can pass parameter values to the report definition. Press the down arrow in the Value field to specify the value that you want to pass to the report definition. Using parameters, you can filter the results that are returned to the grid from the report definition.

Select this check box to create a dynamic column in the grid, sourced from the Report Definition. At run time, the grid generates the columns contained in the specified Report Definition. The grid columns display as they are defined in the Report Definition; for example, the column name, heading, width, format values, and show/hide settings, display as defined in the Report Definition source.

The run-time display automatically updates when the Report Definition changes; there is no need to update the section containing the grid.

A dynamic column is added in the section at design time. You can add static columns before or after the dynamic column in the grid.

If you want to specify a virtual Report Definition page, a clipboard page of type RULE-OBJ-REPORT-DEFINITION, select this check box. The Virtual Report Definition Page field displays.

Displays when the Source of the grid is a Report Definition and the Create grid dynamically check box is selected. There are two options.

Select By Name to use the pagination format as configured in the report definition.

Select By property reference to specify the name of a clipboard page of type RULE-OBJ-REPORT-DEFINITION. When specified, the grid uses the report definition specification in this clipboard page, rather than the one specified in the Report definition bound as the grid source.

Using this technique, you can display columns that are hidden in the report definition, hide columns that are visible, and make subtle changes to the presentation.

If you specified Data Page as the Source, press the down arrow to select the list-type data page that you want to use as the source of the grid.

If the data page has parameters, you can pass parameter values to the data page. In the Value field, specify the value that you want to pass to the data page. Using parameters, you can filter the results that are returned to the grid from the data page.

When a grid is bound to a data page that accepts parameters and the parameter value uses a property reference, the grid automatically refreshes with new items whenever the property value changes. No additional configuration is required. If you do not want the page to refresh automatically with new items whenever the property value changes, select the Disable automatic refresh check box.

Appears if you specified Report definition as the Source. By default, a results page is created for a grid sourced from a report definition.

Select this check box if you want to specify a custom results page. Select how you want to specify an existing clipboard page to use to save the results.

By name: Specify the clipboard page by name.

By property reference: Specify the clipboard page using a property. The property is resolved at run time and the associated clipboard page will be used.

Enter the name or property in the text field.

Optional. If the data results comprise more than a single page (approximately 20 rows of data), you may want to specify a paging format:

Progressive paging: Limits the number of rows initially loaded to render the page more quickly. Remaining items are loaded as-needed, as the user scrolls through the list. When a user drags the scrollbar and releases, all rows above that point in the grid are loaded.

Unlike traditional paging, in which users can access specific pages of data using paging controls, progressive paging enables users to access the entire data set by scrolling. Users can act on the full data set, dragging and dropping to re-order the list and sorting and filtering the entire list. For a description of a working example, see PDN article When and how to use progressive paging to load data into grids.

Progressive paging is available for all data sources, including report definition, and can be used with grids. Progressive paging is not available for tree or tree grids.

Traditional paging: Retrieves a segment, known as a page, from the total data set on the clipboard. You can specify the number of rows per page and select a page navigation control format. The paginate gadget (pyGridPaginator section) is automatically added to the right-most cell in Action Top. You can drag and drop the gadget onto any cell in an action area (do not drop into the repeating area).

Users can access data via the paging controls and can drag and drop rows within a page. If the results produce less than one page, the paginate gadget does not appear at run time.

The options are:

If you are using a Paging option, the data set is large, and performance is an issue, you can populate the clipboard incrementally using a Pagination activity.

The UI Gallery contains a working example of Paging options, including Progressive paging. To view and interact with samples, select Designer Studio> User Interface > UI Gallery . In the Tables & Grids area, select Grid. In the See Also column to the right of the grid sample, select Paging.

Appears if you select a Pagination format other than None. Select the items rows per page (20 is the default). To specify a custom value, select Other and enter a positive integer in the empty field.

If the source is a report definition and the report definition is Dynamic or Virtual, the option As defined in report definition is available. If you select this option, the grid uses the "Page size" value established in the report definition's Report Viewer tab, in the options form for the "Enable paging" check box.

Select a custom activity that populates the clipboard from a Page List in a page size you define. Because the activity limits clipboard size, this option is useful when retrieving large amounts of data from an external Web service or database. You can also use this activity to control sorting and filtering behavior.

Click the Open icon to create a pagination activity or review an existing pagination activity.

For guidance on configuring the parameters in your activity, use a copy of the standard template activity pyTemplateAdvancedGridActivity.

Appears if you select the Specify pagination activity check box and specify a Pagination activity.

Select this check box if you want the activity to control sorting behavior. See standard template activity for parameters. If you do not select this option, the Obj-Sort method is applied to the page in view mode only.

Appears if you select the Specify pagination activity check box and specify a Pagination activity. Select if you want the activity to control filtering behavior. See standard template activity for parameters.

Select one of the following to control when the grid is visible:

• Always: the grid is always visible
• Condition (expression): the grid is visible under the specified condition. In the field that displays, select a condition or click the Open condition builder icon to open the Condition Builder. You can define a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.
• Condition (when): the grid is visible under the specified condition. In the field that displays, select a when rule. Click the Open icon to create a new when condition or review an existing when condition.

Select one of the following to control when grid rows are visible:

• Always: the row is always visible
• Condition (expression): the row is visible under the specified condition. In the field that displays, select a condition or click the Open condition builder icon to open the Condition Builder. You can define a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.
• Condition (when): the row is visible under the specified condition. In the field that displays, select a when rule. Click the Open icon to create a new when condition or review an existing when condition.

Select one of the following to control when grid rows refresh:

• Never: the row never refreshes.
• Condition (expression): the row refreshes under the specified condition. In the field that displays, select a condition or click the Open condition builder icon to open the Condition Builder. You can define a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.
• Condition (when): the row refreshes under the specified condition. In the field that displays, select a when rule. Click the Open icon to create a new when condition or review an existing when condition.

Appears when you specify a when rule as a Grid visibility condition.

Select this check box to cause evaluation and execution of the condition each time the value of a property stated in the condition changes. If unselected, the expression is evaluated and the condition executed when the form is initially presented and whenever the form is refreshed.

By default, controls that allow typing, such as Text Input, are evaluated when the user leaves the field. To re-evaluate conditions as the user types, use the Apply Conditions action with a Keyboard event.

Display header

Appears if Display grid header is selected. Select one of the following to control when the grid header displays:

• Always: the grid header is always visible.
• Condition (expression): the grid header refreshes under the specified condition. In the field that displays, select a condition or click the Open condition builder icon to open the Condition Builder. You can define a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.
• Condition (when rule): the grid header refreshes under the specified condition. In the field that displays, select a when rule. Click the Open icon to create a new when condition or review an existing when condition.

Appears if Display grid footer is selected. Select one of the following to control when the grid footer displays:

• Always: the grid footer is always visible.
• Condition (expression): the grid footer refreshes under the specified condition. In the field that displays, select a condition or click the Open condition builder icon to open the Condition Builder. You can define a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.
• Condition (when rule): the grid footer refreshes under the specified condition. In the field that displays, select a when rule. Click the Open icon to create a new when condition or review an existing when condition.

Optional. If authorized, you can provide a unique Test ID for use in your test suite in order to support better automated testing against any Pega application.

When creating a control that supports Test ID, the Test ID field is initially blank. Use a combination of numbers, letters, and underscores, or click the Generate ID button to create a time stamp as a unique ID. The attribute data-test-id is then generated for the selected element.

When you save an existing section, any supported controls that do not have a Test ID will have one automatically generated. You can override these with a custom ID at a later time.

Once generated, you can view your Test ID in HTML or display it in the Live UI panel.

You also have the option to have all controls that support Test IDs in a ruleset updated in bulk.

A standard, out-of-the-box developer role, PegaRULES:SysAdm4, includes the privilege for Test ID. To disable Test ID for this role, modify the pxTestID privilege.