Back ForwardHow to provide interactive formatting of user inputs

On a user form, your application can provide users with interactive formatting and format validation at the keystroke level, or when the user focus leaves the input field.

The first capability is known as client-side input formatting; the second is known as server input formatting.

NoteDon't confuse input formatting, which can change the appearance of the field on a form with validation, which checks whether a user input meets criteria defined through an edit validate rule and may return an error message and cause the display of an Red X mark. Input formatting occurs only after validation, and never returns an error message.

Building server input formatting

Server input formatting reformats an input field when user focus leaves the field. The new format is computed by the control rule referenced in the Format field of the Field panel, or that field is blank, the control rule referenced in the property itself.

For example, a user input of 1234567 can be automatically reformatted to contain commas (or periods, depending on locale) as 1,234,567.

Note: This feature depends on AJAX processing, which involves a server interaction and delay. To reduce a possible increase in response time, enable this feature only for fields where reformatting is possible and improves usability.

CautionYou can use a control rule that accepts parameters, but you can't specify the parameters. Input formatting assumes default parameter values.

  1. Identify or create the control rule that is to provide the reformatting. Review the HTML code in the Advanced tab to confirm that it includes a <pega:include name="ClientValidation"/> statement.
  2. On the Advanced tab of a harness or flow action, select the Enable Client Side Validation? box.
  3. Optionally, update the property to reference the control rule in the Control field on the Definition tab.

  4. Add the field to a harness, section, or flow action using the Text Input control, Calendar control, or other appropriate control from the Basic control group Basics.
  5. On the Cell Properties panel, select the control rule in the Format field, if you skipped step 3 above.
  6. Locate the Client Event field. Click Magnifying glass to open the Client Event editor.
  7. Select the Activate Input Formatting checkbox. This sets the Client Event field to INPUT-FORMAT.
  8. Save the rule form.
  9. Test.

Client-side input formatting example

A standard file rule demonstrates this facility for formatting Social Security numbers in the format NNN-NN-NNNN. To view an example supported by standard rules:

  1. Create or find a Single Value property of type Text to hold a Social Security number (SSN).
  2. On the Advanced tab of the Property form, select SSN for the Validate field.
  3. Open a flow action or harness. On the HTML tab, select the Enable Client Side Validation? box.
  4. On the Layout or Form tab, drag the Text Input control and drop it in a cell. Review and update the Cell Properties panel.
  5. Save the Flow Action form or Section form.
  6. Select Run from the Actions menu to test the SSN format.

Building a client-side input format

Advanced featureThis capability requires JavaScript skills. If your application requires a new edit validate rule, Java skills are also needed.

This facility uses a JavaScript function on the workstation to respond to each user keystroke in an input field on a user form. The function is linked to the onKeyUp JavaScript event.

  1. Create an edit validate rule for the values in the field. Choose a name that uniquely identifies a format.
  2. Update the property to reference that rule in the Validate field of the Advanced tab.
  3. Review the JavaScript function SSN_Formatter() in the standard text file rule webwb.input_formatter.js.
  4. Copy the default (empty) Rule-HTML-Fragment CustomValidators to your application ruleset. Your copy overrides the default at runtime.
  5. In your copy of CustomValidators, place your JavaScript validator code.
  6. Open a harness. On the HTML tab, select the Enable Client Side Validation? box.
  7. Reference CustomValidators in the Scripts array on the Scripts and Styles tab of the Harness form.
  8. On the Layout tab, drag the Text Input control to place the property in a cell. Complete the Cell Properties panel.
  9. Save the Harness form.
  10. Test the validation function by selecting Run from the Actions menu.
Definitions Ajax, client-side format validation
Related topics About Edit Validate rules

UpUser Interface category