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.

CautionThis 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 HTML tab to confirm that it includes a <pega:include name="ClientValidation"/> statement.
  2. On the HTML 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 (Input Box), Calendar control (Calendar) 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 the magnifying glass icon (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 (Input Box) and drop it in a cell. Review and update the Cell Properties panel.
  5. Save the Flow Action form or Section form.
  6. Click the Preview toolbar button (Preview) 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. Create a new text file rule (Rule-File-Text rule type) to contain a similar JavaScript function for the field of interest, matching the name that you chose earlier in step 1. Associate the function with the onKeyUp JavaScript event, following the example for SSN. Save the Text File form.
  5. Open a harness. On the HTML tab, select the Enable Client Side Validation? box.
  6. Reference the text file rule containing your JavaScript routine in the Scripts array on the Scripts and Styles tab of the Harness form.
  7. On the Layout tab, drag the Text Input control (Input Box) to place the property in a cell. Complete the Cell Properties panel.
  8. Save the Harness form.
  9. Test.
Definitions Ajax, client-side format validation
Related topics About Edit Validate rules

UpUser Interface category