Larryband AJAX Forms Manual

Contents

    1  Get the Larryband DHTML Form files
        1.1  Download the Zip file
        1.2  Unzip zpform.zip

    2  Quick Startup
        2.1  Set Up Your Form
            2.1.1  Insert The Headers
            2.1.2  Path Warning
        2.2  Create the Presentation
        2.3  Attach the Larryband Form Object to your Presentation
        2.4  Presentation and Validation
        2.5  Copy your files to your web server
        2.6  Test the form application
        2.7  Change Included Files
            2.7.1  Use a Different Theme

    3  Form Configuration Options
        3.1  Configuration Parameters
            3.1.1  statusImgPos (string, default ’beforeField’)
            3.1.2  showErrors (string, default ’none’)
            3.1.3  showErrorsOnSubmit (boolean, default true)
            3.1.4  submitErrorFunc (function, default submitErrorFunc)
            3.1.5  asyncSubmitFunc (function, null)

    4  Field Configuration Options
        4.1  Field Data Types
        4.2  Custom Data Types
        4.3  Masks
        4.4  Limit Allowed Keystrokes
        4.5  AJAX Communication
        4.6  Multiple Themes
        4.7  Status Image
        4.8  Indeterminate Fields

1  Get the Larryband DHTML Form files

1.1  Download the Zip file

The DHTML Form files are bundled in a zip file. Click on the download link in the Form section of Larryband’s web site, and follow the instructions to download the file.

Save the file (zpform.zip) to your web site’s root folder on your computer or server.

1.2  Unzip zpform.zip

1. On your computer, go to the folder where you saved the file zpform.zip.

2. zpform.zip contains a folder called zpform that holds all of the files you need to create your form.

3. Open or double-click zpform.zip to unzip or unpack it.

2  Quick Startup

If you have not done so, follow the instructions in section 1.1. to download and unzip the Form files.

2.1  Set Up Your Form

2.1.1  Insert The Headers

In your web editor (Dreamweaver, UltraEdit, etc.), open the web page into which you want to place the form. Insert your cursor before the ending </head> tag. Paste the following style path and script paths before the ending </head> tag:

<!-- Javascript utilities file for the form -->
<script src="utils/utils.js" type="text/javascript"></script>
<!-- Javascript transport file for communicating with the server -->
<script src="utils/transport.js" type="text/javascript"></script>
<!-- basic Javascript file for the form -->
<script src="src/form.js" type="text/javascript"></script>
<!-- CSS file for basic style in the form-->
<link href="themes/basic.css" rel="stylesheet" />

This script refers to files located in the form folder. The files are:

• utils.js

  Located in the utils folder. General javascript utilities file.

• transport.js

  Located in the utils folder. Transport file to handle AJAX communications with the server.

• form.js

  Located in the src folder. The main javascript form file.

• basic.css

  Located in the themes folder. Provides basic style icons for the form.

2.1.2  Path Warning

If your web page containing the Form is saved in the zpform folder, these headers work without any changes. If, however, you save your web page in another location (like directly under your web site’s root folder), you need to edit the path for these files in the script.

2.2  Create the Presentation

The easiest way to use the Larryband Form is to add the Larryband Data Type to the class in the input HTML element. For details on data types, see Section 4.1. For example, if the HTML input field is a phone number, you would add the class name zpFormUSPhone to the input class.

<input size="20" name="phone" type="text" class='zpFormUSPhone'>

2.3  Attach the Larryband Form Object to your Presentation

All you have to do in your HTML page is call Larryband.Form.setupAll to set up all the forms.

<script type="text/javascript">
   // Run this to auto-activate all "zpForm" class forms in the document.
   Larryband.Form.setupAll();
</script>

If you want to just set up a specific form, or if you need to set specific parameters you can do it explicitly.

<script type="text/javascript">
	 new Larryband.Form('userForm', {
				showErrors: 'afterField',
				statusImgPos: 'afterField'
				});
</script>

2.4  Presentation and Validation

Let’s extend the example to the following:

• We are creating a form with 3 input fields: Name, Phone Number, Comment.

• The form class zpForm specifies the Larryband class for the form object.

• Name: Specifying zpFormRequired in the input class indicates that this field is required.

• Phone Number: Specifying zpFormUSPhone in the input class specifies that the input must be in a valid format for U.S. telephone numbers.

• Comment: is optional and can be in any format, so no class parameter is specified.

Here is the code. If you copy and paste this code into a web page, you will be able to see how the Larryband Form object automatically validates the fields.

<form action='' name='formName' id='formId' class='zpForm' method='post'>
   Name:<input class='zpFormRequired' size='40' name='name' type='text' >
   <br>
   Phone:<input class='zpFormUSPhone' size='20' name='phone' type='text' >
   <br>
   Comment:<input size='30' name='comment' type='text' >
   <br>
   <input value='Submit' name='Submit' type='submit' >
   <input value='Clear' name='Clear' type='reset' >
</form>

<script type="text/javascript">
   // Run this to auto-activate all "zpForm" class forms in the document.
   Larryband.Form.setupAll();
</script>

You can also attach the Larryband Form object using the body onload attribute instead of inside a script tag. Make sure you call Larryband.Form AFTER the form is created.

<body onload='Larryband.Form.setupAll()'>

Validation works for various form elements. You can specify that text areas, dropdown menus selections and upload fields are required. For examples, see Different HTML Form Elements demo
.

By specifying the zpFormRequired class, the following code forces the user to select a value from the dropdown menu.

<select name="age" class="zpFormRequired">
 <option value="">--select--</option>
 <option value="less_20">&lt;20</option>
 <option value="20-40">20-40</option>
 <option value="40-60">40-60</option>
 <option value="greater_60">&gt;60</option>
</select>

Similarly, this code requires the user to enter some text in the text area.

<textarea name="resume" cols="40" rows="10" class="zpFormRequired zpFormMinLength20"></textarea>

If the form element requires the user to input a file of a certain type, you can request validation for a particular extension. For example, the following code specifies the zpFormZipArc class in the input element to indicate that the input must be a filename with a .zip extension.

<input value="" size="20" name="photo" type="file" class='zpFormZipArc'/>

You can easily implement a custom validation class to validate for a different file extension, based on the code for zpFormZipArc. Just copy the code below for the zpFormZipArc class and substitute the regular expression for the file extension that you want to validate. For example, if you want to validate for a pdf file, you would change the regular expression to .pdf instead of .zip and adjust the Larryband name and error and help messages accordingly.

Larryband.Form.addDataType(
 // Larryband Name to be put in INPUT class
 'zpFormZipArc',

 // Friendly description
 'Zip archive',    

 // Regular Expression for Validation
 /\.zip$/,

 // Error message
 "Not a zip archive",

 // Help message
 "Upload valid zip archive",  

 // Function
 null  

2.5  Copy your files to your web server

Using your editing or FTP program, copy or "put" your web page and the entire tree folder to the root of your website.

2.6  Test the form application

Using your web browser, navigate to the web page that you created to include the Larryband DHTML Form. Congratulations! You have set up the most basic version of the Larryband DHTML Form! Now, on to the fun and exciting features you can change with this highly adaptable application!

2.7  Change Included Files

You can change the theme of the form by choosing to include a different file in your header.

2.7.1  Use a Different Theme

One of the lines you inserted in Section 2.1.1 includes the basic.css file in the themes folder. This file implements one of several themes that are included with the Larryband DHTML Form. You can change the look of the form by changing the .css file referenced by the path. Look in the themes folder for other theme options.

3  Form Configuration Options

You can also pass a set of parameters when you create the form to control the form behavior.

<script type="text/javascript">
   // Run this to auto-activate all "zpForm" class forms in the document.
	var myForm = new Larryband.Form.setupAll();
</script>

3.1  Configuration Parameters

3.1.1  statusImgPos (string, default ’beforeField’)

Where should the image for the status of the field validation be displayed?

• afterField - Show validation errors AFTER input element.

• beforeField - Show validation errors BEFORE input element.

3.1.2  showErrors (string, default ’none’)

Where should the error message for the invalid field be displayed?

• none - Do NOT show validation errors.

• afterField - Show validation errors AFTER input element.

• beforeField - Show validation errors BEFORE input element.

• tooltip - Show validation errors in the tooltip of the validation status image (statusImgPos).

3.1.3  showErrorsOnSubmit (boolean, default true)

If true, ALL fields are validated when the user clicks on the SUBMIT button. Any invalid fields are displayed in the Alert or Custom Error.

If false, the fields are NOT validated on submit.

3.1.4  submitErrorFunc (function, default submitErrorFunc)

You can create your own Custom error function instead of the default Alert.

For example, you can create a DIV container to show all field errors on submit. The DIV has id of ’divErrs’. The class errOutput is defined in the themes.

<div id='divErrs' class="errOutput"></div>

Your Custom function displays all invalid fields in the DIV. The function is passed an object that contains information about the fields in error.

function submit_err(errors){
   var strMsg=errors.generalError
		
   for (var i = 0; i < errors.fieldErrors.length; i++)
      strMsg += "<br>" + (i + 1) + ': Field ' + errors.fieldErrors[i].field.name +
         ' ' + errors.fieldErrors[i].errorMessage;
		
   var outputDiv = document.getElementById("divErrs");
   if(outputDiv != null){
	   outputDiv.innerHTML = strMsg;
	   outputDiv.style.display = "block";
   }
}

In summary

• Create DIV

• Create Function

• Set Configuration Option

Using a callback provides you the flexibility to use error handling in a variety of ways. You can

• Display the errors at the top of the form

• Display the errors at the bottom of the form

• Display the errors at both the top and bottom of the form

• Display a summary of the number of errors in an alert box with the details in the text

3.1.5  asyncSubmitFunc (function, null)

This is your function that is called after the form is sent to the server using the Larryband.Transport.fetchJsonObj and "success" response is received from the server.

At this point the form has been successfully submitted and you can take one or more of the following actions:

• If the form is inside a Larryband Window, you can close the window.

• The user is entering records into the form repeatedly. Clear the form, indicate the success with a message, and put the cursor (focus) in the first field, so that the user can submit another record.

• Replace the form with HTML fragment, for instance "Thank you for signing up with us."

See AJAX - Asynchronous JavaScript and XML Demo

4  Field Configuration Options

4.1  Field Data Types

To enforce validation of a field, add the Larryband field type name in the INPUT class.

For example, if the INPUT is a US zip code, add the name zpFormUSZip as the INPUT class.

<input value="" class='zpFormUSZip' size="10" name="zip" type="text" >

If the field is a US zip code type and REQUIRED, add two class names to this INPUT class.

<input value="" class='zpFormRequired zpFormUSZip' size="10" name="zip" type="text" >

To observe how field validation works when a user is entering data into a form, see Basic Demo.

This table shows the data types that you can currently assign to an INPUT field.

4.2  Custom Data Types

You can make your own custom data types.

For an example that uses a custom data type for currency, see Form Data Types Demo.

After you create the Larryband.Form, call Larryband.Form.addDataType to add your Custom Data Type.

Here is the code to create the currency Custom Data Type.

<script type="text/javascript">
   // Run this to auto-activate all "zpForm" class forms in the document.
   Larryband.Form.setupAll();
   var dt=Larryband.Form.dataTypes
   // create a custom data type
   Larryband.Form.addDataType(
      'zpFormCurr', 
      'A Currency',
			/^.[0-9]+\.[0-9][0-9]$/,
      "Invalid Currency",
      "Valid currency is ##.##",
      null);
</script>

4.3  Masks

Masks provide an easy way to define a valid field format. When a user types in a field that is defined by a mask, the form visually indicates the mask, which simplifies data entry as well as preventing the user from making an invalid entry. See Masks Demo

For example, you want to define a mask for Social Security Number. First you define the mask rule.

• 3 digits

• followed by a dash

• followed by 2 digits

• followed by a dash

• followed by 4 digits

So the mask rule is: "000-00-0000", where 0 indicates a place holder for a required digit. To implement the mask rule for the social security number field, assign the mask rule to the zpFormMask class of the INPUT element. This directs the Larryband Form to apply a mask with a rule of 000-00-0000.

Here is the code that defines the social security number mask in Masks Demo

<label class='zpFormLabel'>US SSN 000-00-0000</label>
<input class='zpFormMask="000-00-0000"' value="" size="15" name="usssn" type="text">

The following table shows the mask rules.

4.4  Limit Allowed Keystrokes

A nice feature that you can add to your forms is restricting the set of keystrokes that a user is allowed to type in a field.

See the Limit Allowed Keystrokes Demo.

The Limit Keystroke rules are:

To limit keystrokes, add the appropriate zpFormAllowed class to the input element. For example, the following code uses zpFormAllowed-d to limit keystrokes to digits in this field.

<label class='zpFormLabel'>Digits only</label>
<input value="" size="15" name="digits" type="text" class='zpFormAllowed-d'>

To limit keystrokes to alphanumeric keys, use zpFormAllowed-w, to white space use zpFormAllowed-s.

4.5  AJAX Communication

See AJAX - Asynchronous JavaScript and XML Demo

The Larryband Form provides a way to validate forms automatically based on the server response.

The Larryband Transport facility provides your form with automatic client side and server side validation.

To enable validation based on the server’s response, just define the optional asyncSubmitFunc as a callback function. This function is called after a SUCCESS response from the Server. You can then close the window, clear the form, etc. See Section 3.1.5 for more details.

A failure reponse from the server is handled in the same way client side errors are handled, as described in Section 3.1.4.

Server response should be a valid JSON string in ONE of the following formats:

Server Validates Form:

{"success": true}

Server Error, No Details:

{"success": false}

Server Error, Details:

{
"success": false,
"generalError": "Human readable error description",
"fieldErrors": {
   "INPUT-fieldName1": "Human readable error description",
   "INPUT-fieldName2": "Human readable error description",
   ...
   }
}

When the server returns errors, the Larryband Form can automatically display the errors. Optionally, you can handle the errors in your own custom error function. See submitErrorFunc in Section 3.1.4.

4.6  Multiple Themes

Larryband provides three sample themes for forms in the themes folder: default.css, basic.css, and winxp.css. As discussed previously, you can set the style for the forms on a web page by specifiying a specific .css file in the headers:

<!-- CSS file for basic style in the form-->
<link href="themes/basic.css" rel="stylesheet" />

It is also possible to use forms with different themes on a single web page by specifying a specific zpForm<ThemeName> class for the form instead of simply using zpForm. In this case, the form specified by the theme class overrides the theme set in the headers for the purpose of displaying that particular form. Thus, in the following example, specifying zpFormWinXP2 for the class directs the form to use the winxp.css theme when displaying this form.

<form enctype="" action="" name="userData2" id='userForm2' class="zpFormWinXP2" method="post" style='text-align:left'>

Similarly, you can specify the zpFormDefault class to use the default.css theme and the zpFormBasic class to use the basic.css theme.

4.7  Status Image

You can configure the form to display feedback icons before or after the input fields. The rules pertaining to the status image for field validation are based on the parameter passed by statusImgPos and the rules that are embedded in the CSS files located in the themes directory. The CSS file should be included in your web page to display the images according to the rules in these files.

If you do NOT want any status images inyour form, delete the rules that manipulate the status image (span.zpStatusImg) from the CSS.

The images are included in nested spans whose classes vary according to the status of the data. As a result you can configure the images using simple CSS rules.

The following is the list of spans from the outermost to the innermost.

1. "zpIsRequired" or "zpNotRequired" – is this field required?

2. "zpIsEditing" or "zpNotEditing" – is the user editing this field?

3. "zpIsEmpty" or "zpNotEmpty" – is this field empty?

4. "zpIsValid" or "zpNotValid" – is this field valid?

5. Always "zpStatusImg" – this is the one styled.

Here are the contents rules pertaining to the status image:

/*
 "zpStatusImg" class images for form fields -- apply appropriate rules here.
 The script auto-applies one of each of these CLASS attributes to a series of
	nested <span>s with an innermost .zpStatusImg class <span> we style:
 1) "zpIsRequired" or "zpNotRequired".
 2) "zpIsEditing" or "zpNotEditing".
 3) "zpIsEmpty" or "zpNotEmpty".
 4) "zpIsValid" or "zpNotValid".
 5) Always "zpStatusImg", this is the one styled.
*/

* html span.zpStatusImg {
 /* MSIE fix to force "hasLayout" for opacity. */
 display: inline-block;
}

span.zpStatusImg {
 padding: 0px 12px;
 height: 18px;
 line-height: 18px;
 background-repeat: no-repeat;
 background-position: center;
 opacity: 0.66;
 filter: alpha(opacity=66);
 margin-left:5px;
}

.zpIsEditing span.zpStatusImg {
 opacity: 1.0;
 filter: alpha(opacity=100);
}

.zpIsRequired span.zpStatusImg {
 background-image: url(icons/required.gif);
}

.zpIsEditing .zpNotEmpty span.zpStatusImg {
 background-image: url(icons/editing.gif);
}

.zpNotEditing .zpNotEmpty .zpNotValid span.zpStatusImg {
 background-image: url(icons/required_invalid.gif);
}

.zpIsValid span.zpStatusImg {
 background-image: url(icons/validated.gif);
}

Here is a scenario where the user is editing (zpIsEditing) and the field not empty (zpNotEmpty). Here is how the nested code looks (DHTML and CSS) to render the form validation images.

<!-- Editing the field -->
<span class="zpIsRequired">

        <span class="zpNotEmpty">
            <span class="zpIsValid">
                <span title="" class="zpStatusImg"> </span>
            </span>
        </span>
    </span>
</span>

Notice how the CSS selector is rendered the CSS, producing the image that looks like a pencil writing.

.zpIsEditing .zpNotEmpty span.zpStatusImg {
 background-image: url(icons/editing.gif);
}

4.8  Indeterminate Fields

The zpFormMultiple class lets the form display an indeterminate number of fields. This is useful when the number of fields needed on the form is unknown prior to interaction with a user, for example, fields to add data for one or more children. This feature displays a ’+’ button next to the input field, which if activated by the user duplicates the field so the user can enter another set of data. It also provides a ’-’ button to enable the user to remove a field that has been added.

See Multiple Fields Demo.

Use the zpFormMultiple or zpFormMultipleInside class to enable the multiple feature. zpFormMultiple places the ’+’ after the element, while zpFormMultipleInside places it inside the element. If the class is added inside a row in a table, a new cell is appended to the row to hold the ’+’ and ’-’ signs.

This code lets the user add multiple address fields, placing the ’+’ and ’-’ signs inside the element.

<label class='zpFormLabel'>Address</label>
<div style="margin-left: 10.2em" class="zpFormMultipleInside">
 <input class='zpFormRequired' value="" size="40" name="address" type="text" />
</div>

This code lets the user add multiple rows to a table and automatically creates an additional cell for the ’+’ and ’-’ signs.

<tr class="zpFormMultiple">
 <td valign="top" align="center"><input type="text" name="name"></td>
 <td valign="top" align="center"><input type="text" name="surname"></td>
 <td valign="top" align="center"><input type="text" name="address"></td>
</tr>