Champs de formulaire

Aperçu des champs de formulaire standards.

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

Ajoute un champ texte sur une ligne (classe TextInput). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide '' ; utilisez setNullable() pour qu'il renvoie null à la place.

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

Valide automatiquement l'UTF-8, supprime les espaces au début et à la fin, et enlève les sauts de ligne qu'un attaquant pourrait envoyer.

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

Avec setHtmlType(), vous pouvez changer l'apparence visuelle du champ texte en types comme search, tel ou url, tels que définis par la spécification. Rappelez-vous que le changement de type est purement visuel et ne remplace pas la validation. Pour le type url, il est conseillé d'ajouter une règle de validation d'URL.

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

Il est possible de définir une “valeur vide” pour le champ. Elle se comporte un peu comme une valeur par défaut, mais si l'utilisateur ne la change pas, le champ renvoie une chaîne vide ou null.

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

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

Ajoute un champ texte multiligne (classe TextArea). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide '' ; utilisez setNullable() pour qu'il renvoie null à la place.

$form->addTextArea('note', 'Note :')
	->addRule($form::MaxLength, 'Votre note est bien trop longue', 10000);

Valide automatiquement l'UTF-8 et normalise les fins de ligne en \n. Contrairement au champ sur une ligne, aucun espace n'est supprimé aux extrémités.

La longueur maximale peut être limitée avec setMaxLength(). La méthode addFilter() permet de modifier la valeur saisie par l'utilisateur. Une valeur vide peut être définie avec setEmptyValue().

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

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

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

Le champ est rendu sous forme de <input type="number">. À l'aide de 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 texte classique sans le comportement particulier du type number.

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

Ajoute un champ de saisie d'un nombre à virgule flottante (classe TextInput). Renvoie soit un nombre décimal, soit null si l'utilisateur ne saisit rien.

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

Nette et le navigateur Chrome acceptent aussi bien la virgule que le point comme séparateur décimal. Pour que cela fonctionne aussi dans Firefox, il est recommandé de définir l'attribut lang, soit sur le champ concerné, soit sur la page entière, par exemple <html lang="fr">.

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

Ajoute un champ de saisie d'une adresse e-mail (classe TextInput). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide '' ; utilisez setNullable() pour qu'il renvoie null à la place.

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

Vérifie que la valeur est une adresse e-mail valide. Il ne contrôle pas que le domaine existe réellement, seule la syntaxe est vérifiée. Valide automatiquement l'UTF-8 et supprime les espaces au début et à la fin.

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

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

$form->addPassword('password', 'Mot de passe :')
	->setRequired()
	->addRule($form::MinLength, 'Le mot de passe doit comporter au moins %d caractères', 8)
	->addRule($form::Pattern, 'Le mot de passe doit contenir un chiffre', '.*[0-9].*');

Lors du réaffichage du formulaire, le champ sera vide. Valide automatiquement l'UTF-8, supprime les espaces au début et à la fin, et enlève les sauts de ligne qu'un attaquant pourrait envoyer.

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

Ajoute une case à cocher (classe Checkbox). Renvoie true ou false, selon qu'elle est cochée ou non.

$form->addCheckbox('agree', 'J\'accepte les conditions')
	->setRequired('Vous devez accepter nos conditions');

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

Ajoute une liste de cases à cocher permettant de sélectionner plusieurs éléments (classe CheckboxList). Renvoie un tableau des clés des éléments sélectionnés. La méthode getSelectedItems() renvoie les éléments sélectionnés sous forme de paires clé-valeur.

$form->addCheckboxList('colors', 'Couleurs :', [
	'r' => 'rouge',
	'g' => 'vert',
	'b' => 'bleu',
]);

Passez le tableau des éléments proposés en troisième paramètre ou à l'aide de la méthode setItems(). En passant false comme deuxième argument de setItems(), les valeurs servent aussi de clés.

Utilisez setDisabled(['r', 'g']) pour désactiver certains éléments.

Le champ vérifie automatiquement qu'aucune falsification n'a eu lieu et que les éléments sélectionnés font bien partie de ceux proposés et n'ont pas été désactivés. La méthode getRawValue() permet d'obtenir les éléments soumis sans cette vérification importante.

Lors de la définition des éléments sélectionnés par défaut, il vérifie aussi qu'ils font partie de ceux proposés, sinon il lève une exception. Cette vérification peut être désactivée avec checkDefaultValue(false).

Si vous envoyez le formulaire par la méthode GET, vous pouvez choisir une transmission des données plus compacte, qui économise la taille de la query string. Activez-la en définissant un attribut HTML sur le formulaire :

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

addRadioList (string $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 la valeur au lieu de la clé.

$sex = [
	'm' => 'homme',
	'f' => 'femme',
	'o' => 'autre',
];
$form->addRadioList('gender', 'Genre :', $sex);

Passez le tableau des éléments proposés en troisième paramètre ou à l'aide de la méthode setItems().

Utilisez setDisabled(['m']) pour désactiver certains éléments.

Le champ vérifie automatiquement qu'aucune falsification n'a eu lieu et que l'élément sélectionné fait bien partie de ceux proposés et n'a pas été désactivé. La méthode getRawValue() permet d'obtenir l'élément soumis sans cette vérification importante.

Lors de la définition de l'élément sélectionné par défaut, il vérifie aussi qu'il fait partie de ceux proposés, sinon il lève une exception. Cette vérification peut être désactivée avec checkDefaultValue(false).

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

Ajoute une liste déroulante (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 la valeur au lieu de la clé.

$countries = [
	'CZ' => 'République tchèque',
	'SK' => 'Slovaquie',
	'GB' => 'Royaume-Uni',
];

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

Passez le tableau des éléments proposés en troisième paramètre ou à l'aide de la méthode setItems(). Les éléments peuvent aussi former un tableau à deux dimensions (représentant des optgroups) :

$countries = [
	'Europe' => [
		'CZ' => 'République tchèque',
		'SK' => 'Slovaquie',
		'GB' => 'Royaume-Uni',
	],
	'CA' => 'Canada',
	'US' => 'États-Unis',
	'?'  => 'autre',
];

Dans les listes déroulantes, le premier élément a souvent une signification particulière et sert d'invitation à agir. Utilisez la méthode setPrompt() pour ajouter un tel élément.

$form->addSelect('country', 'Pays :', $countries)
	->setPrompt('Choisissez un pays');

Utilisez setDisabled(['CZ', 'SK']) pour désactiver certains éléments.

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

Ajoute une liste déroulante permettant de sélectionner plusieurs éléments (classe MultiSelectBox). Renvoie un tableau des clés des éléments sélectionnés. La méthode getSelectedItems() renvoie les éléments sélectionnés sous forme de paires clé-valeur.

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

Passez le tableau des éléments proposés en troisième paramètre ou à l'aide de la méthode setItems(). Les éléments peuvent aussi former un tableau à deux dimensions.

Utilisez setDisabled(['CZ', 'SK']) pour désactiver certains éléments.

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

Ajoute un champ d'upload de fichier (classe UploadControl). Renvoie un objet FileUpload, même si l'utilisateur n'a envoyé aucun fichier, ce que l'on peut vérifier avec la méthode FileUpload::hasFile(). Avec setNullable(), vous pouvez faire en sorte que le champ renvoie null au lieu d'un objet FileUpload lorsque aucun fichier n'est envoyé.

$form->addUpload('avatar', 'Avatar :')
	->addRule($form::Image, 'L\'avatar doit être au format JPEG, PNG, GIF, WebP ou AVIF.')
	->addRule($form::MaxFileSize, 'La taille maximale est de 1 Mo.', 1024 * 1024);

Si le fichier n'a pas pu être envoyé correctement, le formulaire n'est pas soumis avec succès et une erreur est affichée. Autrement dit, en cas de soumission réussie, il n'est pas nécessaire de vérifier la méthode FileUpload::isOk().

Ne faites jamais confiance au nom de fichier d'origine renvoyé par la méthode FileUpload::getName() ; le client a pu envoyer un nom de fichier malveillant dans l'intention d'endommager ou de pirater votre application.

Les règles MimeType et Image détectent le type requis d'après la signature du fichier et ne vérifient pas son intégrité. Vous pouvez déterminer si une image est endommagée, par exemple, en essayant de la charger.

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

Ajoute un champ permettant d'envoyer plusieurs fichiers à la fois (classe UploadControl). Renvoie un tableau d'objets FileUpload. La méthode FileUpload::hasFile() renverra true pour chacun d'eux.

$form->addMultiUpload('files', 'Fichiers :')
	->addRule($form::MaxLength, 'Vous ne pouvez envoyer que %d fichiers au maximum.', 10);

Si l'un des fichiers n'a pas pu être envoyé correctement, le formulaire n'est pas soumis avec succès et une erreur est affichée. Autrement dit, en cas de soumission réussie, il n'est pas nécessaire de vérifier la méthode FileUpload::isOk() pour chaque fichier.

Ne faites jamais confiance aux noms de fichiers d'origine renvoyés par la méthode FileUpload::getName() ; le client a pu envoyer des noms de fichiers malveillants dans l'intention d'endommager ou de pirater votre application.

addDate (string $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).

Comme valeur par défaut, il accepte des objets implémentant DateTimeInterface, une chaîne contenant une heure, ou un nombre représentant un timestamp UNIX. Il en va de même pour les arguments des règles Min, Max ou Range, qui définissent les dates minimale et maximale autorisées.

$form->addDate('date', 'Date :')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'La date doit être vieille d\'au moins un mois.', new DateTime('-1 month'));

Par défaut, il renvoie un objet DateTimeImmutable. À l'aide de la méthode setFormat(), vous pouvez indiquer un format texte ou un timestamp :

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

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

Ajoute un champ qui permet à l'utilisateur de saisir facilement une heure composée des heures, des minutes et, éventuellement, des secondes (classe DateTimeControl).

Comme valeur par défaut, il accepte des objets implémentant DateTimeInterface, une chaîne contenant une heure, ou un nombre représentant un timestamp UNIX. Seule l'information horaire de ces entrées est utilisée, la date est ignorée. Il en va de même pour les arguments des règles Min, Max ou Range, qui définissent les heures minimale et maximale autorisées. Si la valeur minimale définie est supérieure à la maximale, une plage horaire à cheval sur minuit est créée.

$form->addTime('time', 'Heure :', withSeconds: true)
	->addRule($form::Range, 'L\'heure doit être comprise entre %d et %d.', ['12:30', '13:30']);

Par défaut, il renvoie un objet DateTimeImmutable (avec la date fixée au 1er janvier de l'an 1). À l'aide de la méthode setFormat(), vous pouvez indiquer un format texte :

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

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

Ajoute un champ qui permet à l'utilisateur de saisir facilement à la fois la date et l'heure, composées de l'année, du mois, du jour, des heures, des minutes et, éventuellement, des secondes (classe DateTimeControl).

$form->addDateTime('datetime', 'Date et heure :')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'La date doit être vieille d\'au moins un mois.', new DateTime('-1 month'));

Par défaut, il renvoie un objet DateTimeImmutable. À l'aide de la méthode setFormat(), vous pouvez indiquer un format texte ou un timestamp :

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

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

Ajoute un champ de sélection de couleur (classe ColorPicker). La couleur est renvoyée sous forme de chaîne au format #rrggbb. Si l'utilisateur ne fait aucun choix, il renvoie le noir #000000.

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

addHidden (string $name, mixed $default=null): HiddenField

Ajoute un champ caché (classe HiddenField).

$form->addHidden('userid');

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

Bien que le champ soit caché, il est important de comprendre que sa valeur peut malgré tout être modifiée ou falsifiée par un attaquant. Vérifiez et validez toujours soigneusement toutes les valeurs reçues côté serveur afin d'éviter les risques de sécurité liés à la manipulation des données.

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

Ajoute un bouton d'envoi (classe SubmitButton).

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

Le gestionnaire peut être passé directement au bouton comme troisième paramètre $onSubmit, au lieu de l'accrocher à l'événement onClick :

$form->addSubmit('submit', 'Envoyer', function (SubmitButton $button, $data): void {
	// ...
});

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

$form->addSubmit('register', 'S\'inscrire');
$form->addSubmit('cancel', 'Annuler');

Pour savoir lequel a été cliqué, utilisez :

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

Si vous ne voulez pas valider tout le formulaire lors de l'appui sur un bouton (par exemple pour les boutons Annuler ou Aperçu), utilisez setValidationScope().

addButton (string $name, $caption=null): Button

Ajoute un bouton (classe Button) qui n'a pas de fonction d'envoi. Il peut donc servir à d'autres fonctions, par exemple appeler une fonction JavaScript au clic.

$form->addButton('raise', 'Augmenter le salaire')
	->setHtmlAttribute('onclick', 'raiseSalary()');

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

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

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

Avec plusieurs boutons d'envoi, vous pouvez savoir lequel a été cliqué à l'aide de $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Ajoute un sous-formulaire (classe Container), autrement dit un conteneur, auquel d'autres champs peuvent être ajoutés de la même façon qu'au formulaire. Les méthodes comme setDefaults() ou getValues() fonctionnent également.

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Votre nom :');
$sub1->addEmail('email', 'E-mail :');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Votre nom :');
$sub2->addEmail('email', 'E-mail :');

Les données soumises sont alors renvoyées sous forme de structure multidimensionnelle :

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

Aperçu des réglages

Pour tous les champs, nous pouvons appeler les méthodes suivantes (voir la documentation de l'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 des champs

Rendu :

`setCaption($caption)`	change le label du champ
`setTranslator($translator)`	définit le traducteur
`setHtmlAttribute($name, $value)`	définit un attribut HTML de l'élément
`setHtmlId($id)`	définit l'attribut HTML `id`
`setOption($key, $value)`	définit les options de rendu

Validation :

`setRequired()`	rend le champ obligatoire
`addRule()`	ajoute une règle de validation
`addCondition()`, `addConditionOn()`	définit une condition de validation
`addError($message)`	ajoute un message d'erreur

Pour les champs addText(), addPassword(), addTextArea(), addEmail(), addInteger(), addFloat(), les méthodes suivantes peuvent être appelées :

`setNullable()`	définit si getValue() renvoie `null` au lieu d'une chaîne vide
`setEmptyValue($value)`	définit une valeur spéciale considérée comme une chaîne vide
`setMaxLength($length)`	définit le nombre maximal de caractères autorisé
`addFilter($filter)`	modifie la saisie

Valeurs omises

Si la valeur saisie par l'utilisateur ne nous intéresse pas, nous pouvons l'exclure du résultat de la méthode $form->getValues() ou des données passées aux gestionnaires à l'aide de setOmitted(). C'est utile pour les différents champs de confirmation de mot de passe, les champs anti-spam, etc.

$form->addPassword('passwordVerify', 'Mot de passe à nouveau :')
	->setRequired('Saisissez à nouveau votre mot de passe pour détecter une faute de frappe')
	->addRule($form::Equal, 'Les mots de passe ne correspondent pas', $form['password'])
	->setOmitted();

Désactiver des champs

Les champs peuvent être désactivés à l'aide de setDisabled(). Un champ désactivé ne peut pas être modifié par l'utilisateur.

$form->addText('username', 'Nom d\'utilisateur :')
	->setDisabled();

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

Lors de l'appel de setDisabled(), la valeur du champ est effacée pour des raisons de sécurité. Si vous définissez une valeur par défaut, il faut donc le faire après l'avoir désactivé :

$form->addText('username', 'Nom d\'utilisateur :')
	->setDisabled()
	->setDefaultValue($userName);

Une alternative aux champs désactivés est celle des champs portant l'attribut HTML readonly, que le navigateur envoie bien au serveur. Bien que le champ soit en lecture seule, il est important de comprendre que sa valeur peut malgré tout être modifiée ou falsifiée par un attaquant.

Champs personnalisés

Outre la large palette de champs de formulaire intégrés, vous pouvez ajouter au formulaire des champs personnalisés :

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

La façon d'écrire un tel champ, y compris la lecture des données soumises, la validation et le rendu, est décrite dans un chapitre distinct. Vous y découvrirez aussi les méthodes d'extension, qui vous permettent de créer votre propre méthode d'ajout comme $form->addZip().

Champs de bas niveau

Il est aussi possible d'utiliser des champs qui ne sont écrits que dans le template et ne sont ajoutés au formulaire par aucune des méthodes $form->addXyz(). Par exemple, quand nous listons des enregistrements d'une base de données dont nous ne connaissons à l'avance ni le nombre ni les identifiants, et que nous voulons afficher une case à cocher ou un bouton radio pour chaque ligne, il suffit de le coder dans le template :

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

Et après la soumission, nous récupérons la valeur :

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

où le premier paramètre est le type de l'élément (DataFile pour type=file, DataLine pour les champs sur une ligne comme text, password, email, etc., et DataText pour tous les autres) et le deuxième paramètre sel[] correspond à l'attribut HTML name. Nous pouvons combiner le type de l'élément avec la valeur DataKeys, qui conserve les clés des éléments. C'est particulièrement utile pour select, radioList et checkboxList.

Point essentiel : getHttpData() renvoie une valeur assainie. Dans ce cas, ce sera toujours un tableau de chaînes UTF-8 valides, quoi qu'un attaquant essaie d'envoyer au serveur. C'est analogue au travail direct avec $_POST ou $_GET, à la différence majeure qu'il renvoie toujours des données propres, comme vous en avez l'habitude avec les champs de formulaire standards de Nette.