group.php 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590
  1. <?php
  2. /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
  3. /**
  4. * HTML class for a form element group
  5. *
  6. * PHP versions 4 and 5
  7. *
  8. * LICENSE: This source file is subject to version 3.01 of the PHP license
  9. * that is available through the world-wide-web at the following URI:
  10. * http://www.php.net/license/3_01.txt If you did not receive a copy of
  11. * the PHP License and are unable to obtain it through the web, please
  12. * send a note to license@php.net so we can mail you a copy immediately.
  13. *
  14. * @category HTML
  15. * @package HTML_QuickForm
  16. * @author Adam Daniel <adaniel1@eesus.jnj.com>
  17. * @author Bertrand Mansion <bmansion@mamasam.com>
  18. * @author Alexey Borzov <avb@php.net>
  19. * @copyright 2001-2009 The PHP Group
  20. * @license http://www.php.net/license/3_01.txt PHP License 3.01
  21. * @version CVS: $Id: group.php,v 1.40 2009/04/04 21:34:03 avb Exp $
  22. * @link http://pear.php.net/package/HTML_QuickForm
  23. */
  24. /**
  25. * Base class for form elements
  26. */
  27. //require_once 'HTML/QuickForm/element.php';
  28. /**
  29. * HTML class for a form element group
  30. *
  31. * @category HTML
  32. * @package HTML_QuickForm
  33. * @author Adam Daniel <adaniel1@eesus.jnj.com>
  34. * @author Bertrand Mansion <bmansion@mamasam.com>
  35. * @author Alexey Borzov <avb@php.net>
  36. * @version Release: 3.2.11
  37. * @since 1.0
  38. */
  39. class HTML_QuickForm_group extends HTML_QuickForm_element
  40. {
  41. // {{{ properties
  42. /**
  43. * Name of the element
  44. * @var string
  45. * @since 1.0
  46. * @access private
  47. */
  48. var $_name = '';
  49. /**
  50. * Array of grouped elements
  51. * @var array
  52. * @since 1.0
  53. * @access private
  54. */
  55. var $_elements = array();
  56. /**
  57. * String to separate elements
  58. * @var mixed
  59. * @since 2.5
  60. * @access private
  61. */
  62. var $_separator = null;
  63. /**
  64. * Required elements in this group
  65. * @var array
  66. * @since 2.5
  67. * @access private
  68. */
  69. var $_required = array();
  70. /**
  71. * Whether to change elements' names to $groupName[$elementName] or leave them as is
  72. * @var bool
  73. * @since 3.0
  74. * @access private
  75. */
  76. var $_appendName = true;
  77. // }}}
  78. // {{{ constructor
  79. /**
  80. * Class constructor
  81. *
  82. * @param string $elementName (optional)Group name
  83. * @param array $elementLabel (optional)Group label
  84. * @param array $elements (optional)Group elements
  85. * @param mixed $separator (optional)Use a string for one separator,
  86. * use an array to alternate the separators.
  87. * @param bool $appendName (optional)whether to change elements' names to
  88. * the form $groupName[$elementName] or leave
  89. * them as is.
  90. * @since 1.0
  91. * @access public
  92. * @return void
  93. */
  94. function HTML_QuickForm_group($elementName=null, $elementLabel=null, $elements=null, $separator=null, $appendName = true)
  95. {
  96. $this->HTML_QuickForm_element($elementName, $elementLabel);
  97. $this->_type = 'group';
  98. if (isset($elements) && is_array($elements)) {
  99. $this->setElements($elements);
  100. }
  101. if (isset($separator)) {
  102. $this->_separator = $separator;
  103. }
  104. if (isset($appendName)) {
  105. $this->_appendName = $appendName;
  106. }
  107. } //end constructor
  108. // }}}
  109. // {{{ setName()
  110. /**
  111. * Sets the group name
  112. *
  113. * @param string $name Group name
  114. * @since 1.0
  115. * @access public
  116. * @return void
  117. */
  118. function setName($name)
  119. {
  120. $this->_name = $name;
  121. } //end func setName
  122. // }}}
  123. // {{{ getName()
  124. /**
  125. * Returns the group name
  126. *
  127. * @since 1.0
  128. * @access public
  129. * @return string
  130. */
  131. function getName()
  132. {
  133. return $this->_name;
  134. } //end func getName
  135. // }}}
  136. // {{{ setValue()
  137. /**
  138. * Sets values for group's elements
  139. *
  140. * @param mixed Values for group's elements
  141. * @since 1.0
  142. * @access public
  143. * @return void
  144. */
  145. function setValue($value)
  146. {
  147. $this->_createElementsIfNotExist();
  148. foreach (array_keys($this->_elements) as $key) {
  149. if (!$this->_appendName) {
  150. $v = $this->_elements[$key]->_findValue($value);
  151. if (null !== $v) {
  152. $this->_elements[$key]->onQuickFormEvent('setGroupValue', $v, $this);
  153. }
  154. } else {
  155. $elementName = $this->_elements[$key]->getName();
  156. $index = strlen($elementName) ? $elementName : $key;
  157. if (is_array($value)) {
  158. if (isset($value[$index])) {
  159. $this->_elements[$key]->onQuickFormEvent('setGroupValue', $value[$index], $this);
  160. }
  161. } elseif (isset($value)) {
  162. $this->_elements[$key]->onQuickFormEvent('setGroupValue', $value, $this);
  163. }
  164. }
  165. }
  166. } //end func setValue
  167. // }}}
  168. // {{{ getValue()
  169. /**
  170. * Returns the value of the group
  171. *
  172. * @since 1.0
  173. * @access public
  174. * @return mixed
  175. */
  176. function getValue()
  177. {
  178. $value = null;
  179. foreach (array_keys($this->_elements) as $key) {
  180. $element =& $this->_elements[$key];
  181. switch ($element->getType()) {
  182. case 'radio':
  183. $v = $element->getChecked()? $element->getValue(): null;
  184. break;
  185. case 'checkbox':
  186. $v = $element->getChecked()? true: null;
  187. break;
  188. default:
  189. $v = $element->getValue();
  190. }
  191. if (null !== $v) {
  192. $elementName = $element->getName();
  193. if (is_null($elementName)) {
  194. $value = $v;
  195. } else {
  196. if (!is_array($value)) {
  197. $value = is_null($value)? array(): array($value);
  198. }
  199. if ('' === $elementName) {
  200. $value[] = $v;
  201. } else {
  202. $value[$elementName] = $v;
  203. }
  204. }
  205. }
  206. }
  207. return $value;
  208. } // end func getValue
  209. // }}}
  210. // {{{ setElements()
  211. /**
  212. * Sets the grouped elements
  213. *
  214. * @param array $elements Array of elements
  215. * @since 1.1
  216. * @access public
  217. * @return void
  218. */
  219. function setElements($elements)
  220. {
  221. $this->_elements = array_values($elements);
  222. if ($this->_flagFrozen) {
  223. $this->freeze();
  224. }
  225. } // end func setElements
  226. // }}}
  227. // {{{ getElements()
  228. /**
  229. * Gets the grouped elements
  230. *
  231. * @since 2.4
  232. * @access public
  233. * @return array
  234. */
  235. function &getElements()
  236. {
  237. $this->_createElementsIfNotExist();
  238. return $this->_elements;
  239. } // end func getElements
  240. // }}}
  241. // {{{ getGroupType()
  242. /**
  243. * Gets the group type based on its elements
  244. * Will return 'mixed' if elements contained in the group
  245. * are of different types.
  246. *
  247. * @access public
  248. * @return string group elements type
  249. */
  250. function getGroupType()
  251. {
  252. $this->_createElementsIfNotExist();
  253. $prevType = '';
  254. foreach (array_keys($this->_elements) as $key) {
  255. $type = $this->_elements[$key]->getType();
  256. if ($type != $prevType && $prevType != '') {
  257. return 'mixed';
  258. }
  259. $prevType = $type;
  260. }
  261. return $type;
  262. } // end func getGroupType
  263. // }}}
  264. // {{{ toHtml()
  265. /**
  266. * Returns Html for the group
  267. *
  268. * @since 1.0
  269. * @access public
  270. * @return string
  271. */
  272. function toHtml()
  273. {
  274. // Modified by Ivan Tcholakov, 16-MAR-2010. Suppressing a deprecation warning on PHP 5.3
  275. //$renderer =& new HTML_QuickForm_Renderer_Default();
  276. $renderer = new HTML_QuickForm_Renderer_Default();
  277. //
  278. $renderer->setElementTemplate('{element}');
  279. $this->accept($renderer);
  280. return $renderer->toHtml();
  281. } //end func toHtml
  282. // }}}
  283. // {{{ getElementName()
  284. /**
  285. * Returns the element name inside the group such as found in the html form
  286. *
  287. * @param mixed $index Element name or element index in the group
  288. * @since 3.0
  289. * @access public
  290. * @return mixed string with element name, false if not found
  291. */
  292. function getElementName($index)
  293. {
  294. $this->_createElementsIfNotExist();
  295. $elementName = false;
  296. if (is_int($index) && isset($this->_elements[$index])) {
  297. $elementName = $this->_elements[$index]->getName();
  298. if (isset($elementName) && $elementName == '') {
  299. $elementName = $index;
  300. }
  301. if ($this->_appendName) {
  302. if (is_null($elementName)) {
  303. $elementName = $this->getName();
  304. } else {
  305. $elementName = $this->getName().'['.$elementName.']';
  306. }
  307. }
  308. } elseif (is_string($index)) {
  309. foreach (array_keys($this->_elements) as $key) {
  310. $elementName = $this->_elements[$key]->getName();
  311. if ($index == $elementName) {
  312. if ($this->_appendName) {
  313. $elementName = $this->getName().'['.$elementName.']';
  314. }
  315. break;
  316. } elseif ($this->_appendName && $this->getName().'['.$elementName.']' == $index) {
  317. break;
  318. }
  319. }
  320. }
  321. return $elementName;
  322. } //end func getElementName
  323. // }}}
  324. // {{{ getFrozenHtml()
  325. /**
  326. * Returns the value of field without HTML tags
  327. *
  328. * @since 1.3
  329. * @access public
  330. * @return string
  331. */
  332. function getFrozenHtml()
  333. {
  334. $flags = array();
  335. $this->_createElementsIfNotExist();
  336. foreach (array_keys($this->_elements) as $key) {
  337. if (false === ($flags[$key] = $this->_elements[$key]->isFrozen())) {
  338. $this->_elements[$key]->freeze();
  339. }
  340. }
  341. $html = $this->toHtml();
  342. foreach (array_keys($this->_elements) as $key) {
  343. if (!$flags[$key]) {
  344. $this->_elements[$key]->unfreeze();
  345. }
  346. }
  347. return $html;
  348. } //end func getFrozenHtml
  349. // }}}
  350. // {{{ onQuickFormEvent()
  351. /**
  352. * Called by HTML_QuickForm whenever form event is made on this element
  353. *
  354. * @param string $event Name of event
  355. * @param mixed $arg event arguments
  356. * @param object &$caller calling object
  357. * @since 1.0
  358. * @access public
  359. * @return void
  360. */
  361. function onQuickFormEvent($event, $arg, &$caller)
  362. {
  363. switch ($event) {
  364. case 'updateValue':
  365. $this->_createElementsIfNotExist();
  366. foreach (array_keys($this->_elements) as $key) {
  367. if ($this->_appendName) {
  368. $elementName = $this->_elements[$key]->getName();
  369. if (is_null($elementName)) {
  370. $this->_elements[$key]->setName($this->getName());
  371. } elseif ('' === $elementName) {
  372. $this->_elements[$key]->setName($this->getName() . '[' . $key . ']');
  373. } else {
  374. $this->_elements[$key]->setName($this->getName() . '[' . $elementName . ']');
  375. }
  376. }
  377. $this->_elements[$key]->onQuickFormEvent('updateValue', $arg, $caller);
  378. if ($this->_appendName) {
  379. $this->_elements[$key]->setName($elementName);
  380. }
  381. }
  382. break;
  383. default:
  384. parent::onQuickFormEvent($event, $arg, $caller);
  385. }
  386. return true;
  387. } // end func onQuickFormEvent
  388. // }}}
  389. // {{{ accept()
  390. /**
  391. * Accepts a renderer
  392. *
  393. * @param HTML_QuickForm_Renderer renderer object
  394. * @param bool Whether a group is required
  395. * @param string An error message associated with a group
  396. * @access public
  397. * @return void
  398. */
  399. function accept(&$renderer, $required = false, $error = null)
  400. {
  401. $this->_createElementsIfNotExist();
  402. $renderer->startGroup($this, $required, $error);
  403. $name = $this->getName();
  404. foreach (array_keys($this->_elements) as $key) {
  405. $element =& $this->_elements[$key];
  406. if ($this->_appendName) {
  407. $elementName = $element->getName();
  408. if (isset($elementName)) {
  409. $element->setName($name . '['. (strlen($elementName)? $elementName: $key) .']');
  410. } else {
  411. $element->setName($name);
  412. }
  413. }
  414. $required = !$element->isFrozen() && in_array($element->getName(), $this->_required);
  415. $element->accept($renderer, $required);
  416. // restore the element's name
  417. if ($this->_appendName) {
  418. $element->setName($elementName);
  419. }
  420. }
  421. $renderer->finishGroup($this);
  422. } // end func accept
  423. // }}}
  424. // {{{ exportValue()
  425. /**
  426. * As usual, to get the group's value we access its elements and call
  427. * their exportValue() methods
  428. */
  429. function exportValue(&$submitValues, $assoc = false)
  430. {
  431. $value = null;
  432. foreach (array_keys($this->_elements) as $key) {
  433. $elementName = $this->_elements[$key]->getName();
  434. if ($this->_appendName) {
  435. if (is_null($elementName)) {
  436. $this->_elements[$key]->setName($this->getName());
  437. } elseif ('' === $elementName) {
  438. $this->_elements[$key]->setName($this->getName() . '[' . $key . ']');
  439. } else {
  440. $this->_elements[$key]->setName($this->getName() . '[' . $elementName . ']');
  441. }
  442. }
  443. $v = $this->_elements[$key]->exportValue($submitValues, $assoc);
  444. if ($this->_appendName) {
  445. $this->_elements[$key]->setName($elementName);
  446. }
  447. if (null !== $v) {
  448. // Make $value an array, we will use it like one
  449. if (null === $value) {
  450. $value = array();
  451. }
  452. if ($assoc) {
  453. // just like HTML_QuickForm::exportValues()
  454. $value = HTML_QuickForm::arrayMerge($value, $v);
  455. } else {
  456. // just like getValue(), but should work OK every time here
  457. if (is_null($elementName)) {
  458. $value = $v;
  459. } elseif ('' === $elementName) {
  460. $value[] = $v;
  461. } else {
  462. $value[$elementName] = $v;
  463. }
  464. }
  465. }
  466. }
  467. // do not pass the value through _prepareValue, we took care of this already
  468. return $value;
  469. }
  470. // }}}
  471. // {{{ _createElements()
  472. /**
  473. * Creates the group's elements.
  474. *
  475. * This should be overriden by child classes that need to create their
  476. * elements. The method will be called automatically when needed, calling
  477. * it from the constructor is discouraged as the constructor is usually
  478. * called _twice_ on element creation, first time with _no_ parameters.
  479. *
  480. * @access private
  481. * @abstract
  482. */
  483. function _createElements()
  484. {
  485. // abstract
  486. }
  487. // }}}
  488. // {{{ _createElementsIfNotExist()
  489. /**
  490. * A wrapper around _createElements()
  491. *
  492. * This method calls _createElements() if the group's _elements array
  493. * is empty. It also performs some updates, e.g. freezes the created
  494. * elements if the group is already frozen.
  495. *
  496. * @access private
  497. */
  498. function _createElementsIfNotExist()
  499. {
  500. if (empty($this->_elements)) {
  501. $this->_createElements();
  502. if ($this->_flagFrozen) {
  503. $this->freeze();
  504. }
  505. }
  506. }
  507. // }}}
  508. // {{{ freeze()
  509. function freeze()
  510. {
  511. parent::freeze();
  512. foreach (array_keys($this->_elements) as $key) {
  513. $this->_elements[$key]->freeze();
  514. }
  515. }
  516. // }}}
  517. // {{{ unfreeze()
  518. function unfreeze()
  519. {
  520. parent::unfreeze();
  521. foreach (array_keys($this->_elements) as $key) {
  522. $this->_elements[$key]->unfreeze();
  523. }
  524. }
  525. // }}}
  526. // {{{ setPersistantFreeze()
  527. function setPersistantFreeze($persistant = false)
  528. {
  529. parent::setPersistantFreeze($persistant);
  530. foreach (array_keys($this->_elements) as $key) {
  531. $this->_elements[$key]->setPersistantFreeze($persistant);
  532. }
  533. }
  534. // }}}
  535. } //end class HTML_QuickForm_group
  536. ?>