Copyright (c) 2014, Michael Eisenbraun
Created: 2014-02-05
Updated: 2014-02-05 change log

Guardian 1.0

Guardian is a all-purpose form validation jQuery plugin. It was designed to be flexible and easy to extend to meet any need.

Installation

JavaScript

Include the jQuery Library 1.7 or later and the Guardian Plugin File:

  					
  					

Initialize Guardian:

		          $(document).ready(function() {
		              $('#example').guardian();
		          });
		          

CSS (optional)

HTML

A form tag must be included and all inputs must be within the form. In Guardian now the novalidate attribute is added to the form tag during initialization. This attribute prevents the browser's native validation from activating.

Guardian uses input attributes to determine which inputs to validate and how to validate them, see Input Attributes for more information.

 
					

Input Attributes

Each input that needs to be validated may include the following attributes, depending on whether the input is required and how the input value should be validated.

Options

Guardian has made it easy to customize and extend the plugin.

There two types of options, variables and functions. Variables are used to store class names and string data, where as functions allow for the functionality of the plugin to be extended or customize it for your specific needs. For examples on extending the Guardian, see Extending.

            $(document).ready(function() {
              $('#contactForm').guardian({
                invalid:'my-invalid-class',
                failure: function() {
                  $('#contactForm').prepend('There are '+this.getInvalid().length+ ' invalid fields.'); 
                }
              });
            });
          

Grouping

Grouping is a means of validating multiple inputs as one. Meaning that all inputs must valid for the group to be valid. Grouping could also be used to set a specific element to receive the state classes. All group data is stored within the Global Object in the $groups object. Groups are adding automatically during initialization.

To use grouping, the data-group-name, the data-group-members and id attributes must be added to a parent tag. The following is example of input grouping

            


Checkbox grouping is slightly different in respects, the parent has optional data-group-min and data-group-max attributes and checkbox groups will appear in the $inputs object as one group, whereas input grouping show each individual input.

The following is an example of checkbox grouping.

            

Matching

Matching is a used to confirm that the value of one inputs matches that of another. This would commonly be used to confirm an email address or password.

The following HTML is an example of how to use matching.

            

Extending

The following is a few commons ways to extend Guardian.

Global Object

The major difference between version 2 and version 3 is the introduction of the Global Object. All objects, arrays, methods and variables are available through the Global Object.

The Global Object is accessible from any settings function (e.g. extend) through the this variable, as shown below.

              $('#contactForm').guardian({ extend: function() { console.log(this); } });

The guardian function also returns the Global Object making it possible to access the methods and variables outside of the validate invocation.

              var guardian = $('#contactForm').guardian(); console.log(guardian); 

Global Object:$pattern

$patterns is an object of regular expressions used the validation of input value. The name of each pattern can be used in the value of the data-pattern attribute. The following is a list of the patterns found in the $patterns object. Additional patterns maybe add using the addPatterns(obj) method.

For security reasons, text inputs and textareas that have no pattern attribute, but are required or have a value are validated using alphaNum.

Global Object: $status

$status is used to monitor the current status of the form based on the user action.

Global Object: Other Objects

The following are additional objects within the Global Object.

Global Object: Input Category Arrays

Input Category Arrays are used to categorize inputs based on type or data-pattern. Additional types can be added to any category by using addInputTypes(obj) method.

Global Object: Methods

The following are methods intended for public use within any setting function (e.g. extend) through the this parameter.

Global Object: Other Methods

Global Object: Settings

The following are the intended variables to be updated through the guardian invocation.

Change Log

Version 1.0.0

Feb. 5, 2014