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