Joomla! Documentation™

Introduction

Les champs de formulaire sont des champs contenus dans des balises HTML <form>. La version Joomla! 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 . 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é
accessiblemedia	fournit un accès modal au gestionnaire de médias pour l'insertion d'images avec téléchargement pour les utilisateurs disposant des autorisations appropriées et un champ de texte pour ajouter un texte alternatif.	et suivant
accesslevel	fournit une liste déroulante de visualisation des niveaux d'accès.	et suivant
cachehandler	fournit une liste d'options de mise en cache disponibles.	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.	et suivant
captcha	Permet l'utilisation d'un plugin captcha.	et suivant
category	fournit une liste déroulante des catégories pour une extension.	et suivant
checkbox	fournit une case simple à cocher ou décocher.	et suivant
checkboxes	fournit un nombre illimité de cases à cocher qui peuvent être utilisées pour les multi-sélections.	et suivant
Chrome Style	fournit une liste des templates avec options de style chrome regroupés par templates.	et suivant
color	fournit un sélecteur de couleur en cliquant dans la zone de saisie.	et suivant
Content Language	fournit une liste des langues de contenu.	et suivant
Content Type	fournit une liste des types de contenu.	et suivant
combo	fournit une un ensemble de champs cases.	et suivant
componentlayout	fournit une liste regroupant des templates et d'affichages natifs alternatifs pour un élément de composant.	et suivant
contentlanguage	fournit une liste de langues de contenu installées pour une utilisation avec le plugin de sélection des langues.	et suivant
Database Connection	fournit une liste de connexions à la base de données disponible, éventuellement en limitant à une liste donnée.	et suivant
editor	fournit un champ de zone de texte pour l'éditeur.	et suivant
editors	fournit une liste déroulante des éditeurs WYSIWYG disponibles. Depuis la version , il convient d'utiliser à la place les plugins de types de champs de formulaire.
email	fournit un champ de courriel.	et suivant
file	fournit un champ de saisie pour les fichiers.	et suivant
filelist	fournit une liste déroulante de fichiers d'un répertoire spécifié.	et suivant
folderlist	fournit une liste déroulante des dossiers d'un répertoire spécifié.	et suivant
groupedlist	fournit une liste déroulante d'éléments organisés en groupes.	et suivant
header tag	fournit une liste déroulante des balises de titre (h1-h6).	et suivant
helpsite	fournit une liste déroulante des sites d'aide pour votre installation Joomla.	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").	et suivant
imagelist	fournit une liste déroulante de fichiers image d'un répertoire spécifié.	et suivant
integer	fournit une liste déroulante d'entiers compris entre un minimum et un maximum.	et suivant
language	fournit une liste déroulante des langues installées pour le frontend ou le backend.	et suivant
list	fournit une liste déroulante d'entrées personnalisées.	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.	et suivant
menu	fournit une liste déroulante des menus disponibles à partir de votre site Joomla.	et suivant
Menu Item	fournit une liste déroulante des éléments de menu disponibles à partir de votre site Joomla.	et suivant
meter	fournit un compteur pour afficher la valeur dans une plage.	et suivant
Module Layout	fournit une liste d'affichages alternatifs pour un groupe de modules natifs et de templates.	et suivant
Module Order	fournit une liste déroulante pour définir les modules d'une position donnée.	et suivant
Module Position	fournit une zone de texte pour définir la position d'un module.	et suivant
Module Tag	fournit une liste des éléments HTML5 (utilisé pour l'intégration de module dans une fenêtre).	et suivant
note	fournit un champ texte d'une ligne.	et suivant
number	fournit une zone de texte d'une ligne avec un champ déroulant de chiffres pour définir le champ.	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.	et suivant
plugins	fournit une liste de plugins à partir d'un dossier donné.	et suivant
predefinedlist	Champ de formulaire pour charger une liste de valeurs prédéfinies.	et suivant
radio	fournit des boutons radio pour sélectionner différentes options.	et suivant
range	fournit une barre de défilement horizontale pour spécifier une valeur dans une plage donnée.	et suivant
repeatable	autorise les champs de formulaire proposant autant d'options que souhaitées par l'utilisateur.	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.	et suivant
sessionhandler	fournit une liste déroulante de gestionnaire des options de session.	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.	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.	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.	et suivant
tag	fournit un point d'entrée pour les balises (AJAX ou imbriquées).	et suivant
tel	fournit un champ de saisie pour numéro de téléphone.	et suivant
templatestyle	fournit une liste déroulante des styles de templates.	et suivant
text	fournit une zone de texte pour la saisie des données.	et suivant
textarea	fournit une zone de texte pour la saisie de texte en multi-ligne.	et suivant
timezone	fournit une liste déroulante des fuseaux horaires.	et suivant
URL	fournit un champ de saisie d'URL.	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.	et suivant
useractive	fournit une liste des utilisateurs actifs.	et suivant
usergroup	fournit une liste déroulante des groupes d'utilisateurs. Depuis la version , il convient d'utiliser à la place 'usergrouplist'.	et suivant
usergrouplist	fournit une liste déroulante des groupes d'utilisateurs. Remplace le type de champ de formulaire 'usergroup'.	et suivant
userstate	Champ pour charger une liste des statuts utilisateurs disponibles.	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"
/>

Vous pouvez aussi utiliser une valeur "différente de" telle que showon="foo!:1".

La syntaxe permettant d'afficher le champ "baz" lorsque "foo" n'est pas égal à "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>

Pour afficher un champ lorsqu'un autre champ (par exemple foo) est sélectionné (et donc quand ce champ n'est pas vide), vous pouvez utiliser showon="foo!:" (sans spécifier de valeur).

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

Dépannage : Les attributs ne fonctionnent pas

Si vous avez lu une ancienne version de notre documentation pour les développeurs ou pris le code d'affichage de votre formulaire à partir d'une extension existante, vous rencontrez peut-être des problèmes avec des attributs tels que showon qui ne fonctionnent pas du tout. Pour que certains attributs spéciaux fonctionnent, vos champs doivent être rendus à l'aide de leur méthode renderField(). Par exemple:

<div class="row-fluid">
    <div class="span6">
        <?php 
            foreach($this->form->getFieldset() as $field) {
                echo $field->renderField();        
            }
        ?>
    </div>
</div>