Harness, Section, and Flow Action forms
Adding a Grid layout

Field

Description

If you plan to localize the application using this rule so the application can support users in various languages or locales, choose the text carefully and limit the length to no more than 64 characters. When practical, choose a caption already included in a language pack, to simplify later localization. A field value rule with this text as the final key part is needed for each locale. See About the Localization wizard.

This field is not visible if the Format field contains No Format, Hidden, or Hidden (Sub).

Optional. If you leave this field blank, the grid is always visible. To control its visibility, enter or select one of the following:

• The When Name key part of a when condition rule. Click the pencil icon () to review or create the rule.
• 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.

As a best practice, use the Condition Builder to edit this field. Click the magnifying the glass icon ( ) to open the tool. See Using the Condition Builder to configure dynamic UI actions.

Appears when you enter a simple expression in the Visible When field.

Select this checkbox 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. See Control Form — Completing the Control tab.

• Leave blank so that the state of the layout (expanded ( ) or collapsed ( ) when you save the Harness, Section, or Flow Action form becomes the state upon initial runtime presentation.
• The When Name key part of a when condition rule. Click the pencil icon () to review or create the rule.
• Simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators. For example, enter .Color =="Red"

Appears when you enter a simple expression in the Expand When field.

Select to cause dynamic execution of the condition each time the value of a property stated in the condition changes.

Conditions are automatically re-evaluated when the user updates a property value. 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. See Control Form — Completing the Control tab.

Appears for Tabbed or Accordion values of the Header Type. Select if you want the system to retrieve only the data necessary for the current tab or accordion display. When another tab or accordion is selected, the system will retrieve further data for it. This speeds up first display of the page.

To enable users to take actions, such as submit, on a work item while other content is still being loaded, configure sections to use defer loaded asynchronous declare pages. See PDN How to configure non-blocking UI using Asynchronous Declare Pages (ADP).

If this is the only tab in a group, this option is selected by default and cannot be changed.

For Header Type of Accordion only. Select to remove this layout from the layout group, and add it as a new group directly below the original group. Deselecting this property causes the separated group to merge back into the original group. Deselecting this option causes the separated group to merge back into the original group.

If this is the only accordion in a group, this option is selected by default and cannot be changed.

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 26433 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 runtime.

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 the Paginate Activity on the Advanced tab.

The UI Gallery contains a working example of Paging options, including Progressive. To view and interact with examples and review configurations, select > User Interface > UI Gallery and select Paging in the Repeating Layouts group.

Appears if header type is Bar or Collapsible.

Select a style for the repeating area elements (text, borders, backgrounds, and images) as defined in the Skin rule. To modify the styles, open the Styles tab of the Skin rule and select Layouts>Repeat Tree/Grid. Specify the skin in your Designer Studio General Preferences panel.

The initial settings are as follows:

• Default
• Spreadsheet
• Transparent

To add a header image at the top of the Grid:

1. Open its property panel for this field to start the Image Catalog (a pop-up version of the Image Library landing page).
2. Search for the image you want to use by entering a text string in the Search field and clicking Find.
3. Select an image from the resulting display: at the top right of the panel details about the image appear.
4. To use the selected image, click OK.

The image must already be present in a binary file rule that is part of your application; you cannot search your local computer or the Internet through the Image Catalog.

Appears when you select a Header Image. Add text here to describe the image: those using assistive devices will hear this title although they may not be able to perceive the image.

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.

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

Appears if you enter a Paginate Activity. Select 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 enter a Paginate Activity. Select if you want the activity to control filtering behavior. See standard template activity for parameters.

• The When Name key part of a when condition rule. Click the pencil icon () to review or create the rule.
• 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.

As a best practice, use the Condition Builder to edit this field. Click the magnifying glass icon ( ) to open the tool. See Using the Condition Builder to configure dynamic UI actions.

Enter CSS code for an inline style for a cells in the column. For guided assistance in composing a style definition, click the magnifying glass icon () to open the Style Editor. You can select from predefined lists or type a style definition directly, and preview the results.

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

Optional. Click the magnifying glass icon () in the properties panel to update parameter values that you want to pass from the grid to the report definition. Values are passed when the data is loaded, and when the report definition refreshed due to user actions.

See About Report Definitions.

The edit mode sets the default presentation and behavior configuration for a repeating grid, determining how users view and edit properties.

By default, each edit mode is configured with grid actions — events and associated actions. The default action for all edit modes is Click to Set Focus. If you do not want a grid to have focus, for example, a display-only grid, delete this grid action.

You can add, delete, or edit grid actions as desired; click the magnifying glass icon ( ) next to Edit Mode to configure grid actions. See Completing the Control tab for a description of actions.

When configuring actions in a repeating grid, select the actions from the Handle List Items category. These actions are pre-configured to act upon the rows of the grid.

You can configure sequential actions based on a single event for a repeating grid; for example, Click to Set Focus and Click to Edit Item. The actions are acted upon in the order specified. You can set multiple actions based on different events; for example, Click to Set Focus and Double Click to Edit Item.

You can also configure Keyboard actions to enable users to navigate and access items in a repeating grid. For example, you can configure the Up and Down arrows to set focus to the previous and next rows in a grid, and the Enter key to open the selected item.

For more information about edit modes, see PDN article 26349 About repeating layout edit modes.

The UI Gallery contains working examples of edit modes and grid actions. To view and interact with examples and review configurations, select > User Interface > UI Gallery and select Tree Grid in the Repeating Layouts group or Row Actions in the Combinations group.

Select one of the following Edit Modes. See Completing the Control tab for a description of actions.

The system uses existing grid actions to determine whether to set focus to new rows.

If you want to set focus from within a row in a repeating grid to an editable control outside of the grid, provide the full path to the property, beginning with the parent page, and represent it on the Pages & Classes tab of the layout containing the repeating grid.

For Modal Dialog, Embedded Pane, and Expand Pane, click the pencil icon next to the field to open the template section used to render the layout. By default, the templates are standard rules .pyGridModalTemplate, .pyGridDetails , and .pyGridRowDetails, respectively. To create custom templates, copy these rules into your Applies To class. Do not change the Purpose.

Appears if the Edit Mode is Modal Dialog, Embedded Pane, or Expand Pane, or if Read Only and Show Details are selected. Select or create the flow action that will provide the form for the modal dialog or detail area that appears when the user clicks a row.

Appears if the Edit Mode is Modal Dialog, Embedded Pane, or Expand Pane. Select to allow the user to view the flow action details in read-only mode, which prevents locking the work item (Work- or Assign- item) when it opens.

Select to allow users to move objects higher or lower on the display by dragging and dropping individual rows. Depending on the properties of the objects the rows represent, rows may be moved above or below other rows, or dropped into a row that can receive them to become child entries of that row.

Unavailable if source is Report Definition.
Visual indicators give clues about the process: a line appears between two rows in the list if that is where the row you have started dragging will appear if you release it. A row that can receive the row you have selected as a child will change background color. If your mouse cursor is over an area where you cannot drop the row you have selected, an indicator will remind you that the area is not a valid target. If you attempt to drop the row there, the display will remain unchanged.

Select to allow users to adjust the width of columns on the display by dragging individual columns to the left or right.

Select to allow users to click a row border and drag it beyond the Height setting in the Row Properties panel.

Optional. Select if you want to sequentially number the rows in the grid.

Optional. Select if you want an OnHover style for rows, changing the appearance of a row when the cursor hovers over it. You can set the hover text and background color in the Skin rule.

The UI Gallery contains working examples of Row Hover. To view and interact with examples and review configurations, select > User Interface > UI Gallery and select Tree or Row Editing in the Repeating Layouts group.

Select to allow users to sort the rows on a column in the grid. This setting applies to all columns. You can disable sorting for individual columns by clearing the Enable Sorting checkbox in a column's Cell Properties panel. Sorting is not available for columns containing images, or controls such as buttons or links. This setting overrides the Sort Type settings on Report Definition form's Design tab. For instance, if there are no settings that form, the Sorting selection here enables sorting on the grid.

A tool tip appears at runtime when the user hovers the mouse pointer over the column header. Clicking the header sorts the rows in the column. When sorted, an icon indicating an ascending () or descending () sort order appears to the right of the header label text. The user can alternate the sort order by clicking the header again. You can use the Skin rule to replace the default icons.

Sorting is performed on all rows in the grid. If Paging is enabled and the user changes the sort order, the grid view returns to the first page.

Select to allow users to show only those rows that match a column value filter. This setting enables filtering for all columns that include a property. You can set filter types or disable filtering for individual columns using the Filtering options in the Column Properties panel.

If a column can be filtered, a filter icon ( ) appears on the right side of the column's header cell. The user clicks the icon to display the filter pop-up menu. On the menu, the user selects the checkbox next to each property to include.

Filtering mechanisms also appear in the menus for the following property types. These filtering criteria override checkbox selections.

• Date types (Date and DateTime) — Define a date range in the From and To fields.
• Text — Enter free-form text in the abc field.
• Numeric types (Integer, Decimal, and Double) — Define a range by entering numeric values in the greater than and less than fields.

When finished, the user clicks Apply. The filter icon changes to a filter-on icon () indicating that a filter is applied to the column.

You can use the Skin rule to replace the default icons.

Note the following:

• — Columns containing images, action controls such as buttons or icons, hidden controls (pxHidden), prompt select controls, and subsections cannot be filtered.
• — Filtering on Text properties that are obfuscated in edit-mode return results based on unfiltered data. Filtering should be disabled.
• — For date types, leaving a From or To field blank means to include everything preceding or following the single limit. For example, if you enter From 12/15/2011 and leave To blank, all dates on or after 12/15/2011 are included.
• — For numeric types, leaving a greater than or less than field blank means to include everything preceding or following the single limit. For example, if you enter less than 500 and leave greater than blank, all numbers less than 500 are included.
• The following property types cannot be filtered:
  
  • TextEncrypted
  • Password
  • TimeOfDay
  • Identifier
• Entering a From or To range or search text overrides checkbox selections; these selections are not included in the filter.

Appears if the edit mode is Expand Pane or Read Only with Show Details selected.

Select to display an Expand/Collapse column at the far left of the grid at runtime. The column displays the following icon in each row of the grid:

The Expand/Collapse column is optional; users can click in the row to expand or collapse the pane, or you can insert a button, icon, or link anywhere in the row to enable expand and collapse. If you deleted the default Edit Item action from the Expand Pane edit mode, then select this column to use Expand Pane.

Appears if the edit mode is Expand Pane or Read Only with Show Details selected.

Select to enable users to expand more than one row at a time.

Appears if edit mode is Read Only. Select to allow the user to click a row and display its flow action details beneath the row in read-only mode. The user can expand multiple rows. Enter the flow action in the Flow Action field.

Appears if Show Details is selected. Select to display details for all rows when the user opens the form.

Select this option to specify the maximum height and width of the layout. Further fields appear:

Appears if the Edit Mode is Read Only. When checked, the related work item opens for editing in a work item gadget when the user double-clicks on a row of data in the display. If PRPC cannot find the gadget, it opens the work item in a new tab or new window.

Specify the column width of this column in pixels. You can also adjust the width of a column directly:

1. Click a vertical wireframe cell border.
2. Wait until the pointer shape changes (), then drag the border.

The unlabeled Use at Runtime checkbox to the right of the width field is enabled by default and cannot be edited. This forces the Width value to be used by the browser at runtime, even when data values in this column or in other columns would otherwise cause the browser to present a wider or narrower column. Data values may sometimes wrap or appear truncated.

Optional: Override the stylesheet settings in this cell with local values.

Enter CSS code for an inline style for a cells in the column. For guided assistance in composing a style definition, click the magnifying glass icon () to open the Style Editor. You can select from predefined lists or type a style definition directly, and preview the results.

Appears if the Filtering checkbox is selected on the Repeat Grid panel. Select a filtering option for this column:

• Auto — Displays a checkbox for each unique value and the search or date range fields, depending upon the column data type. This is the default.
• Range/Search — Displays only the search or date range fields, depending upon the column data type. Use this option to enable search or date range on columns in which the value of each row is unique, for example, a description column.
  

• None — No filtering is available on this column.

Appears if the Enable Sorting checkbox is selected on the Repeat Grid panel. This is checked by default. Clear to disable sorting on this column.

Select to display the cell values with the same style the column heading uses. This changes the cell HTML element from <TD> to <TH>, with a resulting style change.

• The When Name key part of a when condition rule. Click the pencil icon () to review or create the rule.
• 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.

As a best practice, use the Condition Builder to edit this field. Click the magnifying glass icon ( ) to open the tool. See Using the Condition Builder to configure dynamic UI actions.

Enter CSS code for an inline style for a cells in the column. For guided assistance in composing a style definition, click the magnifying glass icon () to open the Style Editor. You can select from predefined lists or type a style definition directly, and preview the results.

Enter a positive number for the height in pixels of this cell. (At runtime, normal browser processing for rendering tables determines the actual displayed height.) You can also adjust the height of a row directly:

1. Click a horizontal wireframe cell border.
2. Wait until the pointer shape changes (), then drag the border.

The unlabeled Use at Runtime checkbox to the right of the width field is enabled by default and cannot be edited. This setting forces the Height value to be used by the browser at runtime, even when data values in this column or in other cells would otherwise cause the browser to present a taller or shorter column.

• The When Name key part of a when condition rule. Click the pencil icon () to review or create the rule.
• 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.

As a best practice, use the Condition Builder to edit this field. Click the magnifying glass icon ( ) to open the tool. See Using the Condition Builder to configure dynamic UI actions

An icon that is not visible is also disabled and cannot be clicked.

This setting has no effect if the data source is a Report Definition.

• The When Name key part of a when condition rule. Click the pencil icon () to review or create the rule.
• 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.

As a best practice, use the Condition Builder to edit this field. Click the magnifying glass icon ( ) to open the tool. See Using the Condition Builder to configure dynamic UI actions.

Clear the Use at Runtime checkbox (unlabeled) next to the width field to allow the browser at runtime to determine the width of this column based on the size of the column contents and the size of other columns. The width may vary from use to use depending on the contents of this cell and other cells. (When cleared, the generated HTML for this column includes a <TD> element with no WIDTH= attribute.) The Width value is used as you view the rule form, but not at runtime.

For example, clear this checkbox if the cell is to contain a section that may be wide in some situations and narrow in others.

Select (default) the Use at Runtime checkbox to force the Width value to be used by the browser at runtime, even when data values in this column or in other columns would otherwise cause the browser to present a wider or narrower column. If checked, data values may sometimes wrap or appear truncated.

Enter a positive number for the height in pixels of this cell.

Clear the Use at Runtime checkbox (unlabeled) to allow the browser at runtime to determine the height of this row based on the size of the row contents and the size of other rows. The height may vary from use to use depending on the contents of this cell and other cells. (When cleared, the generated HTML for this column includes a <TD> element with no HEIGHT= attribute.) The Height value is used as you update the rule, but not at runtime.

For example, clear this checkbox if the cell is to contain a section that may be tall in some situations and short in others.

Select the Use at Runtime checkbox to force the Height value to be used by the browser at runtime, even when data values in this column or in other cells would otherwise cause the browser to present a taller or shorter column.

Field

Description

Select the styles you want to apply to the tabs in the group. Select:

• Standard
• Sub
• Other

Field

Description

Select the placement of the tabs at runtime:

• Top
• Bottom
• Left
• Right

If you select Left or Right, specify the horizontal or vertical orientation of the tabs in the Tab Orientation field