Harness, section, and flow action forms - Adding a Row Repeat control

Show all

A repeating layout defines a rectangular area on a work object form or flow action form corresponding to the HTML <TABLE > element. Three repeating layouts are available: Row Repeat, Column Repeat, and Tabbed Repeat.

For a Row Repeat layout, each row of the table corresponds to an element (a single page) of a Page List or Page Group property. The row can present embedded properties for each page, either as fields or formatted by a section rule.

To see an example, review the standard section rule named Work-.PartyDetails, which is based on the Page Group property Work-.pyWorkParty. Special processing in this rule supports restrictions that specify which parties must be present and which parties can appear more than once.

In version V5.4, this control is called a Repeating Layout. The Row Repeat name was introduced with V5.4SP2 to distinguish the Row Repeat horizontal presentation (rows) from the vertical presentation (as columns) and from the tabbed presentation.

1. Adding and deleting a Row Repeat layout

Click the down-arrow ( ) at the right end of the Layout control group () and select the Layout control (). Click and drag the control. When the pointer changes shape to indicate that you can drop the layout, release the mouse button.

On the Layout Options form:

Click the Repeating radio button.
Select Row as the repeat type.
Optionally, check the Stretch to fill page box.
Click OK.

To delete a Row Repeat layout, select the layout and click the Delete Row button (). Do not use the Delete Cell button for this action.

The table initially contains three columns and three rows. Usually, the top row holds labels, the second row holds fields (property values), and the final row contains the Add Row control (). When the section appears at runtime, the second row is repeated for each existing Page List or Page Group page.

Complete the Row Repeat panel — Top fields

Click the magnifying glass icon () to open the Row Repeat panel. Complete all tabs of the panel.

If the panel is pinned (), the wireframe presentation on the rule form changes immediately to reflect of your inputs. If the panel is not pinned (), click Apply to apply your inputs.

Field

Description

Header

Choose a format to control what appears above the layout (known as a header or subheader), and the appearance of both the header or subheader if any, and aspects of the body.

This choice primarily affects styles and appearance. Information in or below a subheader (including Hidden Sub) present information that is right-indented from information in a header.

Using the Application Skin wizard, you can review or revise the styles (colors, fonts, padding and margins) associated with each header or subheader format.

Group/Selection	Description
Default
`No Format`	No header or subheader appears. In addition, no styles applied to the body that are specific to this layout, including background, fonts, colors, padding, margins, and so on. The appearance of the body depends on styles of the enclosing control (which may be another layout).
Header
`Standard`	For a bolder or more prominent header.
`Custom`	For a custom header. Select in the HTML field an HTML rule that defines the content and appearance of the custom header.
`Hidden`	For no header. (This option is not available for the top-level of a harness rule).
SubHeader
`Standard (sub)`	For a bolder or more prominent sub header.
`A B C D`	These names are provided so that you can apply separate styles to the up to 5 types of subheaders (counting the basic `SubHeader`). For example, if your forms include three hierarchical levels of subheaders, you can select `A` for the highest level, `B` for the middle level, and `C` for the lowest level. In the standard style sheets, these subheaders function identically; they differ only in minor ways in the presentation of the subheader: A — No bar in the subheader B — Underlined subheader label C — Outline border D — Black font
`Outline`	Provides no header area, but a border around the contents of the layout with a single text label. (This produces HTML `FieldSet` and `Legend` elements).
`Hidden (Sub)`	For no subheader, but indented body.

In the workform CSS style sheets, the various styles named groupTitleBarzzzz define the appearance of the SubHeader element; for example groupTitleBarBackground. For A, the corresponding styles are named a_groupTitleBarBackground and so on. Similarly, the names of styles for B, C and D start with b_groupTitleBar, c_groupTitleBar, and d_groupTitleBar respectively.

Template

Select a Smart Layout template:

Single — A single column pair.
Double — One column pair, a spacer column and a second column pair.
Triple — Three column pairs with two spacer columns.
Custom — Freeform

HTML

If you selected Custom for the Header field, identify here the second key part of an HTML rule that defines the contents of the header.

Title

Optional. Enter text for the header or subheader, above the table. You can include directives or JSP tags in this text.

When 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 text length to 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.

Visible When

Optional. To cause the entire Row Repeat layout to appear only when certain conditions are true at runtime, select or enter the When Name key part of a when condition rule. At runtime, the system uses the Applies To class of this harness rule as the Applies To key part to locate the when condition rule.

Click the pencil icon () to review or create the when condition rule.

Use this to control visibility of the entire Row Repeat layout. Through a separate test that is applied at runtime to each row, you can control which rows appear.

Complete the Row Repeat panel — General tab

Complete the General tab. To enable SmartPrompt prompting while using this tab, complete the Of Class field before the PageList/Group field.

Field

Description

PageList/
PageGroup

Select or enter the property (of mode Page List or Page Group) that at runtime contains the pages to appear as tabs in this layout. Identify a property within the top-level page that corresponds to the Applies To class of the current rule. (If you are only prototyping the appearance of the harness, section, or flow action form, you can accept the placeholder property @baseclass.pyTemplatePagelist, and complete or ignore other fields on the Tabbed Repeat panel as desired.)

Type a period followed by the property name. For embedded pages, type the qualified name. For example, if myArray is a Page List property, the following are accepted:

.myArray

.page1.myArray

.page1.page2.myArray

Click the pencil icon () to review the property rule.

You can't use the syntax Apagename.Apropertyname in this field (with no leading period) to identify a Page List or Page Group property that is within a different top-level page. To present such properties in a repeating layout, create a section rule with an Applies To class corresponding to the Apagename page, and include the section rule in this rule.

Of Class

Select or enter the class of the pages in the Page List or Page Group property identified the previous field.

Allow Update

For repeating layouts added to the harness, section, or flow action (in release V5.2 or later) select this check box to allow users at runtime to add a new element immediately after an existing element, using the Enter key. For such repeating layouts, this check box does not affect the appearance or function of the Add and Delete operations. See Allowing users to add or delete Page List or Page Group elements (rows).

Header Type

Select one of the following header styles. This field does not appear if the Header value is None, Subheader None, Custom, or Outline.

Header Style	Description
`Bar`	Provides a static horizontal bar at the top of the layout.
`Collapsible`	Provides a horizontal bar at the top of the layout, with the ability to expand or collapse, to show or hide the layout, when clicked
`Tabbed`	Creates a new TabGroup to which additional layouts can be added.
`Accordion`	Creates a new group of layouts that contain collapsible headers. Only one layout can be displayed at once.

Expand When

Optional. Only applies to Collapsible header styles. Select a when condition rule to control whether this layout appears expanded or collapsed upon initial runtime presentation.

If blank, 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.

Defer Load?

This field appears for Collapsible, Tabbed and AccordionHeader Type values. Select to postpone, at runtime, the loading of the contents of this layout from the server until the user clicks to make the body visible.

New Tab Group

For Header Type of Tabbed only. Select to present this layout as the first in a distinct group of tabs, identified by indenting and optionally styles.

New Layout

For Header Type of Accordion only. Select to start this accordion element as the first in a group.

Complete the Row Repeat panel — Advanced tab

Field	Description
Body Visible When	Optional. To cause rows of this repeating layout to appear only when certain conditions are true at runtime, select or enter the When Name key part of a when condition rule. At runtime, the system uses the class of pages in the `Page List` property (not the Applies To class of this harness rule) as the Applies To key part to locate the when condition rule. The when condition rule is evaluated for each row, and so can cause some rows to appear and other rows to be omitted. Click the pencil icon () to review or create the when condition rule.
Width	Optional. Select whether the column widths in the table are to be set at runtime as a percentage of the total width of the work object form or flow action form or in absolute pixels. Choose: `px` — To have the column widths on the work object form or flow action form exactly match, in pixels, the column widths on the current rule form. `%` — To have the column widths on the work object form or flow action form adjust to percentages of the total width of the work object form or flow action form. If you adjust the column on the rule form to be 25% of the total width, the column on the work object form or flow action form will be 25% of the form width, and will grow or shrink if users resize the form. `px-fixed` — To specify a column width exactly. Internet Explorer uses this width even when data values may be longer (after applying styles, padding, margins, and so on). `stretch-spacer` — To adjust the width of the layout columns to match on the current width of the design-time Harness, Section, or Flow action form. Field and Label column widths do not change; Spacer columns are shrunk to be narrower or expanded to be wider. If you choose px-fixed and a property value at runtime is wider than width defined by the pixel value, the value is truncated, and users are unable to see the full value.
ID	Optional. Enter a name that becomes the ID=" " attribute value for the <TABLE > element. This option is useful when a JavaScript function refers to the table.
Summary	Optional. Enter text to supply a value for the `summary` attribute for the generated <TABLE> HTML element (used for screen readers ). If blank, the generated HTML uses the pyLabel value of the `Page List` or `Page Group` property for the attribute value.
Header Image	Optional. Identify the second and third key part of a binary file rule corresponding to a small image. Click the magnifying glass icon () to start the Image Catalog tool. (Not available when the Header value is `None` or `Custom`.)
Style Prefix	Optional. Provides the ability to reference a family of custom styles for headers. For example, type A in this field to use styles named .A_standardheader* rather than the normal .standardheader* styles. Define the prefixed styles in your workform_zzzzz.css text file (created by the Application Skin wizard) or in another text file that you identify on the Scripts and Styles tab of the Harness form. This field is available only if you selected `Tabbed` or `Accordion` for the Layout field.
Append Activity	This field is visible only when Allow Update is selected on the General tab. Leave blank in most cases. To override the default behavior when a user adds a row to the array, identify the second key part of an activity to be called. Design your activity to accept the same parameters as the default activity Work-.AppendToPageGroup or Work-.AppendToPageList (which are final rules). For example, your activity can prevent users from adding rows after reaching a limit, or can compute additional properties for the page. This field is meaningful only for repeating layouts created in Version 5.2 or later that include an add row icon ().
Delete Activity	This field is visible only when Allow Update is selected on the General tab. Leave blank in most cases. To override the default behavior when a user adds a row to the array, identify the second key part of an activity to be called. Design your activity to accept the same parameters as the default activity Work-.RemoveFromPageGroup or Work-.RemoveFromPageList (which are final rules). For example, your activity can require that at least one row remains, or that users can't delete the first row. This field is meaningful only for repeating layouts created in Version 5.2 or later that include a delete row icon ().

Adjusting row and column properties

To view or change row properties, click the circle at the left end of the row. Then click the magnifying glass icon ( ) at the right end of the row.

For details, see Smart Layouts — Adjust Row Properties in Adding a layout.

Use the Column Properties panel change the type of a column, or to apply an inline style to all cells in the column.

To view or change column properties, click a column header and then click the magnifying glass icon ( ).

For details, see Smart Layouts — Adjust Column Properties in Adding a layout.

Creating and deleting columns

Use the cell controls to add columns or delete columns, or merge cells.

In most cases, select an object in the layout before clicking an icon. Certain operations may be unavailable depending on your selection and the layout characteristics.

Control	Description
	Delete the contents of a single cell (not a row or column)
	Insert a new row before (above) the selected row
	Insert a new row after (below) the selected row
	Delete the selected row or layout
	Merge right — Combine the selected cell and the cell to the right.
	Merge down — Combine the selected cell and the cell below it.
	Unmerge All — Undo the previous merges.

The Insert column before ( ), Insert column after(), and Delete column ( ) operations are not available for Smart Layout columns - those with a column type of Label, Field or Spacer). They are available in Freeform layouts.

To reorder rows or columns within a repeating layout, you can select and drag a single row or column using the dots above or to the left of the table; these act as handles.

To duplicate rows or columns within a repeating layout:

Hold down the Ctrl key.
Select the row or column to be duplicated.
Move the pointer to the destination.
Release the Ctrl key to drop a duplicate row or column.

Allowing users to append or delete Page List or Page Group elements (rows)

For Row Repeat layouts created in V5.2 or later, users can add rows, delete rows, or both add and delete rows, depending on which icons you include on the form.

When you first create a Row Repeat layout, a three-by-three table appears. Typically, cells in the top row present column labels, but these cells can also hold other property values (not from the embedded Page List or Page Group pages). Cells in the bottom row are typically used to present the Delete Row icon (), but can also hold other property values (not from the embedded Page List or Page Group pages).

At runtime, the middle row appears once for each page. By default, users can add, append, and delete rows at runtime. You can change this default behavior:

To allow row deletion but not row addition, select and then delete the Add Row icon () that appears at the bottom left of the third row. You can also delete the column containing this row.
To allow row addition but not row deletion, select and delete the Delete Row icon () that appears in the right of the second row.
To disallow both operations, delete both icons.

You can't delete the top or bottom rows; if they are not needed, you can apply a style that makes them not visible at runtime.

Optionally, you can use button controls or URL controls on the repeating layout rather than the standard icons for Add Row and Delete Row icons. The icon, button, or URL control can appear anywhere in the row.

Identifying subscript values for added Page Group pages

When a repeating layout is based on a Page Group property and users click the Add Row icon () to append a new row, or press the Enter key to insert a new row, the system requires a subscript value for the new page.

In a Page Group property, the embedded text property pxSubscript acts as a unique identifier for the pages. This value may also be present in another property found on each page. As a best practice for usability, present the pxSubscript property (as a read-only value) in the left column of each row.

In some cases, the set of allowable values for subscripts are limited to a predefined static list, such as the codes for the 50 states of the United States (AL for Alabama through WY for Wyoming). In other cases, the set of allowable values for subscripts is unpredictable and effectively unrestricted, though each value must be a valid identifier. For example, a home insurance policy may contain a Page Group property with a page for each insured property, with the property identified by a government-issued code.

Process Commander includes standard rules that support both situations. Your application can override the standard rules to allow users to enter or select a subscript value.

Optionally, copy and override the standard section rule @baseclass.SubScriptPromptInput with another section of that name that applies to the page class of the Page Group. Include only one input field on the section display. For example, if there are only a few allowed pxSubscript values, you can present the unused values as a set of radio buttons.
Override the standard property @baseclass.pxSubscript with another property of that name that applies to the page class of the Page Group.
Optionally, on the Table Edits tab of the new property, enumerate the allowable values as a Local List, or define a Remote List that assembles the values dynamically.
Optionally, present the pxSubscript property as a read-only value in the left column of each row (or in another location meaningful to users).
At runtime, when users click the Add Row icon, the system searches for a section named SubScriptPromptInput to allow the users to select a value. This display excludes the subscript values already in use. Make sure that this section prompts for only a single input.

At runtime, the system controls the order of rows presented for a Page Group property. After you append or insert a new row, it may be re-sorted to a different position after the Submit is complete.

About Flow Action rules

About Harness rules

About Section rules