Éléments de formulaire

Aperçu des éléments de formulaire standard.

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

Ajoute un champ de texte sur une seule ligne (classe TextInput). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide '', ou setNullable() peut être utilisé pour spécifier qu'il renvoie null.

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

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

La longueur maximale peut être limitée à l'aide de setMaxLength(). La modification de la valeur saisie par l'utilisateur est possible avec addFilter().

Avec setHtmlType(), le caractère visuel du champ de texte peut être modifié en types tels que search, tel ou url, voir la spécification. N'oubliez pas que le changement de type est purement visuel et ne remplace pas la fonction de validation. Pour le type url, il est conseillé d'ajouter une règle de validation URL spécifique.

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

Une valeur vide (empty-value) peut être définie pour l'élément, ce qui est similaire à une valeur par défaut, mais si l'utilisateur ne la modifie pas, l'élément renvoie une chaîne vide ou null.

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

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

Ajoute un champ pour la saisie de texte multiligne (classe TextArea). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide '', ou setNullable() peut être utilisé pour spécifier qu'il renvoie null.

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

Valide automatiquement l'UTF-8 et normalise les séparateurs de ligne en \n. Contrairement au champ de saisie sur une seule ligne, aucun découpage des espaces n'est effectué.

La longueur maximale peut être limitée à l'aide de setMaxLength(). La modification de la valeur saisie par l'utilisateur est possible avec addFilter(). Une valeur vide peut être définie à l'aide de setEmptyValue().

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

Ajoute un champ pour la 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]);

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

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

Ajoute un champ pour la saisie d'un nombre décimal (classe TextInput). Renvoie soit un float, 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 à la fois la virgule et le point comme séparateurs décimaux. Pour que cette fonctionnalité soit également disponible dans Firefox, il est recommandé de définir l'attribut lang soit pour l'élément concerné, soit pour la page entière, par exemple <html lang="fr">.

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

Ajoute un champ pour la saisie d'une adresse e-mail (classe TextInput). Si l'utilisateur ne remplit pas le champ, il renvoie une chaîne vide '', ou setNullable() peut être utilisé pour spécifier qu'il renvoie null.

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

Vérifie si la valeur est une adresse e-mail valide. Ne vérifie pas si le domaine existe réellement, vérifie uniquement la syntaxe. Valide automatiquement l'UTF-8, supprime les espaces de début et de fin.

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

Ajoute un champ pour la saisie d'un 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, 'Doit contenir un chiffre', '.*[0-9].*');

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

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

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

$form->addCheckbox('agree', 'J\'accepte les conditions')
	->setRequired('Il est nécessaire d\'accepter les conditions');

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

Ajoute des cases à cocher pour 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 valeurs au lieu des clés.

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

Le tableau des éléments proposés est passé comme troisième paramètre ou via la méthode setItems().

Avec setDisabled(['r', 'g']), il est possible de 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 de ceux proposés et n'ont pas été désactivés. La méthode getRawValue() permet d'obtenir les éléments envoyés sans ce contrôle important.

Lors de la définition des éléments sélectionnés par défaut, il vérifie également qu'il s'agit bien de l'un des éléments proposés, sinon il lève une exception. Ce contrôle peut être désactivé avec checkDefaultValue(false).

Si vous soumettez le formulaire avec la méthode GET, vous pouvez choisir un mode de transmission des données plus compact, ce qui économise la taille de la chaîne de requête. Il est activé 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 la valeur au lieu de la clé.

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

Le tableau des éléments proposés est passé comme troisième paramètre ou via la méthode setItems().

Avec setDisabled(['m', 'f']), il est possible de 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é fait bien partie de ceux proposés et n'a pas été désactivé. La méthode getRawValue() permet d'obtenir l'élément envoyé sans ce contrôle important.

Lors de la définition de l'élément sélectionné par défaut, il vérifie également qu'il s'agit bien de l'un des éléments proposés, sinon il lève une exception. Ce contrôle peut être désactivé 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 la valeur au lieu de la clé.

$countries = [
	'FR' => 'France',
	'BE' => 'Belgique',
	'CH' => 'Suisse',
];

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

Le tableau des éléments proposés est passé comme troisième paramètre ou via la méthode setItems(). Les éléments peuvent également être un tableau à deux dimensions :

$countries = [
	'Europe' => [
		'FR' => 'France',
		'BE' => 'Belgique',
		'CH' => 'Suisse',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'autre',
];

Pour les boîtes de sélection, le premier élément a souvent une signification spéciale, servant d'invite à l'action. La méthode setPrompt() est utilisée pour ajouter un tel élément.

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

Avec setDisabled(['FR', 'BE']), il est possible de désactiver des éléments individuels.

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

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

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

Le tableau des éléments proposés est passé comme troisième paramètre ou via la méthode setItems(). Les éléments peuvent également être un tableau à deux dimensions.

Avec setDisabled(['FR', 'BE']), il est possible de désactiver des éléments individuels.

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

Ajoute un champ pour le téléchargement de fichier (classe UploadControl). Renvoie un objet FileUpload, même si l'utilisateur n'a envoyé aucun fichier, ce qui peut être vérifié avec la méthode FileUpload::hasFile().

$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 ne parvient pas à être téléchargé correctement, le formulaire n'est pas soumis avec succès et une erreur s'affiche. C'est-à-dire qu'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 original renvoyé par la méthode FileUpload::getName(), le client pourrait avoir envoyé un nom de fichier malveillant dans le but d'endommager ou de pirater votre application.

Les règles MimeType et Image détectent le type requis en fonction de la signature du fichier et ne vérifient pas son intégrité. Pour savoir si une image n'est pas endommagée, on peut par exemple essayer de la charger.

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

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

$form->addMultiUpload('files', 'Fichiers :')
	->addRule($form::MaxLength, 'Vous pouvez télécharger au maximum %d fichiers', 10);

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

Ne faites jamais confiance aux noms de fichiers originaux renvoyés par la méthode FileUpload::getName(), le client pourrait avoir envoyé un nom de fichier malveillant dans le but d'endommager 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).

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

Par défaut, il renvoie un objet DateTimeImmutable, avec la méthode setFormat(), vous pouvez spécifier un format texte ou un timestamp :

$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 une heure composée des heures, des minutes et éventuellement des secondes (classe DateTimeControl).

Comme valeur par défaut, il accepte soit des objets implémentant l'interface DateTimeInterface, une chaîne de caractères avec l'heure, ou un nombre représentant un timestamp UNIX. De ces entrées, seule l'information temporelle 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 l'heure minimale et maximale autorisée. Si la valeur minimale définie est supérieure à la valeur maximale, une plage horaire dépassant 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 du 1er janvier de l'an 1), avec la méthode setFormat(), vous pouvez spécifier un format texte :

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

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

Ajoute un champ qui permet à l'utilisateur de saisir facilement une date et une 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 dater d\'au moins un mois.', new DateTime('-1 month'));

Par défaut, il renvoie un objet DateTimeImmutable, avec la méthode setFormat(), vous pouvez spécifier un format texte ou un timestamp :

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

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

Ajoute un champ pour choisir une couleur (classe ColorPicker). La couleur est une chaîne de caractères au format #rrggbb. Si l'utilisateur ne fait pas de choix, la couleur noire #000000 est renvoyée.

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

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

Ajoute un champ caché (classe HiddenField).

$form->addHidden('userid');

Avec setNullable(), il est possible de définir qu'il renvoie null au lieu d'une chaîne vide. La modification de la valeur envoyée est possible avec addFilter().

Bien que l'élément soit caché, il est important de noter que la valeur peut toujours être modifiée ou falsifiée par un attaquant. Vérifiez et validez toujours soigneusement toutes les valeurs reçues côté serveur pour prévenir 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', 'Envoyer');

Il est possible d'avoir plusieurs boutons de soumission dans un formulaire :

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

Pour savoir sur lequel on a cliqué, utilisez :

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

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

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

Ajoute un bouton (classe Button) qui n'a pas de fonction de soumission. Il peut donc être utilisé pour une autre fonction, par exemple appeler une fonction JavaScript lors d'un clic.

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

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

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

$form->addImageButton('submit', '/chemin/vers/image');

En utilisant plusieurs boutons de soumission, on peut savoir sur lequel on a cliqué à l'aide de $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Ajoute un sous-formulaire (classe Container), ou conteneur, auquel on peut ajouter d'autres éléments de la même manière qu'on les ajoute au formulaire. Les méthodes setDefaults() ou getValues() fonctionnent également.

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

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

Les données envoyées sont alors renvoyées sous forme de 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 (aperçu complet dans la documentation API) :

`setDefaultValue($value)`	définit la valeur par défaut
`getValue()`	obtient la valeur actuelle
`setOmitted()`	omission de valeur
`setDisabled()`	désactivation des éléments

Rendu :

`setCaption($caption)`	modifie l'étiquette 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)`	options de rendu

Validation :

`setRequired()`	élément requis
`addRule()`	définit une règle de validation
`addCondition()`, `addConditionOn()`	définit une condition de validation
`addError($message)`	transmission du message d'erreur

Pour les éléments addText(), addPassword(), addTextArea(), addEmail(), addInteger(), 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és
`addFilter($filter)`	modification de l'entrée

Omission de valeur

Si la valeur remplie par l'utilisateur ne nous intéresse pas, nous pouvons l'omettre du résultat de la méthode $form->getValues() ou des données transmises aux handlers à l'aide de setOmitted(). Ceci est utile pour divers mots de passe de contrôle, éléments anti-spam, etc.

$form->addPassword('passwordVerify', 'Mot de passe pour vérification :')
	->setRequired('Veuillez saisir à nouveau le mot de passe pour vérification')
	->addRule($form::Equal, 'Les mots de passe ne correspondent pas', $form['password'])
	->setOmitted();

Désactivation des éléments

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

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

Les éléments 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(). Cependant, si vous définissez setOmitted(false), Nette inclura leur valeur par défaut dans ces données.

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

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

Une alternative aux éléments désactivés sont les éléments avec l'attribut HTML readonly, que le navigateur envoie au serveur. Bien que l'élément soit en lecture seule, il est important de noter que sa valeur peut toujours être modifiée ou falsifiée par un attaquant.

Éléments personnalisés

En plus de la large gamme d'éléments de formulaire intégrés, vous pouvez ajouter vos propres éléments personnalisés au formulaire de cette manière :

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

Le formulaire est un enfant de la classe Container et les éléments individuels sont des enfants de Component.

Il existe une manière de définir de nouvelles méthodes de formulaire servant à ajouter des éléments personnalisés (par ex. $form->addZip()). Il s'agit de ce qu'on appelle les méthodes d'extension. L'inconvénient est que l'autocomplétion dans les éditeurs ne fonctionnera pas pour elles.

use Nette\Forms\Container;

// ajoutons 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, 'Au moins 5 chiffres', '[0-9]{5}');
});

// utilisation
$form->addZip('zip', 'Code postal :');

Éléments de bas niveau

Il est également possible d'utiliser des éléments que nous écrivons uniquement dans le template et que nous n'ajoutons pas au formulaire avec l'une des méthodes $form->addXyz(). Par exemple, lorsque nous affichons des enregistrements d'une base de données et que nous ne savons pas à l'avance combien il y en aura ni quels seront leurs ID, 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 soumission, nous obtenons la valeur :

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

où le premier paramètre est le type d'élément (DataFile pour type=file, DataLine pour les entrées sur une seule 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 d'élément avec la valeur DataKeys, qui préserve les clés des éléments. Ceci est particulièrement utile pour select, radioList et checkboxList.

L'essentiel est que getHttpData() renvoie une valeur assainie, dans ce cas, ce sera toujours un tableau de chaînes UTF-8 valides, quoi que l'attaquant ait tenté de soumettre au serveur. C'est analogue au travail direct avec $_POST ou $_GET, mais avec la différence essentielle qu'il renvoie toujours des données propres, comme vous en avez l'habitude avec les éléments standard des formulaires Nette.