Validatr

/ API

Cross Browser HTML5 Form Validation.

View

Widget

Options

The options only apply to an instance of the jQuery widget - not access to the $.validatr class.

Name Type Default Description
dateFormat String 'yyyy-mm-dd'

Any combination of mm, dd, and yyyy separated by a /, - or .

When the date input type is not supported by the browser the input value will be expected in whatever format is specified.

location String right The location of the error message in relation to the input. Possible values are left, right, top, and bottom.
position Fucntion function ($error, $input) {} The position function places the error message on the page. The function receives the jQuery error element and the jQuery input element.
showall Boolean false Show all error messages at once when submitting the form.
template String <div>{{message}}</div> The format for the error message inlcuding wrapping HTML. The message will replace {{message}}.
theme String '' Class names to be added to the error message HTML. If an empty string is provided default (inline) styles will be added.
Preset theme values can be bootstrap or jqueryui, adding framework classes to the message HTML.
valid Fucntion $.noop A function that is called after a successful validation of a form. To prevent the default action (form submission) have this reunction retrun false.

Methods

.validatr('addTest', name[, fn])

Add a custom test to the suite of custom tests that Validatr will perform on an input.

$('form').validatr('addTest', 'example', function (element) {});

//or 

$('form').validatr('addTest', {
    example: function (element) {}
});

Alternate Invocation

$.validatr.addTest(name[, fn])

Parameters

Name Type Description
name String or Object If passed as a string addTest will expect a a second argument fn.
fn Function The callback function for the test. It receives the element that is currently being tested as a parameter.
.validatr('getElements') jQuery Object

Returns all of the elements that will be validated in a form. This includes any elements that exist outside of the form but have the form attrbiute specified.

Alternate Invocation

$.validatr.getElements(form)
.validatr('validateElement', element) Boolean

Returns the validity state of an element (boolean). It will not show any on-screen validation messages.

Alternate Invocation

$.validatr.validateElement(element)
.validatr('validateForm', form) Boolean

Returns the validity state of a form (boolean). It will not show any on-screen validation messages.

Alternate Invocation

$.validatr.validateForm(form)

Messages

Error messages in Validatr are meant to mimic the default messages provided by the browser during native validation. Not all browsers use the exact same messaging, though. I chose to use the Chrome messages since Chrome currently has the most support for native form validation.

L10n and Customization

Validatr exposes the messages it uses and makes them available for customization.

Use This is currently only available for field types that are not supported by a browser, future releases will add the ability to override the error messages for natively supported fields as well.

$.validatr.messages = {
    checkbox: 'Please check this box if you want to proceed.',
    color: 'Please enter a color in the format #xxxxxx',
    email: {
        single: 'Please enter an email address.',
        multiple: 'Please enter a comma separated list of email addresses.'
    },
    pattern: 'Please match the requested format.',
    radio: 'Please select one of these options.',
    range: {
        base: 'Please enter a {{type}}',
        overflow: 'Please enter a {{type}} greater than or equal to {{min}}.', 
        overUnder: 'Please enter a {{type}} greater than or equal to {{min}}<br> and less than or equal to {{max}}.',
        invalid: 'Invalid {{type}}',
        underflow: 'Please enter a {{type}} less than or equal to {{max}}.'
    },
    required: 'Please fill out this field.',
    select: 'Please select an item in the list.',
    time: 'Please enter a time in the format hh:mm:ss',
    url: 'Please enter a url.'
}

The range messages are valid for several different input types, including date, number, range, time, etc. When customizing these mssages make sure to include the {{type}}, {{min}}, and {{max}} keys. These will be replaced with the correct values during the validation process.

Custom Tests

Validtr can run any custom validation you want on an element using the data-* attribute. Use the addTest method to create new custom tests. You can optionally include a value for the data-* attribute that you can retreive in your test.

<input type="text" data-customtest>

Callback

function (element) {
    // Validation logic here

    return {
        valid: true/false,
        message: 'Error'
    };
}
Returns

All tests must return an object in the following form:

{
    valid: Boolean,
    message: 'String'
};
Name Type Description
valid Boolean Whether or not the element passes or failed validation.
message String In the case of failed validation the message that will be displayed.

Included Tests

match

This will test if the current element matches the value of a specified element - targeted though the id or name.

<input type="date" data-match="name-or-id">

as

Accepts a text element to be tested as any other type of element. The value of the attribute is the type of test you want run, such as date or number.

<input type="text" data-as="date">