Source for file FormControl.php

Documentation is available at FormControl.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:  * Base class that implements the basic functionality common to form controls.
  17. 17:  *
  18. 18:  * @copyright  Copyright (c) 2004, 2010 David Grudl
  19. 19:  * @package    Nette\Forms
  20. 20:  *
  21. 21:  * @property-read Form $form 
  22. 22:  * @property-read mixed $control 
  23. 23:  * @property-read mixed $label 
  24. 24:  * @property-read string $htmlName 
  25. 25:  * @property   string $htmlId 
  26. 26:  * @property-read array $options 
  27. 27:  * @property   ITranslator $translator 
  28. 28:  * @property   mixed $value 
  29. 29:  * @property-read Html $controlPrototype 
  30. 30:  * @property-read Html $labelPrototype 
  31. 31:  * @property-read Rules $rules 
  32. 32:  * @property-read array $errors 
  33. 33:  * @property   bool $disabled 
  34. 34:  * @property   bool $rendered 
  35. 35:  * @property   bool $required 
  36. 36: */
  37. 37: abstract class FormControl extends Component implements IFormControl
  38. 38: {
  39. 39:     /** @var string */
  40. 40:     public static $idMask 'frm%s-%s';
  41. 41:  
  42. 42:     /** @var string textual caption or label */
  43. 43:     public $caption;
  44. 44:  
  45. 45:     /** @var mixed unfiltered control value */
  46. 46:     protected $value;
  47. 47:  
  48. 48:     /** @var Html  control element template */
  49. 49:     protected $control;
  50. 50:  
  51. 51:     /** @var Html  label element template */
  52. 52:     protected $label;
  53. 53:  
  54. 54:     /** @var array */
  55. 55:     private $errors array();
  56. 56:  
  57. 57:     /** @var bool */
  58. 58:     private $disabled FALSE;
  59. 59:  
  60. 60:     /** @var string */
  61. 61:     private $htmlId;
  62. 62:  
  63. 63:     /** @var string */
  64. 64:     private $htmlName;
  65. 65:  
  66. 66:     /** @var Rules */
  67. 67:     private $rules;
  68. 68:  
  69. 69:     /** @var ITranslator */
  70. 70:     private $translator TRUE// means autodetect
  71. 71:  
  72. 72:     /** @var array user options */
  73. 73:     private $options array();
  74. 74:  
  75. 75:  
  76. 76:  
  77. 77:     /**
  78. 78:      * @param  string  caption
  79. 79:      */
  80. 80:     public function __construct($caption NULL)
  81. 81:     {
  82. 82:         $this->monitor('Nette\Forms\Form');
  83. 83:         parent::__construct();
  84. 84:         $this->control = Html::el('input');
  85. 85:         $this->label = Html::el('label');
  86. 86:         $this->caption = $caption;
  87. 87:         $this->rules new Rules($this);
  88. 88:     }
  89. 89:  
  90. 90:  
  91. 91:  
  92. 92:     /**
  93. 93:      * This method will be called when the component becomes attached to Form.
  94. 94:      * @param  IComponent 
  95. 95:      * @return void 
  96. 96:      */
  97. 97:     protected function attached($form)
  98. 98:     {
  99. 99:         if (!$this->disabled && $form instanceof Form && $form->isAnchored(&& $form->isSubmitted()) {
  100. 100:             $this->htmlName NULL;
  101. 101:             $this->loadHttpData();
  102. 102:         }
  103. 103:     }
  104. 104:  
  105. 105:  
  106. 106:  
  107. 107:     /**
  108. 108:      * Returns form.
  109. 109:      * @param  bool   throw exception if form doesn't exist?
  110. 110:      * @return Form 
  111. 111:      */
  112. 112:     public function getForm($need TRUE)
  113. 113:     {
  114. 114:         return $this->lookup('Nette\Forms\Form'$need);
  115. 115:     }
  116. 116:  
  117. 117:  
  118. 118:  
  119. 119:     /**
  120. 120:      * Returns name of control within a Form & INamingContainer scope.
  121. 121:      * @return string 
  122. 122:      */
  123. 123:     public function getHtmlName()
  124. 124:     {
  125. 125:         if ($this->htmlName === NULL{
  126. 126:             $s '';
  127. 127:             $name $this->getName();
  128. 128:             $obj $this->lookup('Nette\Forms\INamingContainer'TRUE);
  129. 129:             while (!($obj instanceof Form)) {
  130. 130:                 $s "[$name]$s";
  131. 131:                 $name $obj->getName();
  132. 132:                 $obj $obj->lookup('Nette\Forms\INamingContainer'TRUE);
  133. 133:             }
  134. 134:             $name .= $s;
  135. 135:             if ($name === 'submit'{
  136. 136:                 throw new InvalidArgumentException("Form control name 'submit' is not allowed due to JavaScript limitations.");
  137. 137:             }
  138. 138:             $this->htmlName $name;
  139. 139:         }
  140. 140:         return $this->htmlName;
  141. 141:     }
  142. 142:  
  143. 143:  
  144. 144:  
  145. 145:     /**
  146. 146:      * Changes control's HTML id.
  147. 147:      * @param  string new ID, or FALSE or NULL
  148. 148:      * @return FormControl  provides a fluent interface
  149. 149:      */
  150. 150:     public function setHtmlId($id)
  151. 151:     {
  152. 152:         $this->htmlId $id;
  153. 153:         return $this;
  154. 154:     }
  155. 155:  
  156. 156:  
  157. 157:  
  158. 158:     /**
  159. 159:      * Returns control's HTML id.
  160. 160:      * @return string 
  161. 161:      */
  162. 162:     public function getHtmlId()
  163. 163:     {
  164. 164:         if ($this->htmlId === FALSE{
  165. 165:             return NULL;
  166. 166:  
  167. 167:         elseif ($this->htmlId === NULL{
  168. 168:             $this->htmlId sprintf(self::$idMask$this->getForm()->getName()$this->getHtmlName());
  169. 169:             $this->htmlId str_replace(array('[]''['']')array('''-''')$this->htmlId);
  170. 170:         }
  171. 171:         return $this->htmlId;
  172. 172:     }
  173. 173:  
  174. 174:  
  175. 175:  
  176. 176:     /**
  177. 177:      * Sets user-specific option.
  178. 178:      *
  179. 179:      * Common options:
  180. 180:      * - 'rendered' - indicate if method getControl() have been called
  181. 181:      * - 'required' - indicate if ':required' rule has been applied
  182. 182:      * - 'description' - textual or Html object description (recognized by ConventionalRenderer)
  183. 183:      *
  184. 184:      * @param  string key
  185. 185:      * @param  mixed  value
  186. 186:      * @return FormControl  provides a fluent interface
  187. 187:      */
  188. 188:     public function setOption($key$value)
  189. 189:     {
  190. 190:         if ($value === NULL{
  191. 191:             unset($this->options[$key]);
  192. 192:  
  193. 193:         else {
  194. 194:             $this->options[$key$value;
  195. 195:         }
  196. 196:         return $this;
  197. 197:     }
  198. 198:  
  199. 199:  
  200. 200:  
  201. 201:     /**
  202. 202:      * Returns user-specific option.
  203. 203:      * @param  string key
  204. 204:      * @param  mixed  default value
  205. 205:      * @return mixed 
  206. 206:      */
  207. 207:     final public function getOption($key$default NULL)
  208. 208:     {
  209. 209:         return isset($this->options[$key]$this->options[$key$default;
  210. 210:     }
  211. 211:  
  212. 212:  
  213. 213:  
  214. 214:     /**
  215. 215:      * Returns user-specific options.
  216. 216:      * @return array 
  217. 217:      */
  218. 218:     final public function getOptions()
  219. 219:     {
  220. 220:         return $this->options;
  221. 221:     }
  222. 222:  
  223. 223:  
  224. 224:  
  225. 225:     /********************* translator ****************d*g**/
  226. 226:  
  227. 227:  
  228. 228:  
  229. 229:     /**
  230. 230:      * Sets translate adapter.
  231. 231:      * @param  ITranslator 
  232. 232:      * @return FormControl  provides a fluent interface
  233. 233:      */
  234. 234:     public function setTranslator(ITranslator $translator NULL)
  235. 235:     {
  236. 236:         $this->translator $translator;
  237. 237:         return $this;
  238. 238:     }
  239. 239:  
  240. 240:  
  241. 241:  
  242. 242:     /**
  243. 243:      * Returns translate adapter.
  244. 244:      * @return ITranslator|NULL
  245. 245:      */
  246. 246:     final public function getTranslator()
  247. 247:     {
  248. 248:         if ($this->translator === TRUE{
  249. 249:             return $this->getForm(FALSE$this->getForm()->getTranslator(NULL;
  250. 250:         }
  251. 251:         return $this->translator;
  252. 252:     }
  253. 253:  
  254. 254:  
  255. 255:  
  256. 256:     /**
  257. 257:      * Returns translated string.
  258. 258:      * @param  string 
  259. 259:      * @param  int      plural count
  260. 260:      * @return string 
  261. 261:      */
  262. 262:     public function translate($s$count NULL)
  263. 263:     {
  264. 264:         $translator $this->getTranslator();
  265. 265:         return $translator === NULL $s $translator->translate($s$count);
  266. 266:     }
  267. 267:  
  268. 268:  
  269. 269:  
  270. 270:     /********************* interface IFormControl ****************d*g**/
  271. 271:  
  272. 272:  
  273. 273:  
  274. 274:     /**
  275. 275:      * Sets control's value.
  276. 276:      * @param  mixed 
  277. 277:      * @return FormControl  provides a fluent interface
  278. 278:      */
  279. 279:     public function setValue($value)
  280. 280:     {
  281. 281:         $this->value = $value;
  282. 282:         return $this;
  283. 283:     }
  284. 284:  
  285. 285:  
  286. 286:  
  287. 287:     /**
  288. 288:      * Returns control's value.
  289. 289:      * @return mixed 
  290. 290:      */
  291. 291:     public function getValue()
  292. 292:     {
  293. 293:         return $this->value;
  294. 294:     }
  295. 295:  
  296. 296:  
  297. 297:  
  298. 298:     /**
  299. 299:      * Sets control's default value.
  300. 300:      * @param  mixed 
  301. 301:      * @return FormControl  provides a fluent interface
  302. 302:      */
  303. 303:     public function setDefaultValue($value)
  304. 304:     {
  305. 305:         $form $this->getForm(FALSE);
  306. 306:         if (!$form || !$form->isAnchored(|| !$form->isSubmitted()) {
  307. 307:             $this->setValue($value);
  308. 308:         }
  309. 309:         return $this;
  310. 310:     }
  311. 311:  
  312. 312:  
  313. 313:  
  314. 314:     /**
  315. 315:      * Loads HTTP data.
  316. 316:      * @return void 
  317. 317:      */
  318. 318:     public function loadHttpData()
  319. 319:     {
  320. 320:         $path explode('['strtr(str_replace(array('[]'']')''$this->getHtmlName())'.''_'));
  321. 321:         $this->setValue(ArrayTools::get($this->getForm()->getHttpData()$path));
  322. 322:     }
  323. 323:  
  324. 324:  
  325. 325:  
  326. 326:     /**
  327. 327:      * Disables or enables control.
  328. 328:      * @param  bool 
  329. 329:      * @return FormControl  provides a fluent interface
  330. 330:      */
  331. 331:     public function setDisabled($value TRUE)
  332. 332:     {
  333. 333:         $this->disabled = (bool) $value;
  334. 334:         return $this;
  335. 335:     }
  336. 336:  
  337. 337:  
  338. 338:  
  339. 339:     /**
  340. 340:      * Is control disabled?
  341. 341:      * @return bool 
  342. 342:      */
  343. 343:     public function isDisabled()
  344. 344:     {
  345. 345:         return $this->disabled;
  346. 346:     }
  347. 347:  
  348. 348:  
  349. 349:  
  350. 350:     /********************* rendering ****************d*g**/
  351. 351:  
  352. 352:  
  353. 353:  
  354. 354:     /**
  355. 355:      * Generates control's HTML element.
  356. 356:      * @return Html 
  357. 357:      */
  358. 358:     public function getControl()
  359. 359:     {
  360. 360:         $this->setOption('rendered'TRUE);
  361. 361:         $control clone $this->control;
  362. 362:         $control->name $this->getHtmlName();
  363. 363:         $control->disabled $this->disabled;
  364. 364:         $control->id $this->getHtmlId();
  365. 365:         return $control;
  366. 366:     }
  367. 367:  
  368. 368:  
  369. 369:  
  370. 370:     /**
  371. 371:      * Generates label's HTML element.
  372. 372:      * @param  string 
  373. 373:      * @return Html 
  374. 374:      */
  375. 375:     public function getLabel($caption NULL)
  376. 376:     {
  377. 377:         $label clone $this->label;
  378. 378:         $label->for $this->getHtmlId();
  379. 379:         if ($caption !== NULL{
  380. 380:             $label->setText($this->translate($caption));
  381. 381:  
  382. 382:         elseif ($this->caption instanceof Html{
  383. 383:             $label->add($this->caption);
  384. 384:  
  385. 385:         else {
  386. 386:             $label->setText($this->translate($this->caption));
  387. 387:         }
  388. 388:         return $label;
  389. 389:     }
  390. 390:  
  391. 391:  
  392. 392:  
  393. 393:     /**
  394. 394:      * Returns control's HTML element template.
  395. 395:      * @return Html 
  396. 396:      */
  397. 397:     final public function getControlPrototype()
  398. 398:     {
  399. 399:         return $this->control;
  400. 400:     }
  401. 401:  
  402. 402:  
  403. 403:  
  404. 404:     /**
  405. 405:      * Returns label's HTML element template.
  406. 406:      * @return Html 
  407. 407:      */
  408. 408:     final public function getLabelPrototype()
  409. 409:     {
  410. 410:         return $this->label;
  411. 411:     }
  412. 412:  
  413. 413:  
  414. 414:  
  415. 415:     /**
  416. 416:      * Sets 'rendered' indicator.
  417. 417:      * @param  bool 
  418. 418:      * @return FormControl  provides a fluent interface
  419. 419:      * @deprecated
  420. 420:      */
  421. 421:     public function setRendered($value TRUE)
  422. 422:     {
  423. 423:         $this->setOption('rendered'$value);
  424. 424:         return $this;
  425. 425:     }
  426. 426:  
  427. 427:  
  428. 428:  
  429. 429:     /**
  430. 430:      * Does method getControl() have been called?
  431. 431:      * @return bool 
  432. 432:      * @deprecated
  433. 433:      */
  434. 434:     public function isRendered()
  435. 435:     {
  436. 436:         return !empty($this->options['rendered']);
  437. 437:     }
  438. 438:  
  439. 439:  
  440. 440:  
  441. 441:     /********************* rules ****************d*g**/
  442. 442:  
  443. 443:  
  444. 444:  
  445. 445:     /**
  446. 446:      * Adds a validation rule.
  447. 447:      * @param  mixed      rule type
  448. 448:      * @param  string     message to display for invalid data
  449. 449:      * @param  mixed      optional rule arguments
  450. 450:      * @return FormControl  provides a fluent interface
  451. 451:      */
  452. 452:     public function addRule($operation$message NULL$arg NULL)
  453. 453:     {
  454. 454:         $this->rules->addRule($operation$message$arg);
  455. 455:         return $this;
  456. 456:     }
  457. 457:  
  458. 458:  
  459. 459:  
  460. 460:     /**
  461. 461:      * Adds a validation condition a returns new branch.
  462. 462:      * @param  mixed     condition type
  463. 463:      * @param  mixed      optional condition arguments
  464. 464:      * @return Rules      new branch
  465. 465:      */
  466. 466:     public function addCondition($operation$value NULL)
  467. 467:     {
  468. 468:         return $this->rules->addCondition($operation$value);
  469. 469:     }
  470. 470:  
  471. 471:  
  472. 472:  
  473. 473:     /**
  474. 474:      * Adds a validation condition based on another control a returns new branch.
  475. 475:      * @param  IFormControl form control
  476. 476:      * @param  mixed      condition type
  477. 477:      * @param  mixed      optional condition arguments
  478. 478:      * @return Rules      new branch
  479. 479:      */
  480. 480:     public function addConditionOn(IFormControl $control$operation$value NULL)
  481. 481:     {
  482. 482:         return $this->rules->addConditionOn($control$operation$value);
  483. 483:     }
  484. 484:  
  485. 485:  
  486. 486:  
  487. 487:     /**
  488. 488:      * @return Rules 
  489. 489:      */
  490. 490:     final public function getRules()
  491. 491:     {
  492. 492:         return $this->rules;
  493. 493:     }
  494. 494:  
  495. 495:  
  496. 496:  
  497. 497:     /**
  498. 498:      * Makes control mandatory.
  499. 499:      * @param  string  error message
  500. 500:      * @return FormControl  provides a fluent interface
  501. 501:      * @deprecated
  502. 502:      */
  503. 503:     final public function setRequired($message NULL)
  504. 504:     {
  505. 505:         $this->rules->addRule(':Filled'$message);
  506. 506:         return $this;
  507. 507:     }
  508. 508:  
  509. 509:  
  510. 510:  
  511. 511:     /**
  512. 512:      * Is control mandatory?
  513. 513:      * @return bool 
  514. 514:      * @deprecated
  515. 515:      */
  516. 516:     final public function isRequired()
  517. 517:     {
  518. 518:         return !empty($this->options['required']);
  519. 519:     }
  520. 520:  
  521. 521:  
  522. 522:  
  523. 523:     /**
  524. 524:      * New rule or condition notification callback.
  525. 525:      * @param  Rule 
  526. 526:      * @return void 
  527. 527:      */
  528. 528:     public function notifyRule(Rule $rule)
  529. 529:     {
  530. 530:         if (is_string($rule->operation&& strcasecmp($rule->operation':filled'=== 0{
  531. 531:             $this->setOption('required'TRUE);
  532. 532:         }
  533. 533:     }
  534. 534:  
  535. 535:  
  536. 536:  
  537. 537:     /********************* validation ****************d*g**/
  538. 538:  
  539. 539:  
  540. 540:  
  541. 541:     /**
  542. 542:      * Equal validator: are control's value and second parameter equal?
  543. 543:      * @param  IFormControl 
  544. 544:      * @param  mixed 
  545. 545:      * @return bool 
  546. 546:      */
  547. 547:     public static function validateEqual(IFormControl $control$arg)
  548. 548:     {
  549. 549:         $value $control->getValue();
  550. 550:         foreach ((is_array($value$value array($value)) as $val{
  551. 551:             foreach ((is_array($arg$arg array($arg)) as $item{
  552. 552:                 if ((string) $val === (string) ($item instanceof IFormControl $item->value $item)) {
  553. 553:                     return TRUE;
  554. 554:                 }
  555. 555:             }
  556. 556:         }
  557. 557:         return FALSE;
  558. 558:     }
  559. 559:  
  560. 560:  
  561. 561:  
  562. 562:     /**
  563. 563:      * Filled validator: is control filled?
  564. 564:      * @param  IFormControl 
  565. 565:      * @return bool 
  566. 566:      */
  567. 567:     public static function validateFilled(IFormControl $control)
  568. 568:     {
  569. 569:         return (string) $control->getValue(!== ''// NULL, FALSE, '' ==> FALSE
  570. 570:     }
  571. 571:  
  572. 572:  
  573. 573:  
  574. 574:     /**
  575. 575:      * Valid validator: is control valid?
  576. 576:      * @param  IFormControl 
  577. 577:      * @return bool 
  578. 578:      */
  579. 579:     public static function validateValid(IFormControl $control)
  580. 580:     {
  581. 581:         return $control->rules->validate(TRUE);
  582. 582:     }
  583. 583:  
  584. 584:  
  585. 585:  
  586. 586:     /**
  587. 587:      * Adds error message to the list.
  588. 588:      * @param  string  error message
  589. 589:      * @return void 
  590. 590:      */
  591. 591:     public function addError($message)
  592. 592:     {
  593. 593:         if (!in_array($message$this->errorsTRUE)) {
  594. 594:             $this->errors[$message;
  595. 595:         }
  596. 596:         $this->getForm()->addError($message);
  597. 597:     }
  598. 598:  
  599. 599:  
  600. 600:  
  601. 601:     /**
  602. 602:      * Returns errors corresponding to control.
  603. 603:      * @return array 
  604. 604:      */
  605. 605:     public function getErrors()
  606. 606:     {
  607. 607:         return $this->errors;
  608. 608:     }
  609. 609:  
  610. 610:  
  611. 611:  
  612. 612:     /**
  613. 613:      * @return bool 
  614. 614:      */
  615. 615:     public function hasErrors()
  616. 616:     {
  617. 617:         return (bool) $this->errors;
  618. 618:     }
  619. 619:  
  620. 620:  
  621. 621:  
  622. 622:     /**
  623. 623:      * @return void 
  624. 624:      */
  625. 625:     public function cleanErrors()
  626. 626:     {
  627. 627:         $this->errors array();
  628. 628:     }
  629. 629: