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