You are here: User interface > User interface rules > Harness and section forms > Harness and Section forms - Adding a Button control

Harness and Section forms
Adding a Button control

A layout can contain a Button control, which invokes one or more actions when the user clicks the button. You can configure styles for buttons using the Skin rule. See Skin form — Components tab — Controls — Buttons.

If a section contains a deprecated or outdated button control or another control for which there is an improved alternative, a warning displays, along with an Update Controls button. Click Update Controls to automatically update deprecated controls in the section. Automatic update is not available for all controls; see Upgrading deprecated and outdated controls on the PDN.

Note that buttons that use custom configuration settings, such as the deprecated harness button, are not included in the automatic upgrade. Manually upgrade these button controls to pxButton.

If you have a use case that requires a specific configuration of a standard control, such as a button, you can make a copy of the control and save it using a new name.
For example, if you use a Yes/No radio button frequently, you can save a copy of pxRadioButton as pxYesNoRadioButton. Configure pxYesNoRadioButton to display Yes/No radio buttons, and then use pxYesNoRadioButton wherever you'd like it. Do not modify the Control Modes and UI Element settings.

Adding a button control

  1. Click the down-arrow Arrow at the right end of the Basic control group and select the Button control.
  2. Drag the control into the layout and release the mouse button to drop the control.
    If you are using a cell-based layout and you drag the control into a cell that is not empty, then the dropped control replaces the current contents of the cell.
  3. Click the magnifying glass Magnifying glass to display the Cell Properties panel.
  4. On the Cell Properties panel, define the button using the following tabs:

To view and interact with examples and review configurations, select Designer Studio> User Interface > UI Gallery and then select Button in the Components group.

Button control — General tab

Field

Description

Visibility

Select to determine when the button appears.

  • Select Always to have the field appear at the time this area of the user form (section or flow action) is first work item sent or refreshed. This condition is checked only once.
  • Select 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.
You can determine if the button is enabled or disabled using the Disabled radio buttons on the Presentation tab. You can also specify a privilege rule, in the Privilege field on the Presentation tab, that hides (or disables) the button.
Condition

If you selected Other Condition in the Visibility field, complete this field.

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

Wrap text

Displays only for free form layouts.

Select to force the label text to wrap if it is longer than the button width specified. If this check box is not selected, the text visible on the button may appear truncated at runtime.

Button control — Presentation tab

Field

Description

Label

Enter text or select a property or field value that contains brief text, which appears on the button or as a text link.

As a best practice, start the text with a verb. Consider the collection of controls that appear at runtime collectively; provide each control with a clear and distinctive label. For example, Cancel order.

To allow users to execute an action 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 label appears with the shortcut key underscored.

Hot KeyIf you use shortcut keys in your application, be careful to choose distinct letters for each control; for example, 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.)

Use SmartPrompt to select a field value rule if you plan to localize the text. Enter no more than 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. When practical, choose a caption already included in a language pack, to simplify later localization. See About the Localization wizard.

Tooltip

Specify a tooltip to display when the user hovers the mouse pointer over the button. You can press the down arrow to select a property value or type the text that you want to display as the tooltip.

As a best practice, start the sentence with a verb, either in the imperative ("Enter price of item here") or as an infinitive ("To cancel the order, click here").

Use SmartPrompt to select a field value rule if you plan to localize the text. See About the Localization wizard.

Format

Select a pre-defined format (Standard, Simple, Strong), which is configured in the Skin rule. The default selection is Standard. Use the Skin rule to modify the settings for these formats.

Alternatively, select Other to reference a custom format created in the Skin rule. Press the down arrow in the field that displays to select the format that you want to use.

Image source Select one of the following as the source for the button image:
  • None
  • Simple image
  • Property
  • Icon Class
Image

Insert an icon next to the label by clicking the magnifying glass icon (). This opens the Image Viewer. Select the binary file you wish to use.

If the button or link Format, for example, Standard, contains an image in the background, then that image overlays the image specified here. Button and link formats are defined in the Skin rule.

Image Position

Appears when you enter an image in the Image field.

Select Left or Right to indicate where you want the image to appear in relation to the label.

Property

Appears if you selected Property as the Image source.

Press the down arrow to select the property that you want to use as the source of the image/icon. The property can be an internal binary file (Rule-File-Binary) or an external URL.

Disabled

Select Yes if you want to apply a when condition that tests whether the user can use the control. If selected, the following options appear:

Group/Selection

Description

Disabled condition Select one of the following:
  • The When Name key part of a when condition rule. Click(magnifying glass) to review or create the rule.
  • 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 ( ) to open the tool. See Using the Condition Builder to configure dynamic UI actions.

Run on client

Appears only if the Disabled condition field contains an expression that can be evaluated on the client. Complex expressions and When rules are not eligible.

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

Privilege

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

If there is a privilege and a when rule (see Disabled field), both rules must evaluate to true for the button to be available to the user.

When not met

Appears when you enter a privilege. Select Hide or Disable (the button) if the user fails the privilege rule.

Display advanced presentation options

Select this check box to display fields that enable you to specify custom styles.

As a best practice, define custom styles in the skin. See Skin form — Components tab — General — Custom styles.

Advanced Options

Appears only when you select the Display advanced presentation options check box.

As a best practice, do not select this check box; instead define custom styles in the skin. See Skin form — Components tab — General — Custom styles.

  • Read-write style — Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-write mode.
  • Read-only style — Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-only mode.
  • Inline style — Type CSS code to define an inline style. As a best practice, define custom styles in the skin. See Skin form — Components tab — General — Custom styles.

Copying, deleting, duplicating, or moving a Button

Use these Windows operations to speed development:

About Flow Actions

About Sections

About Harnesses