Le composant CP/Ville permet de trouver une ville en tapant son code postal. Si plusieurs villes correspondent à la saisie du code postal, une liste déroulante permet de choisir la ville. Dans le cas contraire, le champ ville est automatiquement rempli avec l’unique ville correspondante. La vidéo ci-après montre son utilisation :

Au niveau du modèle de données :

• une ville ne peut avoir qu’un code postal cependant un code postal peut-être associé à plusieurs villes ;
• la correspondance entre les villes et les codes postaux se fait via une table code_postal dont voici la structure

Voici un échantillon de données :

Dans le code source du fieldset « Adresse Pro », le futur composant est le panelGroup #pro :

En analysant le code, la représentation du panelGroup #pro selon le modèle des boîtes donne :

Côté java, je ne vais pas entrer dans les détails. J’utilise le bean managé CpVilleBean qui s’occupe de rechercher la/les villes associée/s au CP saisi et qui construit une liste de selectItem pour alimenter le combo dans le cas où il y a plusieurs villes.

Maintenant que je vous ai présenté les fonctionnalités du composant et sa structure, le but est de factoriser ce code afin de pouvoir le réutiliser simplement sans avoir à faire un copier/coller.

Avant factorisation, le code de la vidéo d’exemple ressemble à ceci :

Après factorisation, suivant les deux méthodes que je vais vous présenter, nous obtiendrons :

Voici un comparatif visuel avant/après :

Bloc adresse pro

Bloc adresse perso

Certains éléments vont devenir des paramètres suite à la factorisation du code de notre futur composant. Ainsi la première étape dans la création d’un composant consiste à identifier ses paramètres. Comment ? En faisant exactement ce que nous voulons éviter de faire : un copier/coller. Nous allons donc :

1. Dupliquer les éléments du composant dans la même page via un copier/coller du code ;
2. Le rendre fonctionnel en modifiant un minimum de code ;
3. Comparer les éléments qui diffèrent ;
4. Identifier le code spécifique au scénario de la page courante.

Après avoir testé que les deux composants fonctionnent bien dans une même page, je les ai isolés dans deux fichiers différents et les ai comparés (en utilisant la fonction « compare with each other » d’Eclipse par exemple).

Les éléments qui diffèrent sont donc :

• la propriété cp du bean, valeur du champ de saisi du cp ;
• la propriété ville du bean, valeur du champ de saisie de ville ;
• les id ;
• le nom de la fonction de recherche par CP ;
• les labels des champs de saisie ;
• les tabindex ;
• la taille de l’input text ville ;
• la classe du combo ville (qui permet d’agir sur sa taille) ;
• la fonction notifyChange dans l’événement onchange : elle permet de dégriser le bouton « Enregistrer » suite à une modification de la valeur du champ, elle est donc spécifique au scénario de la page courante.

Nous pouvons passer à l’étape suivante : la création du composant selon la 1re méthode.

La première méthode de création du composant consiste à externaliser le code dans une facelet, un fichier à part que je nomme cpVille.xhtml et que je place de manière arbitraire dans le dossier WebContent/composant/

La balise la plus important est <ui:composition> qui encapsule le code du composant. Attention, tout ce qui est à l’extérieur de cette balise ne sera pas pris en compte !

Dès maintenant, <ui:include> me permet de remplacer les champs cp et ville de mon formulaire exemple de la manière suivante :

Ensuite, je n’ai plus qu’à placer mes paramètres en utilisant des « Expression Languages » #{nom_param} ce qui donne :

Voici la liste des paramètres créés :

• cp : la valeur du champ de saisie du cp ;
• ville : la valeur du champ de saisie de la ville ;
• id : au lieu de créer un paramètre id pour chaque champ, j’utilise un seul paramètre qui sert à construire les autres id en déclarant une variable dans la facelet (<ui:param>). Je peux réutiliser du coup ses variables dans les attributs execute, render, oncomplete de ma fonction. id sert aussi à construire le nom de la fonction JavaScript qui doit être unique pour chaque composant ;
• label : ici aussi j’utilise un seul paramètre qui servira à construire le label du champ cp et du champ ville (affiché en cas de champ vide) ;
• tabindex : le tabindex du champ cp ;
• villeWidth : permet de spécifier la longueur de l’input text ville ;
• styleClass : permet de spécifier une classe qui s’appliquera au composant combo ;
• onchange : fonction JavaScriptqui sera exécutée lors du déclenchement de l’événement onchange des champs de saisie.

Pour les passer à ma facelet, il faut utiliser <ui:param> au niveau de l’inclusion :

Notre composant possède déjà l’essentiel pour être réutilisé dans d’autres écrans, mais il ne permet pas de réaliser ce que la plupart des composants JSF de base permettent à savoir :

• paramétrer sa visibilité : rendered ;
• changer son état actif/inactif/lecture seule : disabled / readonly ;
• rendre un champ obligatoire ou non : required.

De plus comment faire pour ajouter un événement onkeyup/onblur/onfocus sur l’un des inputs text ?

Vous l’avez compris, nous allons lui ajouter d’autres paramètres.

N.B : Remarquez l’utilisation de l’opérateur ternaire qui me permet de spécifier des valeurs par défaut pour rendered, disabled, readonly, villeWidth et tabindexSup.

De plus pour simplifier la surcharge des styles de notre composant, j’ai créé une classe pour chaque élément qui reprend le contenu de l’attribut style. J’ai concaténé le paramètre styleClass à l’attribut styleClass de chaque élément. Les classes ont été externalisées dans un fichier css que voici :

Ce fichier est inclus dans la facelet grâce à la balise <h:outputStylesheet>.

Dans l’exemple de l’adresse pro, pour surcharger la longueur du combo ville je dois maintenant écrire l’instruction css suivante :

Enfin le code javascript utilisé est inclus directement dans la facelet via la balise <h:outputScript>. Voici d’ailleurs le code source de ce fichier :

Pour créer le composant selon la deuxième méthode nous allons créer un fichier dans le répertoire /WebContent/resources/composant. J’ai choisi « composant » de manière arbitraire mais le dossier doit être dans le repertoire resources.

La déclaration du namespace composite nous permet d’utiliser les éléments interface et implementation qui permettent respectivement de :

• déclarer les attributs de notre composant ;
• écrire le code du composant.
  

Voici le code résultant :

Comparée à la première méthode, cette syntaxe offre les avantages suivants en terme de lisibilité :

• aperçu exhaustif de tous les attributs possibles en lisant la partie interface (<composite:attribute>)
• revue rapide des attributs obligatoires via required ;
• revue rapide des valeurs par default via default ;
• revue rapide du type de donnée attendu pour les propriétés de bean via type ;
• vue sur utilité de l’attribut via shortDescription.

Les attributs déclarés peuvent être référencés dans le code source implementation en utilisant la syntaxe #{cc.attrs.nom_attr}.

Pour utiliser le composant, il faut déclarer un namespace qui pointe vers le sous-dossier de resources dans lequel se trouve notre composant :

Ensuite pour l’inclure dans la page, il faut simplement préfixer le nom du fichier par le namespace et déclarer les attributs requis et optionnels.

Comparé à la première méthode, l’utilisation d’un composant composite nous fait bénéficier de l’autocomplétion lors de l’écriture du code et les description des attributs shortDescription seront rendues lisibles par votre IDE.

Je reviens sur la syntaxe de définition du composant. Jusqu’ici, j’ai adapté mon composant résultant de la méthode par inclusion pour créer un composant composite. En fait, le fonctionnement des composants composites me permet de simplifier quelques déclarations.

1. Attributs implicites
   Les attributs « id » et « rendered » n’ont pas besoin d’être déclarés et ne devraient pas l’être, car ils sont implicitement hérités du composant de base dont héritent tous les composants composites.
   Je peux néanmoins laisser la déclaration de « id » pour obliger le développeur à le définir.
   Pour utiliser l’id dans l’implémentation, il est possible d’utiliser la syntaxe #{cc.id}.
2. Génération des id
   Tous les sous-composants JSF qui constituent le composant composite auront un id de la forme suivante :
   idFormulaire:idComposant:idSousComposant.
   Exemple : fCpVil:perso:cp
   Je n’ai donc plus besoin des quatre paramètres idCp, idVille, idVilles, idGroupeVille qui permettaient d’avoir des id uniques pour la méthode 1 par inclusion.

   N.B : Pour utiliser un label qui pointe vers un sous-composant, il faut définir son attribut for avec la syntaxe idComposant:idSousComposant.
   Exemple pour cp : <h:label value= »CP : » for= »perso:cp » />
3. Référencement AJAX
   Du fait du point précédent, le div conteneur du composant ne portera pas l’id saisi. Sur l’exemple de « perso », il sera généré de la manière suivante : fCpVil:perso:perso.
   Du coup, dans la page principale, il n’est plus possible de faire référence au composant dans les requêtes Ajax via execute et render.
   Pour résoudre ce problème, il faut encapsuler la partie implémentation dans un <div> ou un <span> dont l’id est #{cc.clientId}.
   J’ai donc remplacé le premier h:panelGroup par un div.

Finalement, le code du composant est le suivant :

Voilà, nous avons bouclé cet article sur la création d’un composant en JSF.

Après avoir expliqué le fonctionnement du composant exemple CP/Ville, nous avons listé les paramètres, puis créer le composant de deux manières différentes : d’une part en utilisant le principe d’inclusion de facelet et d’autre part en utilisant le principe des composants composites (composite components).

Cependant, je ne peux utiliser le composant sans inclure CpVilleBean dans mon projet. Afin de déporter la logique métier dans le composant, il faudrait utiliser le principe de NamingContainer que je développerai dans un futur tutoriel.

Ressources :

• JSF 2 fu, Part 2: Templating and composite components
• JSF 2 fu: Best practices for composite components

Cet article a également été publié sur notre blog développez.com.