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:
  • Dynamic layout
  • Layout group
  • Repeating dynamic layout
  • Dynamic layout group
  • Table
  • Hierarchical table
  • Navigational tree
  • Columns
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.
  • Dynamic layout, when it is nested in another layout.
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 styles (custom style formats).
  • Dynamic layout
  • Layout group
  • Repeating dynamic layout
  • Dynamic layout group
  • Columns
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.

Note: This option is available only when you select the Report Definition option in the Source field.
  • Table
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.
Note: This option is available only when you select the Property option in the Source field.
  • Hierarchical table
  • Navigational tree
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.
  • Dynamic layout
  • Repeating dynamic layout
  • Columns
Display grid footer Displays a footer below the table. The Display footer list provides options to select when the footer is visible.
  • Table
  • Hierarchical table
  • Navigational tree
Display grid header Displays a header above the table. From the Display header list provides options to select when the header is visible.
  • Table
  • Hierarchical table
  • Navigational tree
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.
  • Dynamic layout
  • Layout group
  • Columns
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.
  • Repeating dynamic layout
Enable adding new tab Provides users with an option to add tabs at run time.
  • Dynamic layout group
Enable numbered accordion For the Accordion option, this parameter activates automatic numbering of collapsible headers.
  • Layout group
  • Dynamic layout group
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. For more information, see Skin form — Components tab — Layouts — Dynamic layouts.
  • Layout group
  • Dynamic layout group
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.
Note: This option is available only for a dynamic layout that is nested in another layout.
  • Layout group
  • Dynamic layout group
Grid summary, Tree Grid summary Contains a short text that describes the table for screen readers.
  • Table
  • Hierarchical table
  • Navigational tree
Optimize code Provides improved client-side performance. The option is recommended for mobile apps.
Note: Some configuration options, such as pagination, are not available when you select this option.
  • Table
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 Harness and Section forms — Using the Condition Builder to configure dynamic UI actions.
  • Dynamic layout
  • Columns
Refresh when active Automatically refreshes the active layout whenever the content changes.
Note: This option is available only for a layout group that is nested in another layout group.
  • Dynamic layout
  • Layout group
  • Repeating dynamic layout
  • Dynamic layout group
  • Columns
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 Harness and Section forms — Using the Condition Builder to configure dynamic UI actions
  • Table
  • Hierarchical table
  • Navigational tree
Row visibility Grid 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 Harness and Section forms — Using the Condition Builder to configure dynamic UI actions
  • Table
  • Hierarchical table
  • Navigational tree
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.
  • Table
  • Hierarchical table
  • Navigational tree
  • Columns
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.
Note: This option is available only when you select the Defer load contents option.
  • Dynamic layout
  • Repeating dynamic layout
  • Columns
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:

By name
The table uses the pagination format that is configured in the custom results page of a report definition that you specify.
By property reference
At run time, when the property is resolved, the associated clipboard page is used.
Note: This option is available only when you select the Report Definition option in the Source field.
  • Table
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:

By name
The table uses the pagination format that is configured in the report definition that you specify.
By property reference
The table uses the report definition in the 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. For this option, you must specify a virtual report definition page, which is a clipboard page of type Rule-Obj-Report-Definition.
Note: This option is available only when you select the Report Definition option in the Source field, and then select the Create grid dynamically option.
  • Table

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.
Note: Users can access data through the paging controls, and they can drag rows within a page. If the results produce less than one page, the paginate gadget does not appear at run time.
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 UI Gallery landing page. 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.
None
No paging.
Page 1 of X (traditional paging)
Presents a page number and a total page count. Users open a page by editing the number and pressing Enter, or by using the navigation buttons.
Page 1,2,3... (traditional paging)
Presents the first group of links as page 1, the second group as page 2, and so on. Users open a page by clicking a number. The display is limited to 10 pages. If there are more than 10 pages, users click (...) to advance to the next group.
Rows 1 - Y (traditional paging)
Presents a range of rows in a drop-down list. Users open a page by selecting a range from the drop-down list or by using the navigation buttons.
First X Results (traditional paging)
Presents a defined set of rows and a total row count. 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.

Users can access the whole data set by clicking Show All, and then reorder data by dragging the rows.

Progressive (progressive paging)
Presents one page of data that contains the number of items that the Page size list specifies. The remaining data is loaded incrementally.

Users can access the whole data set and perform any actions, such as re-ordering data by dragging, sorting, and filtering.

Note: Performance of large data sets is influenced by a variety of factors, for example, the row contents and the end user system. When you use a large data set, sort and filter options instead of paging, provide users with a specific set of rows.
As defined on report definition
The page format is the same as in the report definition.
  • Table
  • Hierarchical table
  • Navigational tree
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.

Note: This option works only when the underlying harness is configured to use the client-side template UI.
  • Repeating dynamic layout
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.
Note: This option works only when the underlying harness is not configured to use the client-side template UI.
  • Repeating dynamic layout
Page size (number of rows) Specifies the number of rows on a page.
  • Repeating dynamic layout
  • Table
  • Hierarchical table
  • Navigational tree
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.
Note: Available only for repeating dynamic layouts and when Pagination format is set to Progressively load on user action.
  • Repeating dynamic layout
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.
  • Repeating dynamic layout
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.
  • Table
Specify pagination activity Activates the selection of a pagination activity. See Pagination activity.
  • Table
  • Hierarchical table
  • Navigational tree
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.
  • Table
  • Hierarchical table
  • Navigational tree
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.

Note: This option is available only when you select the Pagination activity check box.
  • Table
  • Hierarchical table
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.

Note: This option is available only when you select the Pagination activity check box.
  • Table
  • Hierarchical table
  • Navigational tree

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.
  • Dynamic layout
  • Layout group
  • Repeating dynamic layout
  • Dynamic layout group
  • Columns
Heading level Specifies the title formatting style.
  • Dynamic layout
  • Layout group
  • Repeating dynamic layout
  • Dynamic layout group
  • Columns
Include icon with title Adds an icon to the title.
  • Dynamic layout
  • Layout group
  • Repeating dynamic layout
  • Dynamic layout group
  • Columns
Body visibility Determines when the container body is visible. You can choose one of the default options or create your own condition.
  • Dynamic layout
  • Layout group
  • Repeating dynamic layout
  • Dynamic layout group
Header type Determines the form of the header:
Bar
A horizontal bar that is always present. The section appears as a single horizontal strip that displays all labels and values.
Collapsible
A horizontal bar that application users can click to expand or collapse the layout contents.
Fieldset
A border around the contents of the layout with a single text label. This option produces HTML FieldSet and Legend elements.
  • Dynamic layout
  • Layout group
  • Repeating dynamic layout
  • Dynamic layout group
  • Columns
Expand when Provides an option to specify an expression that determines when the content under a header expands in the application.
Note: This option is available only when the Header type is set to Collapsible.
  • Dynamic layout
  • Layout group
  • Repeating dynamic layout
  • Dynamic layout group
  • Columns
Expanded on load Specifies that the content under a header expands when the application first displays the layout.
Note: This option is available only when the Header type is set to Collapsible.
  • Dynamic layout
  • Layout group
  • Repeating dynamic layout
  • Dynamic layout group
  • Columns

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.
  • Dynamic layout
  • Repeating dynamic layout
  • Columns
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.
  • Dynamic layout
  • Repeating dynamic layout
  • Table
  • Hierarchical table
  • Navigational tree
  • Columns

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 WAI-ARIA role and Accessibility. The following roles are available:
  • Dynamic layout
Value Specifies a WAI-ARIA role within the selected role type.
Note: The specific value options are dependent on the role type selected
  • Dynamic layout
Descriptors Specifies the text that appears in auto-generated HTML as the ARIA label so that assistive technology can read it.
  • Dynamic layout