ATG : Implementing Client-Side Validation

Implementing Client-Side Validation with DSP Tags

Applying client-side validation to dsp:input and dsp:select tags enable the following behaviors based on the state of the validation in the input or select element:

Allows an inline indicator graphic to show or hide

Allows a client-side validation message to be added to the message bar when invalid contents are present (optional)

Causes the dojo SubmitButton widget(s) (if present) to enable or disable

To enable client-side validation with a dsp:input or dsp:select tag, use the dsp:tagAttribute tag:

<dsp:input id="dateOfBirth" type="text" value="01/01/1980" size="30" converter="date" date="M/dd/yyyy" bean="/atg/web/messaging/test/UserInfoFormHandler.dateOfBirth">
<dsp:tagAttribute name="dojoType" value="DateTextbox"/>
<dsp:tagAttribute name="lang" value="en-us"/>
<dsp:tagAttribute name="required" value="true"/>
<dsp:tagAttribute name="trim" value="true"/>
<dsp:tagAttribute name="invalidMessage" value="The date of birth is
    invalid."/>
<dsp:tagAttribute name="missingMessage" value="The date of birth is
    required."/>
<dsp:tagAttribute name="inlineIndicator" value="dateOfBirthAlert"/>
</dsp:input>

The dojoType attribute specifies the type of client-side widget to use for the input element.

Note: The dsp:input or equivalent tag must have an ID property defined in order for the SubmitButton auto-enabling feature to work properly.

Available Client-Side Validation Widgets

The following client-side validation widgets are available from dojo:

ValidationTextbox - Provides basic validation functionality, such as required values

IntegerTextbox - Tests for signed or unsigned integer input and ranges

RealNumberTextbox - Tests for real number input and ranges

CurrencyTextbox - Tests if input denotes a monetary value or range

IpAddressTextbox - Tests for a valid IP address

UrlTextbox - Tests for a valid URL

EmailTextbox - Tests for a valid email address

EmailListTextbox - Tests for a list of valid email addresses

DateTextbox - Tests for a valid date in specified locale

TimeTextbox - Tests for a valid time

UsStateTextbox - Tests for a United States state abbreviation

UsZipTextbox - Tests if input is a US zip code: validates zip-5 and zip-5 plus 4

UsSocialSecurityNumberTextbox - Tests for a United States Social Security number

UsPhoneNumberTextbox - Tests for a United States 10-digit telephone number, extension is optional

RegexpTextbox - Tests input based on conformity to a specified regular expression

Refer to the dojo documentation for details on implementing specific widgets.

ATG provides these additional validation widgets:

SimpleComboBox - forces a selection in a drop-down box (use dsp:select with SimpleComboBox)

TextArea - performs range validation on the length of the textarea contents (use dsp:input instead of dsp:textarea with TextArea, since dsp:textarea does not accept dojo widgets)

Preventing the Form from Submitting

The SubmitButton widget is used to prevent a form from submitting while there is invalid content in any of the contained dojo validation widgets:

<dsp:input id="updateUserInfo" type="Submit" value="Submit"
 bean="/atg/web/messaging/test/UserInfoFormHandler.updateUserInfo">
  <dsp:tagAttribute name="dojoType" value="validation:SubmitButton"/>
</dsp:input>

When present in a form, the SubmitButton widget will automatically enable and disable to prevent form submission while there are invalid contents in any of the dojo validation widgets contained in the form. One or more SubmitButton widgets may be used in the same form. If the SubmitButton must be placed outside of the form which it validates, use the form attribute of the SubmitButton to specify the form to validate.

Conditional Validation

Validation may be made conditional based on the state of another element, such as a radio button. First, create a function to test the state of the radio button. The following examples tests a ATG Commerce Service Center radio button:

atg.commerce.csr.rule0 = function () { return
  document.getElementsByName('addressType')[0].checked; };

Then reference the function from the validateIf attribute on the widget:

<dsp:tagAttribute name="validateIf"   value="atg.commerce.csr.rule0.apply()"/>

Now the validation rules of the widget will be applied conditionally only when the referenced function returns true.

Conditional Requirements

A validation widget may be conditionally required based on the evaluation of an expression. As with conditional validation (above), create a function to test the condition. Then reference the function from the requiredIf attribute on the widget. The following example tests an ATG Commerce Service Center condition:

<dsp:tagAttribute name="requiredIf"  value="atg.commerce.csr.rule0.apply()"/>

Now the widget will do required checks only when the condition applies, but will do validation checks always when the widget is non-empty.

Custom Validation Conditions

Custom validation conditions may be applied to any validation widget through the validIf and missingIf attributes. The validIf attribute applies a custom validation condition to the widget:

<dsp:tagAttribute name="validIf" value="this.getValue() != 'foo'"/>

In the above example, the widget will be considered valid only with the expression in the validIf attribute evaluates to true.

The missingIf attribute applies a custom condition to determine whether the widget is missing a required value.

Additional Field Validation

You can use field validation to capture specific information. For example, to add an additional required field to the billing addresses to capture an e-mail address, add code similar to the following on your billing page:

<span class="atg_messaging_requiredIndicator"
  id="emailValidatorAlert">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span>
 <dsp:input type="text" name="emailAddress"
  bean="BillingFormHandler.emailAddress" required="<%=true%>"
  size="25" maxlength="25">
    <dsp:tagAttribute name="dojoType" value="EmailTextbox" />
    <dsp:tagAttribute name="required" value="true" />
    <dsp:tagAttribute name="missingMessage" value="${emailMissing
      }" />
    <dsp:tagAttribute name="invalidMessage"
      value="${emailInvalid}"/>
    <dsp:tagAttribute name="inlineIndicator"
      value="emailValidatorAlert" />
  </dsp:input>

Additionally, you must have a form handler equivalent to BillingFormHandler in the example that accepts the e-mail address as one of its inputs.