Source for file FormControl.php

Documentation is available at FormControl.php

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

Source for file FormControl.php

Namespaces