Harness forms - Placing a button in a harness

On the harness form, a button is located in a cell at the bottom of the resulting user form. When clicked, a button executes an activity.

CAUTION:
Use auto-generated button controls (control pxButton ) in section and flow action layouts. See Button controls.

The UI Gallery landing page contains a working example of this element. To display the gallery, in Dev Studio, click Configure > User Interface > Gallery > UI elements.

1. Drag and drop

On the Design tab, from the Action list, drag Button onto to the area marked <drag buttons here>.

If the cell is not empty, the dropped button replaces the current contents of the cell.

2. Complete the Button Properties panel — Top fields

Click the View properties icon to display the Properties panel.

Your updates to this panel update the rule form upon clicking Apply. If the panel is pinned ( pin ), the wireframe on the rule form changes immediately to reflect your inputs. If the panel is not pinned ( pin ), click Apply to apply your inputs.

Complete the top fields of the Button Properties panel.

Field Description
Type 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 Standard Types for a description of other types.

Button caption 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 run time 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 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 About the Localization wizard.

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

Local Actions This field appears only when the Type is Local Action. Select the local action to occur when the button is clicked.
Load in Modal Window 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.

3. Complete the Cell Properties panel — General tab

Complete the General tab.

Field Description
Width 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 — Components 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.
Height 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 — Components 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 Complete additional information for custom buttons below.

Visible

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.
If you select Other Condition, complete the Visible When field.
Visible When 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 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.

Run on Client? This check box 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.
Disable 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 check box.
Disabled Condition If you selected the Disable check box, identify here a when condition rule (evaluated once) that determines whether the button is enabled.

4. Complete the Cell Properties panel — Presentation tab

  • Privilege – Optional. Select the Privilege Name key part of a privilege rule that controls the availability of this button at run time. During rule resolution at run time, the system uses the Applies To key part of the current rule as the first key part. At run time, the button disabled for users who do not hold this privilege. Click the Open icon to review (or create) the privilege rule.

  • Use Heading Styles – Select to change the cell HTML element from <TD> to <TH>, with a resulting style change. (This is not typically useful for buttons.)
Instead of creating a new custom format in the skin, you can adjust elements in a cell by applying Cascading Style Sheet (CSS) helper classes. For example, you can use a CSS helper class to center an element in a cell or to double the standard right margin for the element.
  • Cell read-write classes – Click the Open helper class picker icon to specify one or more CSS helper classes to apply to this cell when the form is displayed in read-write mode. You can enter several helper classes, separated by a space. Alternatively, you can enter the name of a custom style to apply to this cell.
  • Cell read-only classes – Click the Open helper class picker icon to specify one or more CSS helper classes to apply to this cell when the form is displayed in read-only mode. You can enter several helper classes, separated by a space. Alternatively, you can enter the name of a custom style to apply to this cell.
  • Inline style (not for production use) – You can use this field to define an inline style by entering CSS code. However, entering an inline style results in a guardrail warning. For maintainability and reuse, the recommended approach is to use read-write or read-only classes.
For more information, see CSS helper classes.

Standard Types

If you choose a built-in Type value, the system provides default values for the ToolTip text.

Enter a caption; by convention, the Caption text is often the same text as the Type . Choose ToolTip and Caption text that conveys the outcome of the button press in language familiar to application users.

Standard field value rules named @baseclass.pyButtonLabel.Name determine the label text of these button types, such as "Submit". Your application can override these standard field value rules.

Type Description
Local Action 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 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.
Get Next Work Cancels any unsubmitted changes and finds the most important assignment to work on next.
Finish Assignment Submits changes and marks this assignment as complete.
Expand/Collapse Redraws the form with all areas fully expanded or collapsed.
Contents For a cover work item, changes the form to allow users to view and navigate among the member work items.
Explore For a folder work item, changes the form to allow users to view and navigate among the associated work items.
History Displays the work item history, for users who hold the Work-.AccessAuditTrail privilege.
Attachments 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.
Cancel Closes the current form without applying any changes.
Save Saves the work item with Submit.
Update 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.

Review Presents the user form or flow action form in review-only mode; no updates are allowed.
Show Reopen Screen 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.
Reopen Work Item 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.
Show Flow Location Known as the Where-Am-I? icon, presents the current flow marks the location of the current assignment with an arrow. Requires the Work-.Perform privilege.
Enable Action Section Presents the user form in review-only mode; inputs area allowed in the action section only.

5. Complete additional information for custom buttons

The General tab changes when you choose CUSTOM as the Type value. Access and complete additional fields.

When clicked, the custom button executes an activity, using parameter values determined in this panel or parameter values determined by a user input at runtime.

Field Description
Do Action 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.
Parameters 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.
Pass Current Parameters Select if the parameter page of a calling activity is to be shared with this activity.
params If the activity accepts input parameters, enter constant values for each required parameter.
Target 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.
No Data Submission 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.
Target Name If you selected Custom Frame for the Target field, identify the name of the target window or frame.
Window Width 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.
Window Height 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.

About Harnesses