Source for file FormContainer.php

Documentation is available at FormContainer.php

  1. 1: <?php
  2. 2:  
  3. 3: /**
  4. 4:  * Nette Framework
  5. 5:  *
  6. 6:  * Copyright (c) 2004, 2009 David Grudl (http://davidgrudl.com)
  7. 7:  *
  8. 8:  * This source file is subject to the "Nette license" that is bundled
  9. 9:  * with this package in the file license.txt.
  10. 10:  *
  11. 11:  * For more information please see http://nettephp.com
  12. 12:  *
  13. 13:  * @copyright  Copyright (c) 2004, 2009 David Grudl
  14. 14:  * @license    http://nettephp.com/license  Nette license
  15. 15:  * @link       http://nettephp.com
  16. 16:  * @category   Nette
  17. 17:  * @package    Nette\Forms
  18. 18:  */
  19. 19:  
  20. 20:  
  21. 21:  
  22. 22: require_once dirname(__FILE__'/../ComponentContainer.php';
  23. 23:  
  24. 24: require_once dirname(__FILE__'/../Forms/INamingContainer.php';
  25. 25:  
  26. 26:  
  27. 27:  
  28. 28: /**
  29. 29:  * Container for form controls.
  30. 30:  *
  31. 31:  * @author     David Grudl
  32. 32:  * @copyright  Copyright (c) 2004, 2009 David Grudl
  33. 33:  * @package    Nette\Forms
  34. 34:  *
  35. 35:  * @property-read ArrayIterator $controls 
  36. 36:  * @property-read Form $form 
  37. 37:  * @property-read bool $valid 
  38. 38:  * @property   array $values 
  39. 39:  */
  40. 40: class FormContainer extends ComponentContainer implements ArrayAccessINamingContainer
  41. 41: {
  42. 42:     /** @var FormGroup */
  43. 43:     protected $currentGroup;
  44. 44:  
  45. 45:     /** @var bool */
  46. 46:     protected $valid;
  47. 47:  
  48. 48:  
  49. 49:  
  50. 50:     /********************* data exchange ****************d*g**/
  51. 51:  
  52. 52:  
  53. 53:  
  54. 54:     /**
  55. 55:      * Fill-in with default values.
  56. 56:      * @param  array|Traversable values used to fill the form
  57. 57:      * @param  bool     erase other default values?
  58. 58:      * @return FormContainer  provides a fluent interface
  59. 59:      */
  60. 60:     public function setDefaults($values$erase FALSE)
  61. 61:     {
  62. 62:         $form $this->getForm(FALSE);
  63. 63:         if (!$form || !$form->isAnchored(|| !$form->isSubmitted()) {
  64. 64:             $this->setValues($values$erase);
  65. 65:         }
  66. 66:         return $this;
  67. 67:     }
  68. 68:  
  69. 69:  
  70. 70:  
  71. 71:     /**
  72. 72:      * Fill-in with values.
  73. 73:      * @param  array|Traversable values used to fill the form
  74. 74:      * @param  bool     erase other controls?
  75. 75:      * @return FormContainer  provides a fluent interface
  76. 76:      */
  77. 77:     public function setValues($values$erase FALSE)
  78. 78:     {
  79. 79:         if ($values instanceof Traversable{
  80. 80:             $values iterator_to_array($values);
  81. 81:  
  82. 82:         elseif (!is_array($values)) {
  83. 83:             throw new InvalidArgumentException("Values must be an array, " gettype($values." given.");
  84. 84:         }
  85. 85:  
  86. 86:         $cursor $values;
  87. 87:         $iterator $this->getComponents(TRUE);
  88. 88:         foreach ($iterator as $name => $control{
  89. 89:             $sub $iterator->getSubIterator();
  90. 90:             if (!isset($sub->cursor)) {
  91. 91:                 $sub->cursor $cursor;
  92. 92:             }
  93. 93:             if ($control instanceof IFormControl{
  94. 94:                 if ((is_array($sub->cursor|| $sub->cursor instanceof ArrayAccess&& array_key_exists($name$sub->cursor)) {
  95. 95:                     $control->setValue($sub->cursor[$name]);
  96. 96:  
  97. 97:                 elseif ($erase{
  98. 98:                     $control->setValue(NULL);
  99. 99:                 }
  100. 100:             }
  101. 101:             if ($control instanceof INamingContainer{
  102. 102:                 if ((is_array($sub->cursor|| $sub->cursor instanceof ArrayAccess&& isset($sub->cursor[$name])) {
  103. 103:                     $cursor $sub->cursor[$name];
  104. 104:                 else {
  105. 105:                     unset($cursor);
  106. 106:                     $cursor NULL;
  107. 107:                 }
  108. 108:             }
  109. 109:         }
  110. 110:         return $this;
  111. 111:     }
  112. 112:  
  113. 113:  
  114. 114:  
  115. 115:     /**
  116. 116:      * Returns the values submitted by the form.
  117. 117:      * @return array 
  118. 118:      */
  119. 119:     public function getValues()
  120. 120:     {
  121. 121:         $values array();
  122. 122:         $cursor $values;
  123. 123:         $iterator $this->getComponents(TRUE);
  124. 124:         foreach ($iterator as $name => $control{
  125. 125:             $sub $iterator->getSubIterator();
  126. 126:             if (!isset($sub->cursor)) {
  127. 127:                 $sub->cursor $cursor;
  128. 128:             }
  129. 129:             if ($control instanceof IFormControl && !$control->isDisabled(&& !($control instanceof ISubmitterControl)) {
  130. 130:                 $sub->cursor[$name$control->getValue();
  131. 131:             }
  132. 132:             if ($control instanceof INamingContainer{
  133. 133:                 $cursor $sub->cursor[$name];
  134. 134:                 $cursor array();
  135. 135:             }
  136. 136:         }
  137. 137:         return $values;
  138. 138:     }
  139. 139:  
  140. 140:  
  141. 141:  
  142. 142:     /********************* validation ****************d*g**/
  143. 143:  
  144. 144:  
  145. 145:  
  146. 146:     /**
  147. 147:      * Is form valid?
  148. 148:      * @return bool 
  149. 149:      */
  150. 150:     public function isValid()
  151. 151:     {
  152. 152:         if ($this->valid === NULL{
  153. 153:             $this->validate();
  154. 154:         }
  155. 155:         return $this->valid;
  156. 156:     }
  157. 157:  
  158. 158:  
  159. 159:  
  160. 160:     /**
  161. 161:      * Performs the server side validation.
  162. 162:      * @return void 
  163. 163:      */
  164. 164:     public function validate()
  165. 165:     {
  166. 166:         $this->valid = TRUE;
  167. 167:         foreach ($this->getControls(as $control{
  168. 168:             if (!$control->getRules()->validate()) {
  169. 169:                 $this->valid = FALSE;
  170. 170:             }
  171. 171:         }
  172. 172:     }
  173. 173:  
  174. 174:  
  175. 175:  
  176. 176:     /********************* form building ****************d*g**/
  177. 177:  
  178. 178:  
  179. 179:  
  180. 180:     /**
  181. 181:      * @param  FormGroup 
  182. 182:      * @return FormContainer  provides a fluent interface
  183. 183:      */
  184. 184:     public function setCurrentGroup(FormGroup $group NULL)
  185. 185:     {
  186. 186:         $this->currentGroup = $group;
  187. 187:         return $this;
  188. 188:     }
  189. 189:  
  190. 190:  
  191. 191:  
  192. 192:     /**
  193. 193:      * Adds the specified component to the IComponentContainer.
  194. 194:      * @param  IComponent 
  195. 195:      * @param  string 
  196. 196:      * @param  string 
  197. 197:      * @return void 
  198. 198:      * @throws InvalidStateException
  199. 199:      */
  200. 200:     public function addComponent(IComponent $component$name$insertBefore NULL)
  201. 201:     {
  202. 202:         parent::addComponent($component$name$insertBefore);
  203. 203:         if ($this->currentGroup !== NULL && $component instanceof IFormControl{
  204. 204:             $this->currentGroup->add($component);
  205. 205:         }
  206. 206:     }
  207. 207:  
  208. 208:  
  209. 209:  
  210. 210:     /**
  211. 211:      * Iterates over all form controls.
  212. 212:      * @return ArrayIterator 
  213. 213:      */
  214. 214:     public function getControls()
  215. 215:     {
  216. 216:         return $this->getComponents(TRUE'Nette\Forms\IFormControl');
  217. 217:     }
  218. 218:  
  219. 219:  
  220. 220:  
  221. 221:     /**
  222. 222:      * Returns form.
  223. 223:      * @param  bool   throw exception if form doesn't exist?
  224. 224:      * @return Form 
  225. 225:      */
  226. 226:     public function getForm($need TRUE)
  227. 227:     {
  228. 228:         return $this->lookup('Nette\Forms\Form'$need);
  229. 229:     }
  230. 230:  
  231. 231:  
  232. 232:  
  233. 233:     /********************* control factories ****************d*g**/
  234. 234:  
  235. 235:  
  236. 236:  
  237. 237:     /**
  238. 238:      * Adds single-line text input control to the form.
  239. 239:      * @param  string  control name
  240. 240:      * @param  string  label
  241. 241:      * @param  int  width of the control
  242. 242:      * @param  int  maximum number of characters the user may enter
  243. 243:      * @return TextInput 
  244. 244:      */
  245. 245:     public function addText($name$label NULL$cols NULL$maxLength NULL)
  246. 246:     {
  247. 247:         return $this[$namenew TextInput($label$cols$maxLength);
  248. 248:     }
  249. 249:  
  250. 250:  
  251. 251:  
  252. 252:     /**
  253. 253:      * Adds single-line text input control used for sensitive input such as passwords.
  254. 254:      * @param  string  control name
  255. 255:      * @param  string  label
  256. 256:      * @param  int  width of the control
  257. 257:      * @param  int  maximum number of characters the user may enter
  258. 258:      * @return TextInput 
  259. 259:      */
  260. 260:     public function addPassword($name$label NULL$cols NULL$maxLength NULL)
  261. 261:     {
  262. 262:         $control new TextInput($label$cols$maxLength);
  263. 263:         $control->setPasswordMode(TRUE);
  264. 264:         $this->addComponent($control$name);
  265. 265:         return $control;
  266. 266:     }
  267. 267:  
  268. 268:  
  269. 269:  
  270. 270:     /**
  271. 271:      * Adds multi-line text input control to the form.
  272. 272:      * @param  string  control name
  273. 273:      * @param  string  label
  274. 274:      * @param  int  width of the control
  275. 275:      * @param  int  height of the control in text lines
  276. 276:      * @return TextArea 
  277. 277:      */
  278. 278:     public function addTextArea($name$label NULL$cols 40$rows 10)
  279. 279:     {
  280. 280:         return $this[$namenew TextArea($label$cols$rows);
  281. 281:     }
  282. 282:  
  283. 283:  
  284. 284:  
  285. 285:     /**
  286. 286:      * Adds control that allows the user to upload files.
  287. 287:      * @param  string  control name
  288. 288:      * @param  string  label
  289. 289:      * @return FileUpload 
  290. 290:      */
  291. 291:     public function addFile($name$label NULL)
  292. 292:     {
  293. 293:         return $this[$namenew FileUpload($label);
  294. 294:     }
  295. 295:  
  296. 296:  
  297. 297:  
  298. 298:     /**
  299. 299:      * Adds hidden form control used to store a non-displayed value.
  300. 300:      * @param  string  control name
  301. 301:      * @return HiddenField 
  302. 302:      */
  303. 303:     public function addHidden($name)
  304. 304:     {
  305. 305:         return $this[$namenew HiddenField;
  306. 306:     }
  307. 307:  
  308. 308:  
  309. 309:  
  310. 310:     /**
  311. 311:      * Adds check box control to the form.
  312. 312:      * @param  string  control name
  313. 313:      * @param  string  caption
  314. 314:      * @return Checkbox 
  315. 315:      */
  316. 316:     public function addCheckbox($name$caption)
  317. 317:     {
  318. 318:         return $this[$namenew Checkbox($caption);
  319. 319:     }
  320. 320:  
  321. 321:  
  322. 322:  
  323. 323:     /**
  324. 324:      * Adds set of radio button controls to the form.
  325. 325:      * @param  string  control name
  326. 326:      * @param  string  label
  327. 327:      * @param  array   options from which to choose
  328. 328:      * @return RadioList 
  329. 329:      */
  330. 330:     public function addRadioList($name$label NULLarray $items NULL)
  331. 331:     {
  332. 332:         return $this[$namenew RadioList($label$items);
  333. 333:     }
  334. 334:  
  335. 335:  
  336. 336:  
  337. 337:     /**
  338. 338:      * Adds select box control that allows single item selection.
  339. 339:      * @param  string  control name
  340. 340:      * @param  string  label
  341. 341:      * @param  array   items from which to choose
  342. 342:      * @param  int     number of rows that should be visible
  343. 343:      * @return SelectBox 
  344. 344:      */
  345. 345:     public function addSelect($name$label NULLarray $items NULL$size NULL)
  346. 346:     {
  347. 347:         return $this[$namenew SelectBox($label$items$size);
  348. 348:     
  349. 349:  
  350. 350:  
  351. 351:  
  352. 352:     /**
  353. 353:      * Adds select box control that allows multiple item selection.
  354. 354:      * @param  string  control name
  355. 355:      * @param  string  label
  356. 356:      * @param  array   options from which to choose
  357. 357:      * @param  int     number of rows that should be visible
  358. 358:      * @return MultiSelectBox 
  359. 359:      */
  360. 360:     public function addMultiSelect($name$label NULLarray $items NULL$size NULL)
  361. 361:     {
  362. 362:         return $this[$namenew MultiSelectBox($label$items$size);
  363. 363:     
  364. 364:  
  365. 365:  
  366. 366:  
  367. 367:     /**
  368. 368:      * Adds button used to submit form.
  369. 369:      * @param  string  control name
  370. 370:      * @param  string  caption
  371. 371:      * @return SubmitButton 
  372. 372:      */
  373. 373:     public function addSubmit($name$caption)
  374. 374:     {
  375. 375:         return $this[$namenew SubmitButton($caption);
  376. 376:     }
  377. 377:  
  378. 378:  
  379. 379:  
  380. 380:     /**
  381. 381:      * Adds push buttons with no default behavior.
  382. 382:      * @param  string  control name
  383. 383:      * @param  string  caption
  384. 384:      * @return Button 
  385. 385:      */
  386. 386:     public function addButton($name$caption)
  387. 387:     {
  388. 388:         return $this[$namenew Button($caption);
  389. 389:     }
  390. 390:  
  391. 391:  
  392. 392:  
  393. 393:     /**
  394. 394:      * Adds graphical button used to submit form.
  395. 395:      * @param  string  control name
  396. 396:      * @param  string  URI of the image
  397. 397:      * @param  string  alternate text for the image
  398. 398:      * @return ImageButton 
  399. 399:      */
  400. 400:     public function addImage($name$src NULL$alt NULL)
  401. 401:     {
  402. 402:         return $this[$namenew ImageButton($src$alt);
  403. 403:     }
  404. 404:  
  405. 405:  
  406. 406:  
  407. 407:     /**
  408. 408:      * Adds naming container to the form.
  409. 409:      * @param  string  name
  410. 410:      * @return FormContainer 
  411. 411:      */
  412. 412:     public function addContainer($name)
  413. 413:     {
  414. 414:         $control new FormContainer;
  415. 415:         $control->currentGroup $this->currentGroup;
  416. 416:         return $this[$name$control;
  417. 417:     }
  418. 418:  
  419. 419:  
  420. 420:  
  421. 421:     /**
  422. 422:      * Adds control that repeats a specified prototype for each item in the list.
  423. 423:      * @param  string  control name
  424. 424:      * @return RepeaterControl 
  425. 425:      */
  426. 426:     public function addRepeater($name)
  427. 427:     {
  428. 428:         return $this[$namenew RepeaterControl;
  429. 429:     }
  430. 430:  
  431. 431:  
  432. 432:  
  433. 433:     /********************* interface \ArrayAccess ****************d*g**/
  434. 434:  
  435. 435:  
  436. 436:  
  437. 437:     /**
  438. 438:      * Adds the component to the container.
  439. 439:      * @param  string  component name
  440. 440:      * @param  IComponent 
  441. 441:      * @return void. 
  442. 442:      */
  443. 443:     final public function offsetSet($name$component)
  444. 444:     {
  445. 445:         $this->addComponent($component$name);
  446. 446:     }
  447. 447:  
  448. 448:  
  449. 449:  
  450. 450:     /**
  451. 451:      * Returns component specified by name. Throws exception if component doesn't exist.
  452. 452:      * @param  string  component name
  453. 453:      * @return IComponent 
  454. 454:      * @throws InvalidArgumentException
  455. 455:      */
  456. 456:     final public function offsetGet($name)
  457. 457:     {
  458. 458:         return $this->getComponent($nameTRUE);
  459. 459:     }
  460. 460:  
  461. 461:  
  462. 462:  
  463. 463:     /**
  464. 464:      * Does component specified by name exists?
  465. 465:      * @param  string  component name
  466. 466:      * @return bool 
  467. 467:      */
  468. 468:     final public function offsetExists($name)
  469. 469:     {
  470. 470:         return $this->getComponent($nameFALSE!== NULL;
  471. 471:     }
  472. 472:  
  473. 473:  
  474. 474:  
  475. 475:     /**
  476. 476:      * Removes component from the container. Throws exception if component doesn't exist.
  477. 477:      * @param  string  component name
  478. 478:      * @return void 
  479. 479:      */
  480. 480:     final public function offsetUnset($name)
  481. 481:     {
  482. 482:         $component $this->getComponent($nameFALSE);
  483. 483:         if ($component !== NULL{
  484. 484:             $this->removeComponent($component);
  485. 485:         }
  486. 486:     }
  487. 487:  
  488. 488:  
  489. 489:  
  490. 490:     /**
  491. 491:      * Prevents cloning.
  492. 492:      */
  493. 493:     final public function __clone()
  494. 494:     {
  495. 495:         throw new NotImplementedException('Form cloning is not supported yet.');
  496. 496:     }
  497. 497: