Control form - Completing the Control tab
Applicable to Theme UI-Kit applications
Pega Platform includes a set of standard auto-generated controls. As a best practice, use these controls to save development time and ensure consistency. By default, this tab is displayed when you open an auto-generated control or open a New rule.
Auto-generated controls provide these benefits:
- Eliminate hand-coding, which simplifies design and maintenance.
- Let you to customize a control in a section or harness without having to make multiple copies and reconfigurations.
- Preserve custom settings when you upgrade your system.
- Ensure browser independence and compatibility.
Customizing a control in a section
Auto-generated controls are optimized for most interfaces. If necessary, edit the settings within the section, flow action, or harness in which you are working.
- Open the section or harness that contains the rule.
- Select the cell that holds the rule and click the View properties icon to open its Cell Properties window.
- In the panel, click the Open icon next to the control name.
The control Parameters tab opens, which lists the available settings. Note, that you cannot edit the Control Modes or UI Element settings.
- Modify the settings and save the section.
The system generates the XML representing your edits and stores it in the section.
To reuse a modified control, save a copy of this control to 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.
If you want to revert to the control's configuration, clear the customized instance and re-add the rule.
For more information, see Supported controls when working offline.
Control tab settings
These settings determine the read-only and edit-mode presentation and behavior of the control.
|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:
The Control Modes setting does not appear in the Parameters dialog when customizing the control in a section.
Use this section to specify the control or category of property type used with the control.
|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. You select filters the Format, Options, and
Behaviors settings this tab.
|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:
Use this section to specify parameters for editable and action control modes.
|Specify Size||Available when the UI Element is Text input.
|Min/Max Chars||Available when the UI Element is Text input or
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||Available when 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||Optional. Available when the UI Element is Text input, Text area, Dropdown, Multi-select list, or
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||Available when the UI Element is Text area or
Rich text editor.
|Width||Available when the UI Element is Text area,
Text area, Text input,
or Dropdown and 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, %columns
|Specify Height||Available when the UI Element is Text area or
Rich text editor.
|Height|| Available when you select Custom in 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||Available when the Text Area Height is
Select to display a scrollbar to the right of the area if the content exceeds the number of rows or pixels.
|Min Height||Available when the Text Area Height is Size
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||Available when the Text Area Height is Size
Select one of the following:
|Date/Time|| Available when the UI Element is Date time.
Enables date and time selections in the Calendar control. Select one of the following:
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|| Available when the UI Element is Date time.
Determines the presentation of the control to the user. Select either:
|Allow Text Entry|| Available when the UI element is Date time 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|| Available when the UI Element is Date time 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. Available when the UI Element is Date time and the Display Mode is
Enter a numeric 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. 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|| Available 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|| Available 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||Available when the UI Element is Button (optional),
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
If you use shortcut keys in your application, be careful to choose distinct
letters for each control; for example, you can't have
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. Available when Control Modes is Action or Editable/Read-Only (all UI
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").
When UI Element is
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||Available when the UI Element is Button or Link. Select a pre-defined format (
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. Available 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||Available when you enter a privilege. Select
|Image (for Button or Link)||Optional. Available when the UI Element is Button or
Insert an icon next to the label by clicking the Show Image Viewer icon . This opens the Image Viewer. Select the binary file you wish to use.
If the button or link Format, for example,
|Image Position||Available 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. Available 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:
|Icon||Available when UI Element is Image. Select a
standard icon from the drop-down list. By default, the
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
To use a custom icon, select
|Image (for Icon)||Available when you enter
As a best practice, use sprites rather than individual images for Icon controls.
|Position||Available 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.
Use this area to design the appearance of read-only text or an editable control. Action controls do not use formats.
|Type||Select a format (read-only) used with this property. Your selection filters the
|Obfuscated|| Available when Type is
For read-only, select
For Editable (
|Decimal Places|| Available when Type is
A non-negative integer to control the number of digits presented after the
decimal place. The default is
|Scale|| Available when Type is
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
|Negative Format|| Available when the Type is
Select a format (minus sign or parenthesis) for displaying negative numbers.
You can also specify a CSS class if you select one of the
|Symbol|| Available when Type is
Select an option for representing the number as
|Separators|| Available when Type is
Select to use a thousands' separator. Depending upon the default locale, a comma or period is used.
|Text Alignment|| Available when Type is
Select left, right, or center alignment.
|Auto Prepend / Auto Append|| Available when Type is
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||
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:
Additionally, the number of symbols used determines the display format (when
Years are abbreviated to the last two numbers
if fewer than four "y" symbols are used
Years are abbreviated to the last two numbers if fewer than four "y" symbols are used
Consult the online Java tutorial on SimpleDateFormat for a complete list of custom symbols.
|Round second number after|| Available when DateTime Format is
Enter a numeric 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
Enter a value of 0 to always display a single unit.
|True Label / False Label|| Available when the Type is
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||Select this option to display validation errors to users at run time. When enabled for auto-generated controls in read-only mode, if the control's validation fails, the validation message is displayed. This option is available on 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 have the option enabled.|
To configure actions on the control, select the Actions tab.
ArticleAbout Edit Input rules