:: jeffemminger.com

jValX

Notice:

2006-06-05: removed default invalid field highlighting - you now must specify a css class of "jvalx-invalid-field" and/or "jvalx-invalid-label" to have formatting applied to fields and labels respectively
2006-02-09: change to the signatures of jvalOverride() and jvalReset() is not backwards-compatible - you must pass the form to these methods now. See additional notes

about
download/install
configuring
config attributes
config dataTypes
additional notes
demo

topwhat is jValX?

jValX is an easy way to simplify your client-side form validation, and is all XHTML 1.0 STRICT markup.

topinstall in four easy steps:

download jvalx.js by right-clicking here and choosing "Save as..." or "Save Link to Disk"
include it on your page like so: <script type="text/javascript" src="jvalx.js"></script>
add a "config" comment node adjacent to each form field (see examples below, additional details provided in jvalx.js)
add onsubmit="jValidate(this);" to your <form> tag.

you're done!

the config nodes can even come before the element. just be sure to nest them properly, i.e.
<field1> <field2>
will work, but
<field1> <field2>
will not.

topcreating config nodes:

setting up your config nodes is easy! they're really just HTML comments with some custom attributes added. only the for attribute is mandatory - this maps the config node to it's respective form field. all other config node attributes are optional.

topconfig node attributes:

attribute	value	description
`for`	string	the name of the input field this config node is for (this attribute is mandatory)
`condition`	any valid javascript	the condition to test for when required="conditional". the result of the condition determines if the field is required or not. (true=required)
`constraint`	any valid javascript that evaluates to or returns boolean	optional additional validation logic to be evaluated onsubmit. simply add code or a function that returns boolean, true meaning valid input. (see the "select with constraint" in the demo form below)
`constraintErrorMsg`	string	when a constraint is present, the error message to be displayed (if any) if the input's value fails constraint validation. if omitted, defaults to value of `errorMsg`
`dataType`	any valid dataType name	determines what type of input the field should accept
`errorMsg`	string	the error message to be displayed (if any) if the input's value fails validation. if omitted, defaults to "Please enter a valid value."
`equalOk`	`true\|false`	if dataType="dateRange", whether or not the two dates can be equal, default is false
`firstOk`	`true\|false`	if dataType="select" and required="true", whether or not the first option is an acceptable choice. e.g. if the first option is "Please Choose", then firstOk="false" would prevent this option from being selected. default is false.
`lenient`	`true\|false`	if dataType="decimal", whether or not to allow integers. defaults to `false` if omitted.
`lowerElement`	string	if dataType="dateRange", the name of the form element representing the upper date.
`max`	numeric	maximum numeric value or text length of the input's value, depending on it's dataType
`min`	numeric	minimum numeric value or text length of the input's value, depending on it's dataType
`regex`	any valid regular expression, minus the opening and closing regex delimiters "/"	a regular expression to test the input's value against. NOTE: opening and closing regex delimiters "/" are not necessary, and will be removed if present.
`regexIgnoreCase`	`true\|false`	when the `regex` attribute is present, whether it should be case-insensitive or not.
`required`	`true\|false\|conditional`	whether or not the input must be given a value, default is false
`upperElement`	string	if dataType="dateRange", the name of the form element representing the lower date.

topdataTypes:

dataType	description
alpha	the field will accept any letter, space, hyphen or underscore as input
date	the field will accept U.S. format date: MM/DD/YYYY as input
decimal	the field will accept any decimal as input
email	the field will accept any valid email format as input
integer	the field will accept any integer as input
phone	the field will accept U.S. format phone: x-xxx-xxx-xxxx as input
text	the field will accept any character as input
[null]	dataType attribute may be left blank or omitted altogether, and jValX will default to dataType "text"

topadditional notes:

multiple form submissions: by default, jValX prevents your form from submitting again upon successful validation. if you wish to override this, simply pass true as the second argument to jValidate() in your form tag.

jValidate()'s signature is: jValidate(objectForm[, booleanAllowMultipleSubmissions]), and booleanAllowMultipleSubmissions defaults to false if omitted.
jvalReset(this.form): calling jvalReset(this.form) after successful validation will also re-enable submission.
jvalOverride(this.form);: If you have a Cancel button on your form that is of type="submit", you can abort the form's validation by attaching jvalOverride(this.form); to the button's onclick handler, e.g. <input type="submit" value="Cancel" onclick="jvalOverride(this.form);" />.
radios, checkboxes, etc: groups of elements with the same name need only one config node, provided that the validation rules are the same for all elements in the group. (see the "Pizza" radio group in the demo form below.)

topdemo form:

use the demo form below to watch jValX in action, and to see how easy it is to configure! (example config comment nodes are in green)

<form
  action="javascript:alert('Validation successful');"
  method="get"
  onsubmit="return jValidate(this, true);">

alpha:

<input type="text"
	name="text1"/><!--
	for="text1"
	required="true"
	min="3"
	max="5"
	dataType="alpha"
	regex="^C"
	regexIgnoreCase="false"
	errorMsg="Three to five letters
		beginning with capital \"C\", please." -->

date range:

<input type="text"
	name="date1"
	size="10"/><!--
	for="date1"
	required="true"
	dataType="date"
	upperElement="date2"
	equalOk="false"
	errorMsg="Enter a lower date." -->
<input type="text"
	name="date2"
	size="10"/><!--
	for="date2"
	required="true"
	dataType="date"
	lowerElement="date1"
	equalOk="false"
	errorMsg="Enter an upper date." -->

decimal:

<input type="text"
	name="dec1"/><!--
	for="dec1"
	required="true"
	min="1.1"
	max="2.2"
	dataType="decimal"
	errorMsg="Enter a decimal between 1.1 and 2.2"  -->

email:

<input type="text"
	name="email1"/><!--
	for="email1"
	required="conditional"
	condition="this.form.dec1.value > 1.5"
	dataType="email"
	errorMsg="Please enter a valid email address." -->

integer:

<input type="text"
	name="int1"/><!--
	for="int1"
	required="true"
	min="0"
	max="99"
	dataType="integer"
	errorMsg="Enter an integer between 0 and 99." -->

select with constraint:
select a number greater than or equal to the integer above:

<select name="sel2"
	size="1">
	<option value="-1">Select:</option>
	<option value="0">0</option>
	<option value="1">1</option>
	<option value="2">2</option>
	<option value="3">3</option>
	<option value="4">4</option>
	<option value="5">5</option>
	<option value="6">6</option>
	<option value="7">7</option>
	<option value="8">8</option>
	<option value="9">9</option>
</select>
<!--
	for="sel2"
	required="true"
	constraint="isGteInteger(this, this.form.int1.value)"
	firstOk="false"
	errorMsg="Please select a number."
	constraintErrorMsg="Must be greater than
		or equal to the integer above."
-->

<script type="text/javascript">
function isGteInteger(sel, x) {
	return (sel.options[sel.selectedIndex].value >= x);
}
</script>

required checkbox:
I agree to check this box before proceeding.

<input type="checkbox"
  name="iAgree"
  id="iAgree"/><!--
  for="iAgree"
  required="true"
  errorMsg="You must check \"I agree to
  	check this box before proceeding.\"" -->
<label for="iAgree">
	I agree to check this box before proceeding.
</label>

checkbox:
check me to require a Pizza choice below

<input type="checkbox"
  name="requirePizza"
  id="requirePizza"/>
<label for="requirePizza">
check me to require a Pizza choice below
</label>

conditional radio:
Pizza? Love it Hate it

<input type="radio"
	name="pizza"
	id="pizzaLove"
	value="love"/>
<label for="pizzaLove">Love it</label>
<input type="radio"
	name="pizza"
	id="pizzaHate"
	value="hate"/>
<label for="pizzaHate">Hate it</label>
<!--
	for="pizza"
	required="conditional"
	condition="this.form.requirePizza.checked"
	errorMsg="Please make a choice for Pizza." -->

phone:

<input type="text"
	name="phone1"/><!--
	for="phone1"
	required="true"
	dataType="phone"
	errorMsg="US-format phone: xxx-xxx-xxxx" -->

select:

<select name="sel1"
	size="1"/>
	<option>choose:</option>
	<option>a</option>
	<option>b</option>
</select>
<!--
	for="sel1"
	required="true"
	firstOk="false"
	errorMsg="Select something!"
-->

multiple dataType:

<input type="text"
	name="foo" /><!--
	for="foo"
	required="true"
	dataType="email,phone,decimal"
	errorMsg="email, phone, or decimal please!" -->

required group (all required):
Phone:

<input type="text"
  name="phone"
  size="3"
  maxlength="3" /><!--
  for="phone"
  required="true"
  regex="^\d{3}$"
  errorMsg="Please enter a valid Phone." -->
<input type="text"
  name="phone"
  size="3"
  maxlength="3" /><!--
  for="phone"
  required="true"
  regex="^\d{3}$"
  errorMsg="Please enter a valid Phone." -->
<input type="text"
  name="phone"
  size="4"
  maxlength="4" /><!--
  for="phone"
  required="true"
  regex="^\d{4}$"
  errorMsg="Please enter a valid Phone." -->

optional group (all or none required):
SSN:

<input type="text"
  name="ssn"
  size="3"
  maxlength="3" /><!--
  for="ssn"
  required="false"
  regex="\d{3}"
  errorMsg="Please enter a valid Social Security Number" -->
<input type="text"
  name="ssn"
  size="2"
  maxlength="2" /><!--
  for="ssn"
  required="false"
  regex="\d{2}"
  errorMsg="Please enter a valid Social Security Number" -->
<input type="text"
  name="ssn"
  size="4"
  maxlength="4" /><!--
  for="ssn"
  required="false"
  regex="\d{4}"
  errorMsg="Please enter a valid Social Security Number" -->