Table layout - General tab

Use the General tab of the Layout Properties panel to specify the table's data source, pagination format, refresh and visibility conditions, and header and footer settings.

Table preference

  • Optimize code – Select this check box to provide improved client-side performance and enhanced mobile experience. When you select this check box, the Source field must be set to Data Page and the pagination options are limited.

    Selecting this check box disables certain configuration options to make the grid more suitable for mobile and offline use. A limited set of actions is available.

    Optimized table layouts support the full range of grid, row, and cell visibility options. Grid layout visibility supports client-run expressions offline, and when rule or server-run expressions in a desktop or mobile application.

    Select this check box so that users can personalize the table view at run time or to make the table editable in App Studio. You can then select the Personalize table check box on this tab to allow table personalization or select the Editable in App Studio check box on this tab to allow table editing.

  • Personalize table - This check box is displayed if you select the Optimize code check box. Select this check so that users can personalize the table by specifying which columns to display, resizing and reordering the columns, and setting an initial sort order and initial column filter.

    Select the Save personalization automatically check box to automatically save personalized table settings. If you do not select this check box, users must manually save their personalized table settings.

    Note: If you select the Save personalization automatically check box, the user's initial column filter settings are not saved.

Data source

The data source that you specify in the Source field determines which fields and options are available for configuring the data source.

  • Source – Specify the data source for the table:

    • Property – If you select this setting, use the List/Group field to specify the page list or page group property or to create a new one.

    • Report Definition – If you select this setting, specify the applies-to class in the Applies to field. Use the Report definition field to specify an existing report definition or to create a new one. Selecting this setting makes it possible to configure a dynamic table (grid) and to specify a custom results page.

    • Data Page – If you select this setting, use the Data page field to specify an existing data page or to create a new one.

  • Grid summary – For accessibility purposes, enter a description of the table's purpose. This text does not display in the application's user interface. It is stored in the HTML and accessed by screen readers. This option is available for all three data sources.

  • List/Group – If Source is set to Property, use this field to select the page list or page group property, or to create a new one. You can reference nested page lists and page groups.

  • Applies To – If Source is set to Report Definition, use this field to specify the applies-to class of the report definition.

  • Report definition – If Source is set to Report Definition, use this field to select the report definition or to create a new one. If the report definition has parameters, you can pass parameter values to the report definition. Use 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 table from the report definition.

  • Create grid dynamically – If Source is set to Report Definition, select this check box to create a dynamic column in the table, sourced from the report definition. At run time, the table generates the columns contained in the report definition that you specify, displayed as set up in the report definition. The run-time display of the table automatically updates when the report definition changes; there is no need to update the section containing the table.

    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.

    Selecting this check box enables the Specify virtual report definition page option.

  • Specify virtual report definition – If Source is set to Report Definition and you select the Create grid dynamically check box, this check box is enabled. In the unlabeled drop-down field that displays when you select this check box, specify one of two settings:

    • By name – Uses the pagination format as configured in the report definition. Enter the virtual report definition page in the adjacent field.

    • By property reference – Select this setting and use the adjacent field to specify a virtual report definition page, which is a clipboard page of type RULE-OBJ-REPORT-DEFINITION. The table then uses the report definition in this clipboard page, rather than the report definition that is specified as the data source. With this approach, you can display columns that are hidden in the report definition, hide columns that are visible, or make subtle changes to the presentation.

  • Specify custom results page – If Source is set to Report Definition, you can select this check box to specify a custom results page instead of the default results page. In the unlabeled drop-down field that displays when you select this check box, specify one of two settings:

    • By name – Select this setting and specify the clipboard page in the adjacent field.

    • By property reference – Select this setting and use the adjacent field to specify the property. At run time, the property is resolved and the associated clipboard page is used.

  • Data page – If Source is set to Data Page, use this field to select or create a list-type data page to use as the source for the table.

    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 table uses a data page that accepts parameters and the parameter value uses a property reference, the table 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.

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

Note: 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:
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 Configure > 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.
Additional settings Editable in App Studio - This check box is displayed if you select the Optimize code check box in the Table preference section of this tab. Select this check box if you want to make the table editable at run time in App Studio.

When you select this check box, you can open the table in App Studio and specify a visual style for the table, change the table title, set the table pagination, add and remove columns, modify column titles, resize and reorder columns, and specify minimum and maximum column widths for column resizing.
Identifiers  
Test ID

Optional: If authorized, you can provide a unique Test ID to better support automated testing of your application.

When creating a control that supports you can use a combination of numbers, letters, and underscores, or click the Generate ID button to create a unique ID. The attribute data-test-id is then generated for the selected element.

After the test ID has been 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.

The Test ID is available to access groups that include the PegaRULES:TestID privilege. To disable Test ID, remove the PegaRULES:TestID from the access group.