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

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 run time, 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 run time, the button label appears with the shortcut key underscored, as in Visual Basic applications.

The button caption can also be configured as a property reference. Select Property reference from the drop down in the Button caption field. Enter a property reference in the second text field.

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 Open 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 Localization wizard.

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 Open icon to review or create the field value rule supporting localization.

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

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.

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.

See Complete additional information for custom buttons 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.

• 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 Open 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? check box, 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.

• 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 Using the Condition Builder to configure dynamic UI actions..
• Clear to cause the condition to execute only once, upon initial presentation of the 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 Pega Community article 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.

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.

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

• 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.