JavaScript | Guide to: Customizing an Appen Validator

When you want to use a custom javascript validator for your job, you can refactor an existing Appen validator to fit your needs. You can change the error message that contributors will receive when they do not pass, and you can also change the value that will pass the validation. Utilizing this functionality will save you time, ensure that contributors are completing the task as you envisioned, and provide further instruction if they are completing the task incorrectly.  In the following article, we will first show you how to simply change the message that a contributor sees when something that they enter does not pass validation.  Next, we'll show you how to customize the validator function itself.

Customizing Your Contributor-Facing Validator Message

To change the message that contributors will receive when their answer does not pass the validation, copy the following javascript into the custom javascript area below your job. In this case, you can create a custom validator message for the Appen url validator.

var validator_options = CMLFormValidator.getValidator('url').options
validator_options.errorMessage = function()
{ return ('CUSTOM ERROR MESSAGE HERE.'); }
CMLFormValidator.addAllThese([ ['url', validator_options] ]);

Replace ‘CUSTOM ERROR MESSAGE HERE’ with the text you would like contributors to see.

If, say, you would like to change the error message for the Appen 'required' validator, you could either replace all instances of ‘url’ above with ‘required’, or copy the code and rename the validator_options variable. In that case, you could have two different validator messages, one for the url validator and one for the required validator.  This same javascript tailored for the 'required' validator looks like this:

var validator_options = CMLFormValidator.getValidator(‘required’).options
 validator_options.errorMessage = function()
 { return ('CUSTOM ERROR MESSAGE HERE.'); }
 CMLFormValidator.addAllThese([ [‘required’, validator_options] ]);

Customizing Your Validator's Function

If you would like to define the value that will pass the validation, you can choose a validator to refactor. We recommend selecting our yext_no_international_url validator, since it is highly unlikely that it already exists in your form.

Next, add that validator to the validates attribute on the CML form element you wish to validate. In this case, it is a text field:

<cml:text label="Example validated text field:" name="validated_field" validates="required yext_no_international_url" instructions="Provide more detailed instructions here" />

Then, copy this javascript into the ‘JavaScript’ area below your job:

// This block if/else block is used to hijack the functionality of an existing validator (specifically: yext_no_international_url)
if(!_cf_cml.digging_gold) {
  CMLFormValidator.addAllThese([
    ['yext_no_international_url', {
      errorMessage: function(){
        return ('CUSTOM ERROR MESSAGE HERE.');
      },
      validate: function(element, props){
        // METHOD_TO_VALIDATE must return true or false
        return METHOD_TO_VALIDATE(element)
      }
    }]
  ]);
} else {
  CMLFormValidator.addAllThese([
   ['yext_no_international_url', {
      validate: function(element,props){
         return true
      }
   }]          
  ]);
}
 
// This is the method that will evaluate your validation
// value is the user submitted content of the form element you are validating
function METHOD_TO_VALIDATE(element) {
  var value = element.value
  return value == 'passed'
}

Set your error message where the javascript says ‘CUSTOM ERROR MESSAGE HERE’.

Redefine the METHOD_TO_VALIDATE function to suit your needs. The function must return ‘true’ (validation passed) or ‘false’ (validation failed). As it is structured now, contributors will only pass this validator if they enter ‘passed’ into the task.

Note: The javascript displayed ignores the validator while you are editing or creating test questions.