Nette Documentation Preview

syntax 
Contrôles de formulaires
************************

.[perex]
Aperçu des contrôles de formulaires intégrés.


addText(string|int $name, $label=null, $cols, ?int $maxLength=null): TextInput .[method]
========================================================================================

Ajoute un champ de texte à une ligne (classe [TextInput |api:Nette\Forms\Controls\TextInput]). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide `''`, ou utilise `setNullable()` pour le modifier et renvoyer `null`.

```php
$form->addText('name', 'Name:')
	->setRequired()
	->setNullable();
```

Il valide automatiquement l'UTF-8, coupe les espaces à gauche et à droite et supprime les sauts de ligne qui pourraient être envoyés par un attaquant.

La longueur maximale peut être limitée en utilisant `setMaxLength()`. La [fonction addFilter() |validation#Modifying Input Values] permet de modifier la valeur saisie par l'utilisateur.

Vous pouvez modifier le caractère visuel d'un champ de texte en utilisant des types tels que `search`, `tel`, ou `url` en utilisant `setHtmlType()`, comme indiqué dans la [spécification |https://developer.mozilla.org/en-US/docs/Learn/Forms/HTML5_input_types]. N'oubliez pas que le changement de type n'est que visuel et qu'il n'exécute pas de fonctions de validation. Pour le type `url`, il convient d'ajouter une [règle URL |validation#Text inputs] spécifique.

.[note]
Pour les autres types d'entrée tels que `number`, `range`, `email`, `date`, `datetime-local`, `time`, et `color`, utilisez des méthodes spécialisées telles que [addInteger |#addInteger], [addFloat |#addFloat], [addEmail |#addEmail] [addDate |#addDate], [addTime |#addTime], [addDateTime |#addDateTime], et [addColor |#addColor], qui assurent la validation côté serveur. Les types `month` et `week` ne sont pas encore totalement pris en charge par tous les navigateurs.

La valeur dite vide peut être définie pour l'élément, qui ressemble à la valeur par défaut, mais si l'utilisateur ne l'écrase pas, elle renvoie une chaîne vide ou `null`.

```php
$form->addText('phone', 'Phone:')
	->setHtmlType('tel')
	->setEmptyValue('+420');
```


addTextArea(string|int $name, $label=null): TextArea .[method]
==============================================================

Ajoute un champ de texte multiligne (classe [TextArea |api:Nette\Forms\Controls\TextArea]). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide `''`, ou utilise `setNullable()` pour le modifier et renvoyer `null`.

```php
$form->addTextArea('note', 'Note:')
	->addRule($form::MaxLength, 'Your note is way too long', 10000);
```

Valide automatiquement l'UTF-8 et normalise les sauts de ligne à `\n`. Contrairement à un champ de saisie à ligne unique, il ne coupe pas les espaces blancs.

La longueur maximale peut être limitée en utilisant `setMaxLength()`. La fonction [addFilter() |validation#Modifying Input Values] vous permet de modifier la valeur saisie par l'utilisateur. Vous pouvez définir la valeur dite vide à l'aide de `setEmptyValue()`.


addInteger(string|int $name, $label=null): TextInput .[method]
==============================================================

Ajoute un champ de saisie pour un nombre entier (classe [TextInput |api:Nette\Forms\Controls\TextInput]). Renvoie soit un entier, soit `null` si l'utilisateur ne saisit rien.

```php
$form->addInteger('year', 'Year:')
	->addRule($form::Range, 'L'année doit être comprise entre %d et %d.', [1900, 2023 |1900, 2023]) ;
```

L'élément est rendu sous la forme `<input type="numeric">`. En utilisant la méthode `setHtmlType()`, vous pouvez changer le type en `range` pour l'afficher comme un curseur, ou en `text` si vous préférez un champ de texte standard sans le comportement spécial de `numeric`.


addFloat(string|int $name, $label=null): TextInput .[method]{data-version:3.1.12}
=================================================================================

Adds a field for entering a decimal number ([TextInput |api:Nette\Forms\Controls\TextInput] class). Returns either float or `null`, if the user does not specify anything.

```php
$form->addFloat('niveau', 'Niveau:')
	->setDefaultValue(0)
->addRule($form::Range, 'Le niveau doit être compris entre %d et %d.', [0, 100 |0, 100]) ;
```

L'élément est rendu sous la forme `<input type="numeric">`. En utilisant la méthode `setHtmlType()`, vous pouvez changer le type en `range` pour l'afficher comme un curseur, ou en `text` si vous préférez un champ de texte standard sans le comportement spécial de `numeric`.

Nette et le navigateur Chrome acceptent à la fois une virgule et un point comme séparateurs décimaux. Pour que cette fonctionnalité soit disponible dans Firefox, il est recommandé de définir l'attribut `lang` soit pour l'élément spécifique, soit pour la page entière, par exemple, `<html lang="cs">`.


addEmail(string|int $name, $label=null, int $maxLength=255): TextInput .[method]
================================================================================

Ajoute un champ d'adresse électronique avec contrôle de validité (classe [TextInput |api:Nette\Forms\Controls\TextInput]). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide `''`, ou utilise `setNullable()` pour le modifier et renvoyer `null`.

```php
$form->addEmail('email', 'Email:');
```

Vérifie que la valeur est une adresse électronique valide. Il ne vérifie pas que le domaine existe réellement, seule la syntaxe est vérifiée. Valide automatiquement l'UTF-8, supprime les espaces à gauche et à droite.

La longueur maximale peut être limitée en utilisant `setMaxLength()`. La [fonction addFilter() |validation#Modifying Input Values] vous permet de modifier la valeur saisie par l'utilisateur. Vous pouvez définir la valeur dite vide à l'aide de `setEmptyValue()`.


addPassword(string|int $name, $label=null, $cols, ?int $maxLength=null): TextInput .[method]
============================================================================================

Ajoute un champ de mot de passe (classe [TextInput |api:Nette\Forms\Controls\TextInput]).

```php
$form->addPassword('password', 'Password:')
	->setRequired()
	->addRule($form::MinLength, 'Password has to be at least %d characters long', 8)
	->addRule($form::Pattern, 'Password must contain a number', '.*[0-9].*');
```

Lorsque vous renvoyez le formulaire, l'entrée sera vide. Il valide automatiquement l'UTF-8, coupe les espaces à gauche et à droite et supprime les sauts de ligne qui pourraient être envoyés par un attaquant.


addCheckbox(string|int $name, $caption=null): Checkbox .[method]
================================================================

Ajoute une case à cocher (classe [Checkbox |api:Nette\Forms\Controls\Checkbox]). Le champ renvoie soit `true` soit `false`, selon qu'il est coché ou non.

```php
$form->addCheckbox('agree', 'I agree with terms')
	->setRequired('You must agree with our terms');
```


addCheckboxList(string|int $name, $label=null, ?array $items=null): CheckboxList .[method]
==========================================================================================

Ajoute une liste de cases à cocher pour sélectionner plusieurs éléments (classe [CheckboxList |api:Nette\Forms\Controls\CheckboxList]). Renvoie le tableau des clés des éléments sélectionnés. La méthode `getSelectedItems()` renvoie des valeurs au lieu des clés.

```php
$form->addCheckboxList('colors', 'Colors:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);
```

Nous passons le tableau d'éléments comme troisième paramètre, ou par la méthode `setItems()`.

Vous pouvez utiliser `setDisabled(['r', 'g'])` pour désactiver des éléments individuels.

L'élément vérifie automatiquement qu'il n'y a pas eu de falsification et que les éléments sélectionnés font bien partie des éléments proposés et n'ont pas été désactivés. La méthode `getRawValue()` peut être utilisée pour récupérer les éléments proposés sans cette importante vérification.

Lorsque des valeurs par défaut sont définies, la méthode vérifie également qu'il s'agit de l'un des éléments proposés, sinon elle lève une exception. Cette vérification peut être désactivée avec `checkDefaultValue(false)`.

Si vous soumettez un formulaire à l'aide de la méthode `GET`, vous pouvez choisir une méthode de transfert de données plus compacte qui réduit la taille de la chaîne de requête. Cette option est activée en définissant l'attribut HTML du formulaire :

```php
$form->setHtmlAttribute('data-nette-compact');
```


addRadioList(string|int $name, $label=null, ?array $items=null): RadioList .[method]
====================================================================================

Ajoute des boutons radio (classe [RadioList |api:Nette\Forms\Controls\RadioList]). Renvoie la clé de l'élément sélectionné, ou `null` si l'utilisateur n'a rien sélectionné. La méthode `getSelectedItem()` renvoie une valeur au lieu d'une clé.

```php
$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);
```

Nous passons le tableau d'éléments comme troisième paramètre, ou par la méthode `setItems()`.

Vous pouvez utiliser `setDisabled(['m'])` pour désactiver des éléments individuels.

L'élément vérifie automatiquement qu'il n'y a pas eu de falsification et que l'élément sélectionné est bien l'un de ceux proposés et n'a pas été désactivé. La méthode `getRawValue()` peut être utilisée pour récupérer l'élément soumis sans cette importante vérification.

Lorsque la valeur par défaut est définie, elle vérifie également qu'il s'agit de l'un des éléments proposés, sinon elle lève une exception. Cette vérification peut être désactivée avec `checkDefaultValue(false)`.


addSelect(string|int $name, $label=null, ?array $items=null, ?int $size=null): SelectBox .[method]
==================================================================================================

Ajoute une boîte de sélection (classe [SelectBox |api:Nette\Forms\Controls\SelectBox]). Renvoie la clé de l'élément sélectionné, ou `null` si l'utilisateur n'a rien sélectionné. La méthode `getSelectedItem()` renvoie une valeur au lieu d'une clé.

```php
$countries = [
	'CZ' => 'Czech republic',
	'SK' => 'Slovakia',
	'GB' => 'United Kingdom',
];

$form->addSelect('country', 'Country:', $countries)
	->setDefaultValue('SK');
```

Nous passons le tableau d'éléments comme troisième paramètre, ou par la méthode `setItems()`. Le tableau d'éléments peut également être bidimensionnel :

```php
$countries = [
	'Europe' => [
		'CZ' => 'Czech republic',
		'SK' => 'Slovakia',
		'GB' => 'United Kingdom',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'other',
];
```

Pour les boîtes de sélection, le premier élément a souvent une signification particulière, il sert d'appel à l'action. Utilisez la méthode `setPrompt()` pour ajouter une telle entrée.

```php
$form->addSelect('country', 'Country:', $countries)
	->setPrompt('Pick a country');
```

Vous pouvez utiliser `setDisabled(['CZ', 'SK'])` pour désactiver des éléments individuels.

L'élément vérifie automatiquement qu'il n'y a pas eu de falsification et que l'élément sélectionné est bien l'un de ceux proposés et n'a pas été désactivé. La méthode `getRawValue()` peut être utilisée pour récupérer l'élément soumis sans cette importante vérification.

Lorsque la valeur par défaut est définie, elle vérifie également qu'il s'agit de l'un des éléments proposés, sinon elle lève une exception. Cette vérification peut être désactivée avec `checkDefaultValue(false)`.


addMultiSelect(string|int $name, $label=null, ?array $items=null, ?int $size=null): MultiSelectBox .[method]
============================================================================================================

Ajoute une boîte de sélection multichoix (classe [MultiSelectBox |api:Nette\Forms\Controls\MultiSelectBox]). Renvoie le tableau des clés des éléments sélectionnés. La méthode `getSelectedItems()` renvoie des valeurs au lieu des clés.

```php
$form->addMultiSelect('countries', 'Countries:', $countries);
```

Nous passons le tableau d'éléments comme troisième paramètre, ou par la méthode `setItems()`. Le tableau d'éléments peut également être bidimensionnel.

Vous pouvez utiliser `setDisabled(['CZ', 'SK'])` pour désactiver des éléments individuels.

L'élément vérifie automatiquement qu'il n'y a pas eu de falsification et que les éléments sélectionnés font bien partie des éléments proposés et n'ont pas été désactivés. La méthode `getRawValue()` peut être utilisée pour récupérer les éléments proposés sans cette importante vérification.

Lorsque des valeurs par défaut sont définies, la méthode vérifie également qu'il s'agit de l'un des éléments proposés, sinon elle lève une exception. Cette vérification peut être désactivée avec `checkDefaultValue(false)`.


addUpload(string|int $name, $label=null): UploadControl .[method]
=================================================================

Ajoute un champ de téléchargement de fichier (classe [UploadControl |api:Nette\Forms\Controls\UploadControl]). Renvoie l'objet [FileUpload |http:request#FileUpload], même si l'utilisateur n'a pas téléchargé de fichier, ce qui peut être découvert par la méthode `FileUpload::hasFile()`.

```php
$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Avatar must be JPEG, PNG, GIF or WebP')
	->addRule($form::MaxFileSize, 'Maximum size is 1 MB', 1024 * 1024);
```

Si le fichier n'a pas été téléchargé correctement, le formulaire n'a pas été soumis avec succès et une erreur est affichée. C'est-à-dire qu'il n'est pas nécessaire de vérifier la méthode `FileUpload::isOk()`.

Ne vous fiez pas au nom de fichier original renvoyé par la méthode `FileUpload::getName()`, un client pourrait envoyer un nom de fichier malveillant dans le but de corrompre ou de pirater votre application.

Les règles `MimeType` et `Image` détectent le type de fichier ou d'image requis par sa signature. L'intégrité de l'ensemble du fichier n'est pas vérifiée. Vous pouvez savoir si une image n'est pas corrompue, par exemple en essayant de [la charger |http:request#toImage].


addMultiUpload(string|int $name, $label=null): UploadControl .[method]
======================================================================

Ajoute un champ de téléchargement de fichiers multiples (classe [UploadControl |api:Nette\Forms\Controls\UploadControl]). Retourne un tableau d'objets [FileUpload |http:request#FileUpload]. La méthode `FileUpload::hasFile()` renverra `true` pour chacun d'entre eux.

```php
$form->addMultiUpload('files', 'Files:')
	->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);
```

Si l'un des fichiers ne parvient pas à être téléchargé correctement, le formulaire n'a pas été soumis avec succès et une erreur est affichée. C'est-à-dire qu'il n'est pas nécessaire de vérifier la méthode `FileUpload::isOk()`.

Ne vous fiez pas aux noms de fichiers originaux renvoyés par la méthode `FileUpload::getName()`, un client pourrait envoyer un nom de fichier malveillant dans le but de corrompre ou de pirater votre application.

Les règles `MimeType` et `Image` détectent le type de fichier ou d'image requis par sa signature. L'intégrité de l'ensemble du fichier n'est pas vérifiée. Vous pouvez savoir si une image n'est pas corrompue, par exemple en essayant de [la charger |http:request#toImage].


addDate(string|int $name, $label=null): DateTimeControl .[method]{data-version:3.1.14}
======================================================================================

Ajoute un champ qui permet à l'utilisateur de saisir facilement une date composée de l'année, du mois et du jour (classe [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Pour la valeur par défaut, il accepte soit des objets implémentant la classe `DateTimeInterface`, soit une chaîne de caractères avec l'heure, soit un nombre représentant un horodatage UNIX. Il en va de même pour les arguments `Min`, `Max` ou `Range`, qui définissent la date minimale et maximale autorisée.

```php
$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));
```

Par défaut, elle renvoie un objet `DateTimeImmutable`. La méthode `setFormat()` permet de spécifier un [format texte |https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] ou un horodatage :

```php
$form->addDate('date', 'Date:')
	->setFormat('Y-m-d');
```


addTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl .[method]{data-version:3.1.14}
===============================================================================================================

Ajoute un champ qui permet à l'utilisateur de saisir facilement l'heure sous forme d'heures, de minutes et éventuellement de secondes (classe [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Pour la valeur par défaut, il accepte soit des objets implémentant `DateTimeInterface`, soit une chaîne de caractères avec l'heure, soit un nombre représentant un horodatage UNIX. Seule l'information temporelle de ces entrées est utilisée ; la date est ignorée. Il en va de même pour les arguments `Min`, `Max` ou `Range`, qui définissent la durée minimale et maximale autorisée. Si la valeur minimale définie est supérieure à la valeur maximale, une plage horaire s'étendant jusqu'à minuit est créée.

```php
$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);
```

Par défaut, elle renvoie un objet `DateTimeImmutable` (avec la date du 1er janvier de l'année 1). La méthode `setFormat()` permet de spécifier un [format de texte |https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters]:

```php
$form->addTime('time', 'Time:')
	->setFormat('H:i');
```


addDateTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl .[method]{data-version:3.1.14}
===================================================================================================================

Ajoute un champ qui permet à l'utilisateur de saisir facilement la date et l'heure en indiquant l'année, le mois, le jour, les heures, les minutes et, éventuellement, les secondes (classe [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Pour la valeur par défaut, il accepte soit des objets implémentant la classe `DateTimeInterface`, soit une chaîne de caractères avec l'heure, soit un nombre représentant un horodatage UNIX. Il en va de même pour les arguments `Min`, `Max` ou `Range`, qui définissent la date minimale et maximale autorisée.

```php
$form->addDateTime('datetime', 'Date and Time:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));
```

Par défaut, elle renvoie un objet `DateTimeImmutable`. La méthode `setFormat()` permet de spécifier un [format texte |https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] ou un horodatage :

```php
$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);
```


addColor(string|int $name, $label=null): ColorPicker .[method]{data-version:3.1.14}
===================================================================================

Ajoute un champ de sélection de couleur (classe [ColorPicker |api:Nette\Forms\Controls\ColorPicker]). La couleur est une chaîne au format `#rrggbb`. Si l'utilisateur ne fait pas de sélection, la couleur renvoyée par défaut est le noir `#000000`.

```php
$form->addColor('color', 'Color:')
	->setDefaultValue('#3C8ED7');
```


addHidden(string|int $name, ?string $default=null): HiddenField .[method]
=========================================================================

Ajoute un champ caché (classe [HiddenField |api:Nette\Forms\Controls\HiddenField]).

```php
$form->addHidden('userid');
```

Utilisez `setNullable()` pour le modifier afin qu'il renvoie `null` au lieu d'une chaîne vide. La [fonction addFilter() |validation#Modifying Input Values] permet de modifier la valeur soumise.

Bien que l'élément soit caché, il est **important de réaliser** que sa valeur peut toujours être modifiée ou usurpée par un attaquant. Il faut toujours vérifier et valider soigneusement toutes les valeurs reçues du côté du serveur pour éviter les risques de sécurité liés à la manipulation des données.


addSubmit(string|int $name, $caption=null): SubmitButton .[method]
==================================================================

Ajoute un bouton de soumission (classe [SubmitButton |api:Nette\Forms\Controls\SubmitButton]).

```php
$form->addSubmit('submit', 'Register');
```

Il est possible d'avoir plus d'un bouton d'envoi dans le formulaire :

```php
$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');
```

Pour savoir lequel d'entre eux a été cliqué, utilisez :

```php
if ($form['register']->isSubmittedBy()) {
  // ...
}
```

Si vous ne voulez pas valider le formulaire lorsqu'un bouton d'envoi est pressé (comme les boutons *Annulation* ou *Aperçu*), vous pouvez le désactiver avec [setValidationScope() |validation#Disabling Validation].


addButton(string|int $name, $caption): Button .[method]
=======================================================

Ajoute un bouton (classe [Button |api:Nette\Forms\Controls\Button]) sans fonction de soumission. Il est utile pour lier une autre fonctionnalité à l'id, par exemple une action JavaScript.

```php
$form->addButton('raise', 'Raise salary')
	->setHtmlAttribute('onclick', 'raiseSalary()');
```


addImageButton(string|int $name, ?string $src=null, ?string $alt=null): ImageButton .[method]
=============================================================================================

Ajoute un bouton d'envoi sous la forme d'une image (classe [ImageButton |api:Nette\Forms\Controls\ImageButton]).

```php
$form->addImageButton('submit', '/path/to/image');
```

Lorsque vous utilisez plusieurs boutons d'envoi, vous pouvez savoir lequel a été cliqué avec la commande `$form['submit']->isSubmittedBy()`.


addContainer(string|int $name): Container .[method]
===================================================

Ajoute un sous-formulaire (classe [Container |api:Nette\Forms\Container]), ou un conteneur, qui peut être traité de la même manière qu'un formulaire. Cela signifie que vous pouvez utiliser des méthodes comme `setDefaults()` ou `getValues()`.

```php
$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Your name:');
$sub1->addEmail('email', 'Email:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Your name:');
$sub2->addEmail('email', 'Email:');
```

Les données envoyées sont ensuite renvoyées sous la forme d'une structure multidimensionnelle :

```php
[
	'first' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
	'second' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
]
```


Aperçu des paramètres .[#toc-overview-of-settings]
==================================================

Pour tous les éléments, nous pouvons appeler les méthodes suivantes (voir la [documentation API |https://api.nette.org/forms/master/Nette/Forms/Controls.html] pour un aperçu complet) :

.[table-form-methods language-php]
| `setDefaultValue($value)` | définit la valeur par défaut
| `getValue()` | obtient la valeur actuelle
| `setOmitted()` | [valeurs omises |#omitted values]
| `setDisabled()` | [désactiver les entrées |#disabling inputs]

Rendu :
.[table-form-methods language-php]
| `setCaption($caption)`| changer la légende de l'élément
| `setTranslator($translator)` | définit le [traducteur |rendering#translating]
| `setHtmlAttribute($name, $value)` | définit l'[attribut HTML |rendering#HTML attributes] de l'élément
| `setHtmlId($id)` | définit l'attribut HTML `id`
| `setHtmlType($type)` | définit l'attribut HTML `type`
| `setHtmlName($name)`| définit l'attribut HTML `name`
| `setOption($key, $value)` | définit les [données de rendu |rendering#Options]

Validation :
.[table-form-methods language-php]
| `setRequired()` | [champ obligatoire |validation]
| `addRule()` | règle [de validation |validation#Rules]
| `addCondition()`, `addConditionOn()` | fixer la [condition de validation |validation#Conditions]
| `addError($message)`| [passer le message d'erreur |validation#processing-errors]

Les méthodes suivantes peuvent être appelées pour les éléments `addText()`, `addPassword()`, `addTextArea()`, `addEmail()`, `addInteger()`:

.[table-form-methods language-php]
| `setNullable()`| détermine si getValue() renvoie `null` au lieu d'une chaîne vide.
| `setEmptyValue($value)` | définit la valeur spéciale qui est traitée comme une chaîne vide
| `setMaxLength($length)`| définit le nombre maximum de caractères autorisés
| `addFilter($filter)`| [modifier les valeurs d'entrée |validation#Modifying Input Values]


Valeurs omises .[#toc-omitted-values]
=====================================

Si la valeur saisie par l'utilisateur ne vous intéresse pas, nous pouvons utiliser `setOmitted()` pour l'omettre du résultat fourni par la méthode `$form->getValues​()` ou transmis aux gestionnaires. Cela convient pour divers mots de passe à des fins de vérification, des champs antispam, etc.

```php
$form->addPassword('passwordVerify', 'Password again:')
	->setRequired('Fill your password again to check for typo')
	->addRule($form::Equal, 'Password mismatch', $form['password'])
	->setOmitted();
```


Désactiver les entrées .[#toc-disabling-inputs]
===============================================

Les entrées peuvent être désactivées à l'aide de `setDisabled()`. Une entrée désactivée ne peut pas être modifiée par l'utilisateur.

```php
$form->addText('username', 'User name:')
	->setDisabled();
```

Les entrées désactivées ne sont pas envoyées au serveur par le navigateur, et vous ne les trouverez donc pas dans les données renvoyées par la fonction `$form->getValues()`. Toutefois, si vous définissez `setOmitted(false)`, Nette inclura leur valeur par défaut dans ces données.

Lorsque `setDisabled()` est appelé, **la valeur de l'entrée est effacée** pour des raisons de sécurité. Si vous définissez une valeur par défaut, il est nécessaire de le faire après sa désactivation :

```php
$form->addText('username', 'User name:')
	->setDisabled()
	->setDefaultValue($userName);
```

Une alternative aux entrées désactivées sont les champs avec l'attribut HTML `readonly`, qui sont envoyés au serveur par le navigateur. Bien que le champ ne soit que lisible, il est **important de réaliser** que sa valeur peut toujours être modifiée ou usurpée par un attaquant.


Contrôles personnalisés .[#toc-custom-controls]
===============================================

Outre le large éventail de contrôles de formulaire intégrés, vous pouvez ajouter des contrôles personnalisés au formulaire comme suit :

```php
$form->addComponent(new DateInput('Date:'), 'date');
// syntaxe alternative: $form['date'] = new DateInput('Date:');
```

.[note]
Le formulaire est un descendant de la classe [Container | component-model:#Container] et les éléments sont des descendants de [Component | component-model:#Component].

Il est possible de définir de nouvelles méthodes de formulaire pour ajouter des éléments personnalisés (par exemple `$form->addZip()`). Il s'agit des méthodes dites d'extension. L'inconvénient est que les astuces de code dans les éditeurs ne fonctionnent pas pour elles.

```php
use Nette\Forms\Container;

// ajoute la méthode addZip(string $name, ?string $label = null)
Container::extensionMethod('addZip', function (Container $form, string $name, ?string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::Pattern, 'At least 5 numbers', '[0-9]{5}');
});

// utilisation
$form->addZip('zip', 'ZIP code:');
```


Champs de bas niveau .[#toc-low-level-fields]
=============================================

Pour ajouter un élément au formulaire, il n'est pas nécessaire d'appeler `$form->addXyz()`. Les éléments de formulaire peuvent être introduits exclusivement dans les modèles. Ceci est utile si vous devez, par exemple, générer des éléments dynamiques :

```latte
{foreach $items as $item}
	<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}
```

Après la soumission, vous pouvez récupérer les valeurs :

```php
$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');
```

Dans le premier paramètre, vous spécifiez le type d'élément (`DataFile` pour `type=file`, `DataLine` pour les entrées d'une ligne comme `text`, `password` ou `email` et `DataText` pour le reste). Le deuxième paramètre correspond à l'attribut HTML `name`. Si vous devez préserver les clés, vous pouvez combiner le premier paramètre avec `DataKeys`. Ceci est utile pour `select`, `radioList` ou `checkboxList`.

L'adresse `getHttpData()` renvoie des données d'entrée nettoyées. Dans ce cas, il s'agira toujours d'un tableau de chaînes UTF-8 valides, quel que soit l'attaquant envoyé par le formulaire. C'est une alternative au travail avec `$_POST` ou `$_GET` directement si vous voulez recevoir des données sûres.

Contrôles de formulaires

Aperçu des contrôles de formulaires intégrés.

addText(string|int $name, $label=null, $cols, ?int $maxLength=null): TextInput

Ajoute un champ de texte à une ligne (classe TextInput). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide '', ou utilise setNullable() pour le modifier et renvoyer null.

$form->addText('name', 'Name:')
	->setRequired()
	->setNullable();

Il valide automatiquement l'UTF-8, coupe les espaces à gauche et à droite et supprime les sauts de ligne qui pourraient être envoyés par un attaquant.

La longueur maximale peut être limitée en utilisant setMaxLength(). La fonction addFilter() permet de modifier la valeur saisie par l'utilisateur.

Vous pouvez modifier le caractère visuel d'un champ de texte en utilisant des types tels que search, tel, ou url en utilisant setHtmlType(), comme indiqué dans la spécification. N'oubliez pas que le changement de type n'est que visuel et qu'il n'exécute pas de fonctions de validation. Pour le type url, il convient d'ajouter une règle URL spécifique.

Pour les autres types d'entrée tels que number, range, email, date, datetime-local, time, et color, utilisez des méthodes spécialisées telles que addInteger, addFloat, addEmail addDate, addTime, addDateTime, et addColor, qui assurent la validation côté serveur. Les types month et week ne sont pas encore totalement pris en charge par tous les navigateurs.

La valeur dite vide peut être définie pour l'élément, qui ressemble à la valeur par défaut, mais si l'utilisateur ne l'écrase pas, elle renvoie une chaîne vide ou null.

$form->addText('phone', 'Phone:')
	->setHtmlType('tel')
	->setEmptyValue('+420');

addTextArea(string|int $name, $label=null): TextArea

Ajoute un champ de texte multiligne (classe TextArea). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide '', ou utilise setNullable() pour le modifier et renvoyer null.

$form->addTextArea('note', 'Note:')
	->addRule($form::MaxLength, 'Your note is way too long', 10000);

Valide automatiquement l'UTF-8 et normalise les sauts de ligne à \n. Contrairement à un champ de saisie à ligne unique, il ne coupe pas les espaces blancs.

La longueur maximale peut être limitée en utilisant setMaxLength(). La fonction addFilter() vous permet de modifier la valeur saisie par l'utilisateur. Vous pouvez définir la valeur dite vide à l'aide de setEmptyValue().

addInteger(string|int $name, $label=null): TextInput

Ajoute un champ de saisie pour un nombre entier (classe TextInput). Renvoie soit un entier, soit null si l'utilisateur ne saisit rien.

$form->addInteger('year', 'Year:')
	->addRule($form::Range, 'L'année doit être comprise entre %d et %d.', [1900, 2023 |1900, 2023]) ;

L'élément est rendu sous la forme <input type="numeric">. En utilisant la méthode setHtmlType(), vous pouvez changer le type en range pour l'afficher comme un curseur, ou en text si vous préférez un champ de texte standard sans le comportement spécial de numeric.

addFloat(string|int $name, $label=null): TextInput

Adds a field for entering a decimal number (TextInput class). Returns either float or null, if the user does not specify anything.

$form->addFloat('niveau', 'Niveau:')
	->setDefaultValue(0)
->addRule($form::Range, 'Le niveau doit être compris entre %d et %d.', [0, 100 |0, 100]) ;

L'élément est rendu sous la forme <input type="numeric">. En utilisant la méthode setHtmlType(), vous pouvez changer le type en range pour l'afficher comme un curseur, ou en text si vous préférez un champ de texte standard sans le comportement spécial de numeric.

Nette et le navigateur Chrome acceptent à la fois une virgule et un point comme séparateurs décimaux. Pour que cette fonctionnalité soit disponible dans Firefox, il est recommandé de définir l'attribut lang soit pour l'élément spécifique, soit pour la page entière, par exemple, <html lang="cs">.

addEmail(string|int $name, $label=null, int $maxLength=255): TextInput

Ajoute un champ d'adresse électronique avec contrôle de validité (classe TextInput). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide '', ou utilise setNullable() pour le modifier et renvoyer null.

$form->addEmail('email', 'Email:');

Vérifie que la valeur est une adresse électronique valide. Il ne vérifie pas que le domaine existe réellement, seule la syntaxe est vérifiée. Valide automatiquement l'UTF-8, supprime les espaces à gauche et à droite.

La longueur maximale peut être limitée en utilisant setMaxLength(). La fonction addFilter() vous permet de modifier la valeur saisie par l'utilisateur. Vous pouvez définir la valeur dite vide à l'aide de setEmptyValue().

addPassword(string|int $name, $label=null, $cols, ?int $maxLength=null): TextInput

Ajoute un champ de mot de passe (classe TextInput).

$form->addPassword('password', 'Password:')
	->setRequired()
	->addRule($form::MinLength, 'Password has to be at least %d characters long', 8)
	->addRule($form::Pattern, 'Password must contain a number', '.*[0-9].*');

Lorsque vous renvoyez le formulaire, l'entrée sera vide. Il valide automatiquement l'UTF-8, coupe les espaces à gauche et à droite et supprime les sauts de ligne qui pourraient être envoyés par un attaquant.

addCheckbox(string|int $name, $caption=null): Checkbox

Ajoute une case à cocher (classe Checkbox). Le champ renvoie soit true soit false, selon qu'il est coché ou non.

$form->addCheckbox('agree', 'I agree with terms')
	->setRequired('You must agree with our terms');

addCheckboxList(string|int $name, $label=null, ?array $items=null): CheckboxList

Ajoute une liste de cases à cocher pour sélectionner plusieurs éléments (classe CheckboxList). Renvoie le tableau des clés des éléments sélectionnés. La méthode getSelectedItems() renvoie des valeurs au lieu des clés.

$form->addCheckboxList('colors', 'Colors:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);

Nous passons le tableau d'éléments comme troisième paramètre, ou par la méthode setItems().

Vous pouvez utiliser setDisabled(['r', 'g']) pour désactiver des éléments individuels.

L'élément vérifie automatiquement qu'il n'y a pas eu de falsification et que les éléments sélectionnés font bien partie des éléments proposés et n'ont pas été désactivés. La méthode getRawValue() peut être utilisée pour récupérer les éléments proposés sans cette importante vérification.

Lorsque des valeurs par défaut sont définies, la méthode vérifie également qu'il s'agit de l'un des éléments proposés, sinon elle lève une exception. Cette vérification peut être désactivée avec checkDefaultValue(false).

Si vous soumettez un formulaire à l'aide de la méthode GET, vous pouvez choisir une méthode de transfert de données plus compacte qui réduit la taille de la chaîne de requête. Cette option est activée en définissant l'attribut HTML du formulaire :

$form->setHtmlAttribute('data-nette-compact');

addRadioList(string|int $name, $label=null, ?array $items=null): RadioList

Ajoute des boutons radio (classe RadioList). Renvoie la clé de l'élément sélectionné, ou null si l'utilisateur n'a rien sélectionné. La méthode getSelectedItem() renvoie une valeur au lieu d'une clé.

$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);

Nous passons le tableau d'éléments comme troisième paramètre, ou par la méthode setItems().

Vous pouvez utiliser setDisabled(['m']) pour désactiver des éléments individuels.

L'élément vérifie automatiquement qu'il n'y a pas eu de falsification et que l'élément sélectionné est bien l'un de ceux proposés et n'a pas été désactivé. La méthode getRawValue() peut être utilisée pour récupérer l'élément soumis sans cette importante vérification.

Lorsque la valeur par défaut est définie, elle vérifie également qu'il s'agit de l'un des éléments proposés, sinon elle lève une exception. Cette vérification peut être désactivée avec checkDefaultValue(false).

addSelect(string|int $name, $label=null, ?array $items=null, ?int $size=null): SelectBox

Ajoute une boîte de sélection (classe SelectBox). Renvoie la clé de l'élément sélectionné, ou null si l'utilisateur n'a rien sélectionné. La méthode getSelectedItem() renvoie une valeur au lieu d'une clé.

$countries = [
	'CZ' => 'Czech republic',
	'SK' => 'Slovakia',
	'GB' => 'United Kingdom',
];

$form->addSelect('country', 'Country:', $countries)
	->setDefaultValue('SK');

Nous passons le tableau d'éléments comme troisième paramètre, ou par la méthode setItems(). Le tableau d'éléments peut également être bidimensionnel :

$countries = [
	'Europe' => [
		'CZ' => 'Czech republic',
		'SK' => 'Slovakia',
		'GB' => 'United Kingdom',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'other',
];

Pour les boîtes de sélection, le premier élément a souvent une signification particulière, il sert d'appel à l'action. Utilisez la méthode setPrompt() pour ajouter une telle entrée.

$form->addSelect('country', 'Country:', $countries)
	->setPrompt('Pick a country');

Vous pouvez utiliser setDisabled(['CZ', 'SK']) pour désactiver des éléments individuels.

L'élément vérifie automatiquement qu'il n'y a pas eu de falsification et que l'élément sélectionné est bien l'un de ceux proposés et n'a pas été désactivé. La méthode getRawValue() peut être utilisée pour récupérer l'élément soumis sans cette importante vérification.

Lorsque la valeur par défaut est définie, elle vérifie également qu'il s'agit de l'un des éléments proposés, sinon elle lève une exception. Cette vérification peut être désactivée avec checkDefaultValue(false).

addMultiSelect(string|int $name, $label=null, ?array $items=null, ?int $size=null): MultiSelectBox

Ajoute une boîte de sélection multichoix (classe MultiSelectBox). Renvoie le tableau des clés des éléments sélectionnés. La méthode getSelectedItems() renvoie des valeurs au lieu des clés.

$form->addMultiSelect('countries', 'Countries:', $countries);

Nous passons le tableau d'éléments comme troisième paramètre, ou par la méthode setItems(). Le tableau d'éléments peut également être bidimensionnel.

Vous pouvez utiliser setDisabled(['CZ', 'SK']) pour désactiver des éléments individuels.

L'élément vérifie automatiquement qu'il n'y a pas eu de falsification et que les éléments sélectionnés font bien partie des éléments proposés et n'ont pas été désactivés. La méthode getRawValue() peut être utilisée pour récupérer les éléments proposés sans cette importante vérification.

Lorsque des valeurs par défaut sont définies, la méthode vérifie également qu'il s'agit de l'un des éléments proposés, sinon elle lève une exception. Cette vérification peut être désactivée avec checkDefaultValue(false).

addUpload(string|int $name, $label=null): UploadControl

Ajoute un champ de téléchargement de fichier (classe UploadControl). Renvoie l'objet FileUpload, même si l'utilisateur n'a pas téléchargé de fichier, ce qui peut être découvert par la méthode FileUpload::hasFile().

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Avatar must be JPEG, PNG, GIF or WebP')
	->addRule($form::MaxFileSize, 'Maximum size is 1 MB', 1024 * 1024);

Si le fichier n'a pas été téléchargé correctement, le formulaire n'a pas été soumis avec succès et une erreur est affichée. C'est-à-dire qu'il n'est pas nécessaire de vérifier la méthode FileUpload::isOk().

Ne vous fiez pas au nom de fichier original renvoyé par la méthode FileUpload::getName(), un client pourrait envoyer un nom de fichier malveillant dans le but de corrompre ou de pirater votre application.

Les règles MimeType et Image détectent le type de fichier ou d'image requis par sa signature. L'intégrité de l'ensemble du fichier n'est pas vérifiée. Vous pouvez savoir si une image n'est pas corrompue, par exemple en essayant de la charger.

addMultiUpload(string|int $name, $label=null): UploadControl

Ajoute un champ de téléchargement de fichiers multiples (classe UploadControl). Retourne un tableau d'objets FileUpload. La méthode FileUpload::hasFile() renverra true pour chacun d'entre eux.

$form->addMultiUpload('files', 'Files:')
	->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);

Si l'un des fichiers ne parvient pas à être téléchargé correctement, le formulaire n'a pas été soumis avec succès et une erreur est affichée. C'est-à-dire qu'il n'est pas nécessaire de vérifier la méthode FileUpload::isOk().

Ne vous fiez pas aux noms de fichiers originaux renvoyés par la méthode FileUpload::getName(), un client pourrait envoyer un nom de fichier malveillant dans le but de corrompre ou de pirater votre application.

Les règles MimeType et Image détectent le type de fichier ou d'image requis par sa signature. L'intégrité de l'ensemble du fichier n'est pas vérifiée. Vous pouvez savoir si une image n'est pas corrompue, par exemple en essayant de la charger.

addDate(string|int $name, $label=null): DateTimeControl

Ajoute un champ qui permet à l'utilisateur de saisir facilement une date composée de l'année, du mois et du jour (classe DateTimeControl).

Pour la valeur par défaut, il accepte soit des objets implémentant la classe DateTimeInterface, soit une chaîne de caractères avec l'heure, soit un nombre représentant un horodatage UNIX. Il en va de même pour les arguments Min, Max ou Range, qui définissent la date minimale et maximale autorisée.

$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Par défaut, elle renvoie un objet DateTimeImmutable. La méthode setFormat() permet de spécifier un format texte ou un horodatage :

$form->addDate('date', 'Date:')
	->setFormat('Y-m-d');

addTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Ajoute un champ qui permet à l'utilisateur de saisir facilement l'heure sous forme d'heures, de minutes et éventuellement de secondes (classe DateTimeControl).

Pour la valeur par défaut, il accepte soit des objets implémentant DateTimeInterface, soit une chaîne de caractères avec l'heure, soit un nombre représentant un horodatage UNIX. Seule l'information temporelle de ces entrées est utilisée ; la date est ignorée. Il en va de même pour les arguments Min, Max ou Range, qui définissent la durée minimale et maximale autorisée. Si la valeur minimale définie est supérieure à la valeur maximale, une plage horaire s'étendant jusqu'à minuit est créée.

$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);

Par défaut, elle renvoie un objet DateTimeImmutable (avec la date du 1er janvier de l'année 1). La méthode setFormat() permet de spécifier un format de texte:

$form->addTime('time', 'Time:')
	->setFormat('H:i');

addDateTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Ajoute un champ qui permet à l'utilisateur de saisir facilement la date et l'heure en indiquant l'année, le mois, le jour, les heures, les minutes et, éventuellement, les secondes (classe DateTimeControl).

Pour la valeur par défaut, il accepte soit des objets implémentant la classe DateTimeInterface, soit une chaîne de caractères avec l'heure, soit un nombre représentant un horodatage UNIX. Il en va de même pour les arguments Min, Max ou Range, qui définissent la date minimale et maximale autorisée.

$form->addDateTime('datetime', 'Date and Time:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Par défaut, elle renvoie un objet DateTimeImmutable. La méthode setFormat() permet de spécifier un format texte ou un horodatage :

$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);

addColor(string|int $name, $label=null): ColorPicker

Ajoute un champ de sélection de couleur (classe ColorPicker). La couleur est une chaîne au format #rrggbb. Si l'utilisateur ne fait pas de sélection, la couleur renvoyée par défaut est le noir #000000.

$form->addColor('color', 'Color:')
	->setDefaultValue('#3C8ED7');

addHidden(string|int $name, ?string $default=null): HiddenField

Ajoute un champ caché (classe HiddenField).

$form->addHidden('userid');

Utilisez setNullable() pour le modifier afin qu'il renvoie null au lieu d'une chaîne vide. La fonction addFilter() permet de modifier la valeur soumise.

Bien que l'élément soit caché, il est important de réaliser que sa valeur peut toujours être modifiée ou usurpée par un attaquant. Il faut toujours vérifier et valider soigneusement toutes les valeurs reçues du côté du serveur pour éviter les risques de sécurité liés à la manipulation des données.

addSubmit(string|int $name, $caption=null): SubmitButton

Ajoute un bouton de soumission (classe SubmitButton).

$form->addSubmit('submit', 'Register');

Il est possible d'avoir plus d'un bouton d'envoi dans le formulaire :

$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');

Pour savoir lequel d'entre eux a été cliqué, utilisez :

if ($form['register']->isSubmittedBy()) {
  // ...
}

Si vous ne voulez pas valider le formulaire lorsqu'un bouton d'envoi est pressé (comme les boutons Annulation ou Aperçu), vous pouvez le désactiver avec setValidationScope().

addButton(string|int $name, $caption): Button

Ajoute un bouton (classe Button) sans fonction de soumission. Il est utile pour lier une autre fonctionnalité à l'id, par exemple une action JavaScript.

$form->addButton('raise', 'Raise salary')
	->setHtmlAttribute('onclick', 'raiseSalary()');

addImageButton(string|int $name, ?string $src=null, ?string $alt=null): ImageButton

Ajoute un bouton d'envoi sous la forme d'une image (classe ImageButton).

$form->addImageButton('submit', '/path/to/image');

Lorsque vous utilisez plusieurs boutons d'envoi, vous pouvez savoir lequel a été cliqué avec la commande $form['submit']->isSubmittedBy().

addContainer(string|int $name): Container

Ajoute un sous-formulaire (classe Container), ou un conteneur, qui peut être traité de la même manière qu'un formulaire. Cela signifie que vous pouvez utiliser des méthodes comme setDefaults() ou getValues().

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Your name:');
$sub1->addEmail('email', 'Email:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Your name:');
$sub2->addEmail('email', 'Email:');

Les données envoyées sont ensuite renvoyées sous la forme d'une structure multidimensionnelle :

[
	'first' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
	'second' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
]

Aperçu des paramètres

Pour tous les éléments, nous pouvons appeler les méthodes suivantes (voir la documentation API pour un aperçu complet) :

setDefaultValue($value) définit la valeur par défaut
getValue() obtient la valeur actuelle
setOmitted() valeurs omises
setDisabled() désactiver les entrées

Rendu :

setCaption($caption) changer la légende de l'élément
setTranslator($translator) définit le traducteur
setHtmlAttribute($name, $value) définit l'attribut HTML de l'élément
setHtmlId($id) définit l'attribut HTML id
setHtmlType($type) définit l'attribut HTML type
setHtmlName($name) définit l'attribut HTML name
setOption($key, $value) définit les données de rendu

Validation :

setRequired() champ obligatoire
addRule() règle de validation
addCondition(), addConditionOn() fixer la condition de validation
addError($message) passer le message d'erreur

Les méthodes suivantes peuvent être appelées pour les éléments addText(), addPassword(), addTextArea(), addEmail(), addInteger():

setNullable() détermine si getValue() renvoie null au lieu d'une chaîne vide.
setEmptyValue($value) définit la valeur spéciale qui est traitée comme une chaîne vide
setMaxLength($length) définit le nombre maximum de caractères autorisés
addFilter($filter) modifier les valeurs d'entrée

Valeurs omises

Si la valeur saisie par l'utilisateur ne vous intéresse pas, nous pouvons utiliser setOmitted() pour l'omettre du résultat fourni par la méthode $form->getValues​() ou transmis aux gestionnaires. Cela convient pour divers mots de passe à des fins de vérification, des champs antispam, etc.

$form->addPassword('passwordVerify', 'Password again:')
	->setRequired('Fill your password again to check for typo')
	->addRule($form::Equal, 'Password mismatch', $form['password'])
	->setOmitted();

Désactiver les entrées

Les entrées peuvent être désactivées à l'aide de setDisabled(). Une entrée désactivée ne peut pas être modifiée par l'utilisateur.

$form->addText('username', 'User name:')
	->setDisabled();

Les entrées désactivées ne sont pas envoyées au serveur par le navigateur, et vous ne les trouverez donc pas dans les données renvoyées par la fonction $form->getValues(). Toutefois, si vous définissez setOmitted(false), Nette inclura leur valeur par défaut dans ces données.

Lorsque setDisabled() est appelé, la valeur de l'entrée est effacée pour des raisons de sécurité. Si vous définissez une valeur par défaut, il est nécessaire de le faire après sa désactivation :

$form->addText('username', 'User name:')
	->setDisabled()
	->setDefaultValue($userName);

Une alternative aux entrées désactivées sont les champs avec l'attribut HTML readonly, qui sont envoyés au serveur par le navigateur. Bien que le champ ne soit que lisible, il est important de réaliser que sa valeur peut toujours être modifiée ou usurpée par un attaquant.

Contrôles personnalisés

Outre le large éventail de contrôles de formulaire intégrés, vous pouvez ajouter des contrôles personnalisés au formulaire comme suit :

$form->addComponent(new DateInput('Date:'), 'date');
// syntaxe alternative: $form['date'] = new DateInput('Date:');

Le formulaire est un descendant de la classe Container et les éléments sont des descendants de Component.

Il est possible de définir de nouvelles méthodes de formulaire pour ajouter des éléments personnalisés (par exemple $form->addZip()). Il s'agit des méthodes dites d'extension. L'inconvénient est que les astuces de code dans les éditeurs ne fonctionnent pas pour elles.

use Nette\Forms\Container;

// ajoute la méthode addZip(string $name, ?string $label = null)
Container::extensionMethod('addZip', function (Container $form, string $name, ?string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::Pattern, 'At least 5 numbers', '[0-9]{5}');
});

// utilisation
$form->addZip('zip', 'ZIP code:');

Champs de bas niveau

Pour ajouter un élément au formulaire, il n'est pas nécessaire d'appeler $form->addXyz(). Les éléments de formulaire peuvent être introduits exclusivement dans les modèles. Ceci est utile si vous devez, par exemple, générer des éléments dynamiques :

{foreach $items as $item}
	<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}

Après la soumission, vous pouvez récupérer les valeurs :

$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');

Dans le premier paramètre, vous spécifiez le type d'élément (DataFile pour type=file, DataLine pour les entrées d'une ligne comme text, password ou email et DataText pour le reste). Le deuxième paramètre correspond à l'attribut HTML name. Si vous devez préserver les clés, vous pouvez combiner le premier paramètre avec DataKeys. Ceci est utile pour select, radioList ou checkboxList.

L'adresse getHttpData() renvoie des données d'entrée nettoyées. Dans ce cas, il s'agira toujours d'un tableau de chaînes UTF-8 valides, quel que soit l'attaquant envoyé par le formulaire. C'est une alternative au travail avec $_POST ou $_GET directement si vous voulez recevoir des données sûres.