Configuration options for layouts
Learn about the layout configuration options that you can use to customize your layout. For example, you can specify the format, the visibility of the layout, and the source of data for dynamic layouts.
The layout configuration options are available on the General tab of the Properties panel and are arranged in the following table in alphabetical order.
The options in the Pagination, Identifiers, Container settings, and Accessibility sections are presented in the order in which they appear on the Properties panel. The availability of options depends on the layout type, the context in which the layout is placed, and other options that you select.
General options
| Field | Description | Available for |
|---|---|---|
| Active when | Specifies a condition that determines when a layout that is nested in another layout group is activated. | The following layouts, when they are nested in a Layout group:
|
| Caption | Displays a header or a label for a layout that is nested in another
layout. You can configure additional settings for the header, for example, a type or a heading level. For more information, see the Container settings table. |
|
| Container format | A container determines the background color, border, text style, heading, and
padding of the layout. Apart from the default options, you can apply a custom
container format that is defined in the skin, by selecting
Other, and then specifying the custom format in the
adjacent field. For more information on how to create a skin, see Component style formats. |
|
| Create grid dynamically | Creates a dynamic column in the table that is sourced from a report definition. At run time, the table generates the columns that are displayed in the way that it is set up in the report definition. The run-time display of the table automatically updates when the report definition changes; you do not need to update the section that contains the table. You can add static columns before and after the dynamic column in the grid. You can select additional settings in the Specify virtual report definition option. |
|
| Defer load activity | Runs an activity that is called when loading more data is required. This option is useful when loading all the available data at once when the layout is first rendered on the screen might take a long time. |
|
| Defer load contents | Delays loading the content of the layout at run time until the user clicks an
element on the page. This option improves the first loading time of the page. If you want users to take actions on a work item, for example, submit a from, when the remaining content on the page is still loading, you can configure sections to use defer-loaded asynchronous declare pages. |
|
| Display grid footer | Displays a footer below the table. The Display footer list provides options to select when the footer is visible. |
|
| Display grid header | Displays a header above the table. From the Display header list provides options to select when the header is visible. |
|
| Display header and title | Displays a header for a layout that is not nested. You can configure additional settings for the header, for example, the type or the heading level. For more information, see the Container settings table. |
|
| Display message when there are no rows to display | Displays a message about the lack of rows to load when the data set from which the layout sources data is empty. You can select a section or a field value that contains the message text that you want to display. |
|
| Enable adding new tab | Provides users with an option to add tabs at run time. |
|
| Enable numbered accordion | For the Accordion option, this parameter activates automatic numbering of collapsible headers. |
|
| Enable stretch for tabs | For the Tab display type option, this parameter makes
tabs stretch horizontally or vertically to fit the available space at run
time. You can set the corresponding responsive breakpoints by using a skin. |
|
| Enable touchscreen swipe for tabs and menus | Provides users of touchscreen devices with an option to swipe the contents of the layout at run time. |
|
| Grid summary, Tree Grid summary | Contains a short text that describes the table for screen readers. |
|
| Optimize code | Provides improved client-side performance. This option is recommended for all applications. |
|
| Refresh condition | Determines when the layout refreshes. For example, you can trigger a refresh
when a property changes and when the user adds or deletes a row or a column.
Additionally, you can specify a pre-activity or a data transform to preprocess the
condition. If you choose Condition (expression), you can create your own condition. For more information, see Using the Condition Builder to configure dynamic UI actions. |
|
| Refresh when active | Automatically refreshes the active layout whenever the content changes. |
|
| Row refresh | Determines when to refresh data at the row level. If you choose Condition (expression), you can create your own condition. For more information, see Using the Condition Builder to configure dynamic UI actions |
|
| Row visibilityGrid visibility, Tree Grid visibility | Determines when to display the rows. If you choose Condition (expression), you can create your own condition. For more information, see Using the Condition Builder to configure dynamic UI actions |
|
| Run visibility condition on client | For the Condition (expression) and Condition (when rule) visibility options, this parameter dynamically evaluates the condition each time that the value of a property in the condition changes. |
|
| Specify a pre-loading activity | Specifies an activity to run before loading, when the container is expanded by a click. This activity can compute property values and other aspects of the container that is expanded. As a best practice, create a defer-loaded wrapper section with the retrieval activity, instead of multiple defer-loaded sections with wrapper activities. |
|
| Specify custom results page | Provides an option to define your own clipboard page to store the results of running the Obj-List-View, Obj-Browse, and RDB-List methods. The following options are available:
|
|
| Specify virtual report definition | Uses the pagination format of a report definition set as a source of data for the layout. The following options are available:
|
|
Pagination
Paging divides content into segments, which is helpful when a table contains more than 20 rows of data. By specifying options in the Pagination section, you can control the loading of data on a screen. Pagination options fall into the following categories:- Traditional paging
- Retrieves a data set segment on the clipboard. You can specify the number of rows per page and select a page navigation control format. The paginate gadget (the pyGridPaginator section) is automatically added to the right-most cell in the Action Top section of the table. You can drag the gadget onto any cell in an action area, except for the repeating area.
- Progressive paging
- Limits the number of rows that load when a user accesses the layout to render the page more quickly. The remaining items are loaded as the user scrolls through the list. Progressive paging enables users to access the entire data set by scrolling. Users can perform operations on the full data set by dragging the rows to re-order the list and by sorting and filtering the entire list.
For a working example of the paging options, see Accessing the UI Gallery. You can access paging examples in the See also column to the right of the Table sample.
Pagination
| Field | Description | Available for |
|---|---|---|
| Pagination format | Defines the format of pagination.
|
|
| Progressively load on user action | Retrieves a page from the data set on the clipboard. You can specify the number
of rows on a page and select a page navigation control format. Additional data displays as the user clicks on the page navigation control. The users can access the entire data set. |
|
| Progressively load on scroll | Limits the number of rows that load initially to render the page more quickly. The remaining items load as the user scrolls through the list. The users can access the entire data set. |
|
| Page size (number of rows) | Specifies the number of rows on a page. |
|
| Paginator section | Displays the section that specifies the pagination action and the message about the data that remains to be displayed. You can define your own text and add an icon by selecting a custom section in the adjacent field. |
|
| Display message when there is no more data to load | Displays a message about the lack of data to load, after all the data is displayed. You can select a section or a field value that contains the message text that you want to display. You can also enter your own text by selecting a custom section or a field value in the adjacent field. |
|
| Size grid height to content | Automatically adjusts the height of the grid to eliminate unnecessary whitespaces. For example, if fewer results are returned than the number that is specified in the Page size (number of rows) field, the grid height automatically adjusts. |
|
| Specify pagination activity | Activates the selection of a pagination activity. See Pagination activity. |
|
| Pagination activity | Specifies a custom activity that populates the clipboard from a page list in
the page size that you define. Because the activity limits the clipboard size, this
option is useful for retrieving large amounts of data from an external web service
or database. You can also use this activity to control sorting and filtering. For guidance on configuring the parameters in your activity, use a copy of the standard pyTemplateAdvancedGridActivity template. |
|
| Pagination activity manages sorting | Specifies that an activity controls sorting. If you do not select this option,
the Obj-Sort method is applied to the page only in the view
mode. For guidance on configuring the parameters in your activity, use a copy of the standard pyTemplateAdvancedGridActivity template. |
|
| Pagination activity manages filtering | Specifies that an activity controls filtering. For guidance on configuring the parameters in your activity, use a copy of the standard pyTemplateAdvancedGridActivity template. |
|
Container settings
The options in the Container settings section define the header type, format, and other settings.
| Field | Description | Available for |
|---|---|---|
| Title | Populates the header with the text that you enter, a property, or a field value. |
|
| Heading level | Specifies the title formatting style. |
|
| Include icon with title | Adds an icon to the title. |
|
| Body visibility | Determines when the container body is visible. You can choose one of the default options or create your own condition. |
|
| Header type | Determines the form of the header:
|
|
| Expand when | Provides an option to specify an expression that determines when the content under a header expands in the application. |
|
| Expanded on load | Specifies that the content under a header expands when the application first displays the layout. |
|
Identifiers
In the Identifiers section, you can assign an ID for a guided tour or the testing purposes.
| Field | Description | Available for |
|---|---|---|
| Tour ID | Specifies a unique string that identifies the element as a stop during the creation of a guided tour. You can use numbers, letters, and underscores. |
|
| Test ID | Specifies a unique string that identifies the UI element during automated
testing. You can click the Generate ID button or enter a
value that includes numbers, letters, and underscores. You can view the test ID in HTML or in the Live UI info panel at run time. The test ID is available to access groups that include the PegaRULES:TestID privilege. To disable the test ID, remove the PegaRULES:TestID privilege from the access group. |
|
Accessibility
In the Accessibility section, you can define the layout role type and value for an assistive technology.
| Field | Description | Available for |
|---|---|---|
| Role Type | Specifies a WAI-ARIA role type. The WAI-ARIA role supports accessibility by communicating the role type and value to an assistive technology. For more information, see Accessibility standards in Pega Platform and Accessibility. The following roles are available: |
|
| Value | Specifies a WAI-ARIA role within the selected role type. |
|
| Descriptors | Specifies the text that appears in auto-generated HTML as the ARIA label so that assistive technology can read it. |
|
Previous topic Upgrading panel sets to screen layouts Next topic Sections