tapestry/src/site/apt/javascript/form-validation.apt

 ------
JavaScript Reference - tapestry.form.validation
 ------
Jesse Kuhnert
 ------
26 July 2006
 ------
 
tapestry.form.validation

  Defines the default client side validation logic which will be invoked by {{{../components/form/form.html}Form}} components
  with the <<<clientValidationEnabled>>> parameter set to true. You can override as little or as much of the default
  logic as you would like.

  The source for <<<tapestry.form.validation>>> can be found {{{http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/form/validation.js?view=markup}here}}. 

  <<See also:>> {{{../usersguide/clientside-validation.html}Client-Side Validation}},  {{{form.html}Form}} JavaScript Reference

* tapestry.form.validation.missingClass

  The default CSS class name that will be applied to input fields with missing values. <(also applies to other field 
  types, like <select> elements)>. 

  The current default value is <<fieldMissing>>.

* tapestry.form.validation.invalidClass

  The default CSS class name that will be applied to input fields with invalid values. <(also applies to other field 
  types, like <select> elements)>. 

  The current default value is <<fieldInvalid>>.

* tapestry.form.validation.validateForm(form, profileProperties)

  Main entry point for running form validation. The props object passed in contains a number of 
  fields that are managed by tapestry.form.

*----------------------*---------------*------------*----------*----------------------------------------------+
  Parameter            |    Type	   |  Required  | Default  | 		Description
*----------------------*---------------*------------*----------*----------------------------------------------+
  form 				   | String element id / HTMLForm node |  yes  |          | The element id of the form, or the form html element itself.
*----------------------*---------------*------------*----------*----------------------------------------------+
  profileProperties    | json          |  no        |          | A properties object containing tapestry specific form information, as well as the dojo {{{form.html}validation profile}}s registered with this form.
*----------------------*---------------*------------*----------*----------------------------------------------+

  <<Returns:>> Boolean - If true then form validation passed and the form should be allowed to 
  						 submit to the server, if false the form submission is cancelled and will not
  						 be posted to the server.

** Example
  
  Sample properties format style used:

+----------------------------------------------------------
props = {
	// whether to run validation at all
	validateForm:[true|false],
	
	// set of dojo.validate.check() style profiles
	// that may have been registered with form
	profiles:[profile1, profile2] 
}
+----------------------------------------------------------

  The individual profiles will contain any of the data described by the dojo documentation 
  for <<<dojo.validate.check(form, profile)>>>. In addition to that, each profile will also have a 
  corresponding string message to display if the specified condition has been met. 
  
  For example, if you have specified that a select field named <<<select1>>> was required your 
  profile would look something like:

+----------------------------------------------------------
profile = {
	"required":["select1"], // normal dojo.validate.check data
	"select1":{ // tapestry field/error type specific data
		"required":"You must select a value for select1."
	 }
}
+----------------------------------------------------------

  It is intended for you to call <<<dojo.validate.check(form, profile)>>> for each profile stored in 
  the <<<profiles>>> field, as well as deciding how to display errors / warnings.

* tapestry.form.validation.processResults(form, results, profile)

  Called for each registered profile on a form after <<<dojo.validate.check()>>> has been called. 
  This function is expected to do UI related notifications of fields in error.

*----------------------*---------------*------------*----------*----------------------------------------------+
  Parameter            |    Type	   |  Required  | Default  | 		Description
*----------------------*---------------*------------*----------*----------------------------------------------+
  form 				   | Form node     |  yes       |          | The form node that was processed.
*----------------------*---------------*------------*----------*----------------------------------------------+
  results              | JSON          |  yes       |          | The result of calling <<<dojo.validate.check(form,profile)>>>.
*----------------------*---------------*------------*----------*----------------------------------------------+
  profile              | JSON          |  yes       |          | The original profile used to validate form, also holds validation error messages to be used for each field.
*----------------------*---------------*------------*----------*----------------------------------------------+

  <<Returns:>> Boolean - If <<<false>>> the form should not be submitted and all validation 
  						 should be stopped. If <<<true>>> validation will continue and eventually 
  						 form will be submitted. <(if no other validation logic fails)>

* tapestry.form.validation.handleMissingField(field, profile)

  Default field decorator for missing fields.

*----------------------*---------------*------------*----------*----------------------------------------------+
  Parameter            |    Type	   |  Required  | Default  | 		Description
*----------------------*---------------*------------*----------*----------------------------------------------+
  field 			   | element id    |  yes       |          | The field element that was missing data.
*----------------------*---------------*------------*----------*----------------------------------------------+
  profile              | JSON          |  yes       |          | The form validation profile.
*----------------------*---------------*------------*----------*----------------------------------------------+

* tapestry.form.validation.handleInvalidField(field, profile)

  Default field decorator for invalid fields.

*----------------------*---------------*------------*----------*----------------------------------------------+
  Parameter            |    Type	   |  Required  | Default  | 		Description
*----------------------*---------------*------------*----------*----------------------------------------------+
  field 			   | element id    |  yes       |          | The field element that had invalid data.
*----------------------*---------------*------------*----------*----------------------------------------------+
  profile              | JSON          |  yes       |          | The form validation profile.
*----------------------*---------------*------------*----------*----------------------------------------------+

* tapestry.form.validation.clearValidationDecorations(field, profileProperties)

  Clears out previous css classes set on fields during previous validation checks. This is called
  by <<<tapestry.form.validation.validateForm>>> just before running validation to ensure that any 
  fields previously decorated with css rules reflect any changes users may have made to make them
  valid during the next validation check.

*----------------------*---------------*------------*----------*----------------------------------------------+
  Parameter            |    Type	   |  Required  | Default  | 		Description
*----------------------*---------------*------------*----------*----------------------------------------------+
  field 			   | element id    |  yes       |          | The field element to clear UI validation decorations on.
*----------------------*---------------*------------*----------*----------------------------------------------+
  profileProperties    | json          |  no        |          | A properties object containing tapestry specific form information, as well as the dojo {{{form.html}validation profile}}s registered with this field's form.
*----------------------*---------------*------------*----------*----------------------------------------------+

* tapestry.form.validation.summarizeErrors(form, results, profile)

  Optionally allows an alert dialog/dhtml dialog/etc to be displayed to user to alert them 
  to the invalid state of their form if validation errors have occurred.

  This function is called by the default Tapestry client side form validation semantics to 
  present a modal summary dialog to the user listing the error messages that indicate why 
  their fields are in error.
  
*----------------------*---------------*------------*----------*----------------------------------------------+
  Parameter            |    Type	   |  Required  | Default  | 		Description
*----------------------*---------------*------------*----------*----------------------------------------------+
 form 				   | Form node     |  yes       |          | The form node that was processed.
*----------------------*---------------*------------*----------*----------------------------------------------+
  results              | JSON          |  yes       |          | The result of calling <<<dojo.validate.check(form,profile)>>>.
*----------------------*---------------*------------*----------*----------------------------------------------+
  profileProperties    | json          |  yes       |          | A properties object containing tapestry specific form information, as well as the dojo {{{form.html}validation profile}}s registered with this field's form.
*----------------------*---------------*------------*----------*----------------------------------------------+

** Example

[../images/UsersGuide/validation-dialog.png] Validation dialog example.