Fork me on GitHub

nextVal Download | Usage | Reference | Examples

Download nextVal

PLAID

nextVal is an easy-to-use, flexible and robust form validation plugin for jQuery.
Behold, the awesome.

Current version: 1.7.5

Usage

Form Markup

Each input should have a validate attribute. Elements can also have placeholder and title attributes.

<input type="text" validate="email" placeholder="Please enter a proper email address" />

The validate attribute can be passed multiple values, such as:

<input type="text" validate="email isempty" />

Options for the validate attribute and each respective default error message:

Calling nextVal

It's easy to tell nextVal to validate a form. The below example would validate a form with the name "contact" and would use a summary of error messages instead of inline error messages, and the error message summary would use the content from the title attributes of form elements instead of the default error message text.

$(function() {
   $('form[name=CONTACT]').nextVal({
      useInline:false,
      useSummary:true,
      useTitles:true,
   });
});

The below function would add custom rules for ensuring the password fields match and the xheader content is valid.

$(function() {
   $('form[name=FORMNAME]').nextVal({
      customRules:[
         ['matchpassword',function($o){return !($o.val() == $('#password').val());},''],
         ['xheader',function($o){return !$o.val().match(/^X-[a-zA-Z0-9_\-]+$/);},'Please enter a valid xheader. For example X-UserData1'],
      ]
   });
});

If you're using another plugin that interacts with your form, it's easy to validate that custom functionality. For example, if you have a plugin that tests password strength, you can use nextVal to display a custom error message based on the other plugin's results:

$(function() {
   $('form[name=FORMNAME]').nextVal({
      customRules:[
         ['strongpassword',function($o){var t = $('#userform .password_strength').text();return (t == '' || t == 'Too weak' || t == 'Very weak' || t == 'Weak');},''],
      ]
   });
});

Reference

Error message appearance

useSummary
Defaults to false.
When true, useSummary will collect all of the error messages upon form submission and display them to the user. Use with validationTag to determine the markup of the collected error messages. Use with useTitles to customize the summary content.
useInline
Defaults to true.
When true, useInline will show inline error messages when an element fails validation. This error message placement will show on form submission and may also show on blur, if onBlur is set to true.
useStyles
Defaults to true.
When true, the form elements will have classes applied to them (such as placeholderStyle, passedStyle, and failedStyle). This makes it easy to style each kind of validated input.
styleParent
Defaults to false.
When true, validation classes will be added to the parent of a form element that is being validated.
summaryStyle
Defaults to 'validation-summary'.
This is the class that is applied to the summary of error messages that appears if useSummary is set to true.
messageStyle
Defaults to 'validation-message'.
This is the class that is applied to the individual error messages that appear if useInline is set to true.

Form field appearance

placeholderStyle
Defaults to 'validation-placeholder'.
This class gets added to the input element when the placeholder text is displayed if your browser does not support placeholders.
passedStyle
Defaults to 'validation-passed'.
This class gets added to a form element if the user's entry passes validation.
failedStyle
Defaults to 'validation-failed'.
This class gets added to a form element if the user's entry fails validation.
ignoreFieldClass
Defaults to 'validation-ignore'.
nextVal will ignore this element when validating the form. This can be helpful if you need to add extra

Error message content

useTitles
Defaults to false.
When set to true, the content in the title attribute of the input field will display in the error message summary. When set to false, the default error message content for that type of field will be used in the summary. Be sure to set useSummary to true.
useErrorText
Defaults to true.
If set to true and the errorText attribute is on the input field, the errorText will be displayed as the inline error message instead of title attribute's content. If you use inline messages and the summary of error messages, the summary will still use the default text or the title attribute content if you have useTitles set to true.
summaryId
Defaults to 'vsummary-'.
Defines the prefix of the ID name applied to the element containing the summary of the error messages. This will auto-increment so the summary will be associated with the correct form in case you have more than one form on a page..
messageId
Defaults to 'vmessage-'.
Defines the prefix of the ID name applied to each error message.
validationTag
Defaults to 'ul'.
Determines the HTML element that contains each error message. If ul is used, each error message will be in a li. The summary of error messages will be contained in a ul. If a div is used, each error message will be wrapped in a div.
submitButton
Defaults to ''
Enter a value for submitButton when you are using an element for form submission that is not a submit button input type. This value could be any valid jQuery selector.

Validation Interactions

formCallback
Defaults to function(r){return r;}.
formCallback fires on form submittion after the validation is completed. It gets passed a boolian value; this reutrns true if the form passed and false if it failed
itemCallback
Defaults to function(r){return r;}.
itemCallback functions the same way that formCallback functions, but fires after every item's validation is completed.
onCall
Defaults to function() {return true;}.
onCall occurs when the form submission happens. Before anything is validated with that function you need to return a boolian - true to continue validating, or false to stop.
onBlur
Defaults to false.
When set to true, form will validate a field upon an onblur event (the field losing focus). Use this in conjunction with to trigger inline validation messages as a user fills out your form.

Form Interactions

placeholder
Defaults to true.
If false, older browsers that don't understand the placeholder attribute won't receive additional javascript hooks needed to display the placeholder text.
attach
Defaults to 'top'.
Choose which side of the form to append an error message summary to. You can use top, bottom, custom or any jQuery selector. If you use custom, nextVal looks for an attach attribute on the element being validated for a jQuery selector.
attachInline
Defaults to 'bottom'.
Choose which side of an input field to append an individual error message to. You can use top, bottom, custom or any jQuery selector. If you use custom, nextVal looks for an attach attribute on the element being validated for a jQuery selector.

Custom Validation Rules

customRules
Defaults to Array().
Create your own custom rule with this syntax: Array(Array(NAME, COMPARE FUNCTION, DEFAULT MESSAGE), ... )

Examples

My Basic Login Form



My Basic Styled Login Form

This form uses the validation-passed and validation-failed classes to style the input boxes.



My Custom Error Summary

This example uses custom text for the error message summary and default inline error message text.



My Custom Inline Errors

This example uses custom text for the inline error messages. It also uses styled spans instead of the default list item style.



My Multiple Rules

This example uses multiple rules on a single field.



My Custom Rules

This example uses a custom error rule.


My Basic On Blur And Form Callback Login Form

This form uses the on blur and a form callback event.



Written by John Norton • Documented by Lara Swanson
© 2011