Form Validation

During form validation, Salesforce B2C Commerce checks HTML form field values provided by the customer to ensure that they are valid. You can control how B2C Commerce performs form validation by modifying the corresponding form definition. The form definition determines which fields are validated and how they are validated. If a field value entered by the customer doesn't meet the constraints in the form definition (for example, the entered string is too short), B2C Commerce flags it as a form violation.

Form validation doesn't occur automatically, but is instead controlled by the form action that is fired. For example, the billing form definition contains a general save action:

<action formid="save" valid-form="true"/>

With valid-form set to true, the form is validated.

The type of validation that occurs depends on how you construct the form definition. There are two validation mechanisms: built-in and custom.

Custom Form Validation

You can define custom validation functions for <field> elements and form container elements, such as <form>, <group>, <list>, and <include>. If you define a custom validation function for a form element, B2C Commerce executes that function instead of applying built-in validation.

Custom Data

You can provide custom data during form validation in validation scripts. This data is looped through the validation process and is still accessible when rendering the validation results. This enables you to implement a more sophisticated feedback for the customer. For example, you might want to provide customers with detailed error messaging during address form group validation using data provided by an address validation service or even providing a did you mean alternative for incorrect entries.

This is a general example:

exports.validateMyGroup = function( group : FormGroup )
 {
   ... 
   var data = new HashMap();
   data.put("my_data_1", "some message");
   data.put("my_data_2", 4711);

   var formElementValidationResult = new
FormElementValidationResult(false, 'my.error', data);
   ...
   return formElementValidationResult;
}

See the B2C Commerce API documentation on these classes:

dw.web.FormElementValidationResult: getData() and addData(Object key, Object value) methods
dw.web.FormElement
FormElementValidationResult: getValidationResult() method

Built-in Form Validation

Built-in form validation is based on attribute settings for field definitions. For example, if an email field is marked mandatory="true", B2C Commerce marks the field as invalid if the customer doesn't submit a value. See Field Form Element.

Validation Properties and Flags

When a customer submits a form, field values (strings) are sent electronically and then converted to the appropriate types as defined in the respective form definition.

When an action directs B2C Commerce to validate a form, B2C Commerce submits the form, validate the values entered and update the following flags:

If a field is valid, the system:
1. Sets the valid property to "true".
2. Sets the value property with the parsed value.
3. Reformats the parsed value as specified in the form definition.
4. Sets the htmlValueproperty with the string representation of the formatted value.
If the field is invalid, the system:
1. Sets the valid property to "false".
2. Sets the value property to null.
For the action itself, the system:
1. Sets the fired flag to true.
2. Updates the form's valid firedAction and triggeredActionproperties.

Note: If an inner form definition (called by an < include>) is invalid, the surrounding form definition is also invalid.

Custom Validation Functions

You can configure custom validation functions not only for form fields (<field>) but also for form container elements (<form>, <group>, <list>, and <include>).

The first example shows a custom validation function configured for a <field> element:

<field formid="password"
       label="label.password"
       description="resource.customerpassword"
       type="string"
       mandatory="true"
       range-error="resource.customerpassword"
       validation="${require('~/cartridge/scripts/forms/my_custom_script.ds').my_custom_validation(formfield);}"
/>

The next example shows two custom validation functions configured for two different container elements (<form> and <group>):

<form xmlns="http://www.demandware.com/xml/form/2008-04-19" 
      validation="${require('~/cartridge/scripts/forms/MyCustomValidator.ds').validateThis(formgroup);}">
     ...
     <group formid="myGroup" 
            validation="${require('~/cartridge/scripts/forms/MyCustomValidator.ds').validateThat(formgroup);}">
          ...
     </group>
     ...
</form>

In both examples, the validation attribute specifies the function to be called, and the system expects the validation function to return an appropriate value. Validation functions can return a boolean value or a dw.web.FormElementValidationResult object.

Error Messages

A form definition can specify multiple error messages for each form field (for example, "value-error", "range-error", "missing-error" or "parse-error"). B2C Commerce validates the user entry and exposes one of these error messages in the FormField.error attribute, depending on which validation condition was not satisfied.

Note:

Starting in 15.8, it's possible to validate a field using a custom validation function. When you specify a custom validation function for a given field definition, you should only specify a range-error message. For more information, see Field Form Element.

The order of validation and corresponding error messages is as follows.

B2C Commerce removes white space characters and parses the user entry into a native data type. If the parsing fails, B2C Commerce sets "parse-error". If a regular expression was specified, B2C Commerce applies it. If the match fails, the result is a "parse-error".
If the field was marked as "mandatory" but there is no entry, the result is a "missing-error".
If the field has min/max or minlength/maxlength checks and the entry fails either, the result is a "range-error".
If a form field is invalidated programmatically, either by calling the invalidateFormElement() method or the InvalidateFormElement pipelet, the result is a "value-error".

Field error attributes maintain an order of precedence, as follows:

Missing-error
Parse-error
Range-error
Value-error

The FormElement.invalidateFormElement(error : String) method lets you specify an error message.

You can specify a form-error attribute in a form group. B2C Commerce sets "form-error" when the form group is invalidated programmatically.

Note: Applying invalidateFormElement() to a form group just sets the error message. The isValid() method continues to return the validation status of the child elements.