This is a first cut of a new formslib.php a library of classes for creating and secur...
[moodle.git] / lib / pear / HTML / QuickForm.php
CommitLineData
da6f8763 1<?php
2/* vim: set expandtab tabstop=4 shiftwidth=4: */
3// +----------------------------------------------------------------------+
4// | PHP version 4.0 |
5// +----------------------------------------------------------------------+
6// | Copyright (c) 1997-2003 The PHP Group |
7// +----------------------------------------------------------------------+
8// | This source file is subject to version 2.0 of the PHP license, |
9// | that is bundled with this package in the file LICENSE, and is |
10// | available at through the world-wide-web at |
11// | http://www.php.net/license/2_02.txt. |
12// | If you did not receive a copy of the PHP license and are unable to |
13// | obtain it through the world-wide-web, please send a note to |
14// | license@php.net so we can mail you a copy immediately. |
15// +----------------------------------------------------------------------+
16// | Authors: Adam Daniel <adaniel1@eesus.jnj.com> |
17// | Bertrand Mansion <bmansion@mamasam.com> |
18// +----------------------------------------------------------------------+
19//
20// $Id$
21
22require_once('PEAR.php');
23require_once('HTML/Common.php');
24
25$GLOBALS['HTML_QUICKFORM_ELEMENT_TYPES'] =
26 array(
27 'group' =>array('HTML/QuickForm/group.php','HTML_QuickForm_group'),
28 'hidden' =>array('HTML/QuickForm/hidden.php','HTML_QuickForm_hidden'),
29 'reset' =>array('HTML/QuickForm/reset.php','HTML_QuickForm_reset'),
30 'checkbox' =>array('HTML/QuickForm/checkbox.php','HTML_QuickForm_checkbox'),
31 'file' =>array('HTML/QuickForm/file.php','HTML_QuickForm_file'),
32 'image' =>array('HTML/QuickForm/image.php','HTML_QuickForm_image'),
33 'password' =>array('HTML/QuickForm/password.php','HTML_QuickForm_password'),
34 'radio' =>array('HTML/QuickForm/radio.php','HTML_QuickForm_radio'),
35 'button' =>array('HTML/QuickForm/button.php','HTML_QuickForm_button'),
36 'submit' =>array('HTML/QuickForm/submit.php','HTML_QuickForm_submit'),
37 'select' =>array('HTML/QuickForm/select.php','HTML_QuickForm_select'),
38 'hiddenselect' =>array('HTML/QuickForm/hiddenselect.php','HTML_QuickForm_hiddenselect'),
39 'text' =>array('HTML/QuickForm/text.php','HTML_QuickForm_text'),
40 'textarea' =>array('HTML/QuickForm/textarea.php','HTML_QuickForm_textarea'),
41 'link' =>array('HTML/QuickForm/link.php','HTML_QuickForm_link'),
42 'advcheckbox' =>array('HTML/QuickForm/advcheckbox.php','HTML_QuickForm_advcheckbox'),
43 'date' =>array('HTML/QuickForm/date.php','HTML_QuickForm_date'),
44 'static' =>array('HTML/QuickForm/static.php','HTML_QuickForm_static'),
45 'header' =>array('HTML/QuickForm/header.php', 'HTML_QuickForm_header'),
46 'html' =>array('HTML/QuickForm/html.php', 'HTML_QuickForm_html'),
47 'hierselect' =>array('HTML/QuickForm/hierselect.php', 'HTML_QuickForm_hierselect'),
48 'autocomplete' =>array('HTML/QuickForm/autocomplete.php', 'HTML_QuickForm_autocomplete'),
49 'xbutton' =>array('HTML/QuickForm/xbutton.php','HTML_QuickForm_xbutton')
50 );
51
52$GLOBALS['_HTML_QuickForm_registered_rules'] = array(
53 'required' => array('html_quickform_rule_required', 'HTML/QuickForm/Rule/Required.php'),
54 'maxlength' => array('html_quickform_rule_range', 'HTML/QuickForm/Rule/Range.php'),
55 'minlength' => array('html_quickform_rule_range', 'HTML/QuickForm/Rule/Range.php'),
56 'rangelength' => array('html_quickform_rule_range', 'HTML/QuickForm/Rule/Range.php'),
57 'email' => array('html_quickform_rule_email', 'HTML/QuickForm/Rule/Email.php'),
58 'regex' => array('html_quickform_rule_regex', 'HTML/QuickForm/Rule/Regex.php'),
59 'lettersonly' => array('html_quickform_rule_regex', 'HTML/QuickForm/Rule/Regex.php'),
60 'alphanumeric' => array('html_quickform_rule_regex', 'HTML/QuickForm/Rule/Regex.php'),
61 'numeric' => array('html_quickform_rule_regex', 'HTML/QuickForm/Rule/Regex.php'),
62 'nopunctuation' => array('html_quickform_rule_regex', 'HTML/QuickForm/Rule/Regex.php'),
63 'nonzero' => array('html_quickform_rule_regex', 'HTML/QuickForm/Rule/Regex.php'),
64 'callback' => array('html_quickform_rule_callback', 'HTML/QuickForm/Rule/Callback.php'),
65 'compare' => array('html_quickform_rule_compare', 'HTML/QuickForm/Rule/Compare.php')
66);
67
68// {{{ error codes
69
70/*
71 * Error codes for the QuickForm interface, which will be mapped to textual messages
72 * in the QuickForm::errorMessage() function. If you are to add a new error code, be
73 * sure to add the textual messages to the QuickForm::errorMessage() function as well
74 */
75
76define('QUICKFORM_OK', 1);
77define('QUICKFORM_ERROR', -1);
78define('QUICKFORM_INVALID_RULE', -2);
79define('QUICKFORM_NONEXIST_ELEMENT', -3);
80define('QUICKFORM_INVALID_FILTER', -4);
81define('QUICKFORM_UNREGISTERED_ELEMENT', -5);
82define('QUICKFORM_INVALID_ELEMENT_NAME', -6);
83define('QUICKFORM_INVALID_PROCESS', -7);
84define('QUICKFORM_DEPRECATED', -8);
85define('QUICKFORM_INVALID_DATASOURCE', -9);
86
87// }}}
88
89/**
90* Create, validate and process HTML forms
91*
92* @author Adam Daniel <adaniel1@eesus.jnj.com>
93* @author Bertrand Mansion <bmansion@mamasam.com>
94* @version 2.0
95* @since PHP 4.0.3pl1
96*/
97class HTML_QuickForm extends HTML_Common {
98 // {{{ properties
99
100 /**
101 * Array containing the form fields
102 * @since 1.0
103 * @var array
104 * @access private
105 */
106 var $_elements = array();
107
108 /**
109 * Array containing element name to index map
110 * @since 1.1
111 * @var array
112 * @access private
113 */
114 var $_elementIndex = array();
115
116 /**
117 * Array containing indexes of duplicate elements
118 * @since 2.10
119 * @var array
120 * @access private
121 */
122 var $_duplicateIndex = array();
123
124 /**
125 * Array containing required field IDs
126 * @since 1.0
127 * @var array
128 * @access private
129 */
130 var $_required = array();
131
132 /**
133 * Prefix message in javascript alert if error
134 * @since 1.0
135 * @var string
136 * @access public
137 */
138 var $_jsPrefix = 'Invalid information entered.';
139
140 /**
141 * Postfix message in javascript alert if error
142 * @since 1.0
143 * @var string
144 * @access public
145 */
146 var $_jsPostfix = 'Please correct these fields.';
147
148 /**
149 * Datasource object implementing the informal
150 * datasource protocol
151 * @since 3.3
152 * @var object
153 * @access private
154 */
155 var $_datasource;
156
157 /**
158 * Array of default form values
159 * @since 2.0
160 * @var array
161 * @access private
162 */
163 var $_defaultValues = array();
164
165 /**
166 * Array of constant form values
167 * @since 2.0
168 * @var array
169 * @access private
170 */
171 var $_constantValues = array();
172
173 /**
174 * Array of submitted form values
175 * @since 1.0
176 * @var array
177 * @access private
178 */
179 var $_submitValues = array();
180
181 /**
182 * Array of submitted form files
183 * @since 1.0
184 * @var integer
185 * @access public
186 */
187 var $_submitFiles = array();
188
189 /**
190 * Value for maxfilesize hidden element if form contains file input
191 * @since 1.0
192 * @var integer
193 * @access public
194 */
195 var $_maxFileSize = 1048576; // 1 Mb = 1048576
196
197 /**
198 * Flag to know if all fields are frozen
199 * @since 1.0
200 * @var boolean
201 * @access private
202 */
203 var $_freezeAll = false;
204
205 /**
206 * Array containing the form rules
207 * @since 1.0
208 * @var array
209 * @access private
210 */
211 var $_rules = array();
212
213 /**
214 * Form rules, global variety
215 * @var array
216 * @access private
217 */
218 var $_formRules = array();
219
220 /**
221 * Array containing the validation errors
222 * @since 1.0
223 * @var array
224 * @access private
225 */
226 var $_errors = array();
227
228 /**
229 * Note for required fields in the form
230 * @var string
231 * @since 1.0
232 * @access private
233 */
234 var $_requiredNote = '<span style="font-size:80%; color:#ff0000;">*</span><span style="font-size:80%;"> denotes required field</span>';
235
236 /**
237 * Whether the form was submitted
238 * @var boolean
239 * @access private
240 */
241 var $_flagSubmitted = false;
242
243 // }}}
244 // {{{ constructor
245
246 /**
247 * Class constructor
248 * @param string $formName Form's name.
249 * @param string $method (optional)Form's method defaults to 'POST'
250 * @param string $action (optional)Form's action
251 * @param string $target (optional)Form's target defaults to '_self'
252 * @param mixed $attributes (optional)Extra attributes for <form> tag
253 * @param bool $trackSubmit (optional)Whether to track if the form was submitted by adding a special hidden field
254 * @access public
255 */
256 function HTML_QuickForm($formName='', $method='post', $action='', $target='', $attributes=null, $trackSubmit = false)
257 {
258 HTML_Common::HTML_Common($attributes);
259 $method = (strtoupper($method) == 'GET') ? 'get' : 'post';
260 $action = ($action == '') ? $_SERVER['PHP_SELF'] : $action;
261 $target = empty($target) ? array() : array('target' => $target);
262 $attributes = array('action'=>$action, 'method'=>$method, 'name'=>$formName, 'id'=>$formName) + $target;
263 $this->updateAttributes($attributes);
264 if (!$trackSubmit || isset($_REQUEST['_qf__' . $formName])) {
265 if (1 == get_magic_quotes_gpc()) {
266 $this->_submitValues = $this->_recursiveFilter('stripslashes', 'get' == $method? $_GET: $_POST);
267 foreach ($_FILES as $keyFirst => $valFirst) {
268 foreach ($valFirst as $keySecond => $valSecond) {
269 if ('name' == $keySecond) {
270 $this->_submitFiles[$keyFirst][$keySecond] = $this->_recursiveFilter('stripslashes', $valSecond);
271 } else {
272 $this->_submitFiles[$keyFirst][$keySecond] = $valSecond;
273 }
274 }
275 }
276 } else {
277 $this->_submitValues = 'get' == $method? $_GET: $_POST;
278 $this->_submitFiles = $_FILES;
279 }
280 $this->_flagSubmitted = count($this->_submitValues) > 0 || count($this->_submitFiles) > 0;
281 }
282 if ($trackSubmit) {
283 unset($this->_submitValues['_qf__' . $formName]);
284 $this->addElement('hidden', '_qf__' . $formName, null);
285 }
286 if (preg_match('/^([0-9]+)([a-zA-Z]*)$/', ini_get('upload_max_filesize'), $matches)) {
287 // see http://www.php.net/manual/en/faq.using.php#faq.using.shorthandbytes
288 switch (strtoupper($matches['2'])) {
289 case 'G':
290 $this->_maxFileSize = $matches['1'] * 1073741824;
291 break;
292 case 'M':
293 $this->_maxFileSize = $matches['1'] * 1048576;
294 break;
295 case 'K':
296 $this->_maxFileSize = $matches['1'] * 1024;
297 break;
298 default:
299 $this->_maxFileSize = $matches['1'];
300 }
301 }
302 } // end constructor
303
304 // }}}
305 // {{{ apiVersion()
306
307 /**
308 * Returns the current API version
309 *
310 * @since 1.0
311 * @access public
312 * @return float
313 */
314 function apiVersion()
315 {
316 return 3.2;
317 } // end func apiVersion
318
319 // }}}
320 // {{{ registerElementType()
321
322 /**
323 * Registers a new element type
324 *
325 * @param string $typeName Name of element type
326 * @param string $include Include path for element type
327 * @param string $className Element class name
328 * @since 1.0
329 * @access public
330 * @return void
331 */
332 function registerElementType($typeName, $include, $className)
333 {
334 $GLOBALS['HTML_QUICKFORM_ELEMENT_TYPES'][strtolower($typeName)] = array($include, $className);
335 } // end func registerElementType
336
337 // }}}
338 // {{{ registerRule()
339
340 /**
341 * Registers a new validation rule
342 *
343 * @param string $ruleName Name of validation rule
344 * @param string $type Either: 'regex', 'function' or 'rule' for an HTML_QuickForm_Rule object
345 * @param string $data1 Name of function, regular expression or HTML_QuickForm_Rule classname
346 * @param string $data2 Object parent of above function or HTML_QuickForm_Rule file path
347 * @since 1.0
348 * @access public
349 * @return void
350 */
351 function registerRule($ruleName, $type, $data1, $data2 = null)
352 {
353 include_once('HTML/QuickForm/RuleRegistry.php');
354 $registry =& HTML_QuickForm_RuleRegistry::singleton();
355 $registry->registerRule($ruleName, $type, $data1, $data2);
356 } // end func registerRule
357
358 // }}}
359 // {{{ elementExists()
360
361 /**
362 * Returns true if element is in the form
363 *
364 * @param string $element form name of element to check
365 * @since 1.0
366 * @access public
367 * @return boolean
368 */
369 function elementExists($element=null)
370 {
371 return isset($this->_elementIndex[$element]);
372 } // end func elementExists
373
374 // }}}
375 // {{{ setDatasource()
376
377 /**
378 * Sets a datasource object for this form object
379 *
380 * Datasource default and constant values will feed the QuickForm object if
381 * the datasource implements defaultValues() and constantValues() methods.
382 *
383 * @param object $datasource datasource object implementing the informal datasource protocol
384 * @param mixed $defaultsFilter string or array of filter(s) to apply to default values
385 * @param mixed $constantsFilter string or array of filter(s) to apply to constants values
386 * @since 3.3
387 * @access public
388 * @return void
389 */
390 function setDatasource(&$datasource, $defaultsFilter = null, $constantsFilter = null)
391 {
392 if (is_object($datasource)) {
393 $this->_datasource =& $datasource;
394 if (is_callable(array($datasource, 'defaultValues'))) {
395 $this->setDefaults($datasource->defaultValues($this), $defaultsFilter);
396 }
397 if (is_callable(array($datasource, 'constantValues'))) {
398 $this->setConstants($datasource->constantValues($this), $constantsFilter);
399 }
400 } else {
401 return PEAR::raiseError(null, QUICKFORM_INVALID_DATASOURCE, null, E_USER_WARNING, "Datasource is not an object in QuickForm::setDatasource()", 'HTML_QuickForm_Error', true);
402 }
403 } // end func setDatasource
404
405 // }}}
406 // {{{ setDefaults()
407
408 /**
409 * Initializes default form values
410 *
411 * @param array $defaultValues values used to fill the form
412 * @param mixed $filter (optional) filter(s) to apply to all default values
413 * @since 1.0
414 * @access public
415 * @return void
416 */
417 function setDefaults($defaultValues = null, $filter = null)
418 {
419 if (is_array($defaultValues)) {
420 if (isset($filter)) {
421 if (is_array($filter) && (2 != count($filter) || !is_callable($filter))) {
422 foreach ($filter as $val) {
423 if (!is_callable($val)) {
424 return PEAR::raiseError(null, QUICKFORM_INVALID_FILTER, null, E_USER_WARNING, "Callback function does not exist in QuickForm::setDefaults()", 'HTML_QuickForm_Error', true);
425 } else {
426 $defaultValues = $this->_recursiveFilter($val, $defaultValues);
427 }
428 }
429 } elseif (!is_callable($filter)) {
430 return PEAR::raiseError(null, QUICKFORM_INVALID_FILTER, null, E_USER_WARNING, "Callback function does not exist in QuickForm::setDefaults()", 'HTML_QuickForm_Error', true);
431 } else {
432 $defaultValues = $this->_recursiveFilter($filter, $defaultValues);
433 }
434 }
435 $this->_defaultValues = HTML_QuickForm::arrayMerge($this->_defaultValues, $defaultValues);
436 foreach (array_keys($this->_elements) as $key) {
437 $this->_elements[$key]->onQuickFormEvent('updateValue', null, $this);
438 }
439 }
440 } // end func setDefaults
441
442 // }}}
443 // {{{ setConstants()
444
445 /**
446 * Initializes constant form values.
447 * These values won't get overridden by POST or GET vars
448 *
449 * @param array $constantValues values used to fill the form
450 * @param mixed $filter (optional) filter(s) to apply to all default values
451 *
452 * @since 2.0
453 * @access public
454 * @return void
455 */
456 function setConstants($constantValues = null, $filter = null)
457 {
458 if (is_array($constantValues)) {
459 if (isset($filter)) {
460 if (is_array($filter) && (2 != count($filter) || !is_callable($filter))) {
461 foreach ($filter as $val) {
462 if (!is_callable($val)) {
463 return PEAR::raiseError(null, QUICKFORM_INVALID_FILTER, null, E_USER_WARNING, "Callback function does not exist in QuickForm::setConstants()", 'HTML_QuickForm_Error', true);
464 } else {
465 $constantValues = $this->_recursiveFilter($val, $constantValues);
466 }
467 }
468 } elseif (!is_callable($filter)) {
469 return PEAR::raiseError(null, QUICKFORM_INVALID_FILTER, null, E_USER_WARNING, "Callback function does not exist in QuickForm::setConstants()", 'HTML_QuickForm_Error', true);
470 } else {
471 $constantValues = $this->_recursiveFilter($filter, $constantValues);
472 }
473 }
474 $this->_constantValues = HTML_QuickForm::arrayMerge($this->_constantValues, $constantValues);
475 foreach (array_keys($this->_elements) as $key) {
476 $this->_elements[$key]->onQuickFormEvent('updateValue', null, $this);
477 }
478 }
479 } // end func setConstants
480
481 // }}}
482 // {{{ setMaxFileSize()
483
484 /**
485 * Sets the value of MAX_FILE_SIZE hidden element
486 *
487 * @param int $bytes Size in bytes
488 * @since 3.0
489 * @access public
490 * @return void
491 */
492 function setMaxFileSize($bytes = 0)
493 {
494 if ($bytes > 0) {
495 $this->_maxFileSize = $bytes;
496 }
497 if (!$this->elementExists('MAX_FILE_SIZE')) {
498 $this->addElement('hidden', 'MAX_FILE_SIZE', $this->_maxFileSize);
499 } else {
500 $el =& $this->getElement('MAX_FILE_SIZE');
501 $el->updateAttributes(array('value' => $this->_maxFileSize));
502 }
503 } // end func setMaxFileSize
504
505 // }}}
506 // {{{ getMaxFileSize()
507
508 /**
509 * Returns the value of MAX_FILE_SIZE hidden element
510 *
511 * @since 3.0
512 * @access public
513 * @return int max file size in bytes
514 */
515 function getMaxFileSize()
516 {
517 return $this->_maxFileSize;
518 } // end func getMaxFileSize
519
520 // }}}
521 // {{{ &createElement()
522
523 /**
524 * Creates a new form element of the given type.
525 *
526 * This method accepts variable number of parameters, their
527 * meaning and count depending on $elementType
528 *
529 * @param string $elementType type of element to add (text, textarea, file...)
530 * @since 1.0
531 * @access public
532 * @return object extended class of HTML_element
533 * @throws HTML_QuickForm_Error
534 */
535 function &createElement($elementType)
536 {
537 $args = func_get_args();
538 $element =& HTML_QuickForm::_loadElement('createElement', $elementType, array_slice($args, 1));
539 return $element;
540 } // end func createElement
541
542 // }}}
543 // {{{ _loadElement()
544
545 /**
546 * Returns a form element of the given type
547 *
548 * @param string $event event to send to newly created element ('createElement' or 'addElement')
549 * @param string $type element type
550 * @param array $args arguments for event
551 * @since 2.0
552 * @access private
553 * @return object a new element
554 * @throws HTML_QuickForm_Error
555 */
556 function &_loadElement($event, $type, $args)
557 {
558 $type = strtolower($type);
559 if (!HTML_QuickForm::isTypeRegistered($type)) {
560 $error = PEAR::raiseError(null, QUICKFORM_UNREGISTERED_ELEMENT, null, E_USER_WARNING, "Element '$type' does not exist in HTML_QuickForm::_loadElement()", 'HTML_QuickForm_Error', true);
561 return $error;
562 }
563 $className = $GLOBALS['HTML_QUICKFORM_ELEMENT_TYPES'][$type][1];
564 $includeFile = $GLOBALS['HTML_QUICKFORM_ELEMENT_TYPES'][$type][0];
565 include_once($includeFile);
566 $elementObject =& new $className();
567 for ($i = 0; $i < 5; $i++) {
568 if (!isset($args[$i])) {
569 $args[$i] = null;
570 }
571 }
572 $err = $elementObject->onQuickFormEvent($event, $args, $this);
573 if ($err !== true) {
574 return $err;
575 }
576 return $elementObject;
577 } // end func _loadElement
578
579 // }}}
580 // {{{ addElement()
581
582 /**
583 * Adds an element into the form
584 *
585 * If $element is a string representing element type, then this
586 * method accepts variable number of parameters, their meaning
587 * and count depending on $element
588 *
589 * @param mixed $element element object or type of element to add (text, textarea, file...)
590 * @since 1.0
591 * @return object reference to element
592 * @access public
593 * @throws HTML_QuickForm_Error
594 */
595 function &addElement($element)
596 {
597 if (is_object($element) && is_subclass_of($element, 'html_quickform_element')) {
598 $elementObject = &$element;
599 $elementObject->onQuickFormEvent('updateValue', null, $this);
600 } else {
601 $args = func_get_args();
602 $elementObject =& $this->_loadElement('addElement', $element, array_slice($args, 1));
603 if (PEAR::isError($elementObject)) {
604 return $elementObject;
605 }
606 }
607 $elementName = $elementObject->getName();
608
609 // Add the element if it is not an incompatible duplicate
610 if (!empty($elementName) && isset($this->_elementIndex[$elementName])) {
611 if ($this->_elements[$this->_elementIndex[$elementName]]->getType() ==
612 $elementObject->getType()) {
613 $this->_elements[] =& $elementObject;
614 $elKeys = array_keys($this->_elements);
615 $this->_duplicateIndex[$elementName][] = end($elKeys);
616 } else {
617 $error = PEAR::raiseError(null, QUICKFORM_INVALID_ELEMENT_NAME, null, E_USER_WARNING, "Element '$elementName' already exists in HTML_QuickForm::addElement()", 'HTML_QuickForm_Error', true);
618 return $error;
619 }
620 } else {
621 $this->_elements[] =& $elementObject;
622 $elKeys = array_keys($this->_elements);
623 $this->_elementIndex[$elementName] = end($elKeys);
624 }
625 if ($this->_freezeAll) {
626 $elementObject->freeze();
627 }
628
629 return $elementObject;
630 } // end func addElement
631
632 // }}}
633 // {{{ insertElementBefore()
634
635 /**
636 * Inserts a new element right before the other element
637 *
638 * Warning: it is not possible to check whether the $element is already
639 * added to the form, therefore if you want to move the existing form
640 * element to a new position, you'll have to use removeElement():
641 * $form->insertElementBefore($form->removeElement('foo', false), 'bar');
642 *
643 * @access public
644 * @since 3.2.4
645 * @param object HTML_QuickForm_element Element to insert
646 * @param string Name of the element before which the new one is inserted
647 * @return object HTML_QuickForm_element reference to inserted element
648 * @throws HTML_QuickForm_Error
649 */
650 function &insertElementBefore(&$element, $nameAfter)
651 {
652 if (!empty($this->_duplicateIndex[$nameAfter])) {
653 $error = PEAR::raiseError(null, QUICKFORM_INVALID_ELEMENT_NAME, null, E_USER_WARNING, 'Several elements named "' . $nameAfter . '" exist in HTML_QuickForm::insertElementBefore().', 'HTML_QuickForm_Error', true);
654 return $error;
655 } elseif (!$this->elementExists($nameAfter)) {
656 $error = PEAR::raiseError(null, QUICKFORM_NONEXIST_ELEMENT, null, E_USER_WARNING, "Element '$nameAfter' does not exist in HTML_QuickForm::insertElementBefore()", 'HTML_QuickForm_Error', true);
657 return $error;
658 }
659 $elementName = $element->getName();
660 $targetIdx = $this->_elementIndex[$nameAfter];
661 $duplicate = false;
662 // Like in addElement(), check that it's not an incompatible duplicate
663 if (!empty($elementName) && isset($this->_elementIndex[$elementName])) {
664 if ($this->_elements[$this->_elementIndex[$elementName]]->getType() != $element->getType()) {
665 $error = PEAR::raiseError(null, QUICKFORM_INVALID_ELEMENT_NAME, null, E_USER_WARNING, "Element '$elementName' already exists in HTML_QuickForm::insertElementBefore()", 'HTML_QuickForm_Error', true);
666 return $error;
667 }
668 $duplicate = true;
669 }
670 // Move all the elements after added back one place, reindex _elementIndex and/or _duplicateIndex
671 $elKeys = array_keys($this->_elements);
672 for ($i = end($elKeys); $i >= $targetIdx; $i--) {
673 if (isset($this->_elements[$i])) {
674 $currentName = $this->_elements[$i]->getName();
675 $this->_elements[$i + 1] =& $this->_elements[$i];
676 if ($this->_elementIndex[$currentName] == $i) {
677 $this->_elementIndex[$currentName] = $i + 1;
678 } else {
679 $dupIdx = array_search($i, $this->_duplicateIndex[$currentName]);
680 $this->_duplicateIndex[$currentName][$dupIdx] = $i + 1;
681 }
682 unset($this->_elements[$i]);
683 }
684 }
685 // Put the element in place finally
686 $this->_elements[$targetIdx] =& $element;
687 if (!$duplicate) {
688 $this->_elementIndex[$elementName] = $targetIdx;
689 } else {
690 $this->_duplicateIndex[$elementName][] = $targetIdx;
691 }
692 $element->onQuickFormEvent('updateValue', null, $this);
693 if ($this->_freezeAll) {
694 $element->freeze();
695 }
696 // If not done, the elements will appear in reverse order
697 ksort($this->_elements);
698 return $element;
699 }
700
701 // }}}
702 // {{{ addGroup()
703
704 /**
705 * Adds an element group
706 * @param array $elements array of elements composing the group
707 * @param string $name (optional)group name
708 * @param string $groupLabel (optional)group label
709 * @param string $separator (optional)string to separate elements
710 * @param string $appendName (optional)specify whether the group name should be
711 * used in the form element name ex: group[element]
712 * @return object reference to added group of elements
713 * @since 2.8
714 * @access public
715 * @throws PEAR_Error
716 */
717 function &addGroup($elements, $name=null, $groupLabel='', $separator=null, $appendName = true)
718 {
719 static $anonGroups = 1;
720
721 if (0 == strlen($name)) {
722 $name = 'qf_group_' . $anonGroups++;
723 $appendName = false;
724 }
725 $group =& $this->addElement('group', $name, $groupLabel, $elements, $separator, $appendName);
726 return $group;
727 } // end func addGroup
728
729 // }}}
730 // {{{ &getElement()
731
732 /**
733 * Returns a reference to the element
734 *
735 * @param string $element Element name
736 * @since 2.0
737 * @access public
738 * @return object reference to element
739 * @throws HTML_QuickForm_Error
740 */
741 function &getElement($element)
742 {
743 if (isset($this->_elementIndex[$element])) {
744 return $this->_elements[$this->_elementIndex[$element]];
745 } else {
746 $error = PEAR::raiseError(null, QUICKFORM_NONEXIST_ELEMENT, null, E_USER_WARNING, "Element '$element' does not exist in HTML_QuickForm::getElement()", 'HTML_QuickForm_Error', true);
747 return $error;
748 }
749 } // end func getElement
750
751 // }}}
752 // {{{ &getElementValue()
753
754 /**
755 * Returns the element's raw value
756 *
757 * This returns the value as submitted by the form (not filtered)
758 * or set via setDefaults() or setConstants()
759 *
760 * @param string $element Element name
761 * @since 2.0
762 * @access public
763 * @return mixed element value
764 * @throws HTML_QuickForm_Error
765 */
766 function &getElementValue($element)
767 {
768 if (!isset($this->_elementIndex[$element])) {
769 $error = PEAR::raiseError(null, QUICKFORM_NONEXIST_ELEMENT, null, E_USER_WARNING, "Element '$element' does not exist in HTML_QuickForm::getElementValue()", 'HTML_QuickForm_Error', true);
770 return $error;
771 }
772 $value = $this->_elements[$this->_elementIndex[$element]]->getValue();
773 if (isset($this->_duplicateIndex[$element])) {
774 foreach ($this->_duplicateIndex[$element] as $index) {
775 if (null !== ($v = $this->_elements[$index]->getValue())) {
776 if (is_array($value)) {
777 $value[] = $v;
778 } else {
779 $value = (null === $value)? $v: array($value, $v);
780 }
781 }
782 }
783 }
784 return $value;
785 } // end func getElementValue
786
787 // }}}
788 // {{{ getSubmitValue()
789
790 /**
791 * Returns the elements value after submit and filter
792 *
793 * @param string Element name
794 * @since 2.0
795 * @access public
796 * @return mixed submitted element value or null if not set
797 */
798 function getSubmitValue($elementName)
799 {
800 $value = null;
801 if (isset($this->_submitValues[$elementName]) || isset($this->_submitFiles[$elementName])) {
802 $value = isset($this->_submitValues[$elementName])? $this->_submitValues[$elementName]: array();
803 if (is_array($value) && isset($this->_submitFiles[$elementName])) {
804 foreach ($this->_submitFiles[$elementName] as $k => $v) {
805 $value = HTML_QuickForm::arrayMerge($value, $this->_reindexFiles($this->_submitFiles[$elementName][$k], $k));
806 }
807 }
808
809 } elseif ('file' == $this->getElementType($elementName)) {
810 return $this->getElementValue($elementName);
811
812 } elseif (false !== ($pos = strpos($elementName, '['))) {
813 $base = substr($elementName, 0, $pos);
814 $idx = "['" . str_replace(array(']', '['), array('', "']['"), substr($elementName, $pos + 1, -1)) . "']";
815 if (isset($this->_submitValues[$base])) {
816 $value = eval("return (isset(\$this->_submitValues['{$base}']{$idx})) ? \$this->_submitValues['{$base}']{$idx} : null;");
817 }
818
819 if ((is_array($value) || null === $value) && isset($this->_submitFiles[$base])) {
820 $props = array('name', 'type', 'size', 'tmp_name', 'error');
821 $code = "if (!isset(\$this->_submitFiles['{$base}']['name']{$idx})) {\n" .
822 " return null;\n" .
823 "} else {\n" .
824 " \$v = array();\n";
825 foreach ($props as $prop) {
826 $code .= " \$v = HTML_QuickForm::arrayMerge(\$v, \$this->_reindexFiles(\$this->_submitFiles['{$base}']['{$prop}']{$idx}, '{$prop}'));\n";
827 }
828 $fileValue = eval($code . " return \$v;\n}\n");
829 if (null !== $fileValue) {
830 $value = null === $value? $fileValue: HTML_QuickForm::arrayMerge($value, $fileValue);
831 }
832 }
833 }
834
835 // This is only supposed to work for groups with appendName = false
836 if (null === $value && 'group' == $this->getElementType($elementName)) {
837 $group =& $this->getElement($elementName);
838 $elements =& $group->getElements();
839 foreach (array_keys($elements) as $key) {
840 $name = $group->getElementName($key);
841 // prevent endless recursion in case of radios and such
842 if ($name != $elementName) {
843 if (null !== ($v = $this->getSubmitValue($name))) {
844 $value[$name] = $v;
845 }
846 }
847 }
848 }
849 return $value;
850 } // end func getSubmitValue
851
852 // }}}
853 // {{{ _reindexFiles()
854
855 /**
856 * A helper function to change the indexes in $_FILES array
857 *
858 * @param mixed Some value from the $_FILES array
859 * @param string The key from the $_FILES array that should be appended
860 * @return array
861 */
862 function _reindexFiles($value, $key)
863 {
864 if (!is_array($value)) {
865 return array($key => $value);
866 } else {
867 $ret = array();
868 foreach ($value as $k => $v) {
869 $ret[$k] = $this->_reindexFiles($v, $key);
870 }
871 return $ret;
872 }
873 }
874
875 // }}}
876 // {{{ getElementError()
877
878 /**
879 * Returns error corresponding to validated element
880 *
881 * @param string $element Name of form element to check
882 * @since 1.0
883 * @access public
884 * @return string error message corresponding to checked element
885 */
886 function getElementError($element)
887 {
888 if (isset($this->_errors[$element])) {
889 return $this->_errors[$element];
890 }
891 } // end func getElementError
892
893 // }}}
894 // {{{ setElementError()
895
896 /**
897 * Set error message for a form element
898 *
899 * @param string $element Name of form element to set error for
900 * @param string $message Error message, if empty then removes the current error message
901 * @since 1.0
902 * @access public
903 * @return void
904 */
905 function setElementError($element, $message = null)
906 {
907 if (!empty($message)) {
908 $this->_errors[$element] = $message;
909 } else {
910 unset($this->_errors[$element]);
911 }
912 } // end func setElementError
913
914 // }}}
915 // {{{ getElementType()
916
917 /**
918 * Returns the type of the given element
919 *
920 * @param string $element Name of form element
921 * @since 1.1
922 * @access public
923 * @return string Type of the element, false if the element is not found
924 */
925 function getElementType($element)
926 {
927 if (isset($this->_elementIndex[$element])) {
928 return $this->_elements[$this->_elementIndex[$element]]->getType();
929 }
930 return false;
931 } // end func getElementType
932
933 // }}}
934 // {{{ updateElementAttr()
935
936 /**
937 * Updates Attributes for one or more elements
938 *
939 * @param mixed $elements Array of element names/objects or string of elements to be updated
940 * @param mixed $attrs Array or sting of html attributes
941 * @since 2.10
942 * @access public
943 * @return void
944 */
945 function updateElementAttr($elements, $attrs)
946 {
947 if (is_string($elements)) {
948 $elements = split('[ ]?,[ ]?', $elements);
949 }
950 foreach (array_keys($elements) as $key) {
951 if (is_object($elements[$key]) && is_a($elements[$key], 'HTML_QuickForm_element')) {
952 $elements[$key]->updateAttributes($attrs);
953 } elseif (isset($this->_elementIndex[$elements[$key]])) {
954 $this->_elements[$this->_elementIndex[$elements[$key]]]->updateAttributes($attrs);
955 if (isset($this->_duplicateIndex[$elements[$key]])) {
956 foreach ($this->_duplicateIndex[$elements[$key]] as $index) {
957 $this->_elements[$index]->updateAttributes($attrs);
958 }
959 }
960 }
961 }
962 } // end func updateElementAttr
963
964 // }}}
965 // {{{ removeElement()
966
967 /**
968 * Removes an element
969 *
970 * The method "unlinks" an element from the form, returning the reference
971 * to the element object. If several elements named $elementName exist,
972 * it removes the first one, leaving the others intact.
973 *
974 * @param string $elementName The element name
975 * @param boolean $removeRules True if rules for this element are to be removed too
976 * @access public
977 * @since 2.0
978 * @return object HTML_QuickForm_element a reference to the removed element
979 * @throws HTML_QuickForm_Error
980 */
981 function &removeElement($elementName, $removeRules = true)
982 {
983 if (!isset($this->_elementIndex[$elementName])) {
984 $error = PEAR::raiseError(null, QUICKFORM_NONEXIST_ELEMENT, null, E_USER_WARNING, "Element '$elementName' does not exist in HTML_QuickForm::removeElement()", 'HTML_QuickForm_Error', true);
985 return $error;
986 }
987 $el =& $this->_elements[$this->_elementIndex[$elementName]];
988 unset($this->_elements[$this->_elementIndex[$elementName]]);
989 if (empty($this->_duplicateIndex[$elementName])) {
990 unset($this->_elementIndex[$elementName]);
991 } else {
992 $this->_elementIndex[$elementName] = array_shift($this->_duplicateIndex[$elementName]);
993 }
994 if ($removeRules) {
995 unset($this->_rules[$elementName], $this->_errors[$elementName]);
996 }
997 return $el;
998 } // end func removeElement
999
1000 // }}}
1001 // {{{ addRule()
1002
1003 /**
1004 * Adds a validation rule for the given field
1005 *
1006 * If the element is in fact a group, it will be considered as a whole.
1007 * To validate grouped elements as separated entities,
1008 * use addGroupRule instead of addRule.
1009 *
1010 * @param string $element Form element name
1011 * @param string $message Message to display for invalid data
1012 * @param string $type Rule type, use getRegisteredRules() to get types
1013 * @param string $format (optional)Required for extra rule data
1014 * @param string $validation (optional)Where to perform validation: "server", "client"
1015 * @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
1016 * @param boolean $force Force the rule to be applied, even if the target form element does not exist
1017 * @since 1.0
1018 * @access public
1019 * @throws HTML_QuickForm_Error
1020 */
1021 function addRule($element, $message, $type, $format=null, $validation='server', $reset = false, $force = false)
1022 {
1023 if (!$force) {
1024 if (!is_array($element) && !$this->elementExists($element)) {
1025 return PEAR::raiseError(null, QUICKFORM_NONEXIST_ELEMENT, null, E_USER_WARNING, "Element '$element' does not exist in HTML_QuickForm::addRule()", 'HTML_QuickForm_Error', true);
1026 } elseif (is_array($element)) {
1027 foreach ($element as $el) {
1028 if (!$this->elementExists($el)) {
1029 return PEAR::raiseError(null, QUICKFORM_NONEXIST_ELEMENT, null, E_USER_WARNING, "Element '$el' does not exist in HTML_QuickForm::addRule()", 'HTML_QuickForm_Error', true);
1030 }
1031 }
1032 }
1033 }
1034 if (false === ($newName = $this->isRuleRegistered($type, true))) {
1035 return PEAR::raiseError(null, QUICKFORM_INVALID_RULE, null, E_USER_WARNING, "Rule '$type' is not registered in HTML_QuickForm::addRule()", 'HTML_QuickForm_Error', true);
1036 } elseif (is_string($newName)) {
1037 $type = $newName;
1038 }
1039 if (is_array($element)) {
1040 $dependent = $element;
1041 $element = array_shift($dependent);
1042 } else {
1043 $dependent = null;
1044 }
1045 if ($type == 'required' || $type == 'uploadedfile') {
1046 $this->_required[] = $element;
1047 }
1048 if (!isset($this->_rules[$element])) {
1049 $this->_rules[$element] = array();
1050 }
1051 if ($validation == 'client') {
1052 $this->updateAttributes(array('onsubmit' => 'try { var myValidator = validate_' . $this->_attributes['id'] . '; } catch(e) { return true; } return myValidator(this);'));
1053 }
1054 $this->_rules[$element][] = array(
1055 'type' => $type,
1056 'format' => $format,
1057 'message' => $message,
1058 'validation' => $validation,
1059 'reset' => $reset,
1060 'dependent' => $dependent
1061 );
1062 } // end func addRule
1063
1064 // }}}
1065 // {{{ addGroupRule()
1066
1067 /**
1068 * Adds a validation rule for the given group of elements
1069 *
1070 * Only groups with a name can be assigned a validation rule
1071 * Use addGroupRule when you need to validate elements inside the group.
1072 * Use addRule if you need to validate the group as a whole. In this case,
1073 * the same rule will be applied to all elements in the group.
1074 * Use addRule if you need to validate the group against a function.
1075 *
1076 * @param string $group Form group name
1077 * @param mixed $arg1 Array for multiple elements or error message string for one element
1078 * @param string $type (optional)Rule type use getRegisteredRules() to get types
1079 * @param string $format (optional)Required for extra rule data
1080 * @param int $howmany (optional)How many valid elements should be in the group
1081 * @param string $validation (optional)Where to perform validation: "server", "client"
1082 * @param bool $reset Client-side: whether to reset the element's value to its original state if validation failed.
1083 * @since 2.5
1084 * @access public
1085 * @throws HTML_QuickForm_Error
1086 */
1087 function addGroupRule($group, $arg1, $type='', $format=null, $howmany=0, $validation = 'server', $reset = false)
1088 {
1089 if (!$this->elementExists($group)) {
1090 return PEAR::raiseError(null, QUICKFORM_NONEXIST_ELEMENT, null, E_USER_WARNING, "Group '$group' does not exist in HTML_QuickForm::addGroupRule()", 'HTML_QuickForm_Error', true);
1091 }
1092
1093 $groupObj =& $this->getElement($group);
1094 if (is_array($arg1)) {
1095 $required = 0;
1096 foreach ($arg1 as $elementIndex => $rules) {
1097 $elementName = $groupObj->getElementName($elementIndex);
1098 foreach ($rules as $rule) {
1099 $format = (isset($rule[2])) ? $rule[2] : null;
1100 $validation = (isset($rule[3]) && 'client' == $rule[3])? 'client': 'server';
1101 $reset = isset($rule[4]) && $rule[4];
1102 $type = $rule[1];
1103 if (false === ($newName = $this->isRuleRegistered($type, true))) {
1104 return PEAR::raiseError(null, QUICKFORM_INVALID_RULE, null, E_USER_WARNING, "Rule '$type' is not registered in HTML_QuickForm::addGroupRule()", 'HTML_QuickForm_Error', true);
1105 } elseif (is_string($newName)) {
1106 $type = $newName;
1107 }
1108
1109 $this->_rules[$elementName][] = array(
1110 'type' => $type,
1111 'format' => $format,
1112 'message' => $rule[0],
1113 'validation' => $validation,
1114 'reset' => $reset,
1115 'group' => $group);
1116
1117 if ('required' == $type || 'uploadedfile' == $type) {
1118 $groupObj->_required[] = $elementName;
1119 $this->_required[] = $elementName;
1120 $required++;
1121 }
1122 if ('client' == $validation) {
1123 $this->updateAttributes(array('onsubmit' => 'try { var myValidator = validate_' . $this->_attributes['id'] . '; } catch(e) { return true; } return myValidator(this);'));
1124 }
1125 }
1126 }
1127 if ($required > 0 && count($groupObj->getElements()) == $required) {
1128 $this->_required[] = $group;
1129 }
1130 } elseif (is_string($arg1)) {
1131 if (false === ($newName = $this->isRuleRegistered($type, true))) {
1132 return PEAR::raiseError(null, QUICKFORM_INVALID_RULE, null, E_USER_WARNING, "Rule '$type' is not registered in HTML_QuickForm::addGroupRule()", 'HTML_QuickForm_Error', true);
1133 } elseif (is_string($newName)) {
1134 $type = $newName;
1135 }
1136
1137 // addGroupRule() should also handle <select multiple>
1138 if (is_a($groupObj, 'html_quickform_group')) {
1139 // Radios need to be handled differently when required
1140 if ($type == 'required' && $groupObj->getGroupType() == 'radio') {
1141 $howmany = ($howmany == 0) ? 1 : $howmany;
1142 } else {
1143 $howmany = ($howmany == 0) ? count($groupObj->getElements()) : $howmany;
1144 }
1145 }
1146
1147 $this->_rules[$group][] = array('type' => $type,
1148 'format' => $format,
1149 'message' => $arg1,
1150 'validation' => $validation,
1151 'howmany' => $howmany,
1152 'reset' => $reset);
1153 if ($type == 'required') {
1154 $this->_required[] = $group;
1155 }
1156 if ($validation == 'client') {
1157 $this->updateAttributes(array('onsubmit' => 'try { var myValidator = validate_' . $this->_attributes['id'] . '; } catch(e) { return true; } return myValidator(this);'));
1158 }
1159 }
1160 } // end func addGroupRule
1161
1162 // }}}
1163 // {{{ addFormRule()
1164
1165 /**
1166 * Adds a global validation rule
1167 *
1168 * This should be used when for a rule involving several fields or if
1169 * you want to use some completely custom validation for your form.
1170 * The rule function/method should return true in case of successful
1171 * validation and array('element name' => 'error') when there were errors.
1172 *
1173 * @access public
1174 * @param mixed Callback, either function name or array(&$object, 'method')
1175 * @throws HTML_QuickForm_Error
1176 */
1177 function addFormRule($rule)
1178 {
1179 if (!is_callable($rule)) {
1180 return PEAR::raiseError(null, QUICKFORM_INVALID_RULE, null, E_USER_WARNING, 'Callback function does not exist in HTML_QuickForm::addFormRule()', 'HTML_QuickForm_Error', true);
1181 }
1182 $this->_formRules[] = $rule;
1183 }
1184
1185 // }}}
1186 // {{{ applyFilter()
1187
1188 /**
1189 * Applies a data filter for the given field(s)
1190 *
1191 * @param mixed $element Form element name or array of such names
1192 * @param mixed $filter Callback, either function name or array(&$object, 'method')
1193 * @since 2.0
1194 * @access public
1195 */
1196 function applyFilter($element, $filter)
1197 {
1198 if (!is_callable($filter)) {
1199 return PEAR::raiseError(null, QUICKFORM_INVALID_FILTER, null, E_USER_WARNING, "Callback function does not exist in QuickForm::applyFilter()", 'HTML_QuickForm_Error', true);
1200 }
1201 if ($element == '__ALL__') {
1202 $this->_submitValues = $this->_recursiveFilter($filter, $this->_submitValues);
1203 } else {
1204 if (!is_array($element)) {
1205 $element = array($element);
1206 }
1207 foreach ($element as $elName) {
1208 $value = $this->getSubmitValue($elName);
1209 if (null !== $value) {
1210 if (false === strpos($elName, '[')) {
1211 $this->_submitValues[$elName] = $this->_recursiveFilter($filter, $value);
1212 } else {
1213 $idx = "['" . str_replace(array(']', '['), array('', "']['"), $elName) . "']";
1214 eval("\$this->_submitValues{$idx} = \$this->_recursiveFilter(\$filter, \$value);");
1215 }
1216 }
1217 }
1218 }
1219 } // end func applyFilter
1220
1221 // }}}
1222 // {{{ _recursiveFilter()
1223
1224 /**
1225 * Recursively apply a filter function
1226 *
1227 * @param string $filter filter to apply
1228 * @param mixed $value submitted values
1229 * @since 2.0
1230 * @access private
1231 * @return cleaned values
1232 */
1233 function _recursiveFilter($filter, $value)
1234 {
1235 if (is_array($value)) {
1236 $cleanValues = array();
1237 foreach ($value as $k => $v) {
1238 $cleanValues[$k] = $this->_recursiveFilter($filter, $v);
1239 }
1240 return $cleanValues;
1241 } else {
1242 return call_user_func($filter, $value);
1243 }
1244 } // end func _recursiveFilter
1245
1246 // }}}
1247 // {{{ arrayMerge()
1248
1249 /**
1250 * Merges two arrays
1251 *
1252 * Merges two array like the PHP function array_merge but recursively.
1253 * The main difference is that existing keys will not be renumbered
1254 * if they are integers.
1255 *
1256 * @access puplic
1257 * @param array $a original array
1258 * @param array $b array which will be merged into first one
1259 * @return array merged array
1260 */
1261 function arrayMerge($a, $b)
1262 {
1263 foreach ($b as $k => $v) {
1264 if (is_array($v)) {
1265 if (isset($a[$k]) && !is_array($a[$k])) {
1266 $a[$k] = $v;
1267 } else {
1268 if (!isset($a[$k])) {
1269 $a[$k] = array();
1270 }
1271 $a[$k] = HTML_QuickForm::arrayMerge($a[$k], $v);
1272 }
1273 } else {
1274 $a[$k] = $v;
1275 }
1276 }
1277 return $a;
1278 } // end func arrayMerge
1279
1280 // }}}
1281 // {{{ isTypeRegistered()
1282
1283 /**
1284 * Returns whether or not the form element type is supported
1285 *
1286 * @param string $type Form element type
1287 * @since 1.0
1288 * @access public
1289 * @return boolean
1290 */
1291 function isTypeRegistered($type)
1292 {
1293 return isset($GLOBALS['HTML_QUICKFORM_ELEMENT_TYPES'][strtolower($type)]);
1294 } // end func isTypeRegistered
1295
1296 // }}}
1297 // {{{ getRegisteredTypes()
1298
1299 /**
1300 * Returns an array of registered element types
1301 *
1302 * @since 1.0
1303 * @access public
1304 * @return array
1305 */
1306 function getRegisteredTypes()
1307 {
1308 return array_keys($GLOBALS['HTML_QUICKFORM_ELEMENT_TYPES']);
1309 } // end func getRegisteredTypes
1310
1311 // }}}
1312 // {{{ isRuleRegistered()
1313
1314 /**
1315 * Returns whether or not the given rule is supported
1316 *
1317 * @param string $name Validation rule name
1318 * @param bool Whether to automatically register subclasses of HTML_QuickForm_Rule
1319 * @since 1.0
1320 * @access public
1321 * @return mixed true if previously registered, false if not, new rule name if auto-registering worked
1322 */
1323 function isRuleRegistered($name, $autoRegister = false)
1324 {
1325 if (is_scalar($name) && isset($GLOBALS['_HTML_QuickForm_registered_rules'][$name])) {
1326 return true;
1327 } elseif (!$autoRegister) {
1328 return false;
1329 }
1330 // automatically register the rule if requested
1331 include_once 'HTML/QuickForm/RuleRegistry.php';
1332 $ruleName = false;
1333 if (is_object($name) && is_a($name, 'html_quickform_rule')) {
1334 $ruleName = !empty($name->name)? $name->name: strtolower(get_class($name));
1335 } elseif (is_string($name) && class_exists($name)) {
1336 $parent = strtolower($name);
1337 do {
1338 if ('html_quickform_rule' == strtolower($parent)) {
1339 $ruleName = strtolower($name);
1340 break;
1341 }
1342 } while ($parent = get_parent_class($parent));
1343 }
1344 if ($ruleName) {
1345 $registry =& HTML_QuickForm_RuleRegistry::singleton();
1346 $registry->registerRule($ruleName, null, $name);
1347 }
1348 return $ruleName;
1349 } // end func isRuleRegistered
1350
1351 // }}}
1352 // {{{ getRegisteredRules()
1353
1354 /**
1355 * Returns an array of registered validation rules
1356 *
1357 * @since 1.0
1358 * @access public
1359 * @return array
1360 */
1361 function getRegisteredRules()
1362 {
1363 return array_keys($GLOBALS['_HTML_QuickForm_registered_rules']);
1364 } // end func getRegisteredRules
1365
1366 // }}}
1367 // {{{ isElementRequired()
1368
1369 /**
1370 * Returns whether or not the form element is required
1371 *
1372 * @param string $element Form element name
1373 * @since 1.0
1374 * @access public
1375 * @return boolean
1376 */
1377 function isElementRequired($element)
1378 {
1379 return in_array($element, $this->_required, true);
1380 } // end func isElementRequired
1381
1382 // }}}
1383 // {{{ isElementFrozen()
1384
1385 /**
1386 * Returns whether or not the form element is frozen
1387 *
1388 * @param string $element Form element name
1389 * @since 1.0
1390 * @access public
1391 * @return boolean
1392 */
1393 function isElementFrozen($element)
1394 {
1395 if (isset($this->_elementIndex[$element])) {
1396 return $this->_elements[$this->_elementIndex[$element]]->isFrozen();
1397 }
1398 return false;
1399 } // end func isElementFrozen
1400
1401 // }}}
1402 // {{{ setJsWarnings()
1403
1404 /**
1405 * Sets JavaScript warning messages
1406 *
1407 * @param string $pref Prefix warning
1408 * @param string $post Postfix warning
1409 * @since 1.1
1410 * @access public
1411 * @return void
1412 */
1413 function setJsWarnings($pref, $post)
1414 {
1415 $this->_jsPrefix = $pref;
1416 $this->_jsPostfix = $post;
1417 } // end func setJsWarnings
1418
1419 // }}}
1420 // {{{ setRequiredNote()
1421
1422 /**
1423 * Sets required-note
1424 *
1425 * @param string $note Message indicating some elements are required
1426 * @since 1.1
1427 * @access public
1428 * @return void
1429 */
1430 function setRequiredNote($note)
1431 {
1432 $this->_requiredNote = $note;
1433 } // end func setRequiredNote
1434
1435 // }}}
1436 // {{{ getRequiredNote()
1437
1438 /**
1439 * Returns the required note
1440 *
1441 * @since 2.0
1442 * @access public
1443 * @return string
1444 */
1445 function getRequiredNote()
1446 {
1447 return $this->_requiredNote;
1448 } // end func getRequiredNote
1449
1450 // }}}
1451 // {{{ validate()
1452
1453 /**
1454 * Performs the server side validation
1455 * @access public
1456 * @since 1.0
1457 * @return boolean true if no error found
1458 */
1459 function validate()
1460 {
1461 if (count($this->_rules) == 0 && count($this->_formRules) == 0 &&
1462 $this->isSubmitted()) {
1463 return (0 == count($this->_errors));
1464 } elseif (!$this->isSubmitted()) {
1465 return false;
1466 }
1467
1468 include_once('HTML/QuickForm/RuleRegistry.php');
1469 $registry =& HTML_QuickForm_RuleRegistry::singleton();
1470
1471 foreach ($this->_rules as $target => $rules) {
1472 $submitValue = $this->getSubmitValue($target);
1473
1474 foreach ($rules as $rule) {
1475 if ((isset($rule['group']) && isset($this->_errors[$rule['group']])) ||
1476 isset($this->_errors[$target])) {
1477 continue 2;
1478 }
1479 // If element is not required and is empty, we shouldn't validate it
1480 if (!$this->isElementRequired($target)) {
1481 if (!isset($submitValue) || '' == $submitValue) {
1482 continue 2;
1483 // Fix for bug #3501: we shouldn't validate not uploaded files, either.
1484 // Unfortunately, we can't just use $element->isUploadedFile() since
1485 // the element in question can be buried in group. Thus this hack.
1486 } elseif (is_array($submitValue)) {
1487 if (false === ($pos = strpos($target, '['))) {
1488 $isUpload = !empty($this->_submitFiles[$target]);
1489 } else {
1490 $base = substr($target, 0, $pos);
1491 $idx = "['" . str_replace(array(']', '['), array('', "']['"), substr($target, $pos + 1, -1)) . "']";
1492 eval("\$isUpload = isset(\$this->_submitFiles['{$base}']['name']{$idx});");
1493 }
1494 if ($isUpload && (!isset($submitValue['error']) || 0 != $submitValue['error'])) {
1495 continue 2;
1496 }
1497 }
1498 }
1499 if (isset($rule['dependent']) && is_array($rule['dependent'])) {
1500 $values = array($submitValue);
1501 foreach ($rule['dependent'] as $elName) {
1502 $values[] = $this->getSubmitValue($elName);
1503 }
1504 $result = $registry->validate($rule['type'], $values, $rule['format'], true);
1505 } elseif (is_array($submitValue) && !isset($rule['howmany'])) {
1506 $result = $registry->validate($rule['type'], $submitValue, $rule['format'], true);
1507 } else {
1508 $result = $registry->validate($rule['type'], $submitValue, $rule['format'], false);
1509 }
1510
1511 if (!$result || (!empty($rule['howmany']) && $rule['howmany'] > (int)$result)) {
1512 if (isset($rule['group'])) {
1513 $this->_errors[$rule['group']] = $rule['message'];
1514 } else {
1515 $this->_errors[$target] = $rule['message'];
1516 }
1517 }
1518 }
1519 }
1520
1521 // process the global rules now
1522 foreach ($this->_formRules as $rule) {
1523 if (true !== ($res = call_user_func($rule, $this->_submitValues, $this->_submitFiles))) {
1524 if (is_array($res)) {
1525 $this->_errors += $res;
1526 } else {
1527 return PEAR::raiseError(null, QUICKFORM_ERROR, null, E_USER_WARNING, 'Form rule callback returned invalid value in HTML_QuickForm::validate()', 'HTML_QuickForm_Error', true);
1528 }
1529 }
1530 }
1531
1532 return (0 == count($this->_errors));
1533 } // end func validate
1534
1535 // }}}
1536 // {{{ freeze()
1537
1538 /**
1539 * Displays elements without HTML input tags
1540 *
1541 * @param mixed $elementList array or string of element(s) to be frozen
1542 * @since 1.0
1543 * @access public
1544 * @throws HTML_QuickForm_Error
1545 */
1546 function freeze($elementList=null)
1547 {
1548 if (!isset($elementList)) {
1549 $this->_freezeAll = true;
1550 $elementList = array();
1551 } else {
1552 if (!is_array($elementList)) {
1553 $elementList = preg_split('/[ ]*,[ ]*/', $elementList);
1554 }
1555 $elementList = array_flip($elementList);
1556 }
1557
1558 foreach (array_keys($this->_elements) as $key) {
1559 $name = $this->_elements[$key]->getName();
1560 if ($this->_freezeAll || isset($elementList[$name])) {
1561 $this->_elements[$key]->freeze();
1562 unset($elementList[$name]);
1563 }
1564 }
1565
1566 if (!empty($elementList)) {
1567 return PEAR::raiseError(null, QUICKFORM_NONEXIST_ELEMENT, null, E_USER_WARNING, "Nonexistant element(s): '" . implode("', '", array_keys($elementList)) . "' in HTML_QuickForm::freeze()", 'HTML_QuickForm_Error', true);
1568 }
1569 return true;
1570 } // end func freeze
1571
1572 // }}}
1573 // {{{ isFrozen()
1574
1575 /**
1576 * Returns whether or not the whole form is frozen
1577 *
1578 * @since 3.0
1579 * @access public
1580 * @return boolean
1581 */
1582 function isFrozen()
1583 {
1584 return $this->_freezeAll;
1585 } // end func isFrozen
1586
1587 // }}}
1588 // {{{ process()
1589
1590 /**
1591 * Performs the form data processing
1592 *
1593 * @param mixed $callback Callback, either function name or array(&$object, 'method')
1594 * @param bool $mergeFiles Whether uploaded files should be processed too
1595 * @since 1.0
1596 * @access public
1597 * @throws HTML_QuickForm_Error
1598 */
1599 function process($callback, $mergeFiles = true)
1600 {
1601 if (!is_callable($callback)) {
1602 return PEAR::raiseError(null, QUICKFORM_INVALID_PROCESS, null, E_USER_WARNING, "Callback function does not exist in QuickForm::process()", 'HTML_QuickForm_Error', true);
1603 }
1604 $values = ($mergeFiles === true) ? HTML_QuickForm::arrayMerge($this->_submitValues, $this->_submitFiles) : $this->_submitValues;
1605 return call_user_func($callback, $values);
1606 } // end func process
1607
1608 // }}}
1609 // {{{ accept()
1610
1611 /**
1612 * Accepts a renderer
1613 *
1614 * @param object An HTML_QuickForm_Renderer object
1615 * @since 3.0
1616 * @access public
1617 * @return void
1618 */
1619 function accept(&$renderer)
1620 {
1621 $renderer->startForm($this);
1622 foreach (array_keys($this->_elements) as $key) {
1623 $element =& $this->_elements[$key];
1624 $elementName = $element->getName();
1625 $required = ($this->isElementRequired($elementName) && !$element->isFrozen());
1626 $error = $this->getElementError($elementName);
1627 $element->accept($renderer, $required, $error);
1628 }
1629 $renderer->finishForm($this);
1630 } // end func accept
1631
1632 // }}}
1633 // {{{ defaultRenderer()
1634
1635 /**
1636 * Returns a reference to default renderer object
1637 *
1638 * @access public
1639 * @since 3.0
1640 * @return object a default renderer object
1641 */
1642 function &defaultRenderer()
1643 {
1644 if (!isset($GLOBALS['_HTML_QuickForm_default_renderer'])) {
1645 include_once('HTML/QuickForm/Renderer/Default.php');
1646 $GLOBALS['_HTML_QuickForm_default_renderer'] =& new HTML_QuickForm_Renderer_Default();
1647 }
1648 return $GLOBALS['_HTML_QuickForm_default_renderer'];
1649 } // end func defaultRenderer
1650
1651 // }}}
1652 // {{{ toHtml ()
1653
1654 /**
1655 * Returns an HTML version of the form
1656 *
1657 * @param string $in_data (optional) Any extra data to insert right
1658 * before form is rendered. Useful when using templates.
1659 *
1660 * @return string Html version of the form
1661 * @since 1.0
1662 * @access public
1663 */
1664 function toHtml ($in_data = null)
1665 {
1666 if (!is_null($in_data)) {
1667 $this->addElement('html', $in_data);
1668 }
1669 $renderer =& $this->defaultRenderer();
1670 $this->accept($renderer);
1671 return $renderer->toHtml();
1672 } // end func toHtml
1673
1674 // }}}
1675 // {{{ getValidationScript()
1676
1677 /**
1678 * Returns the client side validation script
1679 *
1680 * @since 2.0
1681 * @access public
1682 * @return string Javascript to perform validation, empty string if no 'client' rules were added
1683 */
1684 function getValidationScript()
1685 {
1686 if (empty($this->_rules) || empty($this->_attributes['onsubmit'])) {
1687 return '';
1688 }
1689
1690 include_once('HTML/QuickForm/RuleRegistry.php');
1691 $registry =& HTML_QuickForm_RuleRegistry::singleton();
1692 $test = array();
1693 $js_escape = array(
1694 "\r" => '\r',
1695 "\n" => '\n',
1696 "\t" => '\t',
1697 "'" => "\\'",
1698 '"' => '\"',
1699 '\\' => '\\\\'
1700 );
1701
1702 foreach ($this->_rules as $elementName => $rules) {
1703 foreach ($rules as $rule) {
1704 if ('client' == $rule['validation']) {
1705 unset($element);
1706
1707 $dependent = isset($rule['dependent']) && is_array($rule['dependent']);
1708 $rule['message'] = strtr($rule['message'], $js_escape);
1709
1710 if (isset($rule['group'])) {
1711 $group =& $this->getElement($rule['group']);
1712 // No JavaScript validation for frozen elements
1713 if ($group->isFrozen()) {
1714 continue 2;
1715 }
1716 $elements =& $group->getElements();
1717 foreach (array_keys($elements) as $key) {
1718 if ($elementName == $group->getElementName($key)) {
1719 $element =& $elements[$key];
1720 break;
1721 }
1722 }
1723 } elseif ($dependent) {
1724 $element = array();
1725 $element[] =& $this->getElement($elementName);
1726 foreach ($rule['dependent'] as $elName) {
1727 $element[] =& $this->getElement($elName);
1728 }
1729 } else {
1730 $element =& $this->getElement($elementName);
1731 }
1732 // No JavaScript validation for frozen elements
1733 if (is_object($element) && $element->isFrozen()) {
1734 continue 2;
1735 } elseif (is_array($element)) {
1736 foreach (array_keys($element) as $key) {
1737 if ($element[$key]->isFrozen()) {
1738 continue 3;
1739 }
1740 }
1741 }
1742
1743 $test[] = $registry->getValidationScript($element, $elementName, $rule);
1744 }
1745 }
1746 }
1747 if (count($test) > 0) {
1748 return
1749 "\n<script type=\"text/javascript\">\n" .
1750 "//<![CDATA[\n" .
1751 "function validate_" . $this->_attributes['id'] . "(frm) {\n" .
1752 " var value = '';\n" .
1753 " var errFlag = new Array();\n" .
1754 " var _qfGroups = {};\n" .
1755 " _qfMsg = '';\n\n" .
1756 join("\n", $test) .
1757 "\n if (_qfMsg != '') {\n" .
1758 " _qfMsg = '" . strtr($this->_jsPrefix, $js_escape) . "' + _qfMsg;\n" .
1759 " _qfMsg = _qfMsg + '\\n" . strtr($this->_jsPostfix, $js_escape) . "';\n" .
1760 " alert(_qfMsg);\n" .
1761 " return false;\n" .
1762 " }\n" .
1763 " return true;\n" .
1764 "}\n" .
1765 "//]]>\n" .
1766 "</script>";
1767 }
1768 return '';
1769 } // end func getValidationScript
1770
1771 // }}}
1772 // {{{ getSubmitValues()
1773
1774 /**
1775 * Returns the values submitted by the form
1776 *
1777 * @since 2.0
1778 * @access public
1779 * @param bool Whether uploaded files should be returned too
1780 * @return array
1781 */
1782 function getSubmitValues($mergeFiles = false)
1783 {
1784 return $mergeFiles? HTML_QuickForm::arrayMerge($this->_submitValues, $this->_submitFiles): $this->_submitValues;
1785 } // end func getSubmitValues
1786
1787 // }}}
1788 // {{{ toArray()
1789
1790 /**
1791 * Returns the form's contents in an array.
1792 *
1793 * The description of the array structure is in HTML_QuickForm_Renderer_Array docs
1794 *
1795 * @since 2.0
1796 * @access public
1797 * @param bool Whether to collect hidden elements (passed to the Renderer's constructor)
1798 * @return array of form contents
1799 */
1800 function toArray($collectHidden = false)
1801 {
1802 include_once 'HTML/QuickForm/Renderer/Array.php';
1803 $renderer =& new HTML_QuickForm_Renderer_Array($collectHidden);
1804 $this->accept($renderer);
1805 return $renderer->toArray();
1806 } // end func toArray
1807
1808 // }}}
1809 // {{{ exportValue()
1810
1811 /**
1812 * Returns a 'safe' element's value
1813 *
1814 * This method first tries to find a cleaned-up submitted value,
1815 * it will return a value set by setValue()/setDefaults()/setConstants()
1816 * if submitted value does not exist for the given element.
1817 *
1818 * @param string Name of an element
1819 * @access public
1820 * @return mixed
1821 */
1822 function exportValue($element)
1823 {
1824 if (!isset($this->_elementIndex[$element])) {
1825 return PEAR::raiseError(null, QUICKFORM_NONEXIST_ELEMENT, null, E_USER_WARNING, "Element '$element' does not exist in HTML_QuickForm::getElementValue()", 'HTML_QuickForm_Error', true);
1826 }
1827 $value = $this->_elements[$this->_elementIndex[$element]]->exportValue($this->_submitValues, false);
1828 if (isset($this->_duplicateIndex[$element])) {
1829 foreach ($this->_duplicateIndex[$element] as $index) {
1830 if (null !== ($v = $this->_elements[$index]->exportValue($this->_submitValues, false))) {
1831 if (is_array($value)) {
1832 $value[] = $v;
1833 } else {
1834 $value = (null === $value)? $v: array($value, $v);
1835 }
1836 }
1837 }
1838 }
1839 return $value;
1840 }
1841
1842 // }}}
1843 // {{{ exportValues()
1844
1845 /**
1846 * Returns 'safe' elements' values
1847 *
1848 * Unlike getSubmitValues(), this will return only the values
1849 * corresponding to the elements present in the form.
1850 *
1851 * @param mixed Array/string of element names, whose values we want. If not set then return all elements.
1852 * @access public
1853 * @return array An assoc array of elements' values
1854 * @throws HTML_QuickForm_Error
1855 */
1856 function exportValues($elementList = null)
1857 {
1858 $values = array();
1859 if (null === $elementList) {
1860 // iterate over all elements, calling their exportValue() methods
1861 foreach (array_keys($this->_elements) as $key) {
1862 $value = $this->_elements[$key]->exportValue($this->_submitValues, true);
1863 if (is_array($value)) {
1864 // This shit throws a bogus warning in PHP 4.3.x
1865 $values = HTML_QuickForm::arrayMerge($values, $value);
1866 }
1867 }
1868 } else {
1869 if (!is_array($elementList)) {
1870 $elementList = array_map('trim', explode(',', $elementList));
1871 }
1872 foreach ($elementList as $elementName) {
1873 $value = $this->exportValue($elementName);
1874 if (PEAR::isError($value)) {
1875 return $value;
1876 }
1877 $values[$elementName] = $value;
1878 }
1879 }
1880 return $values;
1881 }
1882
1883 // }}}
1884 // {{{ isSubmitted()
1885
1886 /**
1887 * Tells whether the form was already submitted
1888 *
1889 * This is useful since the _submitFiles and _submitValues arrays
1890 * may be completely empty after the trackSubmit value is removed.
1891 *
1892 * @access public
1893 * @return bool
1894 */
1895 function isSubmitted()
1896 {
1897 return $this->_flagSubmitted;
1898 }
1899
1900
1901 // }}}
1902 // {{{ isError()
1903
1904 /**
1905 * Tell whether a result from a QuickForm method is an error (an instance of HTML_QuickForm_Error)
1906 *
1907 * @access public
1908 * @param mixed result code
1909 * @return bool whether $value is an error
1910 */
1911 function isError($value)
1912 {
1913 return (is_object($value) && is_a($value, 'html_quickform_error'));
1914 } // end func isError
1915
1916 // }}}
1917 // {{{ errorMessage()
1918
1919 /**
1920 * Return a textual error message for an QuickForm error code
1921 *
1922 * @access public
1923 * @param int error code
1924 * @return string error message
1925 */
1926 function errorMessage($value)
1927 {
1928 // make the variable static so that it only has to do the defining on the first call
1929 static $errorMessages;
1930
1931 // define the varies error messages
1932 if (!isset($errorMessages)) {
1933 $errorMessages = array(
1934 QUICKFORM_OK => 'no error',
1935 QUICKFORM_ERROR => 'unknown error',
1936 QUICKFORM_INVALID_RULE => 'the rule does not exist as a registered rule',
1937 QUICKFORM_NONEXIST_ELEMENT => 'nonexistent html element',
1938 QUICKFORM_INVALID_FILTER => 'invalid filter',
1939 QUICKFORM_UNREGISTERED_ELEMENT => 'unregistered element',
1940 QUICKFORM_INVALID_ELEMENT_NAME => 'element already exists',
1941 QUICKFORM_INVALID_PROCESS => 'process callback does not exist',
1942 QUICKFORM_DEPRECATED => 'method is deprecated',
1943 QUICKFORM_INVALID_DATASOURCE => 'datasource is not an object'
1944 );
1945 }
1946
1947 // If this is an error object, then grab the corresponding error code
1948 if (HTML_QuickForm::isError($value)) {
1949 $value = $value->getCode();
1950 }
1951
1952 // return the textual error message corresponding to the code
1953 return isset($errorMessages[$value]) ? $errorMessages[$value] : $errorMessages[QUICKFORM_ERROR];
1954 } // end func errorMessage
1955
1956 // }}}
1957} // end class HTML_QuickForm
1958
1959class HTML_QuickForm_Error extends PEAR_Error {
1960
1961 // {{{ properties
1962
1963 /**
1964 * Prefix for all error messages
1965 * @var string
1966 */
1967 var $error_message_prefix = 'QuickForm Error: ';
1968
1969 // }}}
1970 // {{{ constructor
1971
1972 /**
1973 * Creates a quickform error object, extending the PEAR_Error class
1974 *
1975 * @param int $code the error code
1976 * @param int $mode the reaction to the error, either return, die or trigger/callback
1977 * @param int $level intensity of the error (PHP error code)
1978 * @param mixed $debuginfo any information that can inform user as to nature of the error
1979 */
1980 function HTML_QuickForm_Error($code = QUICKFORM_ERROR, $mode = PEAR_ERROR_RETURN,
1981 $level = E_USER_NOTICE, $debuginfo = null)
1982 {
1983 if (is_int($code)) {
1984 $this->PEAR_Error(HTML_QuickForm::errorMessage($code), $code, $mode, $level, $debuginfo);
1985 } else {
1986 $this->PEAR_Error("Invalid error code: $code", QUICKFORM_ERROR, $mode, $level, $debuginfo);
1987 }
1988 }
1989
1990 // }}}
1991} // end class HTML_QuickForm_Error
1992?>