Formation: web form automation library for PHP

version 0.9.4 <- MEANS BETA

Note: this code currently has a small bug in PHP 5. It's already fixed in the current version. I'll update this version soon.

Introduction
Examples
Download the source
Contact me
Potential future features
Change history

Introduction

Formation is a web form automation library. Given a form definition, it enables easy validation, processing, and generation of an HTML form.

This documentation is not complete (beta, after all). Currently, it just gives an example of what this code does, but it doesn't give full documentation of all of its features. For now, you'll have to read the code.

By the way, you may find this interesting: All the code you see on this page is the exact same code that's actually run on the page to display and process the form below. I store the code in strings and use them as the source for the highlighted source listings below, and I also eval them to execute the code they contain.

Examples

The best way to understand this is to see it in action. Here's one of the simplest forms possible, a login form. First, you include the Formation library:


<?php require_once('Formation.php');?>

Then, you define your form class.


<?php 

class logIn extends ActionForm{

    function construct(){

        $field = &new ActionField('username','Username');

        $field->required(true);

        $this->add($field);



        $field = &new ActionField('password','Password');

        $field->required(true);

        $this->add($field);



        $this->addSubmit('Log in');

    }

    function validate(){

        if($this->get('username') == 'username' and

            $this->get('password') == 'secretpassword'){

            return true;

        }else{

            $this->addError('Your username/password combination did not validate');

            return false;

        }

    }

    function process(){

        #$_SESSION['logged_in'] = true;

        # process() must return true or false to indicate success or failure

        return true;

    }

}

?>

As you can see, you create a class that inherits from ActionForm. Every form must override the construct and process functions. construct() defines all the fields in your form. process() is called automatically if the submitted form validates (as determined by the validate() method). Note that the code in the process() function is commented out because this code actually runs on this page if you submit the example login form, and I don't want you leaving session variables around :)

Here's the code you'd use to display the form defined above.


<?php 

$form->setWidget('password',FORMATION_PASSWORD);

$form->printDefaultForm('#form'); #makes the location of the form go to the #form anchor

?>

This displays the resulting form:

The above form actually works (try it!). You don't *have* to use the printDefaultForm() function in case you'd like to have more control over how the form is laid out, but I've tried hard to enable most common cases to be handled by printDefaultForm() without having to do more manually. Finally, the code that actually submits the form is as follows:


<?php $form = &new Formation($name='logIn');?>

Formation, upon instantiation, creates a logIn instance and submits it if the form has been submitted. You need to use the $name hack because PHP's references suck. It's not a big deal. Consider it a named parameter like they have in Python. Just make sure you're not already using the $name variable for something else. If you are, use another variable, since the name of what I call $name doesn't matter.

Download the source

Here's the raw source code (just one file), and if you want pretty colors, here's the syntax highlighted version. Remember... beta!

Contact me

If you find any bugs or have any feature requests, or just want to say "hi" or "thanks", please drop me a line.

Potential future features (to do)

Keyboard navigation: accesskeys (docs)
specify tab navigation order
A library of common form validation functions (e-mail addresses, credit cards)
Automatic duplicate submission protection
Possibly: addition of a "read only" mode for showing form submission results.
Possible Javascript usage:
- Maybe automatic client-side validation support
- specify initial input field focus
I have to investigate whether having some kind of templating situation (even if it's just plain PHP -- something like Smarty is certainly overkill), apart from just using PHP and the form library directly, is desirable
Allow elements to be disabled and readonly
For radio buttons and dropdowns for fields that *aren't* required, *maybe* have the option of having a "blank" field in addition to the rest of the fields. Big maybe.
Change setSize to size(), setWidget() to widget, and make a disabled() and readonly() function.
provide little-used form features like optgroups, file selects, and reset buttons

Change History

0.9 - April 23, 2004
- Initial release
0.9.2 - May 8, 2004
- Changed name of FormHelper class to Formation
- No need to assign the name of the action manually in construct(). It's now taken from the name of the action class
- The submit button(s) is now a field in the form itself. This is so you can perform actions based on multiple submit buttons. Correspondingly, added an addSubmit() function to the ActionForm class
- It is now possible to have Formation (formerly FormHelper) instantiate your action for you. The action (ActionForm) and the form (Formation) should still be separate classes so that you can use ActionForms separately, but most of the time you'll want to use them both together. So, you now don't need to instantiate an ActionForm directly, and Formation will do the form submission for you on initialization.
- Fixed bugs, I suppose. I know I did other things. I'll have to do a diff to find out everything I changed
- There were existing known bugs in this release. But, it's stable. I mainly wanted to release this to give myself a stable version to use live on my site while I make changes to the current source
0.9.4 - December 19, 2004
- Many changes
- Renamed constants from FormHelper... to Formation...
- Added support for the POST-Redirect-GET pattern
- Other changes I'll have to list here once I do a diff on the code and see what I changed since *May* :)

Page last edited: November 24, 2005 (utc)

Index

A B C D E F G H I J L M N O P R S T U V W X

All pages

A

B

C

D

E

F

G

H

Hex editors

I

J

L

M

N

O

P

R

S

T

U

V

W

X

Generated in about 0.058s.

(Used 5 db queries)

Keith Devens .com