Skip to content
This repository was archived by the owner on Mar 6, 2025. It is now read-only.

Form

Jump to bottom
Felix Nagel edited this page Oct 9, 2013 · 3 revisions

This widget extends a standard HTML form. A live-validation, a validation while typing, checks every field with a configurable regular expression. You could set your own reg-ex or use one of the predefined patterns.

Update

Demo

In this demo every available HTML default form element is used. First text field checks for a valid email address.

Real-Life examples

Contact me to add your project here.

Functionality features

  • works with almost every form element
  • it’s possible to add a custom error (for example a tooltip)
  • AJAX form submitting (incl. file upload) via jQuery Form Plugin
  • configurable self-validation time out
  • a bunch of predefined validation patterns
  • use your preferred CAPTCHA solution
  • standard jQuery widget methods: disable, enable, destroy

File size of the minified version is 12 KB.

Accessibility features

  • Accessible error messages
  • Keyboard support
  • ARIA Live-Regions

Documentation

It’s necessary to add every form field which should be validated in the multidimensional array forms (widget option). The index (here: inputtext) has to be the ID of the element, except for check-boxes and radio-buttons. These elements need a common class attribute instead of an ID.

Within the “ID array” is always a rules and a msg array. If you set a rule you need to define a message for it.


forms: {			
	inputtext: {
		rules: {
			required: true,		
			regEx: "email",
			lengthMin: 5,
			lengthMax: 25
		},
		msg: {
			required: "Necessary field message.",	
			regEx: "RegEx failure message.",
			length: "Length failure message (One for max and min)."
		}
	}
},.

Attention!

  • You should define value=“default” for default options (like “Please choose…”) within a selectbox. Otherwise the rule required won’t work. This string is configurable (options.selectDefault) Please see demo.
  • Remember: check-boxes and radio-buttons need a class; all other form elements need an ID.
  • Hint: you should definde the rules in the same order like its in the html

Rules

Not every rule works with every type of form field:

Rule Type Working field types
required boolean text, textarea, checkbox, radio, select, file
lengthMin number text, textarea, checkbox, radio, select
lengthMax number text, textarea, checkbox, radio, select
equalTo string text, textarea
regEx string text, textarea, file
custom function text, textarea, file

The rule equalTo should be used for passwords fields. The value has to be the ID of the first password field. See demo source code.

Custom check field

This is a very quick fast way to add your own validation function. Thanks to Igor


mycustom: {
	rules: {
		required: false,
		custom:	function (elementValue) {
				return ((elementValue % 2 ) == 0) ? true : false; 
		}
	},
	msg: {
	      custom: "custom error message."
	}
},.

Define a anonymous function which is automatically passed in the value of the form. All your function has to do is returning a boolean value.

Predefined reg-ex patterns

If rule regEx is defined you could use the following predefined patterns as value or use your own expression.

Value Validation Example
number natural numbers 12345
numberDE numbers and comma separated decimal 1,23 oder 123
numberISO numbers and dot separated decimal 1.23 oder 123
email valid email adresse test@domain.de
url valid URL http://www.domain.de
plz valid German postal code 20457
dateDE German date 01.02.09 or 1.2.2009
dateISO international date 2009-02-01 or 2009-2-1
captcha String undefined, fires callback

When the form validates and is submitted…

Server should check the data and return true or an error message. options.submitSuccess or the returned error message is shown. If transfer fails options.submitError is displayed.

Options

There are a few more options to configure this widget:

Option Type Description
forms Array Array of form fields (ID)
validateLive Boolean turn on or off live validation
validateTimeout Number / String time till live validation, use “blur” to validate only on lost focus
validateTimeoutCaptcha String multiplied with validateTimeout when using captcha rule to protect your server from to much load
validateOff String message for disabling live validation
validateOn String message for disabling live validation
errorSummery Boolean / String deactivate error summery, use “onSubmit” for displaying summery when form is submitted
ajaxOptions Object add every &.ajax option you want, make sure to see additional ones of jQuery Form Plugin
submitError String predefined error message
submitSuccess String predefined success message
disabled Boolean disable widget
selectDefault String Define default value when using select options

Callbacks

Use these callbacks to interact with this widget. Take a look in the demo to see how it works!

  • onInit
  • onformSubmitted
  • onValid (executed for every element with corrected input; returns the id of the element)
  • onError (fired for every element with wrong input; returns the id of the element)
  • onErrors (fired once when one or more error exists)
  • customError (see below)
  • onShowErrors (fired every time a validation is done and when form is submitted, if a error exists or not)
  • onShowSuccess (returns true or a possible error message)
  • checkCaptcha (must return a boolean value which determines a correct or incorrect input)

customError

It’s possible to show custom error messages by using this callback which is fired every time an error is found in an element. Basically you get an array containing all the currently validated elements information. Loop this array to access the errors. Please see the demo to see how this works. The demo uses a modified version of the dev version of jQuery UI tooltip, which is slightly ARIA enabled.

This is an example what this array contains:


array
    -> element (contains the jQuery object of the element)
    -> errors (contains current errors and their state)
        -> required = "new" (possible values: old, new, corrected)
        -> lengthMin = "old"
    -> id = "inputfield" (conatins the ID of the element)
    -> msg(contains all aerror messages)
        -> required = "please add a name"
        -> lengthMin = "your input is too short"
    -> rules (contains all error rules)
        -> required = true
        -> lengthMin = 5
    -> type = "single" (contains the type of the element, possible values: single, group (checkbox, radio) and select)
.

Methods

The method formSubmitted submits the form.

  • validate (parameter is the id of an element [string])
  • formSubmitted
  • disable
  • enable
  • destroy

FAQ

Please check the closed and open issues before asking me for help.



How to add a custom error notification?

Please see the custom error demo, provides within the demos.


How to add a field after initialization?

Please take a look at the add_a_field.html file provided within the examples directory.


How enable live-validation AFTER the form was submitted first?

Please take a look at the after_submit.html file provided within the examples directory.


How to implement dependency for form fields

Please take a look at the dependency.html file provided within the examples directory. The example describes how to make input B to be required only if input A has a value.


How to check a form field server side?

This could be useful to check availability of a username or to verify a given email address (check if domain exists via MX lookup). Please take a look at the username_check.html file provided within the examples directory.


This text is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported Licence.

Clone this wiki locally