FormControls PHP Package

1.0

The FormControls package provides a set of widgets representing HTML form controls.

Description

The Problem

The FormControls package addresses the web development problem of having to keep track of HTML form submissions that are POSTED in a persistent application. That is, an application has a form control (e.g. a text input box) who's value it needs to check and which it needs recreate on subsequent pages.

The normal process for doing this is to check for a POSTed variable corresponding to the control. If this value has changed from the previous value, then the application processes the new value appropriately and then outputs it in the HTML for the refreshed page.

The problem with this approach is that an application has to deal with repetitive logic that detracts from the problem it is trying to solve. Ideally, an application would only need to be informed when a value has changed, and then act on the new data. Unfortunately it also has to keep checking POSTed values, managing where they come from and how they are displayed to the user.

A Solution

FormControls attempts to solve this problem by providing a pseudo event driven model to HTML form controls. It does this by defining objects that represent the various controls. These objects support a variety of events, including an update event. They provide the ability to associate callback functions (actions) with particular events. Whenever a control object detects that an event has occurred (for example the value of it's form field has been updated), it triggers off all its actions that are associated with the event in question.

This model is termed pseudo event driven because the web is inherently stateless in nature. In a GUI application an event can be triggered the instant a user interacts with an application control. With the web, however, a user's interactions with a form are only detectable by PHP once the form has been POSTed to the server. FormControls' widgets, therefore, automatically check whether events have occurred when they are unserialised. The reasoning behind this is that an application would maintain a session with control widgets as session variables. The session variables are automatically serialised at the end of a session script and unserialised at the beginning. Thus an application only needs instantiate its widgets (with whatever actions required) at the beginning of a session. Thereafter it will be informed automatically when a user interacts with a widget.

Usage

Although somewhat contrived, the following self contained example demonstrates basic usage of the package.

<?php

require_once('formcontrols/controls.php');

// A class managing the data we are interested in
class Person 
{
    var $name = null;

    // An action setting the  name from a control
    function setName(&$control) 
        {
            print "Setting your  name...<br/>";
            $this->name = $control->getValue();
        }

    // is the data valid?
    function isValidPerson() 
        {
            return $this->name;
        }
}

// if this is not the first time the session is started, the control
// widgets will update themselves with any data posted by their form
// control.
session_start();

// check to see whether we need to initialise our application
if (!session_is_registered('person')) 
{
    // initialise our data handler
    $_SESSION['person'] = new Person();

    // initialise our control widgets
    $name_control = new TextInput();

    // associate actions and related events with the control widgets
    $name_control->addAction(FC_EVENT_UPDATE,
                             'set_name',
                             array(&$_SESSION['person'], 'setName'));

    // add the widgets to the session
    $_SESSION['name_control'] = &$name_control;
} else {
    // trigger the actions of any events that may have occurred
    $_SESSION['name_control']->triggerActions();
}

// check if our data is valid and do something with it
if ($_SESSION['person']->isValidPerson()) 
{
    printf("<p>Hello! I'm told you're called %s<br/>\n", $_SESSION['person']->name);
    print "Change your name if you'd like...<p/>\n";
}


print '<form method="post">';

// Output our controls ready for user interaction
printf("What is your  name? %s ", $_SESSION['name_control']->toString());

print '<input type="submit" value="name me!"/></form>';

?>

When running the code note that the action (setName()) is only called when the value in the text field is changed. The main application code, moreover, is only dealing with the data that it is interested in. It only has to deal with the control widgets when it needs the HTML.

The benefits of using FormControls pays dividends in larger projects.

Note:

The ControlBox class makes dealing with control widgets easier.

---