Basic Usage - mosbymc/validator GitHub Wiki

##Basic usage: validator.js runs off of data attributes and classes, so no programming is required unless you want to have a custom validation rule. As such, you'll need to include the file "validator.css" in your website. This css file contains class definitions for the various classes that the validator uses. "validator.css" contains only the basic/required level of styling that is required by the validator for functionality and appearence of injected DOM elements.

You'll find you will want to include additional styling with the validator classes. For instance, the "invalid" class is placed on any input that fails to pass validation. In order to show to the user that the input failed validation, you may want to add a red border to all inputs with the "invalid" class. Feel free to add as much styling to each class definition as you wish, but do not remove any of the pre-existing styling as this will affect the apparent functionality of the validator. The css file is commented for each class to let you know what it's used for within the validator. There is also a wiki page that covers the various classes used that you can reference when adding styles.

Validating both the form and input level require many of the same attributes and classes, but there are a few distinctions.

###Form validation: To use the basic form validation, you do not actually need a form surrounding the input elements; any common parent element like a div or fieldset will work just as well. There is a difference between how a true form calls it's success function and how any other element you're using in lieu of a form calls its success function, which is detailed below. The parent element needs only one class to be validated: “formValidate”. Although there are additional options that can be supplied (which will be covered later), this is the only class necessary for basic usage. Putting the validate class on the parent element allows the user to remove the class from one or all forms on the page and effectively turn off validation dynamically since the validator won’t work on any form that doesn’t have this class.

    <fieldset class="formValidate">
    or
    <form class="formValidate" >

Any inputs inside the parent element that should be validated against the validator’s internal library of validation rules needs a “data-validationrules” attribute. This value should be a comma delimited list of the validation rules to test against that input. The data-validationrules attribute uses a library of validation rules to test the value of the input. As an example, if you have an email input, then the attribute should be set as “data-validationrules= email’”. If the email input is also a required field, add an attribute called “data-required” and the validator will check for input too.

    <input type="text" data-required data-validationrules='zip' />

The data-required attribute will work for text inputs, drop-down inputs as long as the default value is an empty string or a string of whitespaces. It will also work for radio button groups to ensure an option has been selected. There are a few other basic validation rules that the validator provides. They are discussed in more detail on the wiki page linked above.

When validating an input, if it is a required field, and it fails the required validation, no other rules will be tested against that particular input. Only if the field passes the required validation or if it isn't a required field will the remaining rules be tested.

If you don’t want to use the library of validation rules or have a need to write your own rule, you can do that with the “data-customrules” attribute which is covered in its own wiki page.

Finally, for the form to take action when validated, if it isn't a true form element, an attribute called “data-formaction” is used on the parent element. The value should be set to a string name of your success function. For instance, if you want to make an AJAX call to the controller with the contents of the form on successful validation, and you named that AJAX function “formSubmit()”, then the data-formaction attribute should be set to “formSubmit” – no open/close parentheses. After validation occurs, if all input elements passed validation, then the formSubmit() function is called.

    <fieldset class="formValidate" data-formaction="formSubmit">

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

    <fieldset class="formValidate" data-formaction="objectNamespace.formSubmit">

Note that the validator will be able to find and execute any namespaced function only as long as it is "publicly" accessible.

If you are using a true form element, then you don't need any data-attribute placed on the form for it to take action on successful validation. Just use the "action" property like you normally would and it will fire when the form has no errors.

    <form method="POST" action="/validator/submitform" enctype="application/x-www-form-urlencoded" class="formValidate">

###Input Validation: Validating a single input is similar to validating a form, except all attributes and classes are put on the input itself and it is tested against the input event by default unless you pass in another event for the validator to listen for. In this case, the input requires a class called “inputValidate”. As in form validation, if you want to turn validation off for an input, simply remove the inputValidate class and it will not be tested.

    <input type="text" data-validationrules="name" class="inputValidate"/>

The input also requires the same data-type attribute as a form input requires and it is used in the same way. Supply a comma delimited list of the validation rules to test against, and on each input event for that element, it will be tested against whichever rules were specified. If multiple validation rules are specified, beyond required, and the input fails several of them, the error messages for each failed rule will be displayed.

    <fieldset class="formValidate" data-formaction="submitThisForm">
       <legend>Basic Form Validation</legend>
       <dl align='left'>
          <input type='text' data-required data-validationrules="phone"/>
          <input type='text' data-required data-validationrules="name"/>
          <input type="text" data-required data-validationrules="phone"/>
          <input type="text" data-required data-validationrules='email'/>
          <input type="text" data-required data-validationrules="password"/>
          <input type="text" data-errorprefix="Password" data-required/>
          <input type="submit" value="Submit" class="validate"/>
       </dl>
    </fieldset>

    <fieldset id="formValidate">
       <form action="/validator/submitform" id="testForm" class="formValidate hover">
          <legend>Basic Form Validation</legend>
          <dl align='left'>
             <input type='text' data-required data-type="phone"/>
             <input type='text' data-required data-type="name"/>
             <input type="text" data-required data-type="phone"/>
             <input type="text" data-type="phone"/>
             <input type="text" data-required data-type='zip' />
             <input type="text" data-required data-type='email'/>
             <input type="text" data-required/>
             <input type="submit" value="Submit" class="validate"/></dt>
          </dl>
       </form>
    </fieldset>

Continue to: Error Message Display Options