cvs: pear /HTML_OOH_Form/container form_container.php

uw Mon Nov 19 20:04:17 2001 EDT Added files: /pear/HTML_OOH_Form/container form_container.php Log: Are you ready for some commits? This is a cool idea some AGI guys came up with on the php conference in germany last week: validation and the value of an element is no longer bound to the element but to a data container. This has several major advantages which I'll describe in the docs later on. Watch out: these commits will break the JavaScript support.

Index: pear/HTML_OOH_Form/container/form_container.php +++ pear/HTML_OOH_Form/container/form_container.php <?php /* vim: set expandtab tabstop=4 shiftwidth=4: */ // +----------------------------------------------------------------------+ // | PHP version 4.0 | // +----------------------------------------------------------------------+ // | Copyright (c) 1997, 1998, 1999, 2000, 2001 The PHP Group | // +----------------------------------------------------------------------+ // | This source file is subject to version 2.0 of the PHP license, | // | that is bundled with this package in the file LICENSE, and is | // | available at through the world-wide-web at | // | http://www.php.net/license/2_02.txt. | // | If you did not receive a copy of the PHP license and are unable to | // | obtain it through the world-wide-web, please send a note to | // | license@php.net so we can mail you a copy immediately. | // +----------------------------------------------------------------------+ // | Authors: Ulf Wendel <ulf.wendel@phpdoc.de> | // +----------------------------------------------------------------------+ // // $Id: form_container.php,v 1.1 2001/11/20 01:04:17 uw Exp $ /** * Framework of a container. * * @author Ulf Wendel <ulf.wendel@phpdoc.de> * @package HTML_OOH_Form * @version $Id: form_container.php,v 1.1 2001/11/20 01:04:17 uw Exp $ */ class form_container { /** * Value of the element. * * @var mixed $value */ var $value = ''; /** * Is the element frozen? * * @var boolean $frozen */ var $frozen = false; /** * Check for ... errors. * * @var array */ var $val_events = array( 'length' => true, 'valid' => true, 'intro' => true ); /** * List of (validation rule) slots that can be set by the constructor. * * @var array */ var $allowed_slots = array( 'value' => 'mixed', 'minlength' => 'int', 'maxlength' => 'int', 'length_e' => 'string', 'valid_regex' => 'string', 'valid_icase' => 'boolean', 'valid_e' => 'string', 'intro' => 'mixed', 'intro_e' => 'string' ); /** * Length error message. * * Error message used to indicate that the length of the value of the element * is eigther smaller than minlength or bigger than maxlength. If no message * is given the length gets not validated. Used together with maxlength * and minlength you can control the length of the user input. * * @var string Default: empty string => validation off * @see $minlength, $maxlength */ var $length_e = ''; /** * Minimal length of the value of the element ( = user input) * * @var integer * @see $length_e, $maxlength */ var $minlength = 0; /** * Maximum length of the value of the element ( = user input) * * Used as HTML attribute (only form_element_text) * as well as for the serverside validation. * * @var integer The default value of -1 means no limit. * @see $length_e, $minlength */ var $maxlength = -1; /** * Regular expression error message. * * Error message used to indicate that the value of the element * doesn't math the regular expression specified with valid_regex. * If no message is given the value gets not validated. Used with * valid_regex and optionally valid_icase you can make sure that * the user input follows certain rules, e.g. some that do * a simple e-mail validation. The RegExp must follow JavaScript (Perl 4) * and preg_* rules. * * @var string * @see $valid_regex, $valid_icase */ var $valid_e = ''; /** * Regular expression used to validate the value of the element ( = user input) * * @var string The default of an empty string means no validation * @see $valid_e, $valid_icase */ var $valid_regex = ''; /** * Regular expression validation case insensitive? * * @var boolean If set to true a case insensitive search is done. * @see $valid_e, $valid_regex */ var $valid_icase = false; /** * Perform a multiline search? * * @var boolean */ var $valid_global = false; function form_container($slots) { reset($slots); while (list($slot, $v) = each($slots)) if ('value' == $slot) $this->setValue($v); else if (isset($this->allowed_slots[$slot])) $this->$slot = $v; } // end constructor /** * Returns the value of an element. * * @param boolean true if the encoded version of the container value is requested * @return mixed value * @access public * @see setValue() */ function getValue($encoded = true) { return ($encoded) ? $this->encode($this->value) : $this->value; } // end func getValue() /** * Encodes the value of the container. * * The encode function is used to transform the value of the container into * a human readable format. * * @param mixed value to encode * @return mixed encoded value * @access public * @see decode(), getJSencode(), getJSdecode() */ function encode($value) { return $value; } // end func encode /** * JavaScript code used to encode the container value * * @return array [function code, function name] * @access public * @see encode(), decode(), getJSdecode() */ function getJSencode() { /* return array('function c_encode(v) { return v + " encoded "; }', 'c_encode'); */ return array('', ''); } // end func getJSencode /** * Decodes a userinput into a raw container value * * @param mixed value to decode * @return mixed decoded value * @access public * @see encode(), getJSencode(), getJSdecode() */ function decode($value) { return $value; } // end func decode /** * JavaScript decode function * * @return array [function code, function name] * @access public * @see decode(), encode(), getJSencode() */ function getJSdecode() { /* return array('function c_decode(v) { return v + " decoded "; }', 'c_decode'); */ return array('', ''); } // end func getJSdecode /** * Returns JavaScript validation parameters * * @param boolean true if the form contains custom validators * @return array * @access public */ function getJS($complex = false) { $eldata = ''; $events = ''; // Length validation: 'l', minlength, maxlength, 'length_e' if ($this->doValidation('length')) { $eldata .= sprintf('"l", %d, %d, "%s", ', $this->minlength, $this->maxlength, str_replace('"', '\"', $this->length_e) ); $events .= 'l'; } // RegExp validation: 'r', 'valid_regex', 'valid_modifier', 'valid_e' if ($this->doValidation('valid')) { $eldata .= sprintf('"r", "%s", "%s%s", "%s", ', str_replace('"', '\"', $this->valid_regex), ($this->valid_icase) ? 'i' : '', (isset($this->valid_global) && $this->valid_global) ? 'g' : '', str_replace('"', '\"', $this->valid_e) ); $events .= 'r'; } // Select / Intro validation: 'i', 'intro', 'intro_e' if ($this->doValidation('intro')) { reset($this->intro); list($intro_value, $intro_label) = each($this->intro); $eldata .= sprintf('"i", "%s", "%s", ', $intro_value, str_replace('"', '\"', $this->intro_e) ); $events .= 'i'; } return array($eldata, $events); } // end func getJS /** * Sets the value of the container * * @param mixed (raw) value * @param boolean true if the value has to be decoded * @access public * @see getValue() */ function setValue($value, $decode = true) { $this->value = ($decode) ? $this->decode($value) : $value; } // end func setValue /** * Freeze the container. * * @access public */ function freeze() { $this->frozen = true; } // end func freeze /** * Thaw out the object * * @access public */ function unfreeze() { $this->frozen = false; } // end func unfreeze /** * Returns the result of the (serverside) validation. * * @return string Error message if there is an error * @access public * @see validateLength(), validateRegEx(), doValidation() * @abstract */ function validate() { return ''; } // end func validate /** * Validate the length of the input value. * * @param mixed $value Optional value, if not specified $this->value gets used. * @return string $errormessage */ function validateLength($value = '') { $value = ($value) ? $value : $this->getValue(); if ($this->doValidation('length') && (strlen($value) < $this->minlength || ($this->maxlength >= 0 && strlen($value) > $this->maxlength))) return $this->length_e . ' '; return ''; } // end func validateLength /** * Compare the element value with the specified RegExp. * * @param mixed $value Optional value, if not specified $this->value gets used. * @return string $errormessage * @see validateLength() */ function validateRegEx($value = '') { if ($this->doValidation('valid')) { $reg = '/' . $this->valid_regex . '/'; if ($this->valid_icase) $reg .= 'i'; if ($this->valid_global) $reg .= 'm'; if (!preg_match($reg, ($value) ? $value : $this->getValue())) return $this->valid_e . ' '; } return ''; } // end func validateRegEx /** * Validate this event? * * @param string $event * @return boolean $ok * @throws form_error */ function doValidation($event) { if ('' == $event || !isset($this->val_events[$event])) { $this->exceptions[] = new form_error("Unknown event: '$event'", __FILE__, __LINE__); return false; } if (false == $this->val_events[$event] || true == $this->frozen) return false; $ok = false; switch (strtolower($event)) { case 'length': if ('' != $this->length_e && (0 != $this->minlength || $this->maxlength >= 0) ) $ok = true; break; case 'valid': if ('' != $this->valid_e && '' != $this->valid_regex) $ok = true; break; case 'intro': if ('' != $this->intro_e && '' != $this->intro) $ok = true; break; } return $ok; } // end func doValidation /** * Defines the events that will be validated. * * You can tell every (default) validator which 'events' * will be validated. This gives you detailed control * on a default validator in you dependencie validators. * 'Event' stands for some properties of an element (length, valid, intro) * as well as the used JavaScript event handler (js_onsubmit, * js_onchange) for the element. * * Using react() you can for example switch off the validation * of the RegExp (valid_e, valid_regexp) writing: * $formelement->react('valid', false); * * @param mixed $events Eighter a string with the name * of one 'event' or an array of 'events'. * Known 'events' are: all, length, valid, intro, * js_onsubmit, js_onchange. 'length' controls * length_e, minlength and maxlength, 'valid' controls * valid_e and valid_regexp and 'intro' controls 'intro', 'intro_e'. * 'js_onsubmit' and 'js_onchange' referr to the JavaScript * event handler. * @param boolean $status Optional, if set to true the specified 'events' will be validated, * otherwise validation is turned off (default: true = on) * @return boolean $ok Returns false if no valid events where found. * @throws form_error * @access public * @see $val_events */ function react($events, $status = true) { if ('all' == $events) $events = $this->val_events; if (!is_array($events) && isset($this->val_events[$events])) $events = array($events => $events); if (!is_array($events)) { $this->exceptions[] = new form_error("Unknown event '$events'.", __FILE__, __LINE__); return false; } $status = ($status) ? true : false; $ok = true; foreach ($events as $event => $v) if (isset($this->val_events[$event])) $this->val_events[$event] = $status; else $ok = false; return $ok; } // end func react } // end class form_container ?>