You are here: Reference > Rule types > Controls > Controls form - Completing the Control tab

Control form
Completing the Control tab

  1. About 
  2. New 
  3. Control 
  4. HTML 
  5. Parameters 
  6. Pages & Classes 
  7. History 
  1. More... 

By default, this tab appears when you open an auto-generated control or open a New rule.

Introduction

The Pega 7 Platform includes a set of standard auto-generated controls. See Standard auto-generated controls. As a best practice, use these controls in new development. Auto-generated controls provide these benefits:

Customizing a control in a section

Auto-generated controls and their settings are optimized for most interfaces. If necessary, edit the settings within the section, flow action, or harness in which you are working.

To customize an auto-generated control:

  1. Open the section or harness that contains the rule.
  2. Select the cell that holds the rule and click Gear icon to open its Cell Properties panel.
  3. In the panel, click the Open icon next to the control name. The control Parameters dialog appears, which displays most of the settings in the underlying rule's Control tab. You cannot edit the Control Modes or UI Element settings.
  4. Make your modifications. If satisfactory, save the section. The system generates the XML representing your edits and stores it in the section.

If you wish to modify an auto-generated control and reuse it in a number of sections, make a copy into your RuleSet and change the Stream Name key part. Keep the original Control Modes and UI Element settings. As a best practice, do use an auto-generated rule to build an entirely new control.

When you clear the Auto-Generated? check box on the HTML tab, the Parameters tab appears.

Caution: Any customization you make to the control in the section is maintained even if the control later changes. Parameters that are not customized apply to all of the instances. For example, if the Expand Options setting in the rule is Collapsed With Icon and you customize the control's Parameter dialog setting to Expanded With Icon, updating the rule setting to No Scrollbar does not change the custom parameter. If you had not customized the Expand Options setting, your rule update is reflected in the control's Parameter dialog.

If you want to revert to the control's configuration, clear the customized instance and re-add the rule.

Note: For more information about controls in offline-enabled applications, see Supported controls when working offline.

Control tab settings

These settings determine the read-only and edit-mode presentation and behavior of the control.

Field

Description

Control Modes Before you begin editing the rule, use the radio buttons to filter the initial array of options and parameters in the form. Select one of the following:
  • Editable/Read-only if you want to configure the associated property for both edit and read-only modes. The options appear in the Basics, Format, Options, and Behaviors areas under Editable and Read-Only column headings. You can configure the following UI Elements:
    • Text Input
    • Text Area
    • Date Picker
    • Check Box
    • Radio Buttons
    • Dropdown
    • Autocomplete
    • Rich Text Editor
  • Read-Only if you want a control that always appears as non-editable text. The Editable column does not appear.
  • Action to set the UI Element to Button, Icon, or Link. Only one column of settings appears, which applies to both editable and read-only control modes as defined in other parameter settings in this form.

Note: The Control Modes field does not appear in the Parameters dialog when customizing the control in a section.

Basics

Use this area to specify the control or category of property type used with the control.


Field

Description

UI Element For Editable/Read Only and Action control modes, select the type of control that appears on the layout. For Read-Only mode, select the type of presentation of the property value. Your selection filters the Format, Options, and Behaviors areas on this tab.

Group/Selection

Description

AutocompleteAdd an Autocomplete control. Appears when Control Mode is set to Editable/Read-Only.
CheckboxAdd a Check Box control. Appears when Control Mode is set to Editable/Read-Only.
DropdownAdd a Dropdown control. Appears when Control Mode is set to Editable/Read-Only.
Radio ButtonsAdd a Radio Button control. Appears when Control Mode is set to Editable/Read-Only.
Text AreaAdd a Text Area control, which can contain more than one line of text. Spellchecking is enabled by default. Appears when Control Mode is set to Editable/Read-Only.
Text InputAdd a Text Input control. Appears when Control Mode is set to Editable/Read-Only.
ButtonAdd a button (with a text label) that triggers an action when clicked. Appears when Control Mode is set to Action. You can include an image next to the label. You can use the Skin rule to specify and create button styles.
TextDisplay values of property types that include text, number, boolean, and date/time. Appears when Control Mode set to Read-Only.
HiddenUse this element when you want to include a property value that is submitted but is not visible to the user. Appears when Control Mode is set to Read-Only.
IconAdd an icon that triggers an action when clicked or hovered on. Appears when Control Mode is set to Action. You can use standard icons or create custom ones. Available actions are the same as the Button control.
LinkAdd a text link that triggers an action when clicked or hovered on. Appears when Control Mode is set to Action. You can include an image next to the label. You can use the Skin rule to specify and create link styles. Available actions are the same as the Button control.
Date PickerAdd a Calendar control. Appears when Control Mode is set to Editable/Read-Only.
Attach ContentAdd an Attach Content control. Available actions are the same as the Button control.
Rich Text EditorAdd a Rich Text Editor control. Appears when Control Mode is set to Editable/Read-Only.

Note: You cannot edit the UI Element field in the Parameters dialog.

Value Select a single-value property or text string that contains the value you want to associate with the control. This option does not appear in Action control mode. Select one of the following:

Group/Selection

Description

Value of associated propertyUses the property or field value entered in the Properties field in the control's Cell Properties panel (located in the section).

In edit mode, this setting is the default and cannot be changed.

Value of a different propertyA Single Value property or field other than the one in the Properties field. You can reference properties on any page identified on the Pages & Classes tab, using the normal notation pagename.propertyname for pages other than the page corresponding to the Applies To class of the rule.
ConstantA text string.

If the Localize? check box is selected on the section's HTML tab, a SmartPrompt appears in the Constant field in the Parameters dialog. Select a field value rule if you plan to localize the text. Enter no more than 64 characters. A field value rule with pyCaption as the second key part and this text as the final key part is needed for each locale.

Note: When a property is computed through a Declare Expression rule, the system presents the value as read only in the control's read-only format.

Options

Use this area to specify parameters for editable and action control modes.

Field

Description

Specify Size Appears when the UI Element is Text Input.

Group/Selection

Description

AutoSelect if you want the layout to determine the width of the control area. Default.
CustomSelect to specify a fixed value in the Width field.
Min/Max Chars Appears if the UI Element is Text Input or Text Area.

Optional. Enter a value that determines the minimum and maximum number of characters that can be entered in the text field or text area. You can designate either value as unlimited by leaving it blank.

Display Character Counter

Appears if the UI Element is Text Area and you specify Max Chars.

Determines whether a count of remaining characters displays at runtime. The counter decrements as the user types. Once the character limit is reached, additional characters are not accepted.

Placeholder

 

Appears if the UI Element is Text Input, Text Area, Dropdown or Date Picker. Optional.

Group/Selection

Description

OtherSelect to display inside the field a hint or instructional text that helps users enter a correct value.
Expected Format (Date Picker only)Select to display the localized DateTime Format value selected in this control.

The text disappears when the user enters a value. If no value is entered, the placeholder text reappears when the field loses focus. You can style Placeholder Text in the Skin.

Specify Width Appears if the UI Element is Text Area or Rich Text Editor.

Group/Selection

Description

AutoSelect if you want the layout to determine the width of the control area. Default.
CustomSelect to specify fixed value in the Width field. You can override this setting in the layout.
Width Appears if the UI Element is Text Area, Text Input, Rich Text Editor, or Dropdownand you select Custom.

Enter a positive integer that is a pixel count, a percentage of the cell area, or a number of columns (Text Area only). In the pull-down list to the right of this field, select the unit of measure:

  • px — pixels
  • % — percentage
  • columns — number of columns
Specify Height

Appears if the UI Element is Text Area or Rich Text Area.

Group/Selection

Description

Auto Select if you want the layout to determine the height of the control area. As a best practice, use this setting.
Size to Content Select if you want the height to expand with the content. This selection also provides collapse options.
Custom Select to specify a fixed height. You can override this setting in the layout.
Height

Appears when you select Customin the Specify Height field for Text Area or Rich Text Area.

Enter a positive integer that is a pixel count or number of rows. In the pull-down list to the right of this field, select the unit of measure. To ensure uniform text area heights within a layout, do not mix row and pixel settings.

Scrollbar Appears when the Text Area Height is Custom.

Select to display a scrollbar to the right of the area if the content exceeds the number of rows or pixels.

Min Height Appears when the Text Area Height is Size to Content.

Enter a positive integer that is a pixel count or number of rows. In the pull-down list to the right of this field, select the unit of measure.

Collapsible Appears when the Text Area Height is Size to Content.

Select one of the following:

Group/Selection

Description

NoThe text area is presented i at a size determined by the Width and Height settings. The user cannot expand or collapse the text area.
Yes, Default ExpandedThe text area is initially presented in expanded mode at a size determined by the Width and Height settings. The user clicks the Collapse icon (Collapsed) to collapse the text area.
Yes, Default CollapsedThe text area is initially presented in display-only mode, with only the Min Height value visible. The user clicks the Expand icon (Collapsed) to expand the area.
Date/Time

Appears when the UI Element is Date Picker.

Enables date and time selections in the Calendar control. Select one of the following:

Group/Selection

Description

Auto
(default)
Based on the associated property type, the system enables the appropriate date or time selections in the control as follows:
  • DateTime — Enables date and time selections. For example, in Drop-down Lists mode, six lists are displayed — one for each date and time value.
  • Date — Enables date selection only. For example, in Calendar mode, the time selection function does not appear in the pop-up calendar.
  • Time (TimeOfDay) — Enables time selection only. For example, in Drop-down Lists mode, three lists are displayed — one for each time value.
DateTime Enables date and time selections.
Date Enables date selections only.
Time Enables time selections only.

As a best practice, use the non-auto options only with DateTime properties or dates stored as valid text strings. Using an option that is unsuitable for the property type may present an incorrect read value at run-time. For example, enabling the Date option for a TimeOfDay property will not display a result.

Display Mode Appears when the UI Element is Date Picker.

Determines the presentation of the control to the user. Select either:

Group/Selection

Description

Text Input + Calendar
(default)
Display a text field that contains a calendar icon. The user can click the icon to select the date and time values in a pop-up calendar. Alternatively, the user can enter a date as a text value by clicking inside the field.
Dropdown ListsDisplay an array of drop-down lists from which the user selects the day, month, year, hour, minute, and A.M./P.M. Locale settings determine the order of the drop-downs. Use this option if the interface is configured for accessibility.
Allow Text Entry

Appears when the UI element is Date Picker and the Display Mode is Text Input + Calendar.

Click Yes (default) to enable the user to enter a text value in the field. Click No to prevent text entry.

Enable Calendar

Appears when the UI Element is Date Picker and the Display Mode is Dropdown Lists.

Click Yes to display a calendar icon with the drop-down lists in the field. This enables the user to use the lists or the pop-up calendar to pick dates and times. No is the default.

Number of Years

Required. Appears when the UI Element is Date Picker and the Display Mode is Dropdowns.

Enter a numerical value indicating the date range (in years) in the Year drop-down list. The list contains an equal number of years forward and backwards from the current year. For example, if the current year is 2011, a value of 10 displays a range of 2007 to 2016 . If the value is an odd number, the odd date is counted as a future year. For instance, a value of 11 displays a range of 2007 to 2017.

Caption

Appears when the UI Element is Checkbox.

Enter text describing the purpose of the control. The user can click this text to select or deselect the check box.

Caption Position

Appears when the UI Element is Checkbox.

Select Left or Right to indicate where you want the caption text to appear in relation to the check box image.

Label

Appears when the UI Element is Button (optional), or Link.

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

Configuring labels

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, as in Visual Basic applications.

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

Localization

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

Optional. Appears when Control Modes is Action or Editable/Read-Only (all UI Elements except Date Picker).

Select a property value or enter a constant that contains a sentence or phrase identifying to users the purpose and function of the control.

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

Note: When UI Element is Icon, the system enters a default value here based upon the value selected in the Icon field.

Localization

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

Format

Appears when the UI Element is Button or Link. 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. A blank field appears when you select this option. Enter the format name.

Privilege Optional. Appears when the Control Mode is Action.

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.

Image
(for Button or Link)

Optional. Appears when the UI Element is Button or Link.

Insert an icon next to the label by clicking. 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.

Disabled

Optional. Appears when the Control Mode is Action.

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 the Open icon 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.

Icon

Appears when UI Element is Icon. Select a standard icon from the drop-down list. By default, the Blank icon is selected when pxIcon is entered in the Control field on the Cell Properties dialog.

If you specify a standard pxIcon variation such as pxIconPrint or pxIconReview, the system selects a standard icon for that rule. For example, if the control is pxIconAddItem, the Add Item icon is selected. See Section, and Flow Action forms — Adding an Icon Control for icon descriptions.

To use a custom icon, select Other.

Image
(for Icon)

Appears when you enter Other in the Icon field. Select to open the Image Viewer. Select the binary file you wish to use.

As a best practice, use sprites rather than individual images for Icon controls.

Position

Appears when the file you select in the Image field is defined as a sprite on the Binary File rule form. See Binary File — Completing the Main tab.

The numbers in the drop-down reflect the number of columns in the sprite. Select the number you wish to use for this control's action. The value in the Tooltip field applies to this position.

For information about icon positions, hover the mouse pointer on the help icon next to this field ( ).

Format

Use this area to design the appearance of read-only text or an editable control. Action controls do not use formats.

Field

Description

Type

Select a format (read-only) used with this property. Your selection filters the format options.

Group/Selection

Description

None The property is not formatted. There are no options.
Text Unedited text, which may contain spaces, tabs, line break characters, and other control characters.
Number Numeric properties on output.
Date/Time Renders DateTime and Text property types in date and time format. See Understanding the Date, Time of Day, and DateTime property types.

Specify the format in the DateTime Format field.

Date Renders DateTime and Text property types in date-only format (hours and minutes are not displayed). See Understanding the Date, Time of Day, and DateTime property types.

Specify the format in the Date Format field.

True/False Boolean values.

Specify the format in the True Label and False Label fields.

Obfuscated

Appears if Type is Text.

For read-only, select Yes if you want to display to the user the characters as a string of bullets.

For Editable (Text Input), select Yes if you want the characters entered by the user to appear as a string of bullets. The input characters are initially added to the clipboard as unencrypted, clear text values. The system computes the hashed value only as the page is committed to the PegaRULES database. Thereafter, the hashed value appears in both the clipboard and the database row.

Decimal Places

Appears if Type is Number.

A non-negative integer to control the number of digits presented after the decimal place. The default is Auto, which displays a maximum of three decimal places (placeholder zeroes are not added). Select to remove all digits after the decimal point and round to the nearest integer. Select All to include all digits.

Scale

Appears if Type is Number.

Select a label indicating the scaling you wish to apply to the number. The scales are K for thousands, M for millions, B for billions, and T for trillions. For instance, if you select Thousands, a value of 20,000 appears as "20 K." If Percentage, the value appears as a percentage sign (.8 appears as "80%").

Negative Format

Appears if the Type is Number.

Select a format (minus sign or parenthesis) for displaying negative numbers.

You can also specify a CSS class if you select one of the Style Ref options. By default, the class name is NegativeNumber.

Symbol

Appears if Type is Number. When a symbol is specified an additional character(s) is prepended to the value. Currency automatically uses the localized currency symbol, constant uses a string, and reference uses a property value.

Select an option for representing the number as

  • Currency — Formats the number as a currency using the default locale.
  • Constant — A text string or character (for example, "%") ASCII character that you enter.
  • Reference — A property value.
Separators

Appears if Type is Number.

Select to use a thousands' separator. Depending upon the default locale, a comma or period is used.

Text Alignment

Appears if Type is Number.

Select left, right, or center alignment.

Auto Prepend

Auto Append

Appears if Type is Text and the control is not obfuscated.

Select a property or constant that you want to add either before or after the displayed property value. For example, when the user name appears, the system can automatically append the full mail extension to the name or prepend the user's title.

DateTime Format
or
Date Format

Appears if Type is Date/Time or Date.

Select one of the following:

  • A DateTime format (for example: 1/1/01 1:00 AM), or a Date format (for example: 1/1/01). The formats are locale-specific, changing automatically based on the value set on each user's Windows workstation, or the locale of a user, as recorded in the Operator ID data instance.
  • The elapsed time format (2 days, 5 hours ago). The system displays the value calculated as the difference between the current system date/time and the date/time value of the property. For example:

Current = 3/21/2011

Property value of 3/20/2011 = 1 day ago

Property value of 3/22/2011 = 1 day from now

The units of measure are minutes, hours, days, and years. If greater than 59 minutes, the value is represented in two units (unless the difference is exactly one unit). For example:

1 hour, 10 minutes

2 days, 20 hours

1 month, 4 days

1 year, 3 months

If less than a minute, the value is displayed as "less than a minute ago" (or from now).

To calculate months and days, the system uses today's numerical day in the previous month(s). For example, if today is March 21, one month ago was February 21, not one month, six days ago.

Note: If the property is a Date type or the format is Date, minutes are excluded.

Use a custom display by selecting "Custom" from the format drop-down list. Enter the appropriate symbols in the field to the right of the drop-down menu to customize the format. For example, if you enter:

EEE, MMM d, yy h:mm a

it will display as:

Sat, May 1, '99 2:00 PM

Note that symbols are case-sensitive. Common symbols include:

  • y - the year number

  • M - the month in a year (text or number)
  • d - the day number in a month
  • E - the day name in a week
  • Y - the year
  • H - the hour in the day (0-23)
  • h - the hour in AM/PM (1-12)
  • m - the minute number in an hour
  • s - the second number in a minute
  • a - indicates AM or PM

Additionally, the number of symbols used determines the display format (when applicable):

Display type

Number of symbols used

Output

Text

1-3

Abbreviation (if applicable)

Text

4 or more

Full form

Number

1 or more

Numbers shorter than the number of symbols used are padded with zeroes when applicable

Years are abbreviated to the last two numbers if fewer than four "y" symbols are used

Text and Number

1-2

Number form

Text and Number

3 or more

Text form

Consult the following link for a complete list of custom symbols:

WWWhttp://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html

2nd Number Cutoff

Appears if DateTime Format is 2 days, 5 hours ago (elapsed time).

Enter a numerical value for the first unit, which determines when the second unit is truncated in the display. When the first unit number reaches or exceeds this value, the second unit does not appear.

For instance, if you set the cutoff value to 5, here is how these dates and times will appear to the user:

1 hour, 45 minutes ago
2 hours, 45 minutes ago
3 hours, 45 minutes ago
4 hours, 45 minutes ago
5 hours
6 hours
etc.

Enter a value of 0 to always display a single unit.

True Label

False Label

Appears if the Type is True/False.

Enter a text string to label either outcome. Used with a boolean type.

If the Localize? check box is selected on the section's HTML tab, a SmartPromptAppears in the Constant field in the Parameters dialog. Select a field value rule if you plan to localize the text. If this text is to be localized. enter no more than 64 characters. A field value rule with pyCaption as the second key part and this text as the final key part is needed for each locale.

Show validation messages in read-only mode

Check this option to display validation errors to users at runtime. When enabled for auto-generated controls in read-only mode, if the control's validation fails, the validation message displays to the user. This option is available in the Presentation tab under Read-only Format. It is also available in the control ruleform. When enabled on the control ruleform, all controls using that ruleform will have the option enabled. Show validation messages in read-only mode is disabled by default.

To configure actions on the control, select the Actions tab.

About Controls