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.
Utilisez setHtmlType()
pour changer le caractère de l'élément d'entrée en
search
, tel
, url
, range
, date
, datetime-local
,
month
, time
, week
, color
. Au lieu des types number
et
email
, nous vous recommandons d'utiliser addInteger et addEmail, qui fournissent 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('level', 'Level:')
->setDefaultValue(0)
->addRule($form::Range, 'Level must be between %d and %d.', [0, 100]);
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.
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): 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.
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): 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.
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.
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
Pour désactiver une entrée, vous pouvez appeler setDisabled()
. Un tel champ ne peut pas être modifié par
l'utilisateur.
$form->addText('username', 'User name:')
->setDisabled();
Notez que le navigateur n'envoie pas du tout les champs désactivés au serveur, de sorte que vous ne les trouverez même pas
dans les données renvoyées par la fonction $form->getValues()
.
Si vous définissez une valeur par défaut pour un champ, vous devez le faire uniquement après l'avoir désactivé :
$form->addText('username', 'User name:')
->setDisabled()
->setDefaultValue($userName);
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.