Harness forms
Placing a button in a harness

Field

Description

Select a function for this button, from the predefined values on this list.

Select CUSTOM to define a button with a custom function. See Standard Types for a description of other types.

Enter brief text that is to appear on the button. As a best practice, start the text with a verb. Consider the collection of buttons that appear at runtime collectively; provide button each with a clear and distinctive label. For example, Cancel order.

To allow users to execute the button activity using a shortcut key combination, include an ampersand character (&) immediately before a letter in the caption text. At runtime, users can press the ALT key and the letter key together to execute the activity. For example, enter &History as a caption text to allow users to access work item history with ALT + h. At runtime, the button label appears with the shortcut key underscored, as in Visual Basic applications.

If your application includes non-autogenerated sections that reference buttons using the ampersand shortcut technique, you must  revise the section to include the following JavaScript within a JavaScript:

pega.u.d. processAccessKeysOnClient = true

If the sections are part of a harness, you can reference a JavaScript function containing the above line on the Scripts and Styles tab of the Harness form.

If you use shortcut keys in your application, be careful to choose distinct letters for each button; you can't have ALT + c as the label for both the Contents button and Close button. (To include an ampersand in a label as text, follow the ampersand by a space character.)

(If this text is to be localized, click the pencil icon () to review or create the field value rule supporting localization.)

Optionally, if this button is within a cell of a section that includes parameter declarations on the Parameters tab, you can enter the notation param.NAME here, to use a parameter value for the button caption, where NAME identifies a string parameter. Make sure that the NAME parameter is declared on the Parameters tab, and that your application provides a non-blank value for the parameter value in all possible situations where the section appears. See Sections — Completing the Parameter tab.

When you plan to localize the application that includes this rule, so the application can support users in various languages or locales, choose the text carefully and limit text length to 64 characters. A field value rule with pyButtonLabel as the second key part and this text as the final key part is needed for each locale. You can define a shortcut key in each language by including an ampersand character before a letter in the Localized Label field. When practical, choose a caption already included in a language pack, to simplify later localization. See About the Localization wizard.

Optional. Enter a sentence or phrase identifying to users the purpose and function of the button.

As a best practice, start the ToolTip text for an input field with a verb; for example, Cancel the order.

If this text is to be localized. enter no more than 64 characters. Click the pencil icon to review or create the field value rule supporting localization.

This field appears only when the Type is Local Action. Select the local action to occur when the button is clicked.

This field appears only when the Type is Local Action. Select to present the local action window as a modal window, which appears in front of all other windows and must be completed (or closed) before the user can perform any other processing. (Make sure the modal window is smaller than the current window.)

Select this when the local action accepts one or more input fields.

Field

Description

As a best practice, use SmartLayouts to achieve uniform width of cells throughout your application's forms. You can set the width of Smart Layout templates using the Skin rule. See Skin form — Styles tab — Layouts — Smart Layouts.

Optional. Enter a positive number for the width in pixels of the cell containing this button. (At runtime, normal browser processing for rendering tables determines the actual displayed width.)

This field appears only when the Width field in the Layout panel or Repeat panel (for the layout containing this cell) is set to px fixed and the cell is not controlled by SmartLayout restrictions. In that case, you can also adjust the width of columns directly:

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

As a best practice, use SmartLayouts to achieve uniform height of cells throughout your application's forms. You can set the height of Smart Layout templates using the Skin rule. See Skin form — Styles tab — Layouts — Smart Layouts.

Optional. 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.)

This field appears only when all columns in the Layout are not controlled by SmartLayout column restrictions (that is, all columns have the None template). In that case, 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.

Do Action
Target Name
Window Width
Window Height

These fields appear only when the type is CUSTOM.

See Complete additional information for custom buttons below.

Select to determine when the button appears.

• Choose Always to have the button appear or be hidden based on the visibility of the enclosing section or flow action when the form is first presented or is refreshed. This condition is checked only once.
• Choose Other Condition to make the visibility depend on a when condition rule, a Boolean expression evaluated only once, or a test evaluated repeatedly upon JavaScript events.

Optional. Enter an expression involving another property, or identify the When Name key part of a when condition rule. Specify one of four outcomes, where true or blank means the button is disabled.

• Leave blank to present the button as disabled always, regardless of the mode of the enclosing layout.
• When condition rule evaluated once — Enter the When Name key part of a when condition rule that determines the mode of this button at runtime, where a true result means the button is disabled. The system uses the Applies To key part of the current rule in rule resolution to locate the when condition rule, and executes the when rule once as it renders the form. Click the pencil icon () to review or create the when condition rule.
• Expression evaluated once — Enter an expression that returns true or false. This expression can involve multiple properties, function calls, and other syntax as supported by the <pega:when > JSP tag.
• Simple expression evaluated upon JavaScript events — To dynamically control the mode of this button with a JavaScript event, enter a simple comparison involving a target property and select the Run on Client? box. The result at runtime determines whether the button is disabled.
  For example, enter .Color =="Red" in this field to disable this button when the property Color has the value Red, and enabled otherwise. Depending on the state of the Run on Client? checkbox, the comparison executes only once as the form is initially displayed, or dynamically. See Using the Condition Builder to configure dynamic UI actions.

This field appears only when you select Other Condition for the Visible field.

This checkbox appears only if the Visible field contains a simple expression that can be evaluated by JavaScript code.

• Select to cause dynamic evaluation of the condition each time the value of any properties mentioned in the condition changes. (Mark the field containing that property as a Client Event.) See Implementing dynamic form actions and the Client Event Editor.
• Clear to cause the condition to execute only once, upon initial presentation of the form.

Select to cause the button to be disabled or enabled based on a test, even when the form is in read-write mode. Complete the next field to modify the effect of this checkbox.

If you selected the Disable checkbox, identify here a when condition rule (evaluated once) that determines whether the button is enabled.

Field

Description

Optional. Select the Privilege Name key part of a privilege rule that controls the availability of this button at runtime. During rule resolution at runtime, the system uses the Applies To key part of the current rule as the first key part.

At runtime, the button disabled for users who do not hold this privilege.

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

Optional. By default, when the user form or flow action form appears in read-write mode, the CSS style named LabelValueWrite applies. You can enter another style name or select from those listed.

Click the pencil icon () to review the text file rule that defines the style sheet.

Optional. By default, when the user form or flow action form appears in read-only mode, the CSS style named LabelValueRead applies. You can enter another style name or select from those listed.

Click the pencil icon () to review the text file rule that defines the style sheet.

To apply inline styling to this cell only, type a CSS style definition in this field. Styles you enter in this field supplement and override style elements defined in style sheets, according to standard CSS rules.

Inline styles are recorded in the generated HTML for the form; they do not alter the CSS definitions.

Use the Style Editor to create a CSS style definition. Click the magnifying glass icon ( ) to open it. You can select the font, color, font size, text align, vertical align, borders, margins, and other attributes of this cell using selection lists. The Style Editor maintains a preview of the resulting presentation. If you alter the style definition directly, click  Apply   to update the preview.

Click OK   to record the style defined with the Style Editor in the panel.

Select to change the cell HTML element from <TD> to <TH>, with a resulting style change. (This is not typically useful for buttons.)

Type

Description

For harnesses only. Allows the user to complete a local action by clicking the button that presents a pop-up form.

• Enter a text caption in the Caption parameter for the button label and optional ToolTip text in the Tooltip parameter.
• Select the local action in the Local Action field.
• Optionally, select Load in Modal window to present the local action window as a modal window, that appears in front of all other windows and must be completed (or closed) before the user can perform any other processing. (Make sure the modal window is smaller than the current window.)

When the user submits the pop-up form, the activity in the After this Action area (on the Action tab) runs.

For an example, see PDN article 25290 How to configure a local action in a button.

This technique may not work with all local actions; some are implemented in a way that depends on characteristics of the Action section.

Cancels any unsubmitted changes and finds the most important assignment to work on next.

Submits changes and marks this assignment as complete.

Redraws the form with all areas fully expanded or collapsed.

For a cover work item, changes the form to allow users to view and navigate among the member work items. You can override a standard list view rule to control details of this display.

For a folder work item, changes the form to allow users to view and navigate among the associated work items.

Displays the work item history, for users who hold the Work-.AccessAuditTrail privilege.

Presents a list of work item attachments, so users can view or add attachments. The button is visible only for users who hold the Work-.AccessAuditTrail privilege.

Closes the current form without applying any changes.

Saves the work item with Submit.

Redraws the form in update mode, for users who hold the Work-.Update privilege. This allows changes to previously input values that appear in sections other than the TAKE ACTION section presented by the flow action.

This capability is not desirable in all applications, as it allows users to overwrite values entered previously, perhaps by other users.

The  Apply   button on the update form sends changed user inputs to the server, but does not commit these changes. Users must select and complete a flow action to cause these changes to save. See Understanding transactions in flow executions.

Presents the user form or flow action form in review-only mode; no updates are allowed.

Shows the form in review mode but allows users to reopen a resolved work item, if they hold the Work-.Reopen privilege. Runs the standard activity Work-.Reopen or an activity of that name in your application.

Reopens a resolved work item, for users who hold the Work-.Reopen privilege. Runs the standard activity Work-.Reopen or an activity of that name in your application.

Known as the Where-Am-I? icon, presents the current flow rule as Visio diagram, and marks the location of the current assignment with an arrow. Requires the Work-.Perform privilege.

Presents the user form in review-only mode; inputs area allowed in the action section only.

Field

Description

Select an activity to execute when users click the button. To find the activity at runtime, the system uses the Applies To key part of this rule as the initial Applies To key part of the activity.

If the activity selected accepts input parameters, sources of parameter values can be set up on this form or entered by a user at runtime.

To define parameter values on this form, enter a constant value or property reference for each parameter.

Select if the parameter page of a calling activity is to be shared with this activity.

If the activity accepts input parameters, enter constant values for each required parameter.

Select one:

• Current window — The placeholder activity @baseclass.TemplateButtonActivity calls Work-.Show-Harness to redisplay the entire user form, or produces another HTML display. (If your custom activity does not produce any HTML to display, a default status message appears.)
• Pop-up window — The custom activity presents its results in a pop-up window. To suppress all results, choose this option and make the activity return an HTML stream that closes upon load.
• Custom Frame — The custom activity presents its results in a new frame. This is an advanced feature that expects the harness to be defined as an HTML FRAMESET. For an example, see the harness PegaSample-CustomerRequest.New.

If you select Current window for the Target field, select to indicate that clicking the button at runtime does not submit the form and so does not update clipboard values.

If you selected Custom Frame for the Target field, identify the name of the target window or frame.

If you selected Pop-up window, enter an integer value to determine the initial width, as a percentage of the entire width of the target window or frame. The default value is 20 percent.

If you selected Pop-up window, enter an integer value to determine the initial height, as a percent of the entire window height, of the target window or frame. The default value is 20 percent.