Validatr

/ API

Cross Browser HTML5 Form Validation.

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">