Source for file Form.php

Documentation is available at Form.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__) . '/../Forms/FormContainer.php';
24:
25:
26:
27: /**
28: * Creates, validates and renders HTML forms.
29: *
30: * @author David Grudl
31: * @copyright Copyright (c) 2004, 2009 David Grudl
32: * @package Nette\Forms
33: * @example forms/basic-example.php Form definition using fluent interfaces
34: * @example forms/manual-rendering.php Manual form rendering and separated form and rules definition
35: * @example forms/localization.php Localization (with Zend_Translate)
36: * @example forms/custom-rendering.php Custom form rendering
37: * @example forms/custom-validator.php How to use custom validator
38: * @example forms/naming-containers.php How to use naming containers
39: * @example forms/CSRF-protection.php How to use Cross-Site Request Forgery (CSRF) form protection
40: * @example forms/custom-encoding.php How to change charset
41: */
42: class Form extends FormContainer
43: {
44: /**#@+ operation name */
45: const EQUAL = ':equal';
46: const IS_IN = ':equal';
47: const FILLED = ':filled';
48: const VALID = ':valid';
49:
50: // button
51: const SUBMITTED = ':submitted';
52:
53: // text
54: const MIN_LENGTH = ':minLength';
55: const MAX_LENGTH = ':maxLength';
56: const LENGTH = ':length';
57: const EMAIL = ':email';
58: const URL = ':url';
59: const REGEXP = ':regexp';
60: const INTEGER = ':integer';
61: const NUMERIC = ':integer';
62: const FLOAT = ':float';
63: const RANGE = ':range';
64:
65: // file upload
66: const MAX_FILE_SIZE = ':fileSize';
67: const MIME_TYPE = ':mimeType';
68:
69: // special case
70: const SCRIPT = 'Nette\Forms\InstantClientScript::javascript';
71: /**#@-*/
72:
73: /** tracker ID */
74: const TRACKER_ID = '_form_';
75:
76: /** protection token ID */
77: const PROTECTOR_ID = '_token_';
78:
79: /** @var array of event handlers; Occurs when the form is submitted and successfully validated; function(Form $sender) */
80: public $onSubmit;
81:
82: /** @var array of event handlers; Occurs when the form is submitted and not validated; function(Form $sender) */
83: public $onInvalidSubmit;
84:
85: /** @var mixed */
86: protected $submittedBy;
87:
88: /** @var Html <form> element */
89: private $element;
90:
91: /** @var IFormRenderer */
92: private $renderer;
93:
94: /** @var ITranslator */
95: private $translator;
96:
97: /** @var array of FormGroup */
98: private $groups = array();
99:
100: /** @var bool */
101: private $isPopulated = FALSE;
102:
103: /** @var bool */
104: private $valid;
105:
106: /** @var array */
107: private $errors = array();
108:
109: /** @var array */
110: private $encoding = 'UTF-8';
111:
112:
113:
114: /**
115: * Form constructor.
116: */
117: public function __construct($name = NULL, $parent = NULL)
118: {
119: $this->element = Html::el('form');
120: $this->element->action = ''; // RFC 1808 -> empty uri means 'this'
121: $this->element->method = 'post';
122: $this->monitor(__CLASS__);
123: parent::__construct($parent, $name);
124: }
125:
126:
127:
128: /**
129: * This method will be called when the component (or component's parent)
130: * becomes attached to a monitored object. Do not call this method yourself.
131: * @param IComponent
132: * @return void
133: */
134: protected function attached($obj)
135: {
136: if ($obj instanceof self) {
137: throw new InvalidStateException('Nested forms are forbidden.');
138: }
139: }
140:
141:
142:
143: /**
144: * Returns self.
145: * @return Form
146: */
147: final public function getForm($need = TRUE)
148: {
149: return $this;
150: }
151:
152:
153:
154: /**
155: * Sets form's action.
156: * @param mixed URI
157: * @return void
158: */
159: public function setAction($url)
160: {
161: $this->element->action = $url;
162: }
163:
164:
165:
166: /**
167: * Returns form's action.
168: * @return mixed URI
169: */
170: public function getAction()
171: {
172: return $this->element->action;
173: }
174:
175:
176:
177: /**
178: * Sets form's method.
179: * @param string get | post
180: * @return void
181: */
182: public function setMethod($method)
183: {
184: $this->element->method = strtolower($method);
185: }
186:
187:
188:
189: /**
190: * Returns form's method.
191: * @return string get | post
192: */
193: public function getMethod()
194: {
195: return $this->element->method;
196: }
197:
198:
199:
200: /**
201: * Adds distinguishing mark.
202: * @param string
203: * @return HiddenField
204: */
205: public function addTracker($name)
206: {
207: return $this[self::TRACKER_ID] = new HiddenField($name);
208: }
209:
210:
211:
212: /**
213: * Cross-Site Request Forgery (CSRF) form protection.
214: * @param string
215: * @param int
216: * @return void
217: */
218: public function addProtection($message = NULL, $timeout = NULL)
219: {
220: $session = $this->getSession()->getNamespace('Nette.Forms.Form/CSRF');
221: $key = "key$timeout";
222: if (isset($session->$key)) {
223: $token = $session->$key;
224: } else {
225: $session->$key = $token = md5(uniqid('', TRUE));
226: }
227: $session->setExpiration($timeout, $key);
228: $this[self::PROTECTOR_ID] = new HiddenField($token);
229: $this[self::PROTECTOR_ID]->addRule(':equal', empty($message) ? 'Security token did not match. Possible CSRF attack.' : $message, $token);
230: }
231:
232:
233:
234: /**
235: * Adds fieldset group to the form.
236: * @param string label
237: * @param bool set this group as current
238: * @return FormGroup
239: */
240: public function addGroup($label = NULL, $setAsCurrent = TRUE)
241: {
242: $group = new FormGroup;
243: $group->setOption('label', $label);
244: $group->setOption('visual', TRUE);
245:
246: if ($setAsCurrent) {
247: $this->setCurrentGroup($group);
248: }
249:
250: if (isset($this->groups[$label])) {
251: return $this->groups[] = $group;
252: } else {
253: return $this->groups[$label] = $group;
254: }
255: }
256:
257:
258:
259: /**
260: * Returns all defined groups.
261: * @return array of FormGroup
262: */
263: public function getGroups()
264: {
265: return $this->groups;
266: }
267:
268:
269:
270: /**
271: * Returns the specified group.
272: * @param string name
273: * @return FormGroup
274: */
275: public function getGroup($name)
276: {
277: return isset($this->groups[$name]) ? $this->groups[$name] : NULL;
278: }
279:
280:
281:
282: /**
283: * Set the encoding for the values.
284: * @param string
285: * @return void
286: */
287: public function setEncoding($value)
288: {
289: $this->encoding = empty($value) ? 'UTF-8' : strtoupper($value);
290: if ($this->encoding !== 'UTF-8' && !extension_loaded('mbstring')) {
291: throw new Exception("The PHP extension 'mbstring' is required for this encoding but is not loaded.");
292: }
293: }
294:
295:
296:
297: /**
298: * Returns the encoding.
299: * @return string
300: */
301: final public function getEncoding()
302: {
303: return $this->encoding;
304: }
305:
306:
307:
308: /********************* translator ****************d*g**/
309:
310:
311:
312: /**
313: * Sets translate adapter.
314: * @param ITranslator
315: * @return void
316: */
317: public function setTranslator(ITranslator $translator = NULL)
318: {
319: $this->translator = $translator;
320: }
321:
322:
323:
324: /**
325: * Returns translate adapter.
326: * @return ITranslator|NULL
327: */
328: final public function getTranslator()
329: {
330: return $this->translator;
331: }
332:
333:
334:
335: /********************* submission ****************d*g**/
336:
337:
338:
339: /**
340: * Tells if the form was submitted.
341: * @return ISubmitterControl|FALSE submittor control
342: */
343: public function isSubmitted()
344: {
345: if ($this->submittedBy === NULL) {
346: $this->processHttpRequest();
347: }
348:
349: return $this->submittedBy;
350: }
351:
352:
353:
354: /**
355: * Sets the submittor control.
356: * @param ISubmitterControl
357: * @return void
358: */
359: public function setSubmittedBy(ISubmitterControl $by = NULL)
360: {
361: $this->submittedBy = $by === NULL ? FALSE : $by;
362: }
363:
364:
365:
366: /**
367: * Detects form submission and loads HTTP values.
368: * @param IHttpRequest optional request object
369: * @return void
370: */
371: public function processHttpRequest($httpRequest = NULL)
372: {
373: $this->submittedBy = FALSE;
374:
375: if ($httpRequest === NULL) {
376: $httpRequest = $this->getHttpRequest();
377: }
378: $httpRequest->setEncoding($this->encoding);
379:
380: if (strcasecmp($this->getMethod(), 'post') === 0) {
381: if (!$httpRequest->isMethod('post')) return;
382: $data = Tools::arrayMergeTree($httpRequest->getPost(), $httpRequest->getFiles());
383:
384: } else {
385: if (!$httpRequest->isMethod('get')) return;
386: $data = $httpRequest->getQuery();
387: }
388:
389: $tracker = $this->getComponent(self::TRACKER_ID, FALSE);
390: if ($tracker) {
391: if (!isset($data[self::TRACKER_ID]) || $data[self::TRACKER_ID] !== $tracker->getValue()) return;
392:
393: } else {
394: if (!count($data)) return;
395: }
396:
397: $this->submittedBy = TRUE;
398: $this->loadHttpData($data);
399: $this->submit();
400: }
401:
402:
403:
404: /**
405: * Fires submit/click events.
406: * @return void
407: */
408: protected function submit()
409: {
410: if (!$this->isSubmitted()) {
411: return;
412:
413: } elseif ($this->submittedBy instanceof ISubmitterControl) {
414: if (!$this->submittedBy->getValidationScope() || $this->isValid()) {
415: $this->submittedBy->click();
416: $this->onSubmit($this);
417: } else {
418: $this->submittedBy->onInvalidClick($this->submittedBy);
419: $this->onInvalidSubmit($this);
420: }
421:
422: } elseif ($this->isValid()) {
423: $this->onSubmit($this);
424:
425: } else {
426: $this->onInvalidSubmit($this);
427: }
428: }
429:
430:
431:
432: /********************* data exchange ****************d*g**/
433:
434:
435:
436: /**
437: * Fill-in with default values.
438: * @param array|Traversable values used to fill the form
439: * @param bool erase other controls?
440: * @return void
441: */
442: public function setDefaults($values, $erase = FALSE)
443: {
444: if (!$this->isSubmitted()) {
445: $this->setValues($values, $erase);
446: }
447: }
448:
449:
450:
451: /**
452: * Fill-in the form with HTTP data. Doesn't check if form was submitted.
453: * @param array user data
454: * @return void
455: */
456: protected function loadHttpData(array $data)
457: {
458: $cursor = & $data;
459: $iterator = $this->getComponents(TRUE);
460: foreach ($iterator as $name => $control) {
461: $sub = $iterator->getSubIterator();
462: if (!isset($sub->cursor)) {
463: $sub->cursor = & $cursor;
464: }
465: if ($control instanceof IFormControl && !$control->isDisabled()) {
466: $control->loadHttpData($sub->cursor);
467: if ($control instanceof ISubmitterControl && (!is_object($this->submittedBy) || $control->isSubmittedBy())) {
468: $this->submittedBy = $control;
469: }
470: }
471: if ($control instanceof INamingContainer) { // going deeper
472: if (isset($sub->cursor[$name]) && is_array($sub->cursor[$name])) {
473: $cursor = & $sub->cursor[$name];
474: } else {
475: unset($cursor);
476: $cursor = NULL;
477: }
478: }
479: }
480: $this->isPopulated = TRUE;
481: }
482:
483:
484:
485: /**
486: * Was form populated by setDefaults() or processHttpRequest() yet?
487: * @return bool
488: */
489: public function isPopulated()
490: {
491: return $this->isPopulated;
492: }
493:
494:
495:
496: /**
497: * Fill-in with values.
498: * @param array|Traversable values used to fill the form
499: * @param bool erase other controls?
500: * @return void
501: */
502: public function setValues($values, $erase = FALSE)
503: {
504: if ($values instanceof Traversable) {
505: $values = iterator_to_array($values);
506:
507: } elseif (!is_array($values)) {
508: throw new InvalidArgumentException("Values must be an array, " . gettype($values) ." given.");
509: }
510:
511: $cursor = & $values;
512: $iterator = $this->getComponents(TRUE);
513: foreach ($iterator as $name => $control) {
514: $sub = $iterator->getSubIterator();
515: if (!isset($sub->cursor)) {
516: $sub->cursor = & $cursor;
517: }
518: if ($control instanceof IFormControl) {
519: if ((is_array($sub->cursor) || $sub->cursor instanceof ArrayAccess) && array_key_exists($name, $sub->cursor)) {
520: $control->setValue($sub->cursor[$name]);
521:
522: } elseif ($erase) {
523: $control->setValue(NULL);
524: }
525: }
526: if ($control instanceof INamingContainer) {
527: if ((is_array($sub->cursor) || $sub->cursor instanceof ArrayAccess) && isset($sub->cursor[$name])) {
528: $cursor = & $sub->cursor[$name];
529: } else {
530: unset($cursor);
531: $cursor = NULL;
532: }
533: }
534: }
535: $this->isPopulated = TRUE;
536: }
537:
538:
539:
540: /**
541: * Returns the values submitted by the form.
542: * @return array
543: */
544: public function getValues()
545: {
546: if (!$this->isPopulated) {
547: throw new InvalidStateException('Form was not populated yet. Call method isSubmitted() or setDefaults().');
548: }
549:
550: $values = array();
551: $cursor = & $values;
552: $iterator = $this->getComponents(TRUE);
553: foreach ($iterator as $name => $control) {
554: $sub = $iterator->getSubIterator();
555: if (!isset($sub->cursor)) {
556: $sub->cursor = & $cursor;
557: }
558: if ($control instanceof IFormControl && !$control->isDisabled() && !($control instanceof ISubmitterControl)) {
559: $sub->cursor[$name] = $control->getValue();
560: }
561: if ($control instanceof INamingContainer) {
562: $cursor = & $sub->cursor[$name];
563: $cursor = array();
564: }
565: }
566: unset($values[self::TRACKER_ID], $values[self::PROTECTOR_ID]);
567: return $values;
568: }
569:
570:
571:
572: /********************* validation ****************d*g**/
573:
574:
575:
576: /**
577: * Is form valid?
578: * @return bool
579: */
580: public function isValid()
581: {
582: if ($this->valid === NULL) {
583: $this->validate();
584: }
585: return $this->valid;
586: }
587:
588:
589:
590: /**
591: * Performs the server side validation.
592: * @return void
593: */
594: public function validate()
595: {
596: if (!$this->isPopulated) {
597: throw new InvalidStateException('Form was not populated yet. Call method isSubmitted() or setDefaults().');
598: }
599:
600: $controls = $this->getControls();
601:
602: $this->valid = TRUE;
603: foreach ($controls as $control) {
604: if (!$control->getRules()->validate()) {
605: $this->valid = FALSE;
606: }
607: }
608: }
609:
610:
611:
612: /**
613: * Adds error message to the list.
614: * @param string error message
615: * @return void
616: */
617: public function addError($message)
618: {
619: if (!in_array($message, $this->errors, TRUE)) {
620: $this->errors[] = $message;
621: $this->valid = FALSE;
622: }
623: }
624:
625:
626:
627: /**
628: * Returns validation errors.
629: * @return array
630: */
631: public function getErrors()
632: {
633: return $this->errors;
634: }
635:
636:
637:
638: /**
639: * @return bool
640: */
641: public function hasErrors()
642: {
643: return (bool) $this->getErrors();
644: }
645:
646:
647:
648: /**
649: * @return void
650: */
651: public function cleanErrors()
652: {
653: $this->errors = array();
654: $this->valid = NULL;
655: }
656:
657:
658:
659: /********************* rendering ****************d*g**/
660:
661:
662:
663: /**
664: * Returns form's HTML element template.
665: * @return Html
666: */
667: public function getElementPrototype()
668: {
669: return $this->element;
670: }
671:
672:
673:
674: /**
675: * Sets form renderer.
676: * @param IFormRenderer
677: * @return void
678: */
679: public function setRenderer(IFormRenderer $renderer)
680: {
681: $this->renderer = $renderer;
682: }
683:
684:
685:
686: /**
687: * Returns form renderer.
688: * @return IFormRenderer|NULL
689: */
690: final public function getRenderer()
691: {
692: if ($this->renderer === NULL) {
693: $this->renderer = new ConventionalRenderer;
694: }
695: return $this->renderer;
696: }
697:
698:
699:
700: /**
701: * Renders form.
702: * @return void
703: */
704: public function render()
705: {
706: $args = func_get_args();
707: array_unshift($args, $this);
708: $s = call_user_func_array(array($this->getRenderer(), 'render'), $args);
709:
710: if (strcmp($this->encoding, 'UTF-8')) {
711: echo mb_convert_encoding($s, 'HTML-ENTITIES', 'UTF-8');
712: } else {
713: echo $s;
714: }
715: }
716:
717:
718:
719: /**
720: * Renders form to string.
721: * @return bool can throw exceptions? (hidden parameter)
722: * @return string
723: */
724: public function __toString()
725: {
726: try {
727: if (strcmp($this->encoding, 'UTF-8')) {
728: return mb_convert_encoding($this->getRenderer()->render($this), 'HTML-ENTITIES', 'UTF-8');
729: } else {
730: return $this->getRenderer()->render($this);
731: }
732:
733: } catch (Exception $e) {
734: if (func_get_args() && func_get_arg(0)) {
735: throw $e;
736: } else {
737: trigger_error($e->getMessage(), E_USER_WARNING);
738: return '';
739: }
740: }
741: }
742:
743:
744:
745: /********************* backend ****************d*g**/
746:
747:
748:
749: /**
750: * @return IHttpRequest
751: */
752: protected function getHttpRequest()
753: {
754: return class_exists('Environment') ? Environment::getHttpRequest() : new HttpRequest;
755: }
756:
757:
758:
759: /**
760: * @return Session
761: */
762: protected function getSession()
763: {
764: return Environment::getSession();
765: }
766:
767: }

Source for file Form.php

Namespaces