Contrôles de formulaires

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

addText(string|int $name, $label=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.

En utilisant setHtmlType(), vous pouvez changer le caractère de l'élément d'entrée en search, tel, url, range, month, week, ou color. Pour d'autres types comme number, email, date, datetime-local, et time, il existe des méthodes distinctes addInteger, addFloat, addEmail, addDate, addTime, et addDateTime, qui s'accompagnent d'une validation côté serveur.

$form->addText('color', 'Choose color:')
	->setHtmlType('color')
	->addRule($form::Pattern, 'invalid value', '[0-9a-f]{6}');

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]) ;

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]) ;

Nette et Chrome acceptent à la fois la virgule et le point comme séparateur décimal. Pour que Firefox accepte également la virgule, vous devez définir la langue correspondante dans l'attribut HTML lang, soit directement dans cet élément, soit dans un élément parent, par exemple <html lang="cs">.

addEmail(string|int $name, $label=null): 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.

addPassword(string|int $name, $label=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).

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): 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.

addMultiSelect(string|int $name, $label=null, array $items=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.

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.

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).

$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.