Harness and Section forms - Adding a Text Input control

A cell in a layout can present the value of a property, as display-only or as an input field. Follow these instructions to control the presentation of a property value in a Text Input control.

Configure styles for the Text Input control using the Skin rule. See Skin form — Components tab — Controls — Text inputs.

The Text Input control uses the auto-generated control pxTextInput . Its look and behavior are governed by the rule form's Control tab. The Parameters tab is not available and the HTML cannot be edited. As a best practice, do not modify a copy of the rule. Instead, use the Parameters dialog available in the control's Cell Properties panel while designing a section, flow action, or harness. See Completing the Control tab.

As a best practice, use the pxTextInput control in new development, rather than the non-auto-generated Default controls. See About the Input Box control.

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

> 1. Drag and drop the Text Input control

  1. From the Basic control group, select Text input.
  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 View properties icon to display the Properties panel and complete the following tabs:

General tab

Field Description
Property Press the down arrow to select a property reference that identifies a single text value.
Label

Select to use the default label for the property or specify your own label. select or create a label.Use SmartPrompt to select a field value rule if you plan to localize the text. See About the Localization wizard.

Default value Optional. Enter a constant value for the property value, a property reference, or an expression, to be used only when the user form or flow action form appears in read-write mode rather than read-only mode.
Placeholder Select None if you do not want to display placeholder text.
Tooltip Specify a tooltip to display when the user hovers the mouse pointer over the control. You can press the down arrow to select a property value or type the text that you want to display as the tooltip.
Visibility

To control the visibility of the label, select one of the following:

  • Always : always visible
  • Condition (expression) : the region is visible under the specified condition. In the field that displays, select a condition or click the Open condition builder icon to open the Condition Builder. You can define a simple 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.
  • Condition (when) : the region is visible under the specified condition. In the field that displays, select a when rule. Click the Open icon to create a new when condition or review an existing when condition.

If this section is to become part of navigation in a composite portal, you can make the header visible only when a specific space is the current space. Enter an expression here similar to the following:

pyCurrentSpace=="ASpaceName"
Then select the Run visibility condition on client check box.
Disable Specify a condition for disabling the text input:
Required This box appears only for fields in cells on flow actions and sections. Select to require that (when the form appears at runtime in read-write mode) users cannot successfully submit the form if the field is blank.

Selecting Required marks the label for this field with an orange asterisk when the flow action form appears in read-write mode. (The asterisk also appears if the Label control's Value For field is not blank and the Label control's Required box is checked.)

For sections, checking this box enables client-side format validation when this section is part of a harness form that has the Enable Client Side Validation box selected on the HTML tab. At runtime, users who leave this field blank and submit the form are notified immediately that the field is required; the form is not transmitted to the server.
Tour ID Optional: Provide an ID for use in a guided tour. Use a combination of numbers, letters, and underscores. Pega Platform uses the Tour ID when it finds an anchor button during a tour stop anchor point.
Test ID

Optional: If authorized, you can provide a unique Test ID for use in your test suite in order to support better automated testing against any Pega application.

When creating a control that supports Test ID, the Test ID field is initially blank. Use a combination of numbers, letters, and underscores, or click the Generate ID button to create a time stamp as a unique ID. The attribute data-test-id is then generated for the selected element. When you save an existing section, any supported controls that do not have a Test ID will have one automatically generated. You can override these with a custom ID at a later time.

Once generated, you can view your Test ID in HTML or display it in the Live UI panel. You also have the option to have all controls that support Test IDs in a ruleset updated in bulk.

A standard, out-of-the-box developer role, PegaRULES:SysAdm4, includes the privilege for Test ID. To disable Test ID for this role, modify the pxTestID privilege.

Presentation tab

Field Description
Edit Options Select an edit mode for this control. The edit mode of the control takes precedence over section and harness settings.
  • Auto — the control uses the edit mode of the section or harness in which it appears. If the section is set to Read Only, then the control is Read Only. If the section is set to Auto, then the control uses the edit mode of the harness. For example, a New harness is editable, while a Review harness is read only.
  • Editable — the control is editable, regardless of the edit mode of the enclosing layout.
  • Read Only — the property value is presented in read-only mode always, or based on a when condition rule or client-side test, even when the enclosing layout is in read-write mode.
Read-only value

Appears only when you select Read Only in the Edit Options field. Enter or 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.
  • A simple 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 the Open condition builder icon to open the tool. See Using the Condition Builder to configure dynamic UI actions.

Specify Size Specifies the width of the text input.

Select Auto if you want the layout to determine the width of the control area. This is the default.

If you want to specify a fixed width for the text input, select Custom and then specify the width in pixels or percentage.

Min/Max Chars Optional.Enter a value that determines the minimum and maximum number of characters that can be entered in the text input. You can designate either value as unlimited by leaving it blank.
Control format Optional. Specifies the style format applied to the control. You can define multiple formats in the skin rule. Press the down arrow to select another format, if applicable.
Label format Read-only option. Specifies the format of the control's label.
Editable Format  
Type
Select a type (editable) used with this property. Your selection filters the format options.
Group/Selection Description
Email Renders the email address as a link. When the link is clicked, the email composer opens with this value populated in the To: field.
Number Numeric properties on output.
Phone Renders the phone number as a link. When the link is clicked, the phone dialer or another configured phone application opens.
Text Unedited text, which may contain spaces, tabs, line break characters, and other control characters.
URL Opens the URL as a link in new window.
Text Alignment Select left, right, or center alignment.
Advanced Options 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.
Read-only format  
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.
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.
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.
Email Renders the email address as a link. When the link is clicked, the email composer opens with this value populated in the To: field.
Number Numeric properties on output.
Phone Renders the phone number as a link. When the link is clicked, the phone dialer or another configured phone application opens.
Text Unedited text, which may contain spaces, tabs, line break characters, and other control characters.
True/False Boolean values.

Specify the format in the True Label and False Label fields.
URL Opens the URL as a link in new window.
DateTime Format

or

Date Format

 Appears if Type is Date/Time or Date.
Text Alignment Appears if Type is Number.

Select left, right, or center alignment.
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.

Use native control on mobile Enables the use of native rendering on mobile devices. At runtime, the date and time pickers display using the mobile browsers native calendar date and time pickers.

To enable native browser support, check the Use native control on mobile.

The native control option only appears for the Date Time control types.
Display Read-only formatting At runtime, read-only formatting displays when the editable field is not in focus. When the editable field is in focus, it behaves as normal input. The actual value gets submitted although the formatted value is displayed. Editable formatting does not appear when there are client-side and server-side validations.

To enable read-only formatting, check the Display value using read-only formatting check box. The read-only formatting option only appears for the Currency, Date Time, Integer, Number and Percentage control types when the Editable Format is Number.

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.

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.
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.
Rounding Method Specifies how halfway values are handled:
  • Default — The default value per the prconfig xml
  • Round towards positive infinity
  • Round towards zero
  • Round towards negative infinity
  • Round down to nearest — round to the nearest neighbor, where an equidistant value is rounded down
  • Round to nearest even number — round to the nearest neighbor, where an equidistant value is rounded to an even value
  • Round up to nearest — round to the nearest neighbor, where an equidistant value is rounded up
  • Round away from zero
Separators Appears if Type is Number.

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

Appears if the Read-only format Type is Text.

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.

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

Select a property or constant that you want to add either before the displayed property value. For example, when the user name appears, the system can automatically prepend the user's title.
Auto Append Appears if Type is Text and the control is not obfuscated.

Select a property or constant that you want to add after the displayed property value. For example, when the user name appears, the system can automatically append the full mail extension to the name.
Show Value As Appears if the Type is True/False.

Select to label either outcome using Text or an Image.

True Image

False Image

Appears if the Type is True/False and Show Value As Image is selected.

Select an image to label either outcome. Used with a boolean type.
True Text

False Text

Appears if the Type is True/False and Show Value As Text is selected.

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 SmartPrompt Appears 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.

Copying, deleting, duplicating, or moving an Text Input control

Use these Windows operations to speed development:

  • To move a cell containing an Text Input control, select the cell and drag and drop it in another cell in the same layout or another layout.
  • To cut, copy, or paste a Text Input control in a cell, right-click in the cell to access a context-menu.