Back Forward Harness and Section forms - Adding a Text Input control

About Harnesses

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.

If you are building a Mobile application, see Supported user interface features for mobile applications.

TipAs a best practice, use the pxTextInput control in new development, rather than the non-auto-generated Default controls (which remains available and supported in V6.X). See About the Input Box control.

TipThe UI Gallery landing page contains a working sample. To view and interact with the sample, select > User Interface > UI Gallery. In the Components area, select Text Input.

Adding a Text input control

  1. Click the down-arrow Arrow at the right end of the Basic control group Basics and 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 magnifying glass Magnifying glass to display the Properties panel and complete the following tabs:

Field

Description

Property

Press the down arrow to select a property reference that identifies a single text value.

Alternatively, you can drag a property name from the lists of properties visible in the Application Explorer. Typically, this works for Single Value properties belonging to in the Applies to class of the current rule (or a higher class). If the container in which this field sits has a non-blank Using Page value, you can drag a Single Value property from within that embedded page property.

Clickmagnifying glass to review the property (if the reference is to an existing property in the Applies To class of this rule or a parent of that class). If the property is not found, the New dialog box for the property form appears.

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.

If this field is in 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 field, 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.

For a harness, the property generally must be on the primary page of the rule — the page corresponding to the Applies To key part of the rule. However, a section within the harness may have a different Applies To class, and that section can include properties from its own class.

NoteIf this field is always displayed as read-only, you can enter a linked property reference here, of the form .AAAA.BBBB, where AAAA is the linked property and BBBB is any property reference in the object identified by the value of AAAA as a key. For example, if the property AAAA has a value corresponding to a key of a Data-Admin-Operator-ID instance, then .AAAA.pyUserName presents that Operator ID's full name. This allows values from that object to appear (read-only) in the run-time display, though your processing does not explicitly load the object onto the clipboard.

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.

NoteChoose a default value that speeds data entry. When the system renders a harness or section in read-only mode (for example because the read-write mode requires a privilege that the current user does not hold), the default value does not appear, because data entry is not permitted.

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 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 to create a new when condition or review an existing when condition.

Advanced featureIf 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 checkbox.
Disable

Select to disable the text input:

  • Never: never disabled
  • Always: always disabled
  • Condition (expression): the text input is disabled under the specified condition. In the field that displays, select a condition or click 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 text input is disabled under the specified condition. In the field that displays, select a when rule. Click to create a new when condition or review an existing when condition.
Wrap Text Select if the label is to be presented as multiple lines when the text is longer than the cell width. If this checkbox box is not selected, the label may appear truncated at runtime.
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.

NoteSelecting Required marks the label for this field with an orange asterisk (REQUIRED) 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.

Presentation tab

Field

Description

Edit Options Select an edit mode for this control. The edit mode of the control, specified here, 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 when

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 icon (magnifying glass) 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.

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

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.

Tooltip

If you want to display a tooltip when the user hovers the mouse pointer over the text input, press the down arrow to select the property that you want to display as a tooltip or type a text string within quotations, for example, "Select to open an item".

Placeholder

 

Select None if you do not want to display placeholder text.

Select Other if you want to display a hint or instructional text in the field. The text disappears when the user enters a value. If the user does not enter a value, the placeholder text reappears when the field loses focus.

Style

Specifies the format of the text input. You can style text input controls and create additional formats in the skin rule. To select a custom format, press the down arrow and select Other.

Advanced Options

NoteThe best practice is to define custom styles in the skin.

  • Cell 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.
  • Cell 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.
  • Cell 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.
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.

Number Numeric properties on output.
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.

NoteDo not confuse format types with property types.

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.

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.

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.

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? checkbox is selected on the section's HTML tab, a SmartPromptSmartPrompt 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

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

Up About Flow Actions

Up About Harnesses

Up About Sections