group.php 16 KB

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