Customizing Validatinator

Adding Custom Validation Methods

To add a new validation method you must extend the Validatinator.prototype.validations object. Also to make sure your validation works 100% perfectly you need to make sure that the first parameter it receives is the field's value and that your validation method returns true if it passes and false otherwise. If your method expects a value from another form field you will need to retrieve that value yourself within the method as, at this time, we do not support grabbing field values other than that of the currently validated field.

Here are two quick examples for adding custom validation methods:

Validatinator.prototype.validations.newValidation = function(fieldValue) {
    return fieldValue === "foo";
}

In this example we will accept another field's value as the second parameter:

Validatinator.prototype.validations.newestValidation = function(fieldValue, anotherFieldsName) {
    // Here we are using a Validatinator utility method that will get a field's value based on the field's
    // and form's name attribute.  We can use the shortcut `this.parent.currentForm` to grab the current validating
    // form's name attribute.  If you are getting the value from another, separate, form you can manually pass in that
    // form's name attribute as the first parameter.
    var anotherFieldsValue = this.utils.getFieldsValue(this.parent.currentForm, anotherFieldsName);
    
    return anotherFieldsValue !== fieldValue && anotherFieldsValue === "foobar";
}

Remember whenever you create a new validation method you must always accompany it with a custom validation error message. See the next section to learn how to add custom error messages.

Adding Custom Validation Error Messages

Overwriting or adding a new validation error message is easy as pie, we offer a quick and simple way to add custom error messages when you instantiate Validatinator. When running new Validatinator() you can pass in an optional second parameter that will take an object that you can use to override or add custom validation error messages.

Here is an example of adding and overwriting Validatinator error messages:

// We create our Validatinator instance we normally would, but we throw in a second parameter to the mix; this second
// parameter accepts an object literal with the name of the validation method as the key and the error message as
// the value.
var validatinator = new Validatinator(
    {
        "my-forms-name-attribute": {
            "my-fields-name-attribute": "required|min:5|max:20",
            "i-am-another-field-in-the-above-form": "required|between:20,30",
        },
        "i-am-another-form": {
            "i-am-a-field-in-the-new-form": "required|alphaNum",
        }
    },
    {
        "required": "I will overwrite the validation error message for the `required` validation method.",
        "newErrorMessage": "I am a totally new validation error message that will be called if the `newErrorMessage` validation method were to run and fail on a form field."
    }
);

The above example changes the validation messages on a Validatinator instances 'global' scope. If you'd like to fine tune it even further you can set custom messages on a per field instance. See here:

// We create our Validatinator instance we normally would, but we throw in a second parameter to the mix; this second
// parameter accepts an object literal with the name of the validation method as the key and the error message as
// the value.
var validatinator = new Validatinator(
    {
        "my-forms-name-attribute": {
            "my-fields-name-attribute": "required|min:5|max:20",
            "i-am-another-field-in-the-above-form": "required|between:20,30",
        },
        "i-am-another-form": {
            "i-am-a-field-in-the-new-form": "required|alphaNum",
        }
    },
    {
        "my-forms-name-attribute": {
            "my-fields-name-attribute": {
                "required": "This is a custom required validation message for our field `my-fields-name-attribute` within the `my-forms-name-attribute` form.",
            },
            "i-am-another-field-in-the-above-form": {
                "required": "This is going to be completely different validation message than the field from above even though they are the same validation methods, `required`."
            }
        },
        "newErrorMessage": "I am a totally new validation error message that will be called if the `newErrorMessage` validation method were to run and fail on a form field.  All forms and fields will inherit this message if they do not create their own custom validation message."
    }
);