group.php 16 KB

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