Champs de formulaires

From Joomla! Documentation

This page is a translated version of the page Form field and the translation is 90% complete.

Other languages:
العربية • ‎English • ‎español • ‎français • ‎Bahasa Indonesia • ‎Nederlands

Introduction

Les champs de formulaire sont des champs contenus dans des balises HTML <form>. La version Joomla! Joomla 2.5 et les plus récentes, proposent une classe JForm permettant de créer facilement et avec beaucoup de flexibilité des formulaires avec un très nombreux choix de types de champs. Chaque type de champ de formulaire est une sous-classe de JFormField.

En plus d'être un outil à la création de page flexible, JFormFields sont également utilisés par Joomla! pour permettre aux administrateurs de configurer Joomla! ou ses extensions sans avoir à changer le code sous-jacent. Avec Joomla! 1.5, cela était réalisé via les classes désormais obsolètes JParameter et JElement.

Pour définir les champs de formulaire dans la configuration d'une extension, vous devez les inclure dans un "fieldset" tel que <fieldset name="basic">, placé à l'intérieur de <fields name="params"> de la section élément <config> dans votre fichier manifest XML.


Validation de formulaires

Joomla! propose des possibilité de validation de formulaire côté client et côté serveur.
La validation côté serveur est un minimum puisque tout ce qui se situe en amont de cela peut être remplacée côté utilisateur. Mais le côté client est le plus convivial, donc utiliser les deux n'est pas une mauvaise idée (surtout depuis que ce dernier est non intrusif et ne générera pas de problèmes sur des navigateurs ou JavaScript est désactivé).

Validation côté client

La validation coté client se fait via javascript lorsque l'utilisateur complète les champs du formulaire.
Les classes HTML required et validate-[xxx] ([xxx] étant une règle Joomla! ou une règle personnalisée ; par exemple : validate-numeric) sont utilisées.

Informations complémentaires : Validation de formulaire côté client

Validation côté serveur

La validation côté serveur se fait après avoir soumis le formulaire et retournera normalement au formulaire en cas de non validation, avec des messages complémentaires.
Les attributs HTML required ("true" ou "required") et validate (avec comme valeur une règle Joomla! ou une règle personnalisée ; par exemple : validate="email") sont utilisés.

Informations complémentaires : Validation de formulaire côté serveur


Types de champs pour formulaires standards

De nombreux types de champs de formulaires sont disponibles dans Joomla. Le tableau ci-dessous dresse la liste de ces types standards ainsi que leur disponibilité. Veuillez utiliser la page de références si vous souhaitez imprimer la documentation sur l'ensemble des champs de formulaires existants.

Pour les versions Joomla 1.5. Veuillez noter que plusieurs de ces champs sont disponibles en tant que types de paramètres pour Joomla! 1.5. Pour une liste des types de paramètres, veuillez consulter les types de paramètres standards pour Joomla! 1.5. Pour une comparaison entre les champs et les types de paramètres, veuillez consulter les champs de formulaires standards et les types de paramètres.

Type Description Disponibilité
accesslevel fournit une liste déroulante de visualisation des niveaux d'accès. Joomla 2.5 et suivant
cachehandler fournit une liste d'options de mise en cache disponibles. Joomla 2.5 et suivant
calendar fournit une zone de texte pour la saisie d'une date. Une icône à côté de la zone de texte fournit un lien vers un calendrier en fenêtre modale, qui peut également être utilisé pour entrer la valeur de la date. Joomla 2.5 et suivant
captcha Permet l'utilisation d'un plugin captcha. Joomla 2.5 et suivant
category fournit une liste déroulante des catégories pour une extension. Joomla 2.5 et suivant
checkbox fournit une case simple à cocher ou décocher. Joomla 2.5 et suivant
checkboxes fournit un nombre illimité de cases à cocher qui peuvent être utilisées pour les multi-sélections. Joomla 2.5 et suivant
Chrome Style fournit une liste des templates avec options de style chrome regroupés par templates. Joomla 3.0 et suivant
color fournit un sélecteur de couleur en cliquant dans la zone de saisie. Joomla 2.5 et suivant
Content Language fournit une liste des langues de contenu. Joomla 2.5 et suivant
Content Type fournit une liste des types de contenu. Joomla 3.1 et suivant
combo fournit une un ensemble de champs cases. Joomla 2.5 et suivant
componentlayout fournit une liste regroupant des templates et d'affichages natifs alternatifs pour un élément de composant. Joomla 2.5 et suivant
contentlanguage fournit une liste de langues de contenu installées pour une utilisation avec le plugin de sélection des langues. Joomla 2.5 et suivant
Database Connection fournit une liste de connexions à la base de données disponible, éventuellement en limitant à une liste donnée. Joomla 2.5 et suivant
editor fournit un champ de zone de texte pour l'éditeur. Joomla 1.6 et suivant
editors fournit une liste déroulante des éditeurs WYSIWYG disponibles. Depuis la version Joomla 2.5, il convient d'utiliser à la place les plugins de types de champs de formulaire. Joomla 1.6
email fournit un champ de courriel. Joomla 2.5 et suivant
file fournit un champ de saisie pour les fichiers. Joomla 2.5 et suivant
filelist fournit une liste déroulante de fichiers d'un répertoire spécifié. Joomla 2.5 et suivant
folderlist fournit une liste déroulante des dossiers d'un répertoire spécifié. Joomla 2.5 et suivant
groupedlist fournit une liste déroulante d'éléments organisés en groupes. Joomla 2.5 et suivant
header tag fournit une liste déroulante des balises de titre (h1-h6). Joomla 3.0 et suivant
helpsite fournit une liste déroulante des sites d'aide pour votre installation Joomla. Joomla 2.5 et suivant
hidden fournit un champ caché pour l'enregistrement d'un champ de formulaire dont la valeur ne peut pas être modifiée directement par un utilisateur dans l'administration (elle peut être modifiée dans le code ou par modification du fichier "params.ini"). Joomla 2.5 et suivant
imagelist fournit une liste déroulante de fichiers image d'un répertoire spécifié. Joomla 2.5 et suivant
integer fournit une liste déroulante d'entiers compris entre un minimum et un maximum. Joomla 2.5 et suivant
language fournit une liste déroulante des langues installées pour le frontend ou le backend. Joomla 2.5 et suivant
list fournit une liste déroulante d'entrées personnalisées. Joomla 2.5 et suivant
media fournit un accès en modal au gestionnaire de médias pour l'insertion d'images avec chargement par les utilisateurs disposant des autorisations appropriées. Joomla 2.5 et suivant
menu fournit une liste déroulante des menus disponibles à partir de votre site Joomla. Joomla 2.5 et suivant
Menu Item fournit une liste déroulante des éléments de menu disponibles à partir de votre site Joomla. Joomla 2.5 et suivant
meter fournit un compteur pour afficher la valeur dans une plage. Joomla 3.2 et suivant
Module Layout fournit une liste d'affichages alternatifs pour un groupe de modules natifs et de templates. Joomla 2.5 et suivant
Module Order fournit une liste déroulante pour définir les modules d'une position donnée. Joomla 2.5 et suivant
Module Position fournit une zone de texte pour définir la position d'un module. Joomla 2.5 et suivant
Module Tag fournit une liste des éléments HTML5 (utilisé pour l'intégration de module dans une fenêtre). Joomla 3.0 et suivant
note fournit un champ texte d'une ligne. Joomla 3.1 et suivant
number fournit une zone de texte d'une ligne avec un champ déroulant de chiffres pour définir le champ. Joomla 3.2 et suivant
password fournit une zone de texte pour la saisie d'un mot de passe. Les caractères du mot de passe seront masqués lors de la saisie. Joomla 2.5 et suivant
plugins fournit une liste de plugins à partir d'un dossier donné. Joomla 2.5 et suivant
predefinedlist Champ de formulaire pour charger une liste de valeurs prédéfinies. Joomla 3.2 et suivant
radio fournit des boutons radio pour sélectionner différentes options. Joomla 2.5 et suivant
range fournit une barre de défilement horizontale pour spécifier une valeur dans une plage donnée. Joomla 3.2 et suivant
repeatable autorise les champs de formulaire proposant autant d'options que souhaitées par l'utilisateur. Joomla 3.2 et suivant
rules fournit une matrice de groupe par options d'action pour la gestion des contrôles d'accès. L'affichage dépend du contexte. Joomla 2.5 et suivant
sessionhandler fournit une liste déroulante de gestionnaire des options de session. Joomla 2.5 et suivant
spacer fournit un séparateur visible entre les champs de formulaire. Ceci est simplement une aide visuelle et aucune valeur n'est enregistrée. Joomla 2.5 et suivant
sql fournit une liste déroulante des entrées obtenues par l'exécution d'une requête dans la base de données Joomla. La première colonne de résultats retournée par la requête fournit les valeurs de la liste déroulante. Joomla 2.5 et suivant
subform Permet l'utilisation des formulaires XML à l’intérieur les uns des autres ou de réutiliser vos formulaires existants à l’intérieur de vos propres formulaires. Joomla 3.6 et suivant
tag fournit un point d'entrée pour les balises (AJAX ou imbriquées). Joomla 3.1 et suivant
tel fournit un champ de saisie pour numéro de téléphone. Joomla 2.5 et suivant
templatestyle fournit une liste déroulante des styles de templates. Joomla 2.5 et suivant
text fournit une zone de texte pour la saisie des données. Joomla 2.5 et suivant
textarea fournit une zone de texte pour la saisie de texte en multi-ligne. Joomla 2.5 et suivant
timezone fournit une liste déroulante des fuseaux horaires. Joomla 2.5 et suivant
URL fournit un champ de saisie d'URL. Joomla 2.5 et suivant
user Champ pour sélectionner un utilisateur à partir d'une liste modale. Affiche le nom d'utilisateur et stocke l'ID d'utilisateur. Joomla 1.6 et suivant
useractive fournit une liste des utilisateurs actifs. Joomla 3.2 et suivant
usergroup fournit une liste déroulante des groupes d'utilisateurs. Depuis la version Joomla 3.2, il convient d'utiliser à la place 'usergrouplist'. Joomla 2.5 et suivant
usergrouplist fournit une liste déroulante des groupes d'utilisateurs. Remplace le type de champ de formulaire 'usergroup'. Joomla 3.2 et suivant
userstate Champ pour charger une liste des statuts utilisateurs disponibles. Joomla 3.2 et suivant


Types de champs de formulaires personnalisés

Une extension peut définir ses propres types de champ, qui peuvent ensuite être utilisés dans ses propres formulaires ou ceux créés par d'autres extensions. Pour plus d'informations, veuillez consulter : Création d'un type de champ de formulaire personnalisé.

Types de champs pour formulaires modales

Si vous avez un champ avec de nombreuses valeurs qui ne conviennent pas pour une zone de sélection, vous pouvez toujours utiliser un type de champ de formulaire modal qui permettra à l'utilisateur de sélectionner un élément à partir d'une fenêtre modale avec un tableau, des options de filtres, etc. (comme pour les fenêtres dans l'administration comme par exemple pour les "articles"). Veuillez consulter Création de formulaires modales

Attributs communs

Labelclass

L'ajout de l'attribut labelclass permet d'ajouter une classe CSS pour les étiquettes des champs de formulaires. Source : http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=28450

Showon

L'ajout de l'attribut showon permet de cacher le champ basé sur la valeur d'un autre champ.

La syntaxe permettant d'afficher le champ bar uniquement lorsque foo est sur "1" et baz est sur "1" :

<field
    name="foo"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="bar"
    type="text"
    showon="foo:1"
/>

Pour correspondre à de multiples valeurs, on peut fournir une liste de valeurs, séparées par des virgules. Comme par exemple showon="foo:1,2"

Pour combiner plusieurs champs, vous pouvez utiliser [AND]. Comme ceci showon="foo:1[AND]bar:1"

La syntaxe permettant d'afficher le champ bar quand foo est paramétré sur "1" et baz sur "1" :

<field
    name="foo"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="baz"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="bar"
    type="text"
    showon="foo:1[AND]baz:1"
/>

Pour combiner plusieurs champs, vous pouvez utiliser [OR]. Comme ceci showon="foo:1[OR]bar:1"

La syntaxe permettant d'afficher le champ bar uniquement lorsque foo est paramétré sur "1" ou baz sur "1" :

<field
    name="foo"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="baz"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="bar"
    type="text"
    showon="foo:1[OR]baz:1"
/>

You can also use value does not equal like showon="field1!:1".

Syntax to show the field "bar" only when "foo" is not equal to "1":

<field
    name="foo"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="baz"
    type="list"
    showon="foo!:1"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>

To show a field when another field (e.g. foo) has been selected (so when that other field is not empty), you can use showon="foo!:" (so without a value specified).

Ceci a été introduit avec le PullRequest : https://github.com/joomla/joomla-cms/pull/3379 et disponible à partir de Joomla! 3.2.4.