wForms is a javascript library that enhances the web form experience without the need for any programming. If you’re not familiar with wForms, here’s a short overview of what it can do:

• show / hide conditional sections based on answers to multiple-choice questions;
• highlight contextual information when a field is in focus;
• validate fields and show appropriate error messages (available in 17 languages);
• repeat form fields;
• and simulate multi-page forms

wForms allows you to make your forms simpler, shorter and ultimately easier to fill out. It is also unobtrusive. If for some reason wForms doesn’t run in someone’s browser - javascript turned off for instance - your form will still work.

wForms 2.0 has improved supports for Mac browsers, a tighter and faster code and is also more modular, paving the road for further enhancements. I will be posting more specific information about the new features in the coming days.

In the meantime you can download it, read more about it and post your feedback here in the comments, or in the support forum.

wforms, web development

The Repeat behavior is certainly the most powerful functionality of the wForms extension and enabling it in a web form is dead simple (class=’repeat’ anyone?). Processing the form submission is trickier though, but the real difficulty with repeated groups arises when you want to populate a form with previously submitted data. You basically need to re-engineer server-side what wForms does client-side.

The Form

Let’s start with a simple form and let’s make the fieldset repeatable by using wForms’ ‘repeat’ class.

<form action="">
<fieldset id="myfieldset" class="repeat“>
<label for=”field1″>Label 1: </label>
<input type=”text” id=”field1″ name=”field1″ />
<label for=”field2″>Label 2: </label>
<input type=”text” id=”field2″ name=”field2″ />
</fieldset>
</form>

Submitted Data

Now, assuming that this form was previously submitted with 3 rows, the data collected on the server contains the following fields:

Populating back the form

In order to show the form back to the user, you need to :

• Loop 3 times over the <fieldset> element.
• Set the value of each field.
• Appends the row index suffix to the id, name and for attributes for every tag in the second and third rows (the first row is always left unchanged by wForms).
• Change the class from ‘repeat’ to ‘removeable’ (sic) for the second and third rows.
• Create the hidden counter field. The name of this field is constructed by adding ‘-RC’ to the id of the tag with the ‘repeat’ class (here ‘myfieldset’).

If the form is correctly set up, wForms will be able to carry on from there, allowing adding more rows or removing the existing ones.

Sequence gaps

Now, as I mentioned previously, the -RC field in wForms does not exactly behave like a row counter. It indicates the highest row index reached. If the user deleted a row before submitting the form, you’ll end up with a gap in the sequence that you need to accommodate for. In the loop logic, you can tell if the row was deleted if you can’t find any name/value pair in your submitted dataset for the given row index.

Code Sample (PHP)

Note: Updated on June 15th 2007.

<?php

$max = (int) $_POST["myfieldset-RC"];
for($i=1;$i<=$max;$i++) {
if($i==1) {
$repeatclass = "repeat";
$rowIndex = "";
}
else {
$repeatclass = "removeable";
$rowIndex = "-".$i;
}
if(isset($_POST["field1".$rowIndex]) && isset($_POST["field2".$rowIndex])) { // account for sequence gap.
?>
<fieldset id="myfieldset<?php echo($rowIndex)?>" class="<?php echo($repeatclass)?>">
<label for="field1<?php echo($rowIndex)?>">Label 1: </label>
<input type="text" id="field1<?php echo($rowIndex)?>" name="field1<?php echo($rowIndex)?>" value="<?php echo($_POST["field1".$rowIndex])?>" />
<label for="field2<?php echo($rowIndex)?>">Label 2: </label>
<input type="text" id="field2<?php echo($rowIndex)?>" name="field2<?php echo($rowIndex)?>" value="<?php echo($_POST["field2".$rowIndex])?>" />
</fieldset>
<?php
}
}

echo "“;

?>

Result

Update: Comments are now closed for this post, but you can go to the wForms forum if you have any question or comment. Thanks !

This documentation was updated on June 28th 2005 (fixed code sample)

The repeat behavior generates form fields dynamically and this makes the server-side processing a bit more complex than with your usual web form. This is a two parts problem: (1) how to retrieve the submitted information and (2) how to pre-fill a form with a repeated element. This post deals with the first and before we start, here’s a short definition: The ‘repeated element’ refers to the element with the ‘repeat’ class (usually a <div>, a <fieldset> or a <tr>).

The Row Count

The wForms extension generates a hidden ‘row count’ field for each repeated element of the form. The name of the field is derived from the id of the repeated element (and you probably want to set that id attribute if you haven’t done so already).

For instance:

<fieldset id=”someid” class=”repeat” >
… some fields…
</fieldset>

wForms will generates the following markup:
<input type=”hidden” id=”someid-RC” name=”someid-RC” value=”" />

The value of the field is a number indicating the number of time the element has been repeated.

The Row Index suffix

In order to maintain the uniqueness of field names, wForms appends a dash followed by the row index to each repeated field.

The first row is left unchanged. This serves two purposes: First, you don’t have to adopt a specific syntax for field names and second, the form can still be processed normally if javascript was unavailable on the client.

Now, it is important to know that there can be gaps in the sequence. For instance, if the user deletes a row before submitting the form, you’ll end up with:

The field named ’somename-2′ is missing. In this situation the row count still indicates 3.
This is by design. It would be rather complicated to adjust the counter and renumber all field names in the browser each time a row is deleted.

In effect, the row count gives the upper bound of the loop and the presence of the field must be tested at each iteration.

PHP Code Sample

Here’s the corresponding code in PHP (from memory, let me know if it has any problem):

<?php
// first value:
$value = $_POST["somename"];
// subsequent values:
if( array_key_exists("someid-RC",$_POST)) {
for($i=2;$i < = (int) $_POST["someid-RC"];$i++) {
if( array_key_exists ("somename-".$i,$_POST)) {
$value = $_POST["somename-".$i];
}
}
}
?>

Code sample updated (see comments below)

You’re welcome to share code samples for different environments, or continue reading: how to prefill a form with a repeated element.

Update: Comments are now closed for this post, but you can go to the wForms forum if you have any question or comment. Thanks !

wForms allows you to easily split a long and tedious form into a multi-page
form. The next and previous page buttons are automatically added
and the form is validated page by page. If javascript is disabled, the form
degrades gracefully in one long form.

Example:

To create a page in the form builder, create a ‘fieldset’ and set its type to ‘page’, then move the appropriate fields in it.

To use the multi-page behavior on your own web forms, follow
the following steps:

1. Enable the wForms extension by adding the following code to the <head> element
   of your page:
   <script type="text/javascript" src="wforms.js" ></script>
2. Add a <div> element
   for each page. The element should have the ‘wfPage’ class and an id starting
   with ‘wfPgIndex-’ followed by the page number.
   <form>
<div class="wfPage" id="wfPgIndex-1">
... form elements (inputs, fieldset, ...)
</div>
<div class="wfPage" id="wfPgIndex-2">
... other form elements (inputs, fieldset, ...)
</div>
<input type='submit' ... />
</form>
3. The wFroms extension generates the ‘Next Page’ / ‘Previous Page’ buttons.
   You can use the ‘wfPageButton’ class to style them. To change the label of
   the buttons, see the documentation
   on customization.

Any form element that is not within a ‘Page’ division is visible on
every page, except for the ’submit’ button, which is hidden until the last
page of the form is reached.

Please note: To prevent incomplete submission of a form, you need to disable the form submission with the ‘enter’ key using the following code (either in a customization.js file, or within a <script> tag *after* the link to wForms.js)

wf.preventSubmissionOnEnter = true;

Update: Comments are now closed for this post, but you can go to the wForms forum if you have any question or comment. Thanks !

This documentation was updated on may 09 2005.

wForms was designed from the onset to be easily customizable.

When the wForms extension loads, it instantiates a javascript object called ‘wf’. Public properties and methods of that object can be easily overwritten for customization purpose.

You should not change wForms.js directly, as it would hinder your ability to install updates. Instead, use a short javascript file, linked after wForms.js.

For instance,

<script type="text/javascript" src="js/wforms.js" ></script>
<script type="text/javascript" src="js/customization.js" ></script>

See the sample customization file.

wForms Behaviors Configuration Options

wf.preserveRadioName [true / false]

Default: true. The Repeat behavior preserves the name attribute of radio inputs accross repeated elements, effectively expanding the radio group. Set to ‘false’ to make repeated radio inputs independant.

wf.preventSubmissionOnEnter [true / false]

Default: false. If set to ‘true’ the form will not be submited when the ‘enter’ key is pressed. ‘True’ is the recommanded setting for multi-page forms, to prevent submission of incomplete forms.

wf.showAlertOnError [true / false]

Default: true. The validation routine will run the showAlert function if there’s an error, with the message in wf.arrErrorMsg[8]

wf.switchScopeRootTag

Default: “FORM”. If you need the Switch behavior to be able to target elements outside of its form, you may change the switchScopeRootTag value to ‘BODY’.

How to modify error messages and text outputs

See the documentation about wForms localization.

wf.showAlert

If you’d like to display the alert message in a different way (popup, insert..) you can overrite the wf.showAlert function.

wf.showAlert = function (nbTotalErrors) {
    alert(self.arrErrorMsg[8].replace('%%',nbTotalErrors));
}


How to add a custom form validation routine

1. Overwrite the default form validation handler with yours:
   wf.functionName_formValidation = "myCustomValidation";
2. Implement your custom function:
   function myCustomValidation (evt) {
// evt is the onsubmit event.

      // call the wForms default validation routine
   if(wf.formValidation(evt)) {

          // do your stuff..

      } else
    // will prevent the form from being submitted.
    return wf.utilities.XBrowserPreventEventDefault(evt);
}

How to change the CSS Classes used by wForms

Here are the classes defined in wForms. You probably won’t need to ever change them, but if you do, you may do so in the customization.js file.

Please note: if your form has been created using the form builder, you need to apply your changes to your form’s HTML as well.

wf.classNamePrefix_switch = “switch”;
wf.classNamePrefix_offState = “offstate”;
wf.classNamePrefix_onState = “onstate”;
wf.className_repeat = “repeat”;
wf.className_delete = “removeable”;
wf.className_required = “required”;
wf.className_validationError_msg = “errMsg”;
wf.className_validationError_fld = “errFld”;
wf.classNamePrefix_validation = “validate”;
wf.className_duplicateLink = “duplicateLink”;
wf.className_removeLink = “removeLink”;
wf.className_activeFieldHint = “field-hint”;
wf.className_inactiveFieldHint = “field-hint-inactive”;
// id attribute suffixes
wf.idSuffix_fieldHint = “-H”;
wf.idSuffix_fieldLabel = “-L”;
wf.idSuffix_fieldError = “-E”;
wf.idSuffix_repeatCounter = “-RC”;

Update: Comments are now closed for this post, but you can go to the wForms forum if you have any question or comment. Thanks !

The purpose of the input validation in wForms is to help users fill out a form
correctly, by defining required fields and allowed formats and by providing appropriate
error messages when the condition for submission are not met.

Example of Form Validation (click on submit)

Implementation

If you use the form builder, you don’t have to worry about these details, but to use the wForms input validation on your own web forms, follow the following steps:

1. Enable the wForms extension by adding the following code to the <head> element of your page:
   <script type="text/javascript" src="wforms.js" ></script>
2. Add any of the following classes to your input fields:

   required

   Field value cannot be empty. Use it on any field type (<input>, <select>,<textarea>).

   validate-alpha

   Allows only alphabetic characters ([a-z], can be modified for localization purpose). Allows an empty value.

   validate-alphanum

   Allows number and alphabetic characters, no ponctuation or exotic characters (can be modified for localization purpose). Allows an empty value.

   validate-date

   Allows a date, in any format supported by the local browser. Allows an empty value.

   validate-email

   Allows only a valid email syntax (someome@somewhere.somext). Allows an empty value.

   validate-integer

   Allows only a number (digits). Allows an empty value.

   validate-float

   Allows float numbers (ex: 0,00). Allows an empty value.

   You may use ‘required’ in combination with any other class. For instance:

   <input type="text" name="wf_Yourname" class="validate-alpha required"/>

3. To require at least one response to a multiple-choice question, add the class ‘required’ to the parent element (the container). For instance:
   <div class="required">
<input type="checkbox" name="something" … />
<input type="checkbox" name="somethingelse" … />
<input type="checkbox" name="anothersomething" … />
</div>
4. Add the following CSS rules to your stylesheet to control the look of the error messages:
   • .errFld {border: 1px solid #F00; /*... or any other css properties ... */}

   • .errMsg { color: #C33; /*... or any other css properties ... */ }

Update: Comments are now closed for this post, but you can go to the wForms forum if you have any question or comment. Thanks !

wForms is a javascript extension that adds commonly needed behaviors to traditional web forms. It follows the principle of progressive enhancement : unobtrusive, cross-browser and degradable. I should also point out that not a single line of code is required to actually use it. That makes the learning curve almost non-existant. If you can add a class to a tag, then you can use wForms.

Implemented behaviors are:

* Switch: Allows you to show/hide relevant parts of a form based on the user inputs.
* Repeat: Allows parts of a form to be repeated if the user wants to provide more answers.
* Field Hint: Displays contextual help based on the current input focus.
* Input Validation: Validates common input types (email, numbers, ..) and displays appropriate error messages.

wForms is not as complete or ambitious as XForms or Web Forms 2.0 are, but at least it works with today’s browsers and is web standards compliant.

Update: Comments are now closed for this post, but you can go to the wForms forum if you have any question or comment. Thanks !

wForms was designed from the onset to be easily adapted to languages other than english.

When the wForms extension loads, it instantiates a javascript object called ‘wf’. Public properties and methods of that object can be easily overwritten for localization purpose.

You should not change wForms.js directly, as it would hinder your ability to install updates. Instead, use a short javascript file, linked after wForms.js.

For instance,

<script type="text/javascript" src="js/wforms.js" ></script>
<script type="text/javascript" src="js/localization-francais.js" ></script>

Available Localization Files

• Please visit http://www.formassembly.com/wForms for the complete list.

How to create your own localization file

1. Translating Error Messages

Error messages are contained in an array (wf.arrErrorMsg[]). Your translation should follow this example :

wf.arrErrorMsg[0] = "Champs requis"; // required field
wf.arrErrorMsg[1] = "Caractères alphabétiques uniquement (a-z)"; // alpha char. only
wf.arrErrorMsg[2] = "Adresse email invalide"; // email
wf.arrErrorMsg[3] = "Entrez un nombre entier"; // integer
wf.arrErrorMsg[4] = "Entrez un nombre"; // float
wf.arrErro rMsg[5] = ""; // password - not implemented
wf.arrErrorMsg[6] = "Caractères alpha-numeriques uniquement (a-z 0-9)"; // alphanumeric
wf.arrErrorMsg[7] = "Date invalide"; // date
wf.arrErrorMsg[8] =”Il y a %% erreur(s). Votre formulaire n’a pas été envoyé.\nVérifiez les informations saisies.”; // %% will be replaced by the actual number of errors.

2. Translating Other Texts

wf.arrMsg[0] = "Ajouter"; // repeat link
wf.arrMsg[1] = "Ajouter un nouveau rang" // title attribute on the repeat link
wf.arrMsg[2] = "Supprimer"; // remove link
wf.arrMsg[3] = "Supprimer le rang" // title attribute on the remove link
wf.arrMsg[4] = "Next Page"; // label used with multi-page forms
wf.arrMsg[5] = "Previous Page"; // label used with multi-page forms

3. Adapting Input Validation

The Alphabetic and Alphanumeric field types are accepting by default only basic latin characters : a-z, A-Z and 0-9. To validate a different character set, the wf.isAlpha() and wf.isAlphanum() methods must be redefined.

These two methods rely on a regular expression to validate the input.

wf.isAlpha = function(s) {
var reg = /^[\u0041-\u007A\u00C0-\u00FF\u0100–\u017F]+$/;
return this.isEmpty(s) || reg.test(s);
}

wf.isAlphaNum = function(s) {
var reg = /^[\u0030-\u0039\u0041-\u007A\u00C0-\u00FF\u0100–\u017F]+$/;
return this.isEmpty(s) || reg.test(s);
}

The expression /^[\u0041-\u007A]+$/ covers the Unicode range 0041 to 007A, which corresponds to the basic latin alphabet.

The expression /^[\u0041-\u007A\u00C0-\u00FF\u0100–\u017F]+$/ covers the Unicode ranges 0041 to 007A, 00C0 to 00FF and 0100 to 017F. This includes the most common variations of the latin alphabet.

Here’s an overview of common Unicode ranges :

See http://www.unicode.org/charts/ for other languages.

Please share your localization files by sending them to webmaster at formassembly dot com.

Update: Comments are now closed for this post, but you can go to the wForms forum if you have any question or comment. Thanks !

Update: Comments are closed for this post, but you can go to the wForms forum if you have any question or comment. Thanks !

The purpose of the Field Hint Behavior is to assign a contextual help to an input field and to highlight the help when the field gets the focus.

A field hint can be a short text, an image, or just about anything you deem appropriate.

Implementation

Of course, if you use the form builder you don’t have to worry about the implementation details. If you use the wForms behaviors on your own forms follow these instructions to set the id and classe attributes correctly. That’s all you will need.

1. Enable the wForms extension by adding the following code to the <head> element of your page:
   <script type="text/javascript" src="wforms.js" ></script>
2. Assuming that the field has its id attribute set to ’someFieldId’, set the field hint id to ’someFieldId-H‘ (append -H) and add the ‘field-hint-inactive‘ class.
   <div id="someFieldId-H" class="field-hint-inactive" >Your Field Hint</div>
3. Add the following CSS rules to your stylesheet to control the visual effect:
• .field-hint {color: #000; /*... or any other css properties ... */}

• .field-hint-inactive { color: #999; /*... or any other css properties ... */ }

That’s all folks. Don’t hesitate to give your feedback.

Note: Comments are now closed for this post, but you can go to the wForms forum if you have any question or comment. Thanks !

Updated documentation: Server-side handling of the Repeat Behavior part 1 and part 2

The Repeat Behavior is a functionality offered by the wForms extension. It allows you to define a section of a form that the visitor can duplicate as many times as he wants.
It is particularly suited for situation when you don’t want to limit the number of possible answers to a question. For example, the professional experience section of a employment form :

As with all wForms behaviors, you don’t need to write a single line of code. Add the class “repeat” to the desired tag and everything inside that element will be duplicable. The wForms extension will even take care of adding the ‘repeat’ link.

In this example, the class was added to the TR tag. Other valid candidates for the repeat class are:
DIV, FIELDSET, SPAN, LI, P (*).

The repeat behavior will not work if set on the following tags: TABLE, UL, OL, INPUT, TEXTAREA, SELECT.

Let’s review how to enable the Repeat behavior in your form:

1. Enable the wForms extension by adding the following code to the <head> element of your page:
   <script type="text/javascript" src="wforms.js" ></script>
2. Add the ’Repeat’ class to the element to be duplicated.
   <div ... class="repeat"> ... </div>
3. The wForms extension generates the ‘repeat’ and ‘remove’ links. You can style them with the following CSS rules:
   .duplicateLink { ... css properties ... }
.removeLink { ... css properties ... }

That’s all folks. For information regarding server-side code, see Server-side handling of the Repeat Behavior part 1 and part 2.

Notes:
(*) and any other tag that can accept a link as a child element.

Update: Comments are now closed for this post, but you can go to the wForms forum if you have any question or comment. Thanks !