Validanguage

1. Validating a form with validateForm()
2. Adding and Disabling Validations
3. Manually Failing a Form Field
4. The showSubmitMessage and showFailedFields Options
5. validanguage.settings.onload
6. Transformation: validanguage.toggle()
7. Setting up Ajax Validations with isAjax

Validating a form with validateForm()

Adding and Disabling Validations

Adding Validations

{String} elemId -- The ID of the field to receive the validation.

{String/Array} eventTypes -- A list of event types which should receive the indicated validations.

{String/Array/Function} validationNames --A list of the validation functions to be added. These must match exactly a validation which is listed in the validanguage.el.formField object, including variable type. Thus, when adding a validation which has a supported shortcut in validanguage.el.formField (such as "required" which is a shortcut for "validateRequired") the full function name must be present in validanguage.el.formField. If youwish to load all the validations which are listed in the validanguage.el.formField.validations array, you can use "*" as a shortcut to listing all the validations individually.

<script type="text/javascript">
   //first we add the new field to validanguage.el
   validanguage.el.newDateField = {
      errorMsg: 'You must enter a valid date',
      validations: [
         {
            name: 'validateRequired'
         },
         {
            name: 'validateDate'
         }
      ]
   }
   //Next we load the new validations with validanguage.addValidation()
   //Note that the new validations must be loaded with the array syntax below,
   //using "validateRequired, validateDate" will not work
   validanguage.addValidation( 'newDateField', ['onsubmit', 'onblur'], ['validateRequired', 'validateDate'] );

   //Instead of listing both validations individually, you could also use the following:
   validanguage.addValidation( 'newDateField', ['onsubmit', 'onblur'], '*' );
</script>

Disabling or Removing Validations

1. Disable the form field. You can use javascript to disable the actual form field, which will also disable all validations for this form field. Example: document.getElementById('formField').disabled = true; //Re-enable validations by setting this to false
2. Mark the element as disabled in validanguage.el.formField. You can also easily disable all validations for a form fields by marking it as disabled in the validanguage.el object corresponding to the form field.
   Example: validanguage.el.formField.disabled = true; //Re-enable validations by setting this to false
3. Disable all validations for the parent form. You can disable all validations for every field in a given form by marking the form as disabled in the validanguage.el object.
   Example: validanguage.el.form1.disabled = true; //re-enable validations by setting this to false
   Or if the form1 object does not yet exist: validanguage.el.form1 = { disabled: true }
4. Use the removeValidation() method to remove some validations while leaving other validations in place. The removeValidation() function can be called to deactivate one or more previously defined validations.

{String} elemId -- The ID of the field for which you wish to remove validations.

{String/Array} eventTypes -- A list of event types for which you wish to remove validations.This enables you to remove a given validation for, say, "onblur", while leaving the validation in place for "onsubmit". If you wish to remove all eventTypes for a given validation(s), you can use "*" as a shortcut to listing all the eventTypes individually.

{String/Array/Function} validationNames --A list of the validation functions to be removed. These must match exactly a validation which is listed in the validanguage.el.formField object, including variable type. Thus, when removing a validation which has a supported shortcut in validanguage.el.formField (such as "required" which is a shortcut for "validateRequired"), you must specify the full function name. If you wish to remove all the validations which are listed in the validanguage.el.formField.validations array, you can use "*" as a shortcut to listing all the validations individually.

<script type="text/javascript">
   validanguage.removeValidation( 'newDateField', ['onsubmit', 'onblur'], ['validateRequired', 'validateDate'] );

   //Or, instead of listing the eventTypes and validations indivudally,
   //you can deactivate them all with the following:
   validanguage.removeValidation( 'newDateField', '*', '*' );
</script>

Manually Failing a Form Field

The showSubmitMessage and showFailedFields Options

showSubmitMessage() function

The showFailedFields option in validanguage.showError()

The field attribute in validanguage.el

validanguage.settings.onload

Transformation: validanguage.toggle()

• Toggle Visibility: You can use validanguage.toggle() to hide and show other form fields or HTML elements based on the user changing a SELECT box or checking/unchecking a field.
• Toggle Values: Allows you to set a value of form field B in response to changes in form field A. This allows you to set a hidden field to 0 or 1 based on whether or not a checkbox has been checked.
• Dynamic Select Boxes: You can add/remove options to select box B in response to what a user chooses for Select Box A.

Using validanguage.toggle() to Toggle Visibility

Using validanguage.toggle() to Toggle Values

Using validanguage.toggle() to Create Dynamic Select Boxes

Setting up Ajax Validations with isAjax

• Customizable timeouts for expired requests. By default, if a form submission is waiting on results for an ajax validation and 30 seconds have elapsed, the form will automatically submit. Thus, users will not be prevented from submitting the form due to network issues or other problems with the ajax call.
• Result caching. Once an ajax request comes back and returns results for a given form field's value, any subsequent validation of the same value will check the cache, instead of triggering a new request.
• Discarding of outdated requests. One of the challenges in dealing with ajax is that there is no guarantee that requests will come back in order. Thus, if you're checking for the availability of a username and the user initially submits "dan" and then submits "dan17" a few seconds later, it is not unheard of for the "dan17" results to come back first, followed later by the "dan" results. Validanguage supports disregarding any older results through the use of an ajaxCounter that is incremented with each request. This counter will be sent to your validation callbacks so they can determine whether or not they are still relevant.

• validanguage.setValidationStatus(id, returnStatus, type, errorMsg) -- Call this function inside your ajax callback to tell Validanguage that the ajax check has returned.
• validanguage.isExpiredAjax(formFieldId, ajaxCounter) -- This function examines the ajaxLookup array to determine whether or not the specified ajaxCounter pertains to the most recent ajax call for that form field.

The isAjax support is primarily for advanced users who have a knowledge of server-side programming. In order to utilize the caching and discarding of outdated requests you will need to integrate the ajaxCounter variable into your ajax calls so that it is sent to the server and then returned inside the response (most likely via JSON encoding). To enable this, any function labelled with isAjax will be called with the form field value as the first argument and an incremented ajaxCounter value as the second argument.