Like me, you are probably confronted with many requests for surveys, questionnaires, feedback forms, registration forms and so forth: forms where the processing requirements are very simple (store in a database or e-mail to a particular address).

Despite the simple requirements, there is often quite a lot of work involved: crafting a database to store results, writing a function to store the data to the database, one to verify submitted data (e.g. make sure that if you've asked for an e-mail address, it contains an @-sign), and marking up the form itself (which can be quite a task if you want to make correct use of <label>, <th scope="blah">, etc.

So I introduce my reusable form functions, with the rather unglamorous name of inc_surveytool.php v1.0.

They are far from finished (expect a 1.1 and a 2.0 version soon -- I have big plans for them). Despite being 1.0, I think there is still a lot of work to be done, and I'd like some feedback.

If you needed to sum them up in one pithy line: It's an entire programming language for creating and validating HTML forms.

Usage

Here is an example of what you can do with them:


<?php
include 'inc_surveytool.php';

print "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\"\n";
print "   \"http://www.w3.org/TR/html4/strict.dtd\">\n";
print "<title>Example Form</title>\n";

$widgets = "Form
mailto:me@example.com
multiplesubmissions=1
showsubmissions=0

Text 1 100 / /
name=Please enter your name:

Integer 1 150
age=Please enter your age:

Multi 1 3
statements=Which of these statements do you agree with?
1=Foo is good.
2=Bar is good.
3=Quux is good.
4=Flibble is good.
5=Blah is good.

GridSingle
satisfaction=Please rate the following.
Cols
1=Excellent
2=Good
3=Average
4=Poor
5=Rubbish
Rows
foo=Foo
bar=Bar
qux=Quux
flb=Flibble
blh=Blah

Units Volume 5
vol=How much do you like Foo?";

form_Main($widgets);
1?>

This will display a semantically marked-up (even nicely indented!) form containing:

  • an input for the user's name, which will be checked to be between 1and 100 digits, and checked that it matches the perl-compatible regular expression / / (i.e. it must contain a space character);
  • an input for the user's age, which will be checked to be an integer between 1 and 150 upon submission;
  • five checkboxes asking them what they agree with: they must tick between 1 and 3 boxes;
  • a table allowing the user to rate some things on a scale of 1 to 5;
  • an input allowing the user to enter a physical volume in a choice of kilolitre, litre, millilitre, brpint, fluidounce, m3, cm3, mm3 with m3 being the default.

When the form is submitted, it will be validated and e-mailed to me@example.com. The submission will be stored in a database. You would be able to visit the form, adding a query string "?adminscreen=1" to view the results. (Security is handled by editing a function called form_WhoisAdmin which can test for IP address, cookies, session data, etc.)

(Oh, and the physical volume I mentioned is converted to litres and stored in both the user's chosen units, and the converted units for easier sorting!)

If the users are logged in, or may be uniquely identified somehow (exactly how to identify each user is specified in function form_Whois, which can be customised for your own site) then it is possible to allow or disallow multiple submissions for one user, and to control what happens when there are multiple submissions (the new submission could over-write the old one, or the submissions could be stored alongside each other). Users returning to the form are able to view previous submissions.

Anyway, all this is only the tip of the iceberg -- it's a very flexible, very capable library of form-building functions.

The reason I post is that I'd like some other people to try it out and get a feel for how it works and what more is needed. I'd also like people to point out any obvious security flaws.

Requirements

  • PHP 4.3;
  • an SQL database (PostgreSQL supported, MySQL has been catered for, but not properly tested);
  • GNU Units ("/usr/bin/units") if you want to be able to use the Units widget.

There is almost zero documentation, so if you'd like to use it, do drop me an e-mail (mail at tobyinkster.co.uk) and I'll try to answer any questions. If there is demand, I might even set up a mailing list.