Namespaces

  • Latte
    • Loaders
    • Macros
    • Runtime
  • Nette
    • Application
      • Responses
      • Routers
      • UI
    • Bridges
      • ApplicationDI
      • ApplicationLatte
      • ApplicationTracy
      • CacheDI
      • CacheLatte
      • DatabaseDI
      • DatabaseTracy
      • DITracy
      • FormsDI
      • FormsLatte
      • Framework
      • HttpDI
      • HttpTracy
      • MailDI
      • ReflectionDI
      • SecurityDI
      • SecurityTracy
    • Caching
      • Storages
    • ComponentModel
    • Database
      • Conventions
      • Drivers
      • Reflection
      • Table
    • DI
      • Config
        • Adapters
      • Extensions
    • Diagnostics
    • Forms
      • Controls
      • Rendering
    • Http
    • Iterators
    • Latte
    • Loaders
    • Localization
    • Mail
    • Neon
    • PhpGenerator
    • Reflection
    • Security
    • Templating
    • Utils
  • NetteModule
  • none
  • Tracy
    • Bridges
      • Nette

Classes

  • Container
  • ControlGroup
  • Form
  • Helpers
  • Rule
  • Rules
  • Validator

Interfaces

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