File Source for SForm.php

<?php
/**
* A fast & powerful PEAR_QuickForm replacement
*
* SForm is short for Seth's Form. Why? Because it's easy to remember, and even
* easier to type. SForm was started out of frusteration with PEAR's QuickForm.
* It was too slow, it wouldn't allow me to create complex rules, the code was
* antiquidated, it didn't nest groups, the API was convoluted, the list went
* on. After spending a few days wrestling with QF, I came to the realization
* that I could code my own package in the time it took me to figure out how to
* bend QuickForm to my will. So that's what I did.
*
* SForm automatically does the standard QF things, like {@link }
* SForm_Rule::toJavaScript() JavaScript generation}, rendering plugins, both
* server-side and {@link SForm_Element::validate() client side validation},
* and is very customizable. Some things not included in QF include non-
* enforced XHTML 1.1 compliance, {@link SForm_Elm_Select::lock()}
* intrinsic rules}, nested groups, and {@link }
* http://www.webstandards.org/learn/tutorials/accessible-forms/beginner/
* automatic accessibility features} like
* <label> tags, optgroups, JavaScript highlighting of errors, and access keys.
* I've tried to keep the API very similar to QuickForm, but I've removed things
* that I found unnecessary or redundant.
*
* SForm is also fast.
*
* The small form that I originally used to develop SForm had a render time of
* 0.10-0.28 seconds when no form was created. Using QuickForm to build a form
* on the page increased the render time to 0.33-0.68 secs. Replacing QuickForm
* with SForm dropped the render time to 0.18-0.42 secs. SForm is almost
* three times faster than QuickForm in this informal test. (All trials
* used eAccelerator with caching and optimization enabled.)
*
* Example:
*
* The SForm API is intentionally very similar to QuickForm. This example was
* converted directly from the {@link http://pear.php.net/manual/en/package.}
* html.html-quickform.tutorial.php QuickForm documentation}. All of the
* examples on {@link http://www.midnighthax.com/quickform.php Keith Edmunds's}
* QuickForm tutorial} also work with similar modifications. It should be noted
* that to make this example XHTML 1.1 compliant, the elements would need to be
* grouped in a fieldset.
*
* <code>
* <?php
* // Load the main classes
* require_once 'SForm.php';
*
* // Instantiate the SForm object
* $form = new SForm('firstForm');
*
* // Set defaults for the form elements
* $form->setDefaults(array( 'name' => 'Joe User' ));
*
* // Add some elements to the form
* $form->addElement('header', null, 'SForm tutorial example');
* $form->addElement('text', 'name', 'Enter your name:',
* array('size' => 50, 'maxlength' => 255));
* $form->addElement('submit', null, 'Send');
*
* // Define filters and validation rules
* $form->applyFilter('name', 'trim');
* $form->addRuleDep('name', 'Please enter your name', 'required', null,'client');
*
* // Try to validate a form
* if ($form->validate()) {
* echo '<h1>Hello, ' . htmlspecialchars($form->exportValue('name')) . '!</h1>';
* exit;
* }
*
* // Output the form
* $form->display();
* ?>
* </code>
*
*
* Note that in the example, addRule() has been changed to {@link }
* SForm::addRuleDep() addRuleDep()}, where 'Dep' stands for
* depriciated. For more information, see the {@link SForm_Rule}
* SForm_Rule documentation}.
*
* Putting it all together:
*
* {@example SForm_usage.php}
* Look in SForm_usage.php for this source
*
* Important differences with the QuickForm API include:
*
* - The construtor. The $target attribute {@link SForm::__construct() has been removed} because it breaks compliance with XHTML 1.1.
* - Rule creation and usage. SForm uses a much more object oriented {@link SForm_Rule Rule model}.
*
* Requirements:
*
* SForm requires at least PHP version 5, but version 5.1 is recommended.
*
* License:
*
* Copyright (c) 2006, Seth Price <{@link mailto:seth@pricepages.org seth@pricepages.org}> All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* - The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
* IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
* @copyright Copyright (c) 2006, Seth Price
* @author Seth Price <seth@pricepages.org>
* @license http://opensource.org/licenses/bsd-license.php New BSD License
* @access public
* @package SForm
* @see SForm::__construct()
* @version 0.1.2
*/
/**
* Document with:
* ./phpdoc -t ../docs -f ../scripts/SForm.php -d ../scripts/SForm -ti "SForm" -o HTML:frames:phpdoc.de
*
* @ignore
*/
/**
* FIXME - clean up exception messages and values.
* @deprecated
* @ignore
*/
define('FORM_ERR_PARENT_EXISTS', 1);
/**
* Create the count interface if needed
*
* The Countable interface is not enabled by default in PHP 5.0, so we'll
* enable it.
*
* @ignore
*/
if(!interface_exists('Countable')){
interface Countable{
public function count();
}
}
/**
* A element is a "leaf" that is actually rendered
*
* All elements and containers are decendents of this class. That said, this
* class is intended to cover as much common functionality as possible.
*
* @access public
* @package SForm
*/
abstract class SForm_Element {
/**
* This is the element's tag ('input', 'select', 'form', etc) and should be
* set by the children as needed.
*
* @var string
*/
protected $tag = 'input';
/**
* Is this element's tag empty?
*
* A tag is empty if it can't contain elements. Examples of empty tags
* include '<input />' and '<img />'. Non-empty tags include '<form>' and
* '<fieldset>'.
*
* @var boolean
*/
protected $emptyTag = true;
/**
* Should we add the 'name' attribute?
*
* @var boolean
*/
protected $addName = true;
/**
* What is the parent to this element?
*
* This points to some subclass of SForm_Container. It is set in
* SForm_Container::addElement().
*
* @var object
*/
protected $parent = null;
/**
* Has the value for this element been set?
*
* @var boolean
*/
protected $valueSet = false;
/**
* The local ID for this element
*
* @var string
*/
private $localId;
/**
* The cached Global ID for this element
*
* @var string
*/
private $globalId;
/**
* Is this element frozen?
*
* @var boolean
*/
private $frozen = false;
/**
* The label for this element
*
* @var string
*/
private $label;
/**
* Rules to apply to this element
*
* @var array
*/
protected $rules = array();
/**
* Are the rules & filters prevented from being modified?
*
* When the rules are rendered (or otherwise used), they are locked to
* prevent someone from adding an additonal rule. This would invalidate any
* calculations done using the previous ruleset.
*
* @var boolean
*/
protected $locked = false;
/**
* Is this a required element?
*
* If an element is marked as required, the 'required' rule is added at
* render time and modifications can be made to the label HTML which mark
* this element as required.
*
* @var boolean
*/
protected $required = false;
/**
* Has this element been validated?
*
* Validated elements have a finished $errors array and will not be
* validated again.
*
* @var boolean
*/
protected $validated = false;
/**
* A list of callback
*/
/**
* What were the results of the validation?
*
* All error strings returned by validation are saved here. If there is no
* error string, then there was no error.
*
* @var array
*/
protected $errors = array();
/**
* A list of filter callbacks
*
* @var array
* @see filter()
*/
protected $filters = array();
/**
* What access keys have been used already?
*
* The default ones are in use by various systems.
*
* @var array
* @todo Comment in which default keys come from which sources.
*/
private static $accesskeys = array(
'f' => true,
'e' => true,
'v' => true,
'g' => true,
'a' => true,
't' => true,
'h' => true,
'd' => true,
's' => true,
'b' => true,
'w' => true );
/**
* Number the elements if not given an ID
*
* @var integer
*/
static protected $defId = 0;
/**
* Attributes for this tag
*
* @var array
*/
protected $attributes = array();
/**
* Global settings
*
* Charset ('charset') is the the type of chars used to encode the HTML.
*
* Auto access key ('autoAccessKey') controls whether access keys are
* automatically assigned to labels.
*
* The element error color ('elmErrorColor') is the background color used on
* elements which threw some sort of error.
*
* Xml close ('xmlClose') alters how the HTML tags are drawn. Mainly, do
* empty tags end in ' />' (XML, XHTML) or '>' (HTML).
*
* Track id ('trackId') is the Local ID of the hidden element used to track
* this form.
*
* The separator ('separator') is used in the Global ID to create sub-groups
* of elements.
*
* The new submit value ('newSubmitValue') is what the JavaScript writes
* into the values of submit buttons when the form is successfully
* submitted.
*
* The maximum upload file size ('maxFileSize') is the maximum upload file
* size. It defaults to 2 MB, which is the PHP 'upload_max_filesize' default.
*
* @var array
* @see self::getLabelHtml()
* @see SForm_Renderer::rendJavaScript()
* @access public
*/
private static $options = array(
'charset' => 'UTF-8',
'autoAccessKey' => 'ak',
'elmErrorColor' => 'yellow',
'xmlClose' => true,
'trackId' => '_trk',
'separator' => '-', // Can be used in CSS selectors
'newSubmitValue' => ' Loading... ',
'maxFileSize' => '2097152',
'requiredSym' => '*');
/**
* The rules
*
* @var array
*/
private static $regRules = array(
'boolean' => array('SForm/Rule/Boolean.php', 'SForm_Rule_Boolean'),
'maxlength' => array(false, 'SForm_Rule_Maxlenth'),
'subset' => array(false, 'SForm_Rule_Subset'),
'required' => array(false, 'SForm_Rule_Required') );
/**
* Construct with an identity. Optionally add a label and more attributes.
*
* $id is the Local ID of this element, and is similar to its name. If none
* is supplied, one will be created. The Local ID is different than the 'id'
* attribute that appears in the rendered form. The id attribute is referred
* to as the Global ID, and is the concatenation of the parent's Global ID,
* a colon, and this Local ID. The ID must contain only chars acceptable in
* the ID SGML token for the resulting page to be valid.
*
* The $label is the the short string that describes this element. If it is
* rendered as HTML, it will automatically be enclosed in '<label>' tags
* which referr to the Global ID of this element. If enabled, an appropriate
* access key will also be found for this element. The access key will be
* rendered with '' and '' tags surrounding it. If
* you wish to communicate with your users that this access key may be used
* to access this field, I suggest that you use CSS like: '.ak{text-
* decoration:underline;}'.
*
* Any additonal $attributes may be added and will be displayed when the
* element is rendered as HTML.
*
* @param string Local ID of this element
* @param string Textual label for this element
* @param array Array of extra attributes
* @link http://www.w3.org/TR/html4/types.html#h-6.2
* @see getLocalId()
* @see getGlobalId()
* @see getLabel()
* @see getLabelHtml()
*/
public function __construct($id = null, $label = null, $attributes = null){
/*
* We should try to dynamically make this as needed from what the parent
* recommends (if avl). Also check the $attributes array for 'name' and
* 'id'.
*/
if($id === null){
$id = self::$defId++;
}
$this->localId = (string) $id;
$this->label = (string) $label;
//Apply each attribute
if(!empty($attributes)){
if(!is_array($attributes)){
throw new Exception('Please form attributes in array("attribute" ' .
'=> "value", ...) form. It\'s ' .
'much faster than parsing a string.');
}
foreach($attributes as $name => $value){
$this->setAttribute($name, $value);
}
}
}
/**
* This is the page-wide unique ID
*
* The Global ID is a page-unique id which is a concatination of the
* parent's Global ID, a colon, and the Local ID. This is done so that
* element groups can be nested arbitrarily deeply with non-uniqe IDs (ex:
* an array: '0','1','2'...).
*
* The Global ID is used as the 'id' HTML attribute and is typically also
* used as the 'name' attribute.
*
* The Global ID cannot be determined until the element is "rooted" to a
* SForm object.
*
* @return string A globally usable ID
*/
public function getGlobalId(){
if($this->globalId){
return $this->globalId;
}
if(empty($this->parent)){
throw new Exception('An element must have a parent, please assign me to one. I\'m lonely.');
}
return $this->globalId = $this->parent->getGlobalId().
self::getOption('separator').
$this->getLocalId();
}
/**
* A Locally usable ID
*
* The local ID is the name that a parent uses to identify its child
* element.
*
* @return string A locally usable ID
*/
public function getLocalId(){
return $this->localId;
}
/**
* The value of this element
*
* The value returned is the same as if the form was rendered, displayed,
* then submitted by the user, in its current state.
*
* @return mixed Element's current value
* @see setValue()
* @see setDefault()
* @uses $valueSet Is the current value overridden by setValue?
*/
public function getValue(){
//Return the set value
if($this->valueSet){
return $this->filterValue($this->getAttribute('value'));
}
//Return the value of whatever was submited
$val = $this->getRequest($this->getGlobalId());
if($val !== null){
$this->setValue($val);
return $this->filterValue($val);
}
//Return what we have
return $this->filterValue($this->getAttribute('value'));
}
/**
* Filters the value
*
* Filters a value that is about to be returned from {@link getValue()}.
*
* @var string Raw value
* @return string Filtered value
* @see getValue()
*/
protected function filterValue($val){
foreach($this->filters as $fil){
$func = $fil[0];
$fil[0] = $val;
$val = call_user_func_array($func, $fil);
}
return $val;
}
/**
* Set the value of this element
*
* This sets the current value of the element, overriding any current value.
*
* @param string Element's value.
* @see setDefault()
* @uses $valueSet Overrides any current value
*/
public function setValue($value){
$this->valueSet = true;
$this->setAttribute('value', $value);
}
/**
* Set the default value of this element
*
* This sets the default value of this element. If there is a user-submitted
* value or a {@link setValue()}, it overrides this one.
*
* @param string Element's value.
* @see setValue()
*/
public function setDefault($value){
if(!$this->valueSet){
$this->setAttribute('value', $value);
}
}
/**
* Markup a label with an accesskey
*
* Marks up the first char in a label with CSS that can show the user which
* key is the access key for this form. If none of the chars match the
* requested one, the char is appended to the end of the label in
* parenthesis.
*
* The class of the access key is set with the autoAccessKey option.
*
* @param string Label to be marked up
* @param string Selected char
* @return string Marked up string
*/
private function markupLabelAK($lbl, $ak){
$cls = self::getOption('autoAccessKey');
if(($i = stripos($lbl, $ak)) === false){
return self::escHtml($lbl).' ('.$ak.')';
} else {
/*
* We need to markup the access key, but escape HTML at the same
* time. It's more tricky than it sounds because we don't wan't to
* escape any chars in the HTML tags.
*/
$offset = strlen(self::escHtml(substr($lbl, 0, $i)));
$replen = strlen(self::escHtml(substr($lbl, $i, 1)));
$esc = self::escHtml($lbl);
return substr_replace($esc, ''.$lbl[$i].'', $offset, $replen);
}
}
/**
* Generates an access key and updated label
*
* Uses an access key to generate a marked up label.
*
* If access key is simply true, it generates an access key by searching
* through the chars of the label for the first one that is a regular char
* ([a-z0- 9]) and is not already in use. If none are found, numbers
* starting from the left side of the std keyboard are used.
*
* @param string Label
* @param string Requested access key
* @return mixed Array of updated label if possible, null otherwise
* @uses markupLabelAK() Markup the label with the found key
* @uses $accesskeys Determine which keys are used
*/
protected function autoAK($lbl, $ak){
//Use requested access key
if($ak !== true){
return array($ak, $this->markupLabelAK($lbl, $ak));
}
$lblLower = strtolower($lbl);
$len = strlen($lbl);
//Look for an access key in the label
for($i = 0; $i < $len; $i++){
$chr = $lblLower[$i];
//Only regular ASCII chars
if(ctype_alnum($chr) && !isset(self::$accesskeys[$chr])){
self::$accesskeys[$chr] = true;
return array($chr, $this->markupLabelAK($lbl, $chr));
}
}
//Look for an access key in numbers
for($i = 1; $i < 11; $i++){
$ak = (string) $i%10;
if(empty(self::$accesskeys[$ak])){
self::$accesskeys[$ak] = true;
return array($ak, $this->markupLabelAK($lbl, $ak));
}
}
//Give up
return null;
}
/**
* Return the label with markup added
*
* Generates the marked up 'label' tag. This includes the 'for' attribute,
* which links this label to the appropriate form element. The label allows
* software (and the people who use it) to understand the layout of your
* form without being able to view it. If the element is required, the value
* of option 'requiredSym' is appended to the beginning of the label.
*
* If requested, an access key is generated, and added to the tag. The
* access key links this label to a specific element. Not only does an
* access key make the page more friendly for people with motor
* disabilities, it will now be easier to quickly navigate the fields in
* your form for data entry.
*
* Access keys can be enabled, set, or disabled via the passed parameters.
* By default, $ak is true and an access key is generated. If a char is
* passed, that char is used as the access key and the label is marked up
* approriately. If false is passed, no access key is used.
*
* @param mixed Do we automatically generate an access key?
* @uses autoAK()
* @link http://www.webstandards.org/learn/tutorials/accessible-forms/beginner/
* @link http://alistapart.com/articles/accesskeys/
*/
public function getLabelHtml($accesskey = true){
$lbl = $this->getLabel();
//Nothing special when frozen (or non-existant)
if($lbl === '' || $this->isFrozen()){
return $lbl;
}
//If it has these attributes, we should be able to do some work transparently
if(self::getOption('autoAccessKey') && $accesskey && !$this->getAttribute('disabled')){
$ak = $this->autoAK($lbl, $accesskey);
} else {
$ak = null;
}
//Add the required symbol
if($this->required){
$req = self::getOption('requiredSym');
} else {
$req = '';
}
$id = $this->getGlobalId();
//Create and save the label
if($ak === null){
return $req.'<label for="'.$id.'">'.self::escHtml($lbl).'</label>';
} else {
return $req.'<label for="'.$id.'" accesskey="'.$ak[0].'">'.$ak[1].'</label>';
}
}
/**
* Return the label string (no markup)
*
* @return string The raw label
* @uses $label
*/
public function getLabel(){
return $this->label;
}
/**
* Locks & adds any last minute stuff
*
* This is here to be overridden as needed by subclasses to add any rules,
* filters, and values immidiately before they are locked. Remember to check
* if it's already locked first, because an element may be locked more than
* once.
*
* @uses $locked
*/
protected function lock(){
$this->locked = true;
}
/**
* Retrieve any JavaScript that should be run onsubmit
*
* Locks the rules and iterates through them to produce a JavaScript string
* appropriate to be run on submission of the form.
*
* @return string Rendered JavaScript
* @uses lock()
* @uses SForm_Rule::toJavaScript()
*/
public function toJavaScript(){
$this->lock();
if($this->isFrozen() || empty($this->rules)){
return '';
}
$js = '';
foreach($this->rules as $rule){
$js .= $rule->toJavaScript();
}
return $js;
}
/**
* Create a HTML representation of this element
*
* Creates a HTML tag appropriate to input a value for this element. At
* minimum, 'id' and 'name' attributes are included. Additonal attributes
* can be added via the methods appropriate for the element. Custom
* attributes can be added via setAttribute().
*
* If this element is frozen, the string representation is returned instead
* of an input field.
*
* @return string HTML
* @see setAttribute()
* @uses $attributes
*/
public function toHtml(){
if($this->isFrozen()){
return $this->toString();
}
$id = $this->getGlobalId();
$this->setAttribute('id', $id);
//Some elements can't have a name attribute
if($this->addName){
$this->setAttribute('name', $id);
}
if($this->emptyTag){
if(self::getOption('xmlClose')){
$slash = ' /';
} else {
$slash = '';
}
return '<'.$this->tag.self::getAttributesString($this->attributes).$slash.'>';
} else {
return '<'.$this->tag.self::getAttributesString($this->attributes).'>';
}
}
/**
* Close an open HTML tags
*
* @return string The HTML needed to close this element
* @see toHtml()
*/
public function toHtmlFin(){
if($this->emptyTag){
return '';
} else {
return '</'.$this->tag.'>';
}
}
/**
* Do we have any hidden tags to append?
*
* Append hidden tags seperately from regular HTML tags so they can be
* collected at the end of the form. That way the visible part of the form
* is parsed and displayed to the user first.
*
* By default, hidden elements are only generated when this element is
* frozen.
*
* @return string HTML of the hidden element
* @uses $attributes
*/
public function toHidden(){
if(!$this->isFrozen()){
return '';
}
$id = $this->getGlobalId();
$this->setAttribute('id', $id);
$this->setAttribute('name', $id);
if(self::getOption('xmlClose')){
$slash = ' /';
} else {
$slash = '';
}
return '<input type="hidden"'.self::getAttributesString($this->attributes).$slash.'>';
}
/**
* How does this value look as a HTML string?
*
* @return string HTML
* @uses getValue()
*/
function toString(){
return self::escHtml($this->getValue());
}
/**
* Set a global option
*
* All available options are pre-set in the {@link $options} array, so we
* will be avoiding some frusteration if we throw an error on a bad option
* selection. Otherwise, we could think that we are retrieving a null value,
* but we have just misspelled the index.
*
* @param string Option name
* @param string Option value
* @uses $options
*/
final public static function setOption($name, $value){
if(isset(self::$options[$name])){
self::$options[$name] = $value;
} else {
throw new Exception('The requested option "'.$name.'" doesn\'t exist.');
}
}
/**
* Get a global option
*
* All available options are pre-set in the {@link $options} array, so we
* will be avoiding some frusteration if we throw an error on a bad option
* selection. Otherwise, we could think that we are retrieving a null value,
* but we have just misspelled the index.
*
* @param string Option name
* @return string Option value
* @uses $options
*/
final public static function getOption($name){
if(isset(self::$options[$name])){
return self::$options[$name];
} else {
throw new Exception('The requested option "'.$name.'" doesn\'t exist.');
}
}
/**
* Set an attribute in $this
*
* @param string Attribute to set
* @param string Value to set (sets value = attribute if null)
* @uses $attributes
*/
public function setAttribute($attr, $value = null){
$attr = strtolower($attr);
if($value === null){
$this->attributes[$attr] = $attr;
} else {
$this->attributes[$attr] = (string) $value;
}
}
/**
* Unset an attribute
*
* @param string Attribute to unset
* @uses $attributes
*/
public function unsetAttribute($attr){
unset($this->attributes[strtolower($attr)]);
}
/**
* Get an attribute in $this
*
* @param string Attribute to get
* @return string Attribute's value
* @uses $attributes
*/
public function getAttribute($attr){
$attr = strtolower($attr);
if(isset($this->attributes[$attr])){
return $this->attributes[$attr];
} else {
return null;
}
}
/**
* Creates an HTML attribute string from an array
*
* @param array Attributes as: attribute => value
* @return string HTML string
*/
protected static function getAttributesString($attributes){
$str = '';
foreach($attributes as $attr => $value){
$str .= ' '.$attr.'="'.self::escHtml($value).'"';
}
return $str;
}
/**
* Escape HTML in a consistant manner
*
* @param string Text to escape
* @return string Text HTML escaped
*/
public static function escHtml($str){
return htmlspecialchars( $str,
ENT_QUOTES,
self::getOption('charset'));
}
/**
* Append this leaf element to the render queue
*
* The renderer is passed to this element so it can call whichever method is
* wanted. (ie: toHtml(), toJavaScript(), and/or toString()).
*
* @param object The renderer to use
* @uses SForm_Renderer::append()
*/
protected function render(SForm_Renderer $rend){
$rend->append($this);
}
/**
* Add a rule to this element
*
* A rule assigned to this element will be controled by this element. All
* validation will come through this element, and any errors will be
* returned via this element. All JavaScript will also be transmitted via
* this element.
*
* If the first argument is a rule object, it will simply be added to this
* element. If it is a string, it is assumed that you want to {@link }
* createRule() create a rule} which is linked to this element.
*
* Each rule can only be assigned to one element, but that element does not
* need to be used by the rule. For example: an element might validate two
* elements in a group, but if the element is added to the group, then any
* errors will be displayed at the group level.
*
* @param mixed The rule to add
* @return object The added rule
* @uses $locked
* @uses SForm_Rule::assignParent()
*/
public function addRule($rule, $message = null, $arg2 = null, $arg3 = null,
$arg4 = null, $arg5 = null, $arg6 = null){
//Create the rule if needed
if(is_string($rule)){
$rule = $this->createRule($rule, $message, $arg2, $arg3, $arg4, $arg5, $arg6);
} elseif(!($rule instanceof SForm_Rule)){
throw new Exception('The passed parameter was neither a rule ' .
'object or the string of a type.');
}
//Can't add rules to locked elements
if($this->locked){
/*
* The results from the rule set have been calculated. If we add any
* more rules, it will make the previous result invalid (and maybe
* incorrect).
*/
throw new Exception('Attempting to add a rule when they\'ve already ' .
'been used. You\'re doing this in the wrong order.');
}
//Special rules
if($rule instanceof SForm_Rule_Required){
$this->required = true;
}
$class = get_class($rule);
/*
* We should be able to avoid adding duplicate rules to an element,
* I'll add exceptions as I find them.
*/
if(isset($this->rules[$class])){
trigger_error('A rule of type "'.$class.'" has already been added to this element "'.$this->getLocalId().'".', E_USER_NOTICE);
}
$this->rules[$class] = $rule;
$rule->assignParent($this);
return $rule;
}
/**
* Creates & returns a rule
*
* @param string Name of the rule
* @param string Error message for the rule
* @return object Created rule
*/
protected function createRule($rule, $message = null, $arg2 = null, $arg3 = null,
$arg4 = null, $arg5 = null, $arg6 = null){
$rule = strtolower($rule);
if(empty(self::$regRules[$rule])){
throw new Exception('The given rule type "'.$rule.'" is not built in. ' .
'If you are adding a custom rule, please simply add ' .
'the object via addRule(). You might be trying to use addRule() ' .
'with the QuickForm API. Please refer to the docs.');
}
$meta = self::$regRules[$rule];
if($meta[0] && !class_exists($meta[1])){
require $meta[0];
}
/*
* This is an ugly way of creating an object with an "arbitrary"
* number of arguments. If you know of a better way, please contact
* me. :)
*/
$rule = new $meta[1]($message, $this, $arg2, $arg3, $arg4, $arg5, $arg6);
if(!($rule instanceof SForm_Rule)){
throw new Exception('Rule not a subclass of SForm_Rule.');
}
return $rule;
}
/**
* Apply a filter to the value
*
* This is passed a callback function which applies some sort of filter to
* any value returned from {@link getValue()}. Any additonal arguments to
* this function will be appended to the arguments of the callback function.
*
* This cannot be called after {@link validate()} or {@link render()},
* because the element is locked.
*
* @param mixed Callback function
*/
public function filter($callback){
if($this->locked){
throw new Exception('Attempted to add a filter to a locked element.');
}
$this->filters[] = func_get_args();
}
/**
* Do we have any errors?
*
* Did this element's validation generate any errors? If it did, return
* those errors as an HTML string. Each error is seperated by a ' '
* tag.
*
* @return string Any errors that were produced
*/
public function getErrorHtml(){
if($this->validate()){
return '';
} else {
if(self::getOption('xmlClose')){
return implode(' ', $this->errors);
} else {
return implode(' ', $this->errors);
}
}
}
/**
* Is this a valid element?
*
* Performs server side validation using any of the added rules. Calls
* {@link lock()} to provide a chance to load any intrinsic rules.
*
* @return boolean Returns true if no errors are found.
* @uses SForm_Rule::toHtml()
* @uses lock()
*/
protected function validate(){
if(!$this->wasSubmitted()){
return false;
} elseif($this->validated){
return empty($this->errors);
}
$this->lock();
$this->validated = true;
$id = $this->getGlobalId();
foreach($this->rules as $rule){
if($rule->isError()){
$this->errors[] = $rule->toString();
}
}
return empty($this->errors);
}
/**
* Set if this element is frozen
*
* @param boolean Is it frozen?
* @uses $frozen
*/
public function freeze($bool = true){
$this->frozen = $bool;
}
/**
* Is this element marked as frozen?
*
* @return boolean Is this element frozen?
* @uses $frozen
*/
public function isFrozen(){
return $this->frozen;
}
/**
* Is this element required?
*
* @return boolean True if this element is required
* @uses $required
*/
public function isRequired(){
return $this->required;
}
/**
* Assign this element's parent
*
* @param object Parent to assign
* @see SForm_Container::addElement()
* @uses $parent
*/
protected function assignParent(SForm_Container $parent){
if($this->parent){
throw new Exception('Parent already exists', FORM_ERR_PARENT_EXISTS);
}
$this->parent = $parent;
}
/**
* Returns a value from the request
*
* @param string Value to retrieve
* @return mixed Value or null
*/
protected function getRequest($val){
if($this->parent){
return $this->parent->getRequest($val);
} else {
throw new Exception('Unable to get a request value until I have a ' .
'parent.');
}
}
/**
* Was this form submitted?
*
* @return boolean Has it been submitted?
*/
public function wasSubmitted(){
if($this->parent){
return $this->parent->wasSubmitted();
} else {
throw new Exception('I need to be grounded in a parent.');
}
}
}
/**
* A container holds one or more elements
*
* A container serves as a parent for as many elements (and other containers) as
* needed. It also inherits all of the properties of SForm_Element, so you can
* assign rules to containers, they can produce JavaScript, they have labels,
* and have opening and closing HTML tags.
*
* @access public
* @package SForm
*/
abstract class SForm_Container extends SForm_Element implements RecursiveIterator, Countable {
/**
* Containers are never empty tags
*
* @var boolean
*/
protected $emptyTag = false;
/**
* Children of this container
*
* @var array
*/
private $children = array();
/**
* Filters which will be applied to the children of this container
*
* @var array
*/
protected $chFilters = array();
/**
* Rules which will be applied to the children of this container
*
* @var array
*/
protected $chRules = array();
/**
* List of registered elements
*
* 'name' => array('include str', 'class name')
*
* @var array
*/
private static $regElms = array(
'fieldset' => array(false, 'SForm_Fieldset'),
'header' => array('SForm/Elm/Header.php', 'SForm_Elm_Header'),
'hidden' => array(false, 'SForm_Elm_Hidden'),
'checkbox' => array(false, 'SForm_Elm_Checkbox'),
'text' => array(false, 'SForm_Elm_Text'),
'submit' => array(false, 'SForm_Elm_Submit'),
'reset' => array(false, 'SForm_Elm_Reset'),
'textarea' => array(false, 'SForm_Elm_Textarea'),
'select' => array(false, 'SForm_Elm_Select'),
'group' => array(false, 'SForm_Group'));
/**
* Does the current element have children?
*
* Implemented as part of the {@link http://www.php.net/~helly/php/ext/spl/interfaceRecursiveIterator.html RecursiveIterator}
* SPL interface}
*
* @return boolean Is the current element a container?
*/
final public function hasChildren(){
return current($this->children) instanceof SForm_Container;
}
/**
* Return the current element
*
* Implemented as part of the {@link http://www.php.net/~helly/php/ext/spl/interfaceRecursiveIterator.html RecursiveIterator}
* SPL interface}
*
* @return object The current child
*/
final public function getChildren(){
if($this->hasChildren()){
return current($this->children);
} else {
return null;
}
}
/**
* Move the current element to the first one
*
* Implemented as part of the {@link http://www.php.net/manual/en/language.oop5.iterations.php}
* Iterator SPL interface}
*/
final public function rewind(){
reset($this->children);
}
/**
* Return the current element
*
* Implemented as part of the {@link http://www.php.net/manual/en/language.oop5.iterations.php}
* Iterator SPL interface}
*
* @return object
*/
final public function current(){
return current($this->children);
}
/**
* Return the key of the current element
*
* Implemented as part of the {@link http://www.php.net/manual/en/language.oop5.iterations.php}
* Iterator SPL interface}
*
* @return string Returns the current Local ID
*/
final public function key(){
return key($this->children);
}
/**
* Advance pointer and return the new current
*
* Implemented as part of the {@link http://www.php.net/manual/en/language.oop5.iterations.php}
* Iterator SPL interface}
*
* @return object New current object
*/
final public function next(){
return next($this->children);
}
/**
* Is the current ponter valid?
*
* Implemented as part of the {@link http://www.php.net/manual/en/language.oop5.iterations.php}
* Iterator SPL interface}
*
* @return boolean True if the current pointer is valid
*/
final public function valid(){
return (boolean) current($this->children);
}
/**
* Return number of children
*
* Implemented as part of the {@link http://www.php.net/~helly/php/ext/spl/interfaceCountable.html Countable SPL interface}
*
* @return integer How many children are there
*/
final public function count(){
return count($this->children);
}
/**
* Adds an element to this container
*
* This function has behavior that changes depending on the first argument
* passed to it.
*
* If the first argument is an element object, it is added to this container
* as a child.
*
* If the first argument is a string, the arguments are first passed through
* {@link createElement()} and an element is created. That element is then
* added to this container as a child.
*
* The element is then returned.
*
* @param mixed Element or type of element to add
* @return object Added element
* @uses $children
* @uses createElement()
*/
public function addElement($elm, $arg1 = null, $arg2 = null, $arg3 = null,
$arg4 = null, $arg5 = null, $arg6 = null){
if(is_string($elm)){
$elm = $this->createElement($elm, $arg1, $arg2, $arg3, $arg4, $arg5, $arg6);
} elseif(!($elm instanceof SForm_Element)){
throw new Exception('The passed parameter was neither an element ' .
'object or the string of a type.');
}
$elmId = $elm->getLocalId();
if(isset($this->children[$elmId])){
throw new Exception('Child by this ID already exists');
}
$elm->assignParent($this);
$this->children[$elmId] = $elm;
return $elm;
}
/**
* Creates an element
*
* Creates whichever argument is specified by the first argument.
* Valid strings are generally the same as the the element that you are
* trying to create. A '<select>' element is created with a 'select' string.
*
* Parameters past the first will be passed to the constructor of the
* created object.
*
* @param string Type of element to add.
* @param mixed First argument for object constructor...
* @return object Created object.
* @uses $regElms
*/
public static function createElement($elm, $arg1 = null, $arg2 = null, $arg3 = null,
$arg4 = null, $arg5 = null, $arg6 = null){
$elm = strtolower($elm);
if(empty(self::$regElms[$elm])){
throw new Exception('The given element type "'.$elm.'" is not built in. ' .
'If you have created a custom element, please simply ' .
'pass the object to addElement().');
}
$meta = self::$regElms[$elm];
if($meta[0] && !class_exists($meta[1])){
require $meta[0];
}
/*
* This is an ugly way of creating an object with an "arbitrary"
* number of arguments. If you know of a better way, please contact
* me. :)
*/
$elm = new $meta[1]($arg1, $arg2, $arg3, $arg4, $arg5, $arg6);
if(!($elm instanceof SForm_Element)){
throw new Exception('Element not a subclass of SForm_Element.');
}
return $elm;
}
/**
* Returns an element using the Global ID
*
* The Global ID is the ID used in the HTML document or by getElementById()
* in JavaScript.
*
* @param string Global ID to fetch
* @return object Requested object (or null)
*/
public function getGlobalElement($id){
if(!$this->parent){
throw new Exception('Unable to retrieve an element by Global ID when ' .
'this container isn\'t rooted to a form. Please add me to ' .
'a form.');
}
$this->parent->getGlobalElement($id);
}
/**
* Returns an element using the Local ID
*
* The Local ID is the ID that passed to an element's constructor. It is
* useful for reequesting a specific child of an element. For iterating
* through elements, see the Iterator interface. Specifically {@link }
* next()}.
*
* @param string Local ID to fetch
* @return object Requested obect (or null)
*/
public function getElement($id){
$id = (string) $id;
if(empty($this->children[$id])){
return null;
} else {
return $this->children[$id];
}
}
/**
* Removes an element from this group
*
* @param string The id of the object to remove
* @return object The removed object
*/
public function removeElement($id){
$ret = $this->getElement($id);
unset($this->children[$id]);
return $ret;
}
/**
* Apply a filter to the elements
*
* This is the same as using {@link SForm_Element::filter()}, but the first
* argument is the child to apply this filter to.
*
* The filter is not applied to child elements until this container is
* {@link render() rendered} or {@link validate() validated}. If the child
* doesn't exist at that time, an exception is thrown.
*
* If you wish to apply the filter to this container's value, see
* {@link filter()}.
*
* @param string Element to apply the filter too
* @param mixed The filter callback
* @see SForm_Element::filter()
* @see render()
* @see validate()
*/
public function applyFilter($element, $filter){
$this->chFilters[] = func_get_args();
}
/**
* Create a HTML representation of this container
*
* Constructs the HTML tag that opens this container. Normally this is
* either a <form> tag or a <fieldset> tag. The 'id' attribute is
* automatically filled with this container's Global ID. Other attributes
* may be added via {@link setAttribute()}.
*
* @return string Opening tag for this container
* @see setAttribute()
*/
public function toHtml(){
$id = $this->getGlobalId();
$this->setAttribute('id', $id);
return '<'.$this->tag.self::getAttributesString($this->attributes).'>';
}
/**
* Add any requested filters and rules, then lock this container
*
* We override the parent in order to add filters and rules.
*
* @see applyFilter()
*/
protected function lock(){
if($this->locked){
return;
}
//Apply all filters
foreach($this->chFilters as $filter){
$elmId = array_shift($filter);
if($elmId == '__ALL__'){
foreach($this->children as $elm){
call_user_func_array(array($elm,'filter'), $filter);
}
} else {
if($elm = $this->getElement($elmId)){
call_user_func_array(array($elm,'filter'), $filter);
} else {
throw new Exception('The element "'.$elmId.'" wasn\'t ' .
'found when we were trying to apply a filter.');
}
}
}
parent::lock();
}
/**
* Is this valid?
*
* Validates this container and all of its children. Keep in mind that no
* rules can be added after an element is validated because that would
* invalidate the validation. If there was no request submitted, it is
* assumed that validation is not passed.
*
* Rules can be added via {@link addRule()}.
*
* @return boolean Is this container & its children valid?
* @uses parent::validate()
*/
protected function validate(){
//No request? No validate.
if(!$this->wasSubmitted()){
return false;
}
//Validate all children
$valid = parent::validate();
foreach($this->children as $child){
if(!$child->validate()){
$valid = false;
}
}
return $valid;
}
/**
* Set the frozen status of this container and its children
*
* Setting a container as frozen. Being frozen doesn't have an effect on
* containers. {@link parent::freeze() Frozen elements} will prevent their
* values from being altered, though.
*
* @param boolean Are we freezing this or thawing it?
* @uses parent::freeze()
*/
public function freeze($bool = true){
$this->frozen = $bool;
foreach($this->children as $child){
$child->freeze($bool);
}
}
/**
* Render this container and all elements in it
*
* @param object The renderer to use
* @uses parent::render()
*/
protected function render(SForm_Renderer $rend){
$this->lock();
$rend->push($this);
foreach($this->children as $child){
$child->render($rend);
}
$rend->pop($this);
}
}
/**
* I am the alpha and the omega, I am the form.
*
* The SForm is the root for all elements, and they will not fully funcion
* without being rooted to a SForm. All rendering operations should begin
* with {@link SForm::render()}, validation begins with {@link SForm::validate()},
* and processing can be accomplished with {@link SForm::toArray()}. For more
* information on SForm usage, see the {@link SForm.php package documentation}.
*
* @package SForm
* @see __construct()
* @see SForm.php
*/
class SForm extends SForm_Container {
/**
* Why yes, this is a form
*
* @var string
*/
protected $tag = 'form';
/**
* Defaults are stored here
*
* @var array
* @deprecated
*/
protected $defaults = array();
/**
* Are we tracking the submit?
*
* @var boolean
*/
protected $trackSubmit;
/**
* Create a form
*
* The ID parameter sets both the Global ID and the Local ID to be the same,
* since we are at the top level. All children of this form will use this ID
* as a prefix to their Global IDs.
*
* The method determines how we will send the data that is input. A 'get'
* method sends the data in the URL after a '?' and 'post' sends the data in
* the body of the HTTP request. An advantage of using 'get' is the
* results of the submission can be book marked. A disadvantage of using
* 'get' is that a form can be maliciously submitted without the user's
* knowledge by making them access the URL (ex: an embedded imag). 'get'
* requests are also awkward for large amounts of data.
*
* The action is what URL to send the data to. Generally you want to send
* the data back to the original URL so you can continue processing it and
* present errors if needed.
*
* Include extra attributes if you feel lucky.
*
* $trackSubmit inserts an extra hidden element. If this element isn't
* included in the submission, it is ignored. It defaults to true. Be
* careful when setting this to false, because the submission may then
* validate without a button ever being clicked. You might want to add a
* required rule to prevent this from happening.
*
* Changes from HTML_QuickForm:
* $target has been removed because it is not in XHTML 1.1. Use $attributes
* if you wish to add it back.
*
* $action is required in XHTML 1.1, so if one isn't provided, $_SERVER
* ['SCRIPT_URL'] is used.
*
* $trackSubmit has been set to true by default, because otherwise a form
* without required elements may validate without being submitted.
*
* $id does not apply a 'name' attribute to the form because this is illegal
* in XHTML 1.1.
*
* @param string This form's ID
* @param string Method attribute of the form ('post' or 'get')
* @param string Action attribute of the form
* @param array Custom attributes for this form
* @param boolean Track whether this form was submitted.
* @uses $request
*/
function __construct($id, $method = 'post', $action = '', $attributes = null, $trackSubmit = true){
parent::__construct($id, '', $attributes);
//Set the method
switch($method){
case 'post':
$this->request =& $_POST;
break;
case 'get':
$this->request =& $_GET;
break;
case 'request':
$this->request =& $_REQUEST;
$method = 'post';
break;
default:
throw new Exception('Method type not recognized: '.$method);
}
$this->setAttribute('method', $method);
//Set the action (required in XHTML 1.1)
if($action === ''){
//Send form to self
if(isset($_SERVER['SCRIPT_URL'])){
$action = $_SERVER['SCRIPT_URL'];
}
// SCRIPT_URL is not set in PHP 5.1
elseif(isset($_SERVER['SCRIPT_NAME'])){
$action = $_SERVER['SCRIPT_NAME'];
}
//Hopefully the browser will take care of it
else {
$action = '';
}
}
$this->setAttribute('action', $action);
//If we are tracking submit, then we need to have a hidden field
if($trackSubmit){
//Setup a required hidden element
$tid = SForm_Element::getOption('trackId');
$this->addElement(new SForm_Elm_Hidden($tid, '', array('value' => true)));
$this->trackSubmit = true;
}
}
/**
* Get an element by its Global ID
*
* Retrieves an element based on it's Global ID. When at all possible, I'd
* suggest that you retrieve elements via {@link getElement()}.
*
* @param string Global ID
* @return object Requested element (or null)
*/
public function getGlobalElement($id){
return $this->recursiveGetElement(strval($id), $this);
}
/**
* Find an element by its Global ID
*
* @param string Part of Global ID
* @param object Container we are currently searching in
* @return object The requested element
*/
private function recursiveGetElement($id, SForm_Container $cont){
$locId = $id;
$sep = self::getOption('separator');
while(!($elm = $cont->getElement($locId))){
if(($i = strrpos($locId, $sep)) === false){
return null;
}
$locId = substr($locId, 0, $i);
}
if($id == $locId){
return $elm;
}
if(($i = strpos($id, $sep)) === false){
return null;
}
return $this->recursiveGetElement(substr($id, $i+1), $elm);
}
/**
* All children of this form inheret their IDs from it.
*
* When {@link parent::getGlobalId()} is called on a child, it calls its
* parent's getGlobalId() method and appends the results to its own
* Local ID. When the calling reaches the SForm level, it's at the root and
* there are no more parents, so the Local ID is returned.
*
* @return string The Local and Global ID
* @uses getLocalId()
*/
public function getGlobalId(){
return $this->getLocalId();
}
/**
* Returns a nested array of all returned values
*
* Uses the default renderer to collect the values of all elements into an
* array. If objects are nested, then the array is nested also.
*
* @return array Values of this form in an array.
* @uses SForm_Renderer
*/
public function toArray(){
$rend = new SForm_Renderer();
$this->render($rend);
return $rend->fetch($this);
}
/**
* Was this form submitted?
*
* @return boolean Has it been submitted?
*/
public function wasSubmitted(){
//Use the tracking element
if($this->trackSubmit){
$id = SForm_Element::getOption('trackId');
return (bool) $this->getRequest($this->getElement($id)->getGlobalId());
}
//This is how we track the form without tracking it
else {
return !empty($this->request);
}
}
/**
* Set the default values of local elements
*
* This is here for HTML_QuickForm compatability. Please use
* {@link SForm_Element::setDefault()} instead. The reasoning is that all
* operations that are associated with perticular elements should operate on
* those elements, so this usage makes more sense.
*
* Also, when using QF, I found myself simply collecting values into an
* array at the same layer as element creation. After the the array was
* completed, I had to pass it through various layers of my program to
* finally set the defaults. Using {@link SForm_Element::setDefault()} makes
* things easier, also.
*
* Internally, element defaults are stored and set in {@link render()} using
* the {@link SForm_Element::setDefault()} method at render time. Any calls
* to {@link SForm_Element::setDefault()} will be overridden by the
* values in this form. The elements are retrieved using {@link }
* getElement()}. This is due to the internal differences between QF and
* SForm. It doesn't mesh exactly with QuickForm, and you have been warned.
* Maybe you should use {@link SForm_Element::setDefault()} instead.
*
* @param array List of defaults for the elements.
* @see SForm_Element::setDefault()
* @see render()
* @see getElement()
* @deprecated
*/
public function setDefaults($defaults){
foreach($defaults as $id => $def){
$this->defaults[$id] = $def;
}
}
/**
* Returns an element's value
*
* @param string Element to retrieve value for
* @return string Element's value
* @deprecated
*/
public function exportValue($name){
if($elm = $this->getElement($name)){
return $elm->getValue();
} else {
throw new Exception('The element "'.$name.'" wasn\'t found.');
}
}
/**
* Add a rule to given field(s)
*
* Please use {@link addRule()} instead. This is only here for compatability
* reasons.
*
* @param mixed Element name(s)
* @param string Error message
* @param string Type of rule
* @param string Extra data
* @param string Where to preform validation
* @deprecated
*/
public function addRuleDep($element, $message, $type, $format = '', $validation = 'server'){
$elms = array();
//Sort out the elements
if(is_array($element)){
foreach($element as $elmId){
if($elm = $this->getElement($elmId)){
$elms[] = $elm;
} else {
throw new Exception('Bad element name "'.$elmId.'"');
}
}
$baseElm = $elms[0];
} else {
if($elms = $this->getElement($element)){
$baseElm = $elms;
} else {
throw new Exception('Bad element name "'.$element.'"');
}
}
//Create the rule
if($validation == 'server'){
$rule = $baseElm->createRule($type, $message, $elms, $format);
$rule->validateOnClient(false);
$baseElm->addRule($rule);
} else {
$baseElm->addRule($type, $message, $elms, $format);
}
}
/**
* Renders a form with the provided renderer
*
* Render the form using the given {@link SForm_Renderer renderer}. If any
* defaults have been applied using {@link setDefaults()}, they are applied
* to the local elements here.
*
* @param object The renderer to use
* @uses $defaults
* @uses parent::render()
*/
public function render(SForm_Renderer $rend){
//Apply all defaults
foreach($this->defaults as $id => $def){
if($elm = $this->getElement($id)){
$elm->setDefault($def);
} else {
throw new Exception('The element "'.$id.'" wasn\'t found when ' .
'we were trying to apply it\'s default "'.$def.'".');
}
}
$rend->startForm($this);
parent::render($rend);
}
/**
* Is this valid?
*
* Validates this form. Keep in mind that no rules can be added after an
* element is validated because that would invalidate the validation. If
* there was no request submitted, it is assumed that validation is not
* passed.
*
* Rules can be added via {@link addRule()}.
*
* @return boolean Is this form valid?
* @uses parent::validate()
*/
public function validate(){
return parent::validate();
}
/**
* Prints this form to std out
*
* @param object Renderer to use
*/
public function display($rend = null){
if($rend == null){
$rend = new SForm_Renderer_HTML();
} elseif(!($rend instanceof SForm_Renderer)){
throw new Exception('Passed renderer is not a subclass of ' .
'SForm_Renderer.');
}
$this->render($rend);
echo $rend->fetch($this);
}
/**
* Enables file uploading
*
* This is not currently working. Please {@link mailto:}
* sprice@pricepages.org request} if needed.
*/
public function enableFileUpload(){
throw new Exception('FIXME');
}
/**
* Process the results of the form
*
* This method is depreciated because it takes less code and you gain more
* functionality if you just call the callback function yourself. Use {@link }
* toArray()} to get the array, then call the function. That simple.
*
* @param mixed Callback function
* @deprecated
*/
public function process($callback){
return call_user_func($callback, $this->toArray());
}
/**
* Create a group and add it to this form
*
* This is depreciated because you can just do this yourself by
* {@link SForm_Group creating a group} (or {@link SForm_Fieldset fieldset})
* and adding to the form via {@link SForm:: addElement()}. It's less
* confusing, also.
*
* @param array Elements in group
* @param string Group name
* @param string Group label
* @return object Added group
* @deprecated
*/
public function addGroup($elements, $id = null, $label = null){
$grp = new SForm_Group($id, $label);
foreach($elements as $elm){
$grp->addElement($elm);
}
return $this->addElement($grp);
}
/**
* Returns a value from the request
*
* @param string Value to retrieve
* @return mixed Value or null
*/
protected function getRequest($val){
if(isset($this->request[$val])){
return $this->request[$val];
} else {
return null;
}
}
/**
* Temp method for testing
*
* @deprecated
* @ignore
*/
function smartyFetch($file, $addlVars = null){
if(!class_exists('ECSmarty'))
require 'ECSmarty.php';
$tpl = new ECSmarty(false);//Disable Smarty cache
$rndr = new SForm_Renderer_Array();
$this->render($rndr);
$arr = $rndr->fetch($this);
// var_dump($arr);exit;
$tpl->assign($arr);
if($addlVars){
$tpl->assign($addlVars);
}
return $tpl->fetch($file);
}
}
/**
* Group elements
*
* @package SForm
*/
class SForm_Group extends SForm_Container {
/**
* Return the label
*
* @param boolean This isn't used here
* @return string The label
*/
public function getLabelHtml($accesskey = true){
if($lbl = $this->getLabel()){
return self::escHtml($lbl);
} else {
return '';
}
}
/**
* Open the group
*
* @return string Nothing. It's a boring group.
*/
public function toHtml(){
return '';
}
/**
* Close this element group
*
* @return string Nothing. It's a boring group.
*/
public function toHtmlFin(){
return '';
}
}
/**
* Group elements in a '<fieldset>'
*
* Groups a set of elements in '<fieldset>' tags. All XHTML 1.1 compliant
* scripts must have elements seperated from their surrounding form by tags such
* as the fieldset. Also, it is pleasing to the eye and {@link http://www.webstandards.org/learn/tutorials/accessible-forms/intermediate/ more}
* accessable} to use fieldsets to group associated elements.
*
* Use the {@link __construct() label in the constructor} to create a legend for
* this fieldset. The legend will be rendered in the html label, using {@link }
* getLabelHtml()}.
*
* You can group fieldsets within each other, so feel free to use them with
* reckless abandon.
*
* @package SForm
*/
class SForm_Fieldset extends SForm_Container {
/**
* By default, render this as a fieldset
*
* @var string
*/
protected $tag = 'fieldset';
/**
* Return the label as a legend tag
*
* Place a legend on this fieldset. The legend should be contained inside
* the fieldset tags.
*
* @param boolean This isn't used here
* @return string The label as a legend tag
*/
public function getLabelHtml($accesskey = true){
if($lbl = $this->getLabel()){
return '<legend>'.self::escHtml($lbl).'</legend>';
} else {
return '';
}
}
/**
* Close this element group
*
* @return string HTML that closes the group
*/
public function toHtmlFin(){
return '</'.$this->tag.'>';
}
}
/**
* Create rules for elements
*
* The SForm rules are very different than the QuickForm rules. Their advantages
* over QuickForm rules are twofold: They are designed to easily validate any
* number of elements simultaneously. They are also designed to throw an error
* (if needed) at any location in the form.
*
* This means that you can easily create complex rules, such as validating a
* credit card number depnding on which type of credit card is selected. You can
* require a user to fill in identifying information if they don't have a user
* name. You can better control filling out billing vs. shipping information.
* You can also do any of this in JavaScript.
*
* Much of this can even be done without defining a new class by using the
* {@link SForm_Rule_Boolean} to create an on-the-fly server and client side
* boolean statement.
*
* Usage:
*
* Because of the changes, the API is different. For example, this code from
* the original quick start guide:
*
* <code>
* $form->addElement('text', 'name', 'Enter your name:',
* array('size' => 50, 'maxlength' => 255));
*
* $form->addRule('name', 'Please enter your name', 'required', null,'client');
* </code>
*
*
* Can be changed into this, for the same functionality:
*
* <code>
* $form->addElement('text', 'name', 'Enter your name:',
* array('size' => 50, 'maxlength' => 255));
*
* $form->addRuleDep('name', 'Please enter your name', 'required', null,'client');
* </code>
*
*
* Note that in the example, addRule() has been changed to {@link }
* SForm::addRuleDep() addRuleDep()}, where 'Dep' stands for
* depriciated.
*
*
* The correct SForm usage, though, is (shorthand):
*
* <code>
* $nameElm = $form->addElement('text', 'name', 'Enter your name:',
* array('size' => 50, 'maxlength' => 255));
*
* $nameElm->addRule('required', 'Please enter your name');
* </code>
*
*
* Or even (fully object oriented):
*
* <code>
* $nameElm = new SForm_Elm_Text('name', 'Enter your name:',
* array('size' => 50, 'maxlength' => 255));
*
* $reqRule = new SForm_Rule_Required('Please enter your name', $nameElm);
*
* $nameElm->addRule($reqRule);
*
* $form->addElement($nameElm);
* </code>
*
* @package SForm
* @subpackage Rules
*/
abstract class SForm_Rule {
/**
* Has this rule been asigned to an element?
*
* @var boolean
*/
protected $hasParent = false;
/**
* Should we use this rule with JavaScript?
*
* @var boolean
*/
protected $validateOnClient = true;
/**
* NO YUO!
*
* The message that is returned when an error is thrown. {@link toHtml()}
* can be overridden and the message made more dynamic, if desired.
*
* @var string
*/
protected $message;
/**
* Which elements fall under this jurisdiction?
*
* @var array
*/
protected $elements = array();
/**
* The names of local JavaScript variables
*
* To save cycles and bytes, values are stored in local JavaScript variables
* before they are used in client side validation. This array is indexed by
* the Global ID, and the values are the names of the local variables.
*
* @var array
*/
static protected $jsElmVar = array();
/**
* The counter for temp local variables
*
* @var integer
*/
static protected $jsElmNum = 0;
/**
* Construct a rule with one element and one error message
*
* The first argument is always the error message, and the second argument
* is always an element or array of elements (as appropriate).
*
* The elements passed here are not necessarily the element that validates
* this rule and throws an error message. This way, the rule can
* validate two or more fields in a group, but the error appears in the
* group. This rule will later be added to said element or container with
* {@link SForm_Element::addRule()}.
*
* By default, the message is static, but you are encouraged to create
* dynamic messages that address the specific error and element via {@link }
* SForm_Element::getValue()} and {@link SForm_Element::getLabel()}
* respectively. Make sure, though, that messages still work on both the
* server side and client side.

	SForm

[ class tree: SForm ] [ index: SForm ] [ all elements ]

Source for file SForm.php