Custom validation rules - mosbymc/validator GitHub Wiki

Custom validation rules

To add custom validation rules to an input, use the “data-customrules” attribute. The value should be a comma delimited list of functions for the validator to call when validating the specific input.

    <input type='text' data-customrules="customRuleExample1,customRuleExample2"/>

Or, if the function is namespaced inside of an object, you would set the value as:

    <input type='text' data-customrules="objectNamespace.customRuleExample"/>

The custom validation rule can also be inside of a function object and the validator can call it as well as long as it is reachable from the window level. However, I'd recommend not doing this as the validator must actually call the function object first in order to get a reference to it so it can access the actual validation rule. This will result in all the code inside the function object executing. If the function object just returns an object with attributes/methods on it and doesn't actually execute any code, then you shouldn't have a problem. Nonetheless, even though the validator would be able to find and execute any function declared inside a function object, it's a practice I'd recommend against.

This works the same way as the data-type attribute; it take a comma delimited list of custom validation function names, without the open/close parentheses, and tests the input against them. Note that the validator will be able to find and execute any namespaced function only as long as it is "publicly" accessible.

When calling the custom rules, the validator will pass the context as the input element that is currently being validated. That means that the keyword "this" will refer to the input element. The validator will also pass a single parameter, a callback into the validator to be used once your custom function has completed.

After your custom rule tests the input, use the callback function to return to the validator. The callback should be passed up to three parameters. The first is a required boolean that denotes whether or not the input passed or failed validation for the function. The second and third parameters are only used if the input failed validation. The second parameter is the error message that you want to be displayed next to the input, and the third parameter specifies the width of the error span to display. Supplying the third parameter is optional and will override the default width of 200 pixels.

    function customRuleExample(callback) {
       try {
          if ($(this).val().length < 1) {  //fails validation, passing back all parameters including the width param
             callback(false, "Failed custom rule.", 150);
          }
          else {
             callback(true);  //passed validation, only need to pass back "valid" param inside object
          }
       }
       catch {
          callback(false, "Failed validation");
    }

Note the logic is wrapped in a try catch for the custom validation rule. I highly recommend doing this for all custom validation rules where there's a chance for exceptions. Although the validator can catch an exception thrown in a synchronous custom rule, an asynchronous rule is another matter. Since it's impossible for the validatior to know whether a custom function is synchronous or asynchronous beforehand, and you may want to handle exceptions in a different manner than the validator, make sure to wrap all code that can potentially fail in a try/catch.

Continue to: Restricting character input