Netspinner - Software consultancy and training

Synforce

Synforce is a Javascript library that provides real-time syntax enforcement on data entered into text input boxes in HTML forms. Synforce is Open Source software, licensed under the GNU Lesser General Public License (the LGPL).

The input text box is commonly used for gathering unstructured data, but suffers from the lack of any standard way to ensure that a user enters only data of an appropriate type: for example, although you may provide a text box to gather a customer's name, if the customer is inattentive (or even malicious) he may enter his telephone number instead. Synforce goes some way to ensuring that this cannot occur, by checking the syntax of the data entered as it is typed, and discarding characters that would violate the syntax that you wish to enforce.

For example, the text box below allows only the entry of integer data; any character that would violate the syntax of an integer (i.e. one or more digits) is discarded, and a warning popup is displayed:

Enter an integer

Of course, since Synforce relies on the browser's Javascript implementation, it is possible for this check to be evaded relatively easily, or for unsupported browsers to display inappropriate behaviour; for this reason, a script should never assume that the data submitted by a form is syntactically valid, and should perform a second round of server-side syntax checking.

The example above is implemented as follows:

The work is done by the Javascript function validate_integer, which examines each character typed in the text box, and discards it if it would violate the syntax that it enforces, and accepts it otherwise. The first two arguments (this and event) give the function access to the keypress information; the last argument, 2, tells it for how many seconds it should display the warning box in the event of a syntax violation.

Synforce has been tested on Internet Explorer 5+ and Mozilla 1.2+. Other browsers may display undesirable behaviour.

Download the Code

If you have read enough, you may wish to download the code: synforce-1.0.tgz. This provides the Javascript Synforce library, and a copy of this page, which describes further details of the usage and implementation of the library.

Please let us know if you use Synforce, or make any improvements to it that may be of general interest.

Validaters and Finalizers

Synforce enforces syntax in two distinct ways. Firstly, as seen above, some functions validate keypress data (characters typed, for example). These are called validaters, and each validater enforces a particular syntax, examples being validate_integer, validate_email, and so on. In Javascript terms, validaters are onkeypress handlers.

Secondly, other functions, known as finalizers, check the syntax of the data in a text box when the user has finished with it. If necessary, a finalizer alters the contents in some way, to ensure that it conforms with a particular syntax. For example, the text box below capitalizes each whitespace separated word; this may be useful if the text box represents a user's name: you expect names to look like "Jane Smith", rather than "jAne sMItH":

Enter your first and family names

Finalizers are Javascript onblur handlers, which execute whenever the user switches the screen focus away from the form element in question. The code for this example is:

Sometimes you want both real-time syntax validation and syntax completion. Because validaters and finalizers use different Javascript handlers, this presents no problem. In the next example, we check for a valid email address (in the commonest form only, name@domain.subdomain). However, if you switch focus to another element before completing the email address, it is finalized for you, defaulting to the .co.uk domain:

Enter an email address

Here, the appropriate onkeypress handler is:

onkeypress="return validate_email(this, event, 2);"

with the onblur handler being:

onblur="finalize_email(this, 'co.uk');"

Using Synforce

It is straightforward to use Synforce on a web page:

Include the Synforce Javascript library
Add HTML for the warning box to the page
Add the appropriate validaters and finalizers to the text boxes

1. Include the Synforce Javascript library

The Synforce library is provided in a single file, synforce.js, which provides the various validater and finalizer functions. To include this on a web page, copy the file to an appropriate directory on your website, and provide a corresponding <SCRIPT> section to refer to it. For example:

2. Add HTML for the warning box to the page

The warning box is implemented as a HTML table wrapped in a <SPAN> which gives it a unique identifier of "warning_box", and more importantly, ensures that it is initially not displayed, and has absolute positioning, as follows:

<span id="warning_box" style="position:absolute; display: none;">
	<table class="Warning_table" cellspacing="2" width="350px">
		<tr class="Warning_table_row">
			<td class="Warning_table_data">dummy</td>
		</tr>
	</table>
</span>

When a warning is to be displayed, the Synforce code changes the 'dummy' text to that of the warning, sets the position of the warning box so that it is just above the element that generated the error, and makes it visible for a configurable period of time (which is provided by the third parameter to the validaters).

You can include the HTML shown above anywhere convenient on the page. A suitable place may be at the very end, just before the closing <BODY> tag.

3. Add the appropriate validaters and finalizers to the text boxes

To validate a text box, you must define an appropriate Javascript onkeypress handler. To finalize a text box, you must define an appropriate Javascript onblur handler. There are examples below which display the code required for this.

Validaters have one configurable value, the length of time for which to display the warning box. This is set via the third parameter to the functions, which specifies the number of seconds for which it is to be displayed. Experience shows that 2 seconds is adequate.

Implementation Details

If you are interested in seeing how Synforce is implemented, or want to know how to add a new validater or finalizer, look at the Synforce Implementation Details page.

The Synforce Validaters and Finalizers

This section describes, with functioning demos, all of the Synforce validaters and finalizers. Since the implementing code is displayed, you can use this page as a 'cut and paste' template for your own use.

Where a validater and finalizer are designed to work together on the same data, we show this in the examples below.

Validaters

Function: validate_date_list

Validates a comma or space separated list of dates of the month, like 1,16,31 or 1 16 31. A date is a number between 1 and 31, for the purposes of this function.

Demo:

Enter a list of dates

Implementation:

Function: validate_email

Validates an email address in the format name@domain. e.g. fred@netspinner.co.uk and rob.smythe-pilkington@glitzy.place.in.fr. are valid email addresses, as far as this function is concerned, whereas bill@@some.domain.co.uk and fred@my.domain..co.uk are not.

Note that we also show the use of the associated finalizer, finalize_email. This ensures that an incomplete email adddress (i.e. one which does not end in a valid top level domain) is terminated with the supplied domain completion text (which in the example below is co.uk)

Demo:

Enter an email address

Implementation:

Function: validate_identifier

Validates an identifier i.e. a string representing a valid variable name in many common programming languages. For the purposes of this function, an identifier is a sequence of alphabetic characters, digits, and underscores.

Demo:

Enter an identifier

Implementation:

Function: validate_integer

Validates an integer i.e. a string containing a consecutive sequence of digits, with no leading zeros. For example, 0, 123067, and 9999 are valid integers, but 0123 is not.

Demo:

Enter an integer

Implementation:

Function: validate_minute_list

Validates a comma or space separated list of minutes, like 15,23,45 or 15 23 45. A minute is a number between 0 and 59, for the purposes of this function.

Demo:

Enter a list of minutes

Implementation:

Function: validate_name

Validates a name, where a name starts with a letter and is followed by zero or more letters and dashes. Consecutive dashes are disallowed. For example, Alfie and Smyth-Fotherington are considered to be valid, whereas l33t--haX0R is not.

Demo:

Enter a name

Implementation:

Function: validate_price

Validates a price, where a price is considered to be a decimal number represented to 2 decimal places (for example, 250.99, or 1200.01).

Note that we also show the use of the associated finalizer, finalize_price

Demo:

Enter a price

Implementation:

Function: validate_telno

Validates a telephone number, where a telephone number is a consecutive string of digits and spaces, or a number in "international" format (e.g. +44 (0)1234 56789). Consecutive spaces are disallowed.

Demo:

Enter a telephone number

Implementation:

Function: validate_signed_integer

Validates a signed integer i.e. a string stariting with an optional leading sign character (- or +), containing a consecutive sequence of digits, with no leading zeros. For example, +123, -99, 0, 123067, and 9999 are valid integers, but 0123 and +0 are not.

Demo:

Enter a (possibly signed) integer

Implementation:

Function: validate_UK_postcode

Validates an (approximation to) a UK postcode, which is considered to be a string starting with an uppercase character and followed by uppercase characters, digits, and spaces. Consecutive spaces are disallowed. Note that this function does not check that the data entered corresponds to a valid UK postcode, except in a rather loose syntactic sense.

Demo:

Enter a UK postcode

Implementation:

Function: validate_USA_state_abbrev

Validates a USA state abbreviation.

Demo:

Enter a USA state abbreviation

Implementation:

Finalizers

Function: finalize_email

If necessary, terminates the supplied text with the completion domain. This function considers the email address to be finalize if it ends in a valid top level domain. For example, bill@my.domain.co.uk and bill@my.domain.fr. are valid, whereas bill@some-domain is not, and would be finalized to bill@some-domain.co.uk (given the settings used on this page).

Demo:

See above.

Implementation:

See above.

Function: finalize_ucfirst

Uppercases the first character of every whitespace separated word in the text, and lowercases all others.

Demo:

Enter mixed case text

Implementation: