You are here: User interface > User interface rules > Harness and section forms > Grid layout - General tab

Grid layout - General tab

Click the Gear icon in the Grid Repeat Layout header to display the Properties panel, and then select the General tab to define the source of the grid.

Optimize for mobile Select the Optimize for mobile option to provide improved client-side performance and enhanced mobile experience. Some layout properties will be unavailable. The Source can only be a data page and pagination options are limited. Conditions are unavailable.
Data Source
Source

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.

List/Group If you specified Property, select the Page List or Page Group property that you want to use as the data Source. You can reference nested Page Lists and Page Groups; for example, Page.Page.Page.Page.PageList; or DataObject.PageList.
Applies To If you specified Report Definition, select the Applies To key part of the rule.
Report definition

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.

Create grid dynamically

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.

Specify virtual report definition

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.

Data Page

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.

Specify custom results page

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.

Grid Summary Type a description of the grid for accessibility purposes. This description does not display in the UI. It is stored in the HTML and accessed by screen readers.
Pagination  
Pagination format

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.
Note: If the results produce less than one page, the paginate gadget does not appear at run time.

The options are:

None

No paging (default).

Page 1 of X

Traditional paging. Presents an editable page number and a total page count. To navigate, users edit the number and press Enter, or use the navigation buttons.

Page 1,2,3...

Traditional paging. Presents the first group of N links as page 1, the second group as page 2, and so on, where N is the total number of rows divided by the Page size (number of rows) value plus 1 if the total row number is not an exact multiple of rows per page.
For example, if the Page size (number of rows) value is 20 and the report contains 207 rows, the first page contains rows 1 to 20, and the last (11th) page contains the final 7 rows. To navigate, users click a number to open a page ( 1, 2, ...) within the range. The display is limited to 10 pages. If there are more than 10 pages, users can click (... ) to advance to the next group.

Rows 1 - Y

Traditional paging. Presents a range of rows (defined in the Page size (number of rows) field) in a drop-down list. To navigate, users select a range in the drop-down list or use the navigation buttons.

First X Results

Traditional paging. Presents the data in either of two page views. The first view is a subset of the data on the clipboard and comprises the top rows defined by the Page size (number of rows) setting. For example, if the setting is 50 and there are 200 rows on the clipboard, a label at the top of the list reads "Showing 50 of 200."

To view the entire data set (200 in this example), the user clicks the Show All link. This enables a user to drag rows at the top of the set and drop them onto the bottom. The other paging options break large data sets into individual pages and do not have this capability.

The user can toggle click the link to toggle between the first and total views.

Progressive

Progressive paging. Presents one page of data, containing the number of items specified in Page size (number of rows), while incrementally loading the remaining data. When a user drags the scrollbar and releases, all rows above that point in the grid are loaded.

Additional data displays as the user scrolls through the list, providing the user with access to the full list and associated actions, such as re-ordering data by dragging and dropping, sorting, and filtering.

If fewer results are returned than the number specified in Page size (number of rows), the height of the grid automatically adjusts to eliminate unnecessary white space when Size grid height to content is selected.

Note: Performance with large data sets is influenced by a variety of factors including the row contents and the end-user’s system. Sorting and filtering can provide alternate ways for a user to access a specific set of rows.

As defined on report definition The page format will be the same as what is configured in the report definition.

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.

Size grid height to content Appears if you select Progressive as the Pagination format. Select to enable the height of the grid to automatically adjust, eliminating unnecessary white space. For example, if fewer results are returned than the number specified in Page size (number of rows), the grid height automatically adjusts.
Page size (number of rows)

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.

Specify pagination activity Appears if you selected a paging option in the Pagination format field. Select if you want to specify a pagination activity.
Pagination activity

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.

Pagination activity manages sorting

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.

Pagination activity manages filtering

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.

Conditions  
Grid visibility

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.
Row visibility

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.
Row Refresh

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.
Run visibility condition on client?

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.

Header and Footer
Display grid header Select if you want to display a grid header. You can include actions, such as add and delete row, in the grid header. If pagination is enabled in the grid, the controls for pagination display in the grid header.

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.
Display grid footer Select if you want to display a grid footer. You can include actions, such as add and delete row, in the grid footer.
Display footer

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.
Identifiers  
Test ID

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.