- Download
- Blog
- Docs
- Talk
- Labs
- Code

# FormCheck

Performs different tests on forms and indicates errors.

#### Usage

Works with these types of fields :

- input (text, radio, checkbox)
- textarea
- select

You just need to add a specific class to each fields you want to check. For example, if you add the class

>     validate['required','length[4, -1]','differs[email]','digit']

the value’s field must be set (required) with a minimum length of four chars (4, -1), must differs of the input named email (differs[email]), and must be digit.

You can perform check during the datas entry or on the submit action, shows errors as tips or in a div before or after the field, show errors one by one or all together, show a list of all errors at the top of the form, localize error messages, add new regex check, ...

The layout is design only with css. Now I added a hack to use transparent png with IE6, so you can use png images in formcheck.css (works only for theme, so the file must be named formcheck.css). It can also works with multiple forms on a single html page. The class supports now internationalization. To use it, simply specify a new <script> element in your html head, like this : <script type=”text/javascript” src=”formcheck/lang/fr.js”></script>.

If you add the class

>     validate['submit']

to an element like an anchor (or anything else), this element will act as a submit button.

N.B. : you must load the language script before the formcheck and this method overpass the old way. You can create new languages following existing ones. You can otherwise still specifiy the alerts’ strings when you initialize the Class, with options. If you don’t use a language script, the alert will be displayed in english.

#### Test type

You can perform various test on fields by addind them to the validate class. Be careful to not use space chars. Here is the list of them.

required | The field becomes required. This is a regex, you can change it with class options.
alpha | The value is restricted to alphabetic chars. This is a regex, you can change it with class options.
alphanum | The value is restricted to alphanumeric characters only. This is a regex, you can change it with class options.
nodigit | The field doesn’t accept digit chars. This is a regex, you can change it with class options.
digit | The value is restricted to digit (no floating point number) chars, you can pass two arguments (f.e. digit[21,65]) to limit the number between them. Use -1 as second argument to not set a maximum.
number | The value is restricted to number, including floating point number. This is a regex, you can change it with class options.
email | The value is restricted to valid email. This is a regex, you can change it with class options.
phone | The value is restricted to phone chars. This is a regex, you can change it with class options.
url: | The value is restricted to url. This is a regex, you can change it with class options.
confirm | The value has to be the same as the one passed in argument. f.e. confirm[password].
differs | The value has to be diferent as the one passed in argument. f.e. differs[user].
length | The value length is restricted by argument (f.e. length[6,10]). Use -1 as second argument to not set a maximum.

You can also use a custom function to check a field. For example, if you have a field with class

>     validate['required','%customCheck']

the function customCheck(el) will be called to validate the field. ‘%customcheck’ works with other validate(s) together, and ‘~customcheck’ works if the element past the other validate(s). Here is an example of what customCheck could look :

>     function customCheck(el){
>         if (!el.value.test(/^[A-Z]/)) {
>             el.errors.push("Username should begin with an uppercase letter");
>             return false;
>         } else {
>             return true;
>         }
>     }

It is now possible to register new fields after a new FormCheck call by using FormCheck::register (see <FormCheck::dispose> too).

#### Parameters

When you initialize the class with addEvent, you can set some options. If you want to modify regex, you must do it in a hash, like for display or alert. You can also add new regex check method by adding the regex and an alert with the same name.

#### Required

form_id | The id of the formular. This is required.

#### Optional

submitByAjax | you can set this to true if you want to submit your form with ajax. You should use provided events to handle the ajax request (see below). By default it is false.
ajaxResponseDiv | id of element to inject ajax response into (can also use onAjaxSuccess). By default it is false.
ajaxEvalScripts | use evalScripts in the Request response. Can be true or false, by default it is false.
onAjaxRequest | Function to fire when the Request event starts.
onAjaxSuccess | Function to fire when the Request receives . Args: response [the request response] - see Mootools docs for Request.onSuccess.
onAjaxFailure | Function to fire if the Request fails.
tipsClass | The class to apply to tipboxes’ errors. By default it is ‘fc-tbx’.
errorClass | The class to apply to alertbox (not tips). By default it is ‘fc-error’.
fieldErrorClass | The class to apply to fields with errors, except for radios. You should also turn on options.addClassErrorToField. By default it is ‘fc-field-error’
trimValue | If set to true, strip whitespace (or other characters) from the beginning and end of values. By default it is false.
validateDisabled | If set to true, disabled input will be validated too, otherwise not.

#### Display

This is a hash of display settings. in here you can modify.

showErrors | 0 : onSubmit, 1 : onSubmit & onBlur, by default it is 1.
titlesInsteadNames | 0 : When you do a check using differs or confirm, it takes the field name for the alert. If it’s set to 1, it will use the title instead of the name.
errorsLocation | 1 : tips, 2 : before, 3 : after, by default it is 1.
indicateErrors | 0 : none, 1 : one by one, 2 : all, by default it is 1.
indicateErrorsInit | 0 : determine if the form must be checked on initialize. Could be usefull to force the user to update fields that don’t validate.
keepFocusOnError | 0 : normal behaviour, 1 : the current field keep the focus as it remain errors. By default it is 0.
checkValueIfEmpty | 0 : When you leave a field and you have set the showErrors option to 1, the value is tested only if a value has been set. 1 : The value is tested in any case. By default it is 1.
addClassErrorToField | 0 : no class is added to the field, 1 : the options.fieldErrorClass is added to the field with an error (except for radio). By default it is 0.
fixPngForIe | 0 : do nothing, 1 : fix png alpha for IE6 in formcheck.css. By default it is 1.
replaceTipsEffect | 0 : No effect on tips replace when we resize the broswer, 1: tween transition on browser resize;
closeTipsButton | 0 : the close button of the tipbox is hidden, 1 : the close button of the tipbox is visible. By default it is 1.
flashTips | 0 : normal behaviour, 1 : the tipbox “flash” (disappear and reappear) if errors remain when the form is submitted. By default it is 0.
tipsPosition | ’right’ : the tips box is placed on the right part of the field, ‘left’ to place it on the left part. By default it is ‘right’.
tipsOffsetX | Horizontal position of the tips box (margin-left), , by default it is 100 (px).
tipsOffsetY | Vertical position of the tips box (margin-bottom), , by default it is -10 (px).
listErrorsAtTop | List all errors at the top of the form, , by default it is false.
scrollToFirst | Smooth scroll the page to first error and focus on it, by default it is true.
fadeDuration | Transition duration (in ms), by default it is 300.

#### Alerts

This is a hash of alerts settings. in here you can modify strings to localize or wathever else. %0 and %1 represent the argument.

required | ”This field is required.”
alpha | ”This field accepts alphabetic characters only.”
alphanum | ”This field accepts alphanumeric characters only.”
nodigit | ”No digits are accepted.”
digit | ”Please enter a valid integer.”
digitmin | ”The number must be at least %0”
digitltd | ”The value must be between %0 and %1”
number | ”Please enter a valid number.”
email | ”Please enter a valid email: <br /><span>E.g. email target=”yourname@domain.com” name=”yourname@domain.com”</span>”
phone | ”Please enter a valid phone.”
url | ”Please enter a valid url: <br /><span>E.g. url target=”http://www.domain.com” name=”http://www.domain.com”</span>”
confirm | ”This field is different from %0”
differs | ”This value must be different of %0”
length_str | ”The length is incorrect, it must be between %0 and %1”
length_fix | ”The length is incorrect, it must be exactly %0 characters”
lengthmax | ”The length is incorrect, it must be at max %0”
lengthmin | ”The length is incorrect, it must be at least %0”
checkbox | ”Please check the box”
radios | ”Please select a radio”
select | ”Please choose a value”

#### Example

You can initialize a formcheck (no scroll, custom classes and alert) by adding for example this in your html head this code :

>     <script type="text/javascript">

>         window.addEvent('domready', function() {
>             var myCheck = new FormCheck('form_id', {
>                 tipsClass : 'tips_box',
>                 display : {
>                     scrollToFirst : false
>                 },
>                 alerts : {
>                     required : 'This field is ablolutely required! Please enter a value'
>                 }
>             })
>         });
>     </script>

#### About

formcheck.js v.1.4.1 for mootools v1.2 | 12 / 2008

by Floor SA (http://www.floor.ch) MIT-style license

Created by Luca Pillonel, last modified by Luca Pillonel

#### Credits

This class was inspired by fValidator by Fabio Zendhi Nagao (http://zend.lojcomm.com.br)

Thanks to oneZ, Blots, huughelmink, chdeliens, and everyone who contribute to this project...

Summary

FormCheck | Performs different tests on forms and indicates errors.
Functions |
initialize | Constructor
register | Allows you to declare afterward new fields to the formcheck, to check dynamically loaded fields for example.
dispose | Allows you to remove a declared field from formCheck
addListener | Private method
validate | Private method
simpleValidate | Private method
validateRegex | Private method
validateConfirm | Private method
validateDiffers | Private method
isChildType | Private method
validateGroup | Private method
listErrorsAtTop | Private method
manageError | Private method
addError | Private method
addPositionEvent | Update tips position after a browser resize
removeError | Private method
focusOnError | Private method
fixIeStuffs | Private method
makeTips | Private method
reinitialize | Private method
submitByAjax | Private method
onSubmit | Private method

### Functions

### initialize

> initialize : function( | form,
> | options | )

Constructor

Add event on formular and perform some stuff, you now, like settings, ...

### register

> register : function( | el | )

Allows you to declare afterward new fields to the formcheck, to check dynamically loaded fields for example.

#### Example

>     <script type="text/javascript">

>         window.addEvent('domready', function() {
>             formcheck = new FormCheck('form_id');
>         });

>         // ...some code...

>         var newField = new Element('input', {
>             class   : "validate['required']",
>             name    : "new-field"
>         }).inject('form_id');
>         formcheck.register(newField);

>         new Element('input', {
>             class   : "validate['required']",
>             name    : "another-field",
>             id      : "another-field"
>         }).inject('form_id');
>         formcheck.register($('another-field'));
>     </script>

#### See also

FormCheck::dispose

### dispose

> dispose : function( | element | )

Allows you to remove a declared field from formCheck

#### Example

>     <script type="text/javascript">
>         window.addEvent('domready', function() {
>             formcheck = new FormCheck('form_id');
>         });

>         // ...some code...

>         formcheck.dispose($('obsolete-field'));
>     </script>

#### See also

FormCheck::register

### addListener

> addListener : function( | el | )

Private method

Add listener on fields

### validate

> validate : function( | el | )

Private method

Dispatch check to other methods

### simpleValidate

> simpleValidate : function( | el | )

Private method

Perform simple check for select fields and checkboxes

### validateRegex

> validateRegex : function( | el,
> | ruleMethod,
> | ruleArgs | )

Private method

Perform regex validations

### validateConfirm

> validateConfirm: function( | el,
> | ruleArgs | )

Private method

Perform confirm validations

### validateDiffers

> validateDiffers: function( | el,
> | ruleArgs | )

Private method

Perform differs validations

### isChildType

> isChildType: function( | el | )

Private method

Determine if the field is a group of radio or not.

### validateGroup

> validateGroup : function( | el | )

Private method

Perform radios validations

### listErrorsAtTop

> listErrorsAtTop : function( | obj | )

Private method

Display errors

### manageError

> manageError : function( | el,
> | method | )

Private method

Manage display of errors boxes

### addError

> addError : function( | obj | )

Private method

Add error message

### addPositionEvent

> addPositionEvent : function( | obj | )

Update tips position after a browser resize

### removeError

> removeError : function( | obj | )

Private method

Remove the error display

### focusOnError

> focusOnError : function ( | obj | )

Private method

Create set the focus to the first field with an error if needed

### fixIeStuffs

> fixIeStuffs : function ()

Private method

Fix png for IE6

### makeTips

> makeTips : function( | txt | )

Private method

Create tips boxes

### reinitialize

> reinitialize: function()

Private method

Reinitialize form before submit check

### submitByAjax

> submitByAjax: function()

Private method

Send the form by ajax, and replace the form with response

### onSubmit

> onSubmit: function( | event | )

Private method

Perform check on submit action

> initialize : function( | form,
> | options | )

Constructor

> register : function( | el | )

Allows you to declare afterward new fields to the formcheck, to check dynamically loaded fields for example.

> dispose : function( | element | )

Allows you to remove a declared field from formCheck

> addListener : function( | el | )

Private method

> validate : function( | el | )

Private method

> simpleValidate : function( | el | )

Private method

> validateRegex : function( | el,
> | ruleMethod,
> | ruleArgs | )

Private method

> validateConfirm: function( | el,
> | ruleArgs | )

Private method

> validateDiffers: function( | el,
> | ruleArgs | )

Private method

> isChildType: function( | el | )

Private method

> validateGroup : function( | el | )

Private method

> listErrorsAtTop : function( | obj | )

Private method

> manageError : function( | el,
> | method | )

Private method

> addError : function( | obj | )

Private method

> addPositionEvent : function( | obj | )

Update tips position after a browser resize

> removeError : function( | obj | )

Private method

> focusOnError : function ( | obj | )

Private method

> fixIeStuffs : function ()

Private method

> makeTips : function( | txt | )

Private method

> reinitialize: function()

Private method

> submitByAjax: function()

Private method

> onSubmit: function( | event | )

Private method
Close