The sfjs object may be used to add dynamic validation to form fields. This differs from the field validation configurable in the Storefront Administrator site in that it can be done at runtime leveraging more specific rules and conditions, since custom functions are supported in addition to regular expressions. These methods are particularly useful when fields need to be validated only under exceptional circumstances.
■ Validation may be applied to any field type.
■ Validation can only be set via sfjs when there is no preexisting validation.
■ Validation set via sfjs behaves the same as validation configured in the admin UI.
■ Validation can only be set once. If multiple validation calls are attempted, all but the last will be ignored.
■ Fields may be manually validated with sfjs to allow for asynchronous validation.
■ Other field values or conditions may be inputs to the validation function.
■ If present the customization page progress bar automatically updates based on all current validation parameters in the step forms.
■ Validation should not be applied to hidden fields (hiding a field automatically suspends all its validation).
■ These sfjs function are not intended for use with optional field validation. Use existing Storefront Administrator field configuration options instead.
Best practices for configuring validation
Admin validation and show/hide settings should be used if they are sufficient for the required form complexity. If sfjs is used to show and hide fields, admin validation may not have the required information to know that some validation has been suspended by a field being hidden via sfjs. When this happens, you may see a form that is 100% complete—
—but fails server-side validation—
—since that is governed by the admin validation settings. If you check the browser console, you will see an additional message indicating which fields are hidden via sfjs but being validated by admin-side validation:
To fix this situation, log into the Storefront Administrator site, navigate to the Customize step configuration page within the product, and then open each field listed in the console message in turn and set its validation to “None.” Then use either sfjs.createRegExValidation() or sfjs.createCustomValidation() to recreate the required validation on the client side.
sfjs.isValid(fieldNameOrId);
Return values
Returns true or false depending on whether field is validated or not.
Remarks
This function is only a reference to the validity flag. It does not itself validate or process anything.
Can be called directly from the field reference or through the sfjs object.
sfjs.setValid(fieldNameOrId, setToValid);
or
sfjs.fields.SomeFieldName.setValid(setToValid);
Remarks
These methods can be used to manually toggle validation to valid or invalid. Specify true for setToValid to make the field valid or false for invalid.
These methods cannot be applied to fields with existing validation configured in Storefront Administrator, or via dynamic regex validation, as they are already controlled by internal validation logic.
Applying these methods in a custom function is allowed even if setting validity happens after the function runs. This is useful for AJAX calls to external services.
Setting field validation can be used to validate a field with an external service where the result of the validation query is unknown until the query returns from said external source.
Can be called directly from the field reference or through the sfjs object.
Example
sfjs.setValid("ff_Title", true); //Sets title field to validated state
sfjs.fields.ff_Title.setValid(true); //Sets title field to validated state
Check or reference validation present in form fields
The following functions allow you to find all validation objects for an entire form, group, or group part.
Since version 9.3
Contains all validation objects for every field with validation currently set. Object contents are indexed by field ID. Note: This reference only contains the validation data of each field, not the field object itself.
Method
sfjs.validation
validationInThisGroup
Since version 9.1
Method
groupObjectReference.validationInThisGroup
Remarks
The validation reference in groups (like a set of tabs) contains an array of field objects that contain validation, listed in the order they appear on the form. These objects can be used for any field reference or function.
validationInThisPart
Since version 9.1
Method
partObjectReference.validationInThisPart
Remarks
The validation reference in group parts (like an individual tab) contains an array of field objects that contain validation, listed in the array the order they appear on the form. These objects can be used for any field reference or function.
Standard validation configured through the Storefront Administrator is intended for use with fields that are guaranteed to have a valid value before the product may be added to the cart. If you have field validation that must be aware of being hidden or enforced conditionally, use the following methods instead.
sfjs.createCustomValidation (fieldNameOrId, errorMessage,
validationFunction, onChangeOnly)
Returns
The validationFunction must either return true or false, or must run setValid() on the field when it is done. If nothing is returned or set the field will be consistently left as valid.
Remarks
Creating a custom function to validate the field value allows using very complex rules, multiple regular expressions, or external services.
The validationFunction may use the setValid() method if it is not immediately known whether a field is valid or not based on the value alone (using an external services call, for example).
Example 1 (Direct)
//create your custom validation function
function myValidateFieldMethod(ctrlObj, fieldID){
if(ctrlObj.FieldValue == "President"){
return true;
}else{
return false;
}
}
//create custom validation for the Title field using your validation function
sfjs.createCustomValidation("Title", "Must be 'President'",
myValidateFieldMethod);
Example 2 (Indirect, via AJAX)
//create your custom validation function
function myValidateFieldMethod(ctrolObj, fieldID){
$.ajax({
url: "http://SomeExternalValidator.com?valueToCheck=" + ctrolObj.FieldValue,
dataType: "json",
contentType: "application/x-www-form-urlencoded",
success: function (result) {
var field = sfjs.fields[fieldID];
if(result == "ValueIsValidated"){
field.setValid(true);
}else{
Field.setValid(false);
}
}
});
}
//create custom validation using your validation function, only updates on change
sfjs.createCustomValidation("Title", "Must be 'President'",
myValidateFieldMethod, true);
sfjs.createRegExValidation(fieldNameOrId, regEx, errorMessage, makeOptional);
Parameters
■ fieldNameOrId—The name or ID of a field (case sensitive).
■ regEx—Regular expression that binds to the field. Values that match the regex pass validation, otherwise they are immediately marked invalid.
■ errorMessage—Custom string that is displayed to the user when the field is invalid (optional).
■ makeOptional—Set to true to validate both values that match the regular expression as well as blank values (optional). All other values will still be invalid.
Example
//sets Title field to validate for the title ‘president’
sfjs.createRegExValidation("ff_Title", /president/gi, "Must say 'President'");
//same as above, but accepts blank value
sfjs.createRegExValidation("ff_Title", /president/gi, "Must say 'President'", true);
//sets NumberOfFish field to require at least some numeric value
sfjs.createRegExValidation("ff_NumberOfFish", /\d/gi, "Must contain a number");