formcontrols/controls.php

Go to the documentation of this file.

<?php

// EVENT CONSTANTS

define('FC_EVENT_UPDATE', 1);
define('FC_EVENT_CLICK', 2);
define('FC_EVENT_SELECT', 4);
define('FC_EVENT_DESELECT', 8);


function gen_control_name($as_array = false) 
{
    $control_name = md5(uniqid(mt_rand(), true));
    if ($as_array)
        $control_name .= '[]';
    
    return $control_name;
}

function is_valid_control_name($name, $multiple = false) 
{
    if (!$multiple)
        return preg_match('#^\w+$#', $name);
    else
        return preg_match('#^\w+\[\]$#', $name);
}

function is_subclass($child, $parent) {
    if(is_string($child)) {
        $child = strtolower($child);
        $parent = strtolower($parent);
        do {
            if (!$child = get_parent_class($child))
                return false;
        } while ($child != $parent);
        return true;
    }

    return is_subclass_of($child, $parent);
}

function check_class($unknown, $base) 
{
    if (!class_exists($unknown))
        trigger_error("The class '$unknown' has not been declared", E_USER_ERROR);
    if (!is_subclass($unknown, $base))
        if ($unknown != $base)
            trigger_error("'$unknown' is not a '$base' or subclass thereof", E_USER_ERROR);
}

class XHTMLElement
{
    var $dom_document;
    var $node;
    var $serialise;

    function XHTMLElement($name) 
        {
            $this->dom_document = domxml_new_doc("1.0");
            $element = $this->dom_document->create_element($name);
            $this->node = $this->dom_document->append_child($element);            
        }

    function getElementName() 
        {
            return $this->node->node_name();
        }

    function getAttribute($name) 
        {
            return $this->node->get_attribute($name);
        }

    function setAttribute($name, $value)
        {
            $this->node->set_attribute($name, $value);
        }

    function setBooleanAttribute($name, $state) 
        {
            if ($state)
                $this->node->set_attribute($name, $name);
            else
                $this->removeAttribute($name);
        }

    function hasAttribute($name) 
        {
            return $this->node->has_attribute($name);
        }

    function removeAttribute($name) 
        {
            return $this->node->remove_attribute($name);
        }

    function toXHTML() 
        {
            return $this->dom_document->dump_node($this->node);
        }

    /***************************************************
     * Printable INTERFACE
     ***************************************************/

    function toString() 
        {
            return $this->toXHTML();
        }

    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/
    
    function __sleep() 
        {
            $this->serialise = $this->toXHTML();
            return array('serialise');
        }

    function __wakeup() 
        {
            $this->dom_document = domxml_open_mem($this->serialise);
            $this->node = $this->dom_document->document_element();
            $this->serialise = null;
        }
}

class ControlElement extends XHTMLElement 
{
    var $actions;
    var $events;
    var $display;
    
    function ControlElement($name, $control_name = null) 
        {
            $this->XHTMLElement($name);

            $control_name = gen_control_name($this->submitsMultipleValues());
            
            $this->setControlName($control_name);
            $this->setDisplay(true);
            $this->actions = array();
            $this->events = array();

            $this->addEvent(FC_EVENT_UPDATE);
        }    

    /***************************************************
     * Control INTERFACE
     ***************************************************/

    function getId() 
        {
            return $this->getAttribute('id');
        }

    function setId($id) 
        {
            $this->setAttribute('id', $id);
        }
    
    function isSimpleControl() 
        {
            return true;
        }
    
    function submitsMultipleValues() 
        {
            return false;
        }

    function display() 
        {
            return $this->display;
        }

    function setDisplay($display) 
        {
            if ($display)
                $this->display = true;
            else
                $this->display = false;
        }

    function disabled() 
        {
            return $this->hasAttribute('disabled');
        }

    function setDisabled($disabled) 
        {
            $this->setBooleanAttribute('disabled', $disabled);
        }
    
    function updated() 
        {
            return $this->eventHasOccurred(FC_EVENT_UPDATE);
        }

    function setUpdated($updated) 
        {
            if ($updated)
                $this->setEventHasOccurred(FC_EVENT_UPDATE, true);
            else
                $this->setEventHasOccurred(FC_EVENT_UPDATE, false);
        }

    function checkControlName($name) 
        {
            if (!is_valid_control_name($name, $this->submitsMultipleValues())) // ensure it's a valid name
                trigger_error("The name '$name' is not a valid control name", E_USER_ERROR);
        }

    function getControlName() 
        {
            return $this->getAttribute('name');
        }

    function setControlName($name) 
        {
            $this->checkControlName($name);
            $this->setAttribute('name', $name);
        }

    function getValue() 
        {
        }
    
    function setValue($value) 
        {
            $this->setUpdated(true);
        }    

    // ACTION HANDLING METHODS

    function addAction($event, $name, $callback) 
        {
            if ($this->actionExists($name))
                trigger_error("The action '$name' already exists", E_USER_ERROR);

            if (!is_callable($callback))
                trigger_error("The callback function to associate with the action '$name' is not valid", E_USER_ERROR);

            if (!$this->isValidEvent($event))
                trigger_error("The event to associate with the action '$name' is not valid", E_USER_ERROR);
            
            $this->actions[$name] = array($callback, $event, false);
        }

    function setActionTriggered($name, $state) 
        {
            if (!$this->actionExists($name))
                trigger_error("The action '$name' does not exist", E_USER_ERROR);

            $this->actions[$name][2] = ($state) ? true : false;
        }
    
    function actionTriggered($name) 
        {
            if ($this->actionExists($name))
                return $this->actions[$name][2];

            return false;
        }

    function &getAction($name) 
        {
            if ($this->actionExists($name))
                return $this->actions[$name][0];

            return false;
        }

    function getEvent($name) 
        {
            if ($this->actionExists($name))
                return $this->actions[$name][1];

            return false;
        }

    function getActionNames($event = 0) 
        {
            if (!$event)
                return array_keys($this->actions);

            if (!$this->isValidEvent($event))
                trigger_error("The event is not valid", E_USER_ERROR);

            $names = array();
            foreach (array_keys($this->actions) as $name) 
                {
                    if (($event ^ $this->getEvent($name)) !== 0)
                        $names[] = $name;
                }
            return $names;
        }

    function getActions($event = 0) 
        {
            $names = $this->getActionNames($event);
            $actions = array();
            foreach ($names as $name) 
                {
                    $actions[] =& $this->getAction($name);
                }
            
            return $actions;
        }
    
    function actionExists($name) 
        {
            return isset($this->actions[$name]);
        }

    function triggerAction($name) 
        {
            if (!$this->actionExists($name))
                trigger_error("The action '$name' does not exist", E_USER_ERROR);

            if ($this->actionTriggered($name))
                return false;
            
            $event = $this->getEvent($name);

            if (!$this->eventHasOccurred($event))
                return false;

            $this->setActionTriggered($name, true);

            $callback =& $this->getAction($name);
            return call_user_func($callback, &$this);
        }
    
    function removeAction($name) 
        {
            unset($this->actions[$name]);
        }

    function triggerActions() 
        {
            foreach ($this->getActionNames() as $action) 
                {
                    $this->triggerAction($action);
                }
        }

    // EVENT MANIPULATIONS

    function addEvent($event) 
        {
            if ($this->isValidEvent($event))
                trigger_error("The event is not valid", E_USER_ERROR);

            $this->events[$event] = false;
        }
    
    function eventHasOccurred($event) 
        {
            return $this->events[$event];
        }

    function setEventHasOccurred($event, $state) 
        {
            if (!$this->isValidEvent($event))
                trigger_error("The event is not supported", E_USER_ERROR);

            $this->events[$event] = ($state) ? true : false;

            // reset all the triggered state of all actions
            foreach ($this->getActionNames($event) as $action) 
                {
                    $this->setActionTriggered($action, false);
                }
        }
    
    function supportedEvents() 
        {
            $events = array_keys($this->events);
            $bits = 0;

            foreach ($events as $event) 
                {
                    $bits = $bits ^ $event;
                }
            
            return $bits;
        }
    
    function isValidEvent($event) 
        {
            return ($event & $this->supportedEvents()) !== 0;
        }

    function resetEvents() 
        {
            // reset the events to false
            $events = array_keys($this->events);
            
            foreach ($events as $event) 
                {
                    $this->setEventHasOccurred($event, false);
                }

            // reset the actions trigger state to false
            foreach ($this->getActionNames() as $action) 
                {
                    $this->setActionTriggered($action, false);
                }
        }

    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/

    function _processPOSTED($post) 
        {
            if ($post === null)    // catch common case
                return;

            if (!$this->submitsMultipleValues() and get_magic_quotes_gpc())
                $post = stripslashes($post);
            
            if ($post != $this->getValue()) {
                //debugVar($post);
                $this->setValue($post);
            }
        }
    
    function __wakeup() 
        {
            parent::__wakeup();
            
            $this->resetEvents();

            $name = $this->getControlName();

            if (substr($name, -2) == '[]') // get rid of the [] if there is one in the control name
                $name = substr($name, 0, -2);

            if (isset($_POST[$name]))
                $this->_processPOSTED($_POST[$name]);
            else
                $this->_processPOSTED(null);
        }

    function __sleep() 
        {
            $sleep_vars = parent::__sleep();
            array_push($sleep_vars, 'actions', 'display', 'events');
            return $sleep_vars;
        }
}

class TextArea extends ControlElement 
{
    function TextArea($value = '') 
        {
            $this->ControlElement('textarea');
            $this->setValue($value);
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/
    
    function getValue() 
        {
            return $this->node->get_content();
        }

    function setValue($value) 
        {
            $this->setUpdated(true);
            
            if ($this->node->has_child_nodes()) {
                $text_node = $this->node->first_child();
                return $text_node->set_content($value);
            }
            return $this->node->set_content($value);
        }
}

class Input extends ControlElement
{
    function Input($type, $control_name = null)
        {
            $this->ControlElement('input', $control_name);
            $this->setAttribute('type', $type);
        }
}

class ValueInput extends Input 
{
    function ValueInput($type, $control_name = null) 
        {
            $this->Input($type, $control_name);
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/

    function getValue() 
        {
            return $this->getAttribute('value');
        }

    function setValue($value) 
        {
            $this->setUpdated(true);

            $this->setAttribute('value', $value);
        }
}

class TextInput extends ValueInput
{
    function TextInput($value = null) 
        {
            $this->ValueInput('text');
            $this->SetValue($value);
        }
}

class PasswordInput extends ValueInput 
{
    function PasswordInput($value = null) 
        {
            $this->ValueInput('password');
            $this->SetValue($value);
        }
}

class HiddenInput extends ValueInput
{
    function HiddenInput($value = null) 
        {
            $this->ValueInput('hidden');
            $this->setValue($value);
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/

    function setDisabled($disabled)
        {
        }
}

class ClickedInput extends ValueInput 
{
    function ClickedInput($type, $value, $control_name = null) 
        {
            $this->ValueInput($type, $control_name);
            $this->setValue($value);

            $this->addEvent(FC_EVENT_CLICK);
        }

    function clicked() 
        {
            return $this->eventHasOccurred(FC_EVENT_CLICK);
        }

    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/

    function _processPOSTED($post) 
        {
            if ($post !== null) {
                $this->setEventHasOccurred(FC_EVENT_CLICK, true); // it's been clicked
                parent::_processPOSTED($post);
            } else {
                $this->setEventHasOccurred(FC_EVENT_CLICK, false);
            }
        }    
}

class SubmitInput extends ClickedInput 
{
    function SubmitInput($value) 
        {
            $this->ClickedInput('submit', $value);
        }
}

class ImageInput extends ClickedInput
{
    var $value;
    
    function ImageInput($src = null, $control_name = null) 
        {
            $this->ClickedInput('image', null);
            if ($src !== null)
                $this->setSrc($src);
        }

    function getXY() 
        {
            return array('x' => $this->value[0],
                         'y' => $this->value[1]);
        }

    function getX() 
        {
            return $this->value[0];
        }

    function getY() 
        {
            return $this->value[1];
        }

    /***************************************************
     * Image INTERFACE
     ***************************************************/

    function getSrc() 
        {
            return $this->getAttribute('src');
        }
    
    function setSrc($src) 
        {
            $this->setAttribute('src', $src);
        }

    
    /***************************************************
     * Control INTERFACE
     ***************************************************/

    function submitsMultipleValues() 
        {
            return true;
        }

    function getValue() 
        {
            return $this->value;
        }

    function setValue($value) 
        {
            if (!is_array($value)) {
                $this->value = array();
                return;
            }
            if (sizeof($value) != 2)
                trigger_error("The value array must consist of two elements", E_USER_ERROR);
            if (!is_numeric($value[0]) or !is_numeric($value[0]))
                trigger_error("The value elements must be numeric", E_USER_ERROR);

            $this->setUpdated(true);

            $this->value = $value;
        }
}

class EnhancedImageInput extends ImageInput 
{
    var $enabled_src;
    var $disabled_src;
    
    function EnhancedImageInput($enabled_src, $disabled_src, $control_name = null)
        {
            $this->ImageInput($enabled_src, $control_name = null) ;
            $this->enabled_src = $enabled_src;
            $this->disabled_src = $disabled_src;
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/

    function setDisabled($disabled)
        {
            parent::setDisabled($disabled);

            $this->setSrc((!$this->disabled()) ? $this->enabled_src : $this->disabled_src);    
        }
    
    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/
    
    function __sleep() 
        {
            $sleep_vars = parent::__sleep();
            array_push($sleep_vars,
                       'enabled_src',
                       'disabled_src');
            return $sleep_vars;
        }
    
}

class ResetInput extends ValueInput
{
    function ResetInput($value) 
        {
            $this->ValueInput('reset');
            $this->setValue($value);
        }
}

class Option extends ControlElement 
{
    var $control_name;

    function Option($value, $label = null, $control_name = null) 
        {
            $this->ControlElement('option', $control_name);
            $this->setLabel($label);
            $this->setValue($value);

            $this->addEvent(FC_EVENT_SELECT);
            $this->addEvent(FC_EVENT_DESELECT);
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/

    function getValue() 
        {
            return $this->getAttribute('value');
        }

    function setValue($value) 
        {
            $this->setUpdated(true);

            $this->setAttribute('value', $value);
        }

    // OVERRIDDEN Control ELEMENT METHODS
    
    function getControlName() 
        {
            return $this->control_name;
        }

    function setControlName($name) 
        {
            $this->checkControlName($name);
            $this->control_name = $name;
        }
    
    /***************************************************
     * SelectableControl INTERFACE
     ***************************************************/

    function getLabel() 
        {
            return $this->node->get_content();
        }

    function setLabel($label) 
        {
            if ($this->node->has_child_nodes()) {
                $text_node = $this->node->first_child();
                return $text_node->set_content($label);
            }
            return $this->node->set_content($label);
        }

    function selected() 
        {
            return $this->hasAttribute('selected');
        }
    
    function select() 
        {
            $this->setBooleanAttribute('selected', true);
            $this->setEventHasOccurred(FC_EVENT_SELECT, true);
            $this->setEventHasOccurred(FC_EVENT_DESELECT, false);
        }
    
    function deselect() 
        {
            $this->setBooleanAttribute('selected', false);
            $this->setEventHasOccurred(FC_EVENT_DESELECT, true);
            $this->setEventHasOccurred(FC_EVENT_SELECT, false);
        }

    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/
    
    function __sleep() 
        {
            $sleep_vars = parent::__sleep();
            array_push($sleep_vars, 'control_name');
            return $sleep_vars;
        }
}

class SingleOption extends Option 
{
    function SingleOption($value, $label = null, $control_name = null) 
        {
            $this->Option($value, $label, $control_name);
        }

    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/

    function _processPOSTED($post) 
        {
            //debugVar($post);

            // don't alter the state if there isn't any post
            if ($post === null)
                return;

            // update the selection state
            if ($post == $this->getValue()) {
                if (!$this->selected())
                    $this->select();
            } elseif ($this->selected()) {
                $this->deselect();
            }
        }
}

class MultipleOption extends Option 
{
    function MultipleOption($value, $label = null, $control_name = null) 
        {
            $this->Option($value, $label, $control_name);
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/
    
    function submitsMultipleValues() 
        {
            return true;
        }

    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/

    function _processPOSTED($post) 
        {
            //debugVar($post);

            if ($post === null) // catch the common case
                return;

            if (is_array($post)) {
                if (in_array($this->getValue(), $post)) {
                    if (!$this->selected()) {
                        $this->select();
                    }
                    return;
                }
            }

            $this->deselect();            
        }
}

class CheckedInput extends ValueInput
{
    var $label;
    
    function CheckedInput($type, $label = null, $control_name = null) 
        {
            $this->ValueInput($type, $control_name);
            $this->setLabel($label);

            $this->addEvent(FC_EVENT_SELECT);
            $this->addEvent(FC_EVENT_DESELECT);
        }
    
    /***************************************************
     * SelectableControl INTERFACE
     ***************************************************/

    function getLabel() 
        {
            return $this->label;
        }

    function setLabel($label) 
        {
            $this->label = $label;
        }
    
    function selected() 
        {
            return $this->hasAttribute('checked');
        }
    
    function select()
        {
            $this->setBooleanAttribute('checked', true);
            $this->setEventHasOccurred(FC_EVENT_SELECT, true);
            $this->setEventHasOccurred(FC_EVENT_DESELECT, false);
        }
    
    function deselect() 
        {
            $this->setBooleanAttribute('checked', false);
            $this->setEventHasOccurred(FC_EVENT_DESELECT, true);
            $this->setEventHasOccurred(FC_EVENT_SELECT, false);
        }

    /***************************************************
     * Printable INTERFACE
     ***************************************************/

    function toString() 
        {
            $xhtml = $this->toXHTML();
            $label = $this->getLabel();
            $id = $this->getId();
            
            return sprintf('%s&nbsp;<label for="%s">%s</label>', $xhtml, $id, $label);
        }
    
    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/

    function __sleep() 
        {
            $sleep_vars = parent::__sleep();
            array_push($sleep_vars, 'label');
            return $sleep_vars;
        }
}


class RadioInput extends CheckedInput
{
    function RadioInput($value, $label = null, $control_name = null) 
        {
            $this->CheckedInput('radio', $label, $control_name);
            $this->setValue($value);
        }

    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/

    function _processPOSTED($post) 
        {
            //debugVar($post);

            // don't alter the state if there isn't any post
            if ($post === null)
                return;

            // update the selection state
            if ($post == $this->getValue()) {
                if (!$this->selected())
                    $this->select();
            } elseif ($this->selected()) {
                $this->deselect();
            }
        }
}

class CheckboxInput extends CheckedInput 
{
    function CheckboxInput($value, $label = null, $control_name = null) 
        {
            $this->CheckedInput('checkbox', $label, $control_name, true);
            $this->setValue($value);
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/

    function submitsMultipleValues() 
        {
            return true;
        }

    /***************************************************
     * Printable INTERFACE
     ***************************************************/

    function toString() 
        {
            $string = parent::toString();
            return $string .= sprintf('<input type="hidden" name="%s" value="">', $this->getControlName());    // this is required so that a value is posted even if all checkboxes with this name are deselected
        }    
    
    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/

    function _processPOSTED($post) 
        {
            //debugVar($post);

            if ($post === null) // catch the common case
                return;

            if (is_array($post)) {
                if (in_array($this->getValue(), $post)) {
                    if (!$this->selected()) {
                        $this->select();
                    }
                    return;
                }
            }

            $this->deselect();            
        }

}

class FileInput extends Input 
{
    var $filename;
    
    function FileInput() 
        {
            $this->Input('file');
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/

    function getValue() 
        {
            return $this->filename;
        }

    function setValue($value) 
        {
            $this->setUpdated(true);

            $this->filename = $value;
        }

    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/
    
    function __wakeup() 
        {
            parent::__wakeup();

            $name = $this->getControlName();
            $matches = preg_split('#\[(\w+|\d+)\]#', $name, -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY);
            if (sizeof($matches) == 0)
                return;
            
            //debugVar($matches);
            $root_name = array_shift($matches);
            if (!isset($_FILES[$root_name]))
                return;
            
            $files =& $_FILES[$root_name];
            $upload_data = array();

            foreach ($files as $info => $content) 
                {
                    if (!is_array($content)) {
                        $upload_data[$info] = $content;
                        continue;
                    }
                        
                    $final_val =& $content;
                    foreach ($matches as $value) {
                        //debugVar($post);
                        if (isset($final_val[$value])) {
                            $final_val =& $final_val[$value];
                        }
                    }
                    $upload_data[$info] = $final_val;
                }

            $filename = $upload_data['tmp_name'].'/'.$upload_data['name'];
            if (is_uploaded_file($upload_data['tmp_name']))
                $this->setValue($filename);
        }
}

class ControlContainer 
{
    var $controls;
    var $trigger_order;

    function ControlContainer() 
        {
            $this->controls = array();
            $this->trigger_order = array();
        }

    /***************************************************
     * Container INTERFACE
     ***************************************************/

    function &get($id)
        {
            if (!$this->exists($id))
                trigger_error("The id '$id' does not exist", E_USER_ERROR);
            return $this->controls[$id];
        }

    function &getByValue($value) 
        {
            foreach ($this->getAllControls() as $control) 
                {
                    if ($control->submitsMultipleValues()) {
                        if (in_array($value, $control->getValue()))
                            return $control->getByValue($value);
                    } elseif ($control->getValue() == $value) {
                        return $control;
                    }
                }
            return null;
        }
    
    function add(&$control) 
        {
            $id = $control->getId();
            if (!strlen($id))
                trigger_error("The control does not have an id", E_USER_ERROR);

            if ($this->exists($id))
                trigger_error("The id '$id' already exists", E_USER_ERROR);

            $this->controls[$id] =& $control;            

            $this->trigger_order[] = $control->getId();
        }    

    function exists($id) 
        {
            return isset($this->controls[$id]);
        }

    function count() 
        {
            return sizeof($this->controls);
        }

    function &remove($id) 
        {
            if (!$this->exists($id))
                return false;
            $control =& $this->get($id);
            unset($this->controls[$id]);

            $trigger_count = sizeof($this->trigger_order);
            for ($i = 0; $i < $trigger_count; $i++) {
                if ($this->trigger_order[$i] == $id) {
                    if ($i == 0)
                        array_shift($this->trigger_order);
                    elseif ($i == $trigger_count - 1)
                        array_pop($this->trigger_order);
                    else {
                        $this->trigger_order = array_merge(array_slice($this->trigger_order, 0, $i), array_slice($this->trigger_order, $i+1));
                    }
                }
            }

            return $control;
        }

    function getAllIds() 
        {
            return array_keys($this->controls);
        }

    function getAllControls() 
        {
            $controls = array();

            foreach ($this->getAllIds() as $id) 
                {
                    $controls[] =& $this->controls[$id];
                }
            
            return $controls;
        }    

    function getDisplayableIds() 
        {
            $displayable = array();
            
            foreach ($this->getAllIds() as $id) 
                {
                    if ($this->childDisplay($id))
                        $displayable[] = $id;
                }

            return $displayable;
        }
    
    function getDisplayableControls() 
        {
            $displayable = array();

            foreach ($this->getDisplayableIds() as $id) 
                {
                    $displayable[] =& $this->get($id);
                }

            return $displayable;
        }

    // UTILITY METHODS

    function childDisplay($id) 
        {
            $control =& $this->get($id);
            return $control->display();            
        }
    
    function childToString($id) 
        {
            $control =& $this->get($id);
            return $control->toString();
        }

    function childUpdated($id) 
        {
            $control =& $this->get($id);
            return $control->updated();
        }
    
    // ACTION MANIPULATIONS
    
    function triggerChildActions() 
        {
            foreach ($this->getTriggerOrder() as $id) 
                {
                    $control =& $this->get($id);
                    $control->triggerActions();
                }
        }
    
    function getTriggerOrder() 
        {
            return $this->trigger_order;
        }

    function setTriggerOrder($order) 
        {
            $control_count = $this->count();
            
            if (sizeof($order) != $control_count)
                trigger_error('the action order does not contain the same number of elements as there are controls');

            if (sizeof(array_unique($order)) != $control_count)
                trigger_error("The action order does not consist of unique values", E_USER_ERROR);
            
            $new_order = array();
            foreach ($order as $id) 
                {
                    if (!$this->exists($id))
                        trigger_error("A control with id '$id' does not exist", E_USER_ERROR);
                    
                    $new_order[] = $id;
                }
            $this->order = $new_order;
        }

    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/

    function __sleep() 
        {
            return array('controls', 'trigger_order');            
        }
}

class ControlChoice extends ControlContainer
{
    var $control_name;
    var $id;
    var $control_class;
    var $actions;
    var $selected;
    var $display;
    var $events;

    function ControlChoice($control_class, $choice) 
        {            
            $this->ControlContainer();
            $control_name = gen_control_name($this->submitsMultipleValues());
            $this->setControlName($control_name);
            $this->setDisplay(true);
            $this->actions = array();
            $this->selected = array();
            $this->events = array();

            $this->addEvent(FC_EVENT_UPDATE);

            $this->setControlClass($control_class);
            
            if (is_array($choice)) {
                $values = array();

                foreach ($choice as $id => $object)
                    {

                        $label = $value = null;
                        if (is_array($object)) {
                            if (sizeof($object) > 1) {
                                $label = $object[0];
                                $value = $object[1];
                            } else {
                                $label = $id;
                                $value = $object[0];
                            }
                        } else {
                            $label = $object;
                            $value = $id;
                        }

                        if (in_array($value, $values))
                            trigger_error("Bad value for id '$id'; the value is not unique", E_USER_ERROR);

                        array_push($values, $value);
                        
                        $control =& new $control_class($value, $label, $control_name);
                        $control->setId($id);
                        $this->add($control);        
                    }
            }

        }
    
    /***************************************************
     * Control INTERFACE
     ***************************************************/

    function isSimpleControl() 
        {
            return false;
        }

    function submitsMultipleValues() 
        {
            return false;
        }

    function display() 
        {
            return $this->display;
        }

    function setDisplay($display) 
        {
            if ($display)
                $this->display = true;
            else
                $this->display = false;
        }
    
    function checkControlName($name) 
        {
            if (!is_valid_control_name($name, $this->submitsMultipleValues())) // ensure it's a valid name
                trigger_error("The name '$name' is not a valid control name", E_USER_ERROR);
        }

    function setControlName($name) 
        {
            $this->checkControlName($name);
            $this->control_name = $name;

            foreach ($this->getAllIds() as $id) 
                {
                    $control =& $this->get($id);
                    $control->setControlName($name);
                }
        }

    function getControlName() 
        {
            return $this->control_name;
        }
    
    function updated() 
        {
            return $this->eventHasOccurred(FC_EVENT_UPDATE);
        }
    
    function getId() 
        {
            return $this->id;
        }

    function setId($id) 
        {
            $this->id = $id;
        }    

    function getValue() 
        {
        }

    function setValue($value) 
        {
        }
    
    // ACTION HANDLING METHODS

    function addAction($event, $name, $callback) 
        {
            if ($this->actionExists($name))
                trigger_error("The action '$name' already exists", E_USER_ERROR);

            if (!is_callable($callback))
                trigger_error("The callback function to associate with the action '$name' is not valid", E_USER_ERROR);

            if (!$this->isValidEvent($event))
                trigger_error("The event to associate with the action '$name' is not valid", E_USER_ERROR);
            
            $this->actions[$name] = array($callback, $event, false);
        }

    function setActionTriggered($name, $state) 
        {
            if (!$this->actionExists($name))
                trigger_error("The action '$name' does not exist", E_USER_ERROR);

            $this->actions[$name][2] = ($state) ? true : false;
        }
    
    function actionTriggered($name) 
        {
            if ($this->actionExists($name))
                return $this->actions[$name][2];

            return false;
        }

    function &getAction($name) 
        {
            return $this->actions[$name][0];
        }

    function getEvent($name) 
        {
            return $this->actions[$name][1];
        }

    function getActionNames($event = 0) 
        {
            if (!$event)
                return array_keys($this->actions);

            if (!$this->isValidEvent($event))
                trigger_error("The event is not valid", E_USER_ERROR);

            $names = array();
            foreach (array_keys($this->actions) as $name) 
                {
                    if (($event ^ $this->getEvent($name)) !== 0)
                        $names[] = $name;
                }
            return $names;
        }

    function getActions($event = 0) 
        {
            $names = $this->getActionNames($event);
            $actions = array();
            foreach ($names as $name) 
                {
                    $actions[] =& $this->getAction($name);
                }
            
            return $actions;
        }
    
    function actionExists($name) 
        {
            return isset($this->actions[$name]);
        }

    function triggerAction($name) 
        {
            if (!$this->actionExists($name))
                trigger_error("The action '$name' does not exist", E_USER_ERROR);

            if ($this->actionTriggered($name))
                return false;
            
            $event = $this->getEvent($name);

            if (!$this->eventHasOccurred($event))
                return false;

            $this->setActionTriggered($name, true);

            $callback =& $this->getAction($name);
            return call_user_func($callback, &$this);
        }
    
    function removeAction($name) 
        {
            unset($this->actions[$name]);
        }

    function triggerActions() 
        {
            foreach ($this->getActionNames() as $action) 
                {
                    $this->triggerAction($action);
                }

            $this->triggerChildActions();
        }

    // EVENT MANIPULATIONS

    function addEvent($event) 
        {
            if ($this->isValidEvent($event))
                trigger_error("The event is already exists", E_USER_ERROR);

            $this->events[$event] = false;
        }

    function eventHasOccurred($event) 
        {
            if ($event & FC_EVENT_UPDATE) {
                $current_selected = $this->getSelectedIds();

                // if the array lengths are different then an update has occurred
                if (sizeof($current_selected) != sizeof($this->selected))
                    $this->setEventHasOccurred(FC_EVENT_UPDATE, true);

                // are the contents different?
                if (sizeof(array_diff($current_selected, $this->selected)))
                    $this->setEventHasOccurred(FC_EVENT_UPDATE, true);
            }

            return $this->events[$event];
        }

    function setEventHasOccurred($event, $state) 
        {
            if (!$this->isValidEvent($event))
                trigger_error("The event is not supported", E_USER_ERROR);

            $this->events[$event] = ($state) ? true : false;

            // reset all the triggered state of all actions
            foreach ($this->getActionNames($event) as $action) 
                {
                    $this->setActionTriggered($action, false);
                }
        }
    
    function supportedEvents() 
        {
            $events = array_keys($this->events);
            $bits = 0;

            foreach ($events as $event) 
                {
                    $bits = $bits ^ $event;
                }
            
            return $bits;
        }
    
    function isValidEvent($event) 
        {
            return ($event & $this->supportedEvents()) !== 0;
        }

    function resetEvents() 
        {
            // reset the events to false
            $events = array_keys($this->events);
            
            foreach ($events as $event) 
                {
                    $this->setEventHasOccurred($event, false);
                }

            // reset the actions trigger state to false
            foreach ($this->getActionNames() as $action) 
                {
                    $this->setActionTriggered($action, false);
                }
        }

    /***************************************************
     * Container INTERFACE
     ***************************************************/

    function add(&$control) 
        {
            parent::add($control);
            $control->setControlName($this->getControlName());
        }

    /***************************************************
     * Choice INTERFACE
     ***************************************************/
    
    function setControlClass($control_class) 
        {
            $this->control_class = $control_class;
        }
    
    
    function getControlClass() 
        {
            return $this->control_class;
        }
    
    function &addChoice($value, $label = null, $selected = false) 
        {
            $control_class = $this->getControlClass();
            $choice =& new $control_class($value, $label, $this->getControlName());
            $choice->setId($value);

            if ($selected)
                $choice->select();

            $this->add($choice);
            return $choice;
        }    
    
    function getSelectedIds() 
        {
            $selected_ids = array();
            foreach ($this->getAllIds() as $id) 
                {
                    if ($this->selected($id))
                        array_push($selected_ids, $id);
                }
            return $selected_ids;
        }

    function getSelectedControls() 
        {
            $selected_controls = array();
            foreach ($this->getSelectedIds() as $id) 
                {
                    $selected_controls[] =& $this->get($id);
                }
            return $selected_controls;
        }
    
    function selectedCount() 
        {
            return sizeof($this->getSelectedIds());
        }
    
    function select($id) 
        {
            $control =& $this->get($id);
            return $control->select();
        }

    function selected($id) 
        {
            $control =& $this->get($id);
            return $control->selected();
        }
    
    function deselect($id) 
        {
            $control =& $this->get($id);
            return $control->deselect();
        }


    /***************************************************
     * Printable INTERFACE
     ***************************************************/

    function toString() 
        {
            $strings = array();

            foreach ($this->getDisplayableControls() as $control) 
                {
                    array_push($strings, $control->toString());
                }

            return implode('<br/>', $strings);
        }


    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/

    function __wakeup() 
        {
            $this->resetEvents();
        }
    
    function __sleep() 
        {
            $this->selected = $this->getSelectedIds();

            $sleep_vars = parent::__sleep();
            array_push($sleep_vars, 'control_name', 'id', 'control_class', 'actions', 'selected', 'display', 'events');
            return $sleep_vars;
        }
}

class SingleChoice extends ControlChoice 
{
    
    function SingleChoice($control_class, $choice) 
        {
            $this->ControlChoice($control_class, $choice);
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/

    function getValue() 
        {
            $selected = $this->getSelectedControls();
            if (sizeof($selected) == 1)
                return $selected[0]->getValue();
            return null;
        }
    
    /***************************************************
     * Choice INTERFACE
     ***************************************************/

    function select($id) 
        {
            parent::select($id);

            foreach ($this->getSelectedIds() as $selected_id) 
                {
                    if ($id != $selected_id)
                        $this->deselect($selected_id);
                }
        }
}

class RadioChoice extends SingleChoice 
{
    function RadioChoice($choice, $radio_class = 'RadioInput') 
        {
            check_class($radio_class, 'RadioInput');
            
            $this->SingleChoice($radio_class, $choice);
        }    
}

class MultipleChoice extends ControlChoice 
{
    function MultipleChoice($control_class, $choice) 
        {
            $this->ControlChoice($control_class, $choice);
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/
    
    function submitsMultipleValues() 
        {
            return true;
        }

    function getValue() 
        {
            $selected = array();
            foreach ($this->getSelectedControls() as $control) 
                {
                    $selected[] = $control->getValue();
                }
            return $selected;
        }
    
}

class CheckboxChoice extends MultipleChoice 
{
    function CheckboxChoice($choice, $checkbox_class = 'CheckboxInput') 
        {
            check_class($checkbox_class, 'CheckboxInput');

            $this->MultipleChoice($checkbox_class, $choice);
        }
}


class SelectElement extends ControlElement
{
    var $controlchoice;
    
    function SelectElement($choice = null) 
        {
            if ($this->submitsMultipleValues())
                $this->controlchoice = new MultipleChoice('MultipleOption', $choice);
            else
                $this->controlchoice = new SingleChoice('SingleOption', $choice);
            
            $this->ControlElement('select', $this->controlchoice->getControlName());
        }

    function setAttribute($name, $value)
        {
            if ($name == 'multiple') {
                if ($this->submitsMultipleValues() and $this->hasAttribute('multiple')) // check to see if we can set the attribute. Can only be set once, in the constructor.
                    trigger_error("The 'multiple' attribute cannot be changed", E_USER_ERROR);
            }

            parent::setAttribute($name, $value);
        }

    function toXHTML() 
        {
            $dom_document = $this->dom_document->clone_node(true);
            $root = $dom_document->document_element();
            foreach ($this->getDisplayableControls() as $option) 
                {
                    $node = $option->node->clone_node(true);
                    $root->append_child($node);
                }
            
            return $dom_document->dump_node($root);            
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/
    
    function isSimpleControl() 
        {
            return false;
        }

    function submitsMultipleValues() 
        {
            return false;
        }
    
    function setId($id) 
        {
            parent::setId($id);
            $this->controlchoice->setId($id);
        }

    function getValue() 
        {
            return $this->controlchoice->getValue();
        }
    
    function setControlName($name) 
        {
            parent::setControlName($name);
            if ($this->controlchoice)
                $this->controlchoice->setControlName($name);
        }    

    function triggerActions() 
        {
            parent::triggerActions();
            $this->triggerChildActions();
        }

    function eventHasOccurred($event) 
        {
            if ($event == FC_EVENT_UPDATE) {
                $this->setEventHasOccurred(FC_EVENT_UPDATE, $this->controlchoice->eventHasOccurred(FC_EVENT_UPDATE));
            }
            
            return parent::eventHasOccurred($event);
        }
    
    /***************************************************
     * Choice INTERFACE
     ***************************************************/

    function setControlClass($control_class) 
        {
            $this->controlchoice->setControlClass($control_class);
        }
    
    
    function getControlClass() 
        {
            return $this->controlchoice->getControlClass();
        }
    
    
    function &addChoice($value, $label = null, $selected = false) 
        {
            return $this->controlchoice->addChoice($value, $label, $selected);
        }

    function selectedCount() 
        {
            return $this->controlchoice->selectedCount();
        }

    function getSelectedIds() 
        {
            return $this->controlchoice->getSelectedIds();
        }

    function getSelectedControls() 
        {
            return $this->controlchoice->getSelectedControls();
        }

    function select($id)
        {
            return $this->controlchoice->select($id);
        }

    function selected($id) 
        {
            return $this->controlchoice->selected($id);
        }

    function deselect($id)
        {
            return $this->controlchoice->deselect($id);
        }

    /***************************************************
     * Container INTERFACE
     ***************************************************/

    function triggerChildActions() 
        {
            $this->controlchoice->triggerChildActions();
        }
    
    function &getByValue($value) 
        {
            return $this->controlchoice->getByValue($value);
        }
    
    function &get($id) 
        {
            return $this->controlchoice->get($id);
        }

    function add(&$control) 
        {
            return $this->controlchoice->add($control);
        }

    function exists($id) 
        {
            return $this->controlchoice->exists($id);
        }

    function &remove($id) 
        {
            return $this->controlchoice->remove($id);
        }

    function getAllIds() 
        {
            return $this->controlchoice->getAllIds();
        }

    function getAllControls() 
        {
            return $this->controlchoice->getAllControls();
        }

    function getDisplayableIds() 
        {
            return $this->controlchoice->getDisplayableIds();
        }

    function getDisplayableControls() 
        {
            return $this->controlchoice->getDisplayableControls();
        }

    function childDisplay($id) 
        {
            return $this->controlchoice->display();            
        }
    
    function childToString($id) 
        {
            return $this->controlchoice->toString();
        }

    function childUpdated($id) 
        {
            return $this->controlchoice->updated();
        }    
    
    /***************************************************
     * Serialisation INTERFACE
     ***************************************************/

    function __wakeup() 
        {
            parent::__wakeup();

            // remove serialised options
            foreach ($this->node->child_nodes() as $node) 
                {
                    $node->unlink_node($node);
                }
        }
    
    function __sleep() 
        {
            $sleep_vars = parent::__sleep();
            array_push($sleep_vars, 'controlchoice');
            return $sleep_vars;
        }
}

class SingleSelect extends SelectElement 
{
    function SingleSelect($choice = null) 
        {
            $this->SelectElement($choice);
        }
}

class MultipleSelect extends SelectElement 
{
    function MultipleSelect($choice = null) 
        {
            $this->SelectElement($choice);
            $this->setBooleanAttribute('multiple', true);
        }

    /***************************************************
     * Control INTERFACE
     ***************************************************/

    function submitsMultipleValues() 
        {
            return true;
        }    

    /***************************************************
     * Printable INTERFACE
     ***************************************************/

    function toString() 
        {
            $string = parent::toString();
            return $string .= sprintf('<input type="hidden" name="%s" value="">', $this->getControlName());    // this is required so that a value is posted even if all options are deselected
        }
}

?>

---