Tutoriel sur les Composite-Components de JSF2

Olivier Butterlin

L'objectif du tutoriel est de vous faire découvrir les composite-components en JSF2 et les possibilités avancées au travers d'un exemple de gestion de clé externe très utile dans bien des applications.

Les sources de l'exemple sont disponibles ici.

Pour réagir au contenu de cet article, un espace de dialogue vous est proposé sur le forum Commentez .

- Titre : Tutoriel sur les Composite-Components de JSF2

- Auteur : Olivier Butterlin

- Parution : 19 janvier 2015

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2015 Olivier Butterlin. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Présentation

- II. Création d'un composant

- II-A. Définition de l'interface

- II-B. Définition de l'implémentation

- III. Utilisation d'un composant dans une page

- IV. Étude de cas complexe : les clés étrangères

- IV-A. Présentation

- IV-B. La base de données

- IV-C. L'aspect du composant

- IV-D. Partie interface

- IV-E. Classe spécialisée du composant

- IV-E-1. Classe abstraite de factorisation

- IV-E-2. La classe d'implémentation de notre composant

- IV-F. Partie implémentation

- IV-F-1. Partie affichage

- IV-F-2. Partie liste de sélection

- V. Conclusion et remerciements

I - Présentation

Arrivé avec Facelets et la version 2.0 de JSF, le composite-component est un terme désignant une forme de template qui agit comme un composant graphique (UI-Component) réutilisable.

Il utilise une déclaration XML plutôt que du Java et est accessible sous le nom de domaine (namespace) http://java.sun.com/jsf/composite.

Il est placé dans un répertoire « resources ».

II - Création d'un composant

La mise en œuvre est très simple, il suffit de :

- créer un répertoire resources à la racine du projet web (/WebContent/resources) ;

- créer un fichier d'extension xhtml pour la définition d'un composant.

On peut bien sûr structurer le répertoire « resources » en fonction de ses besoins. Il pourrait être judicieux de créer un sous-répertoire « composants » sous « resources ».

Le fichier de définition aura la structure suivante

1. <html xmlns="http://www.w3.org/1999/xhtml"

2. xmlns:h="http://java.sun.com/jsf/html"

3. xmlns:f="http://java.sun.com/jsf/core"

4. xmlns:composite="http://java.sun.com/jsf/composite">

6. <composite:interface>

7. // Définition de l'interface du composant

8. </composite:interface>

10. <composite:implementation>

11. // Définition de l'implémentation

12. </composite:implementation>

13. </html>

II-A - Définition de l'interface

La partie interface définit le « contrat » du composant. Dans ce contrat, on trouvera des paramètres sous forme d'attributs de l'interface et/ou un type associé au composant.

Les attributs de la balise <composite:interface> (les attributs sans grande importance sont grisés)

Attribut

Définition

name

Déclaration d'un attribut du composant.

componentType

Type (classe) associé au composant. Lorsque le composant gère plusieurs éléments graphiques, les encapsuler dans une classe spécialisée peut s'avérer extrêmement utile.

displayName

Nom à afficher par une palette de composants.

shortDescription

Description courte.

prefered

S'agit-il d'un composant « préféré » ?

expert

Le composant est uniquement pour des utilisateurs experts.

La partie interface pourrait être vide s'il n'y avait aucun attribut à passer au composant, mais il faut bien reconnaître que l'intérêt serait des plus réduit, une inclusion de page ferait largement l'affaire dans ce cas.

Généralement, on y définit les attributs (paramètres) de configuration du composant.

La syntaxe générale est :

<composite:élément attribut1="valeur1" ... attributN="valeurN">

Les éléments les plus utiles sont :

Élément

Définition

Attribue

Déclaration d'un attribut du composant.

valueHolder

Un élément (ou plusieurs) du composant expose une implémentation de javax.faces.component.ValueHolder.

editableValueHolder

Un élément (ou plusieurs) du composant expose une implémentation de javax.faces.component.EditableValueHolder.

clientBehavior

Un élément (ou plusieurs) du composant expose une implémentation de javax.faces.component.behavior.ClientBehavior.

actionSource

Un élément (ou plusieurs) du composant expose une implémentation de javax.faces.component.ActionSource2

Liste des attributs par élément.

composite:attribute

Attribut

Description

Name

Nom de l'attribut.

Default

Valeur par défaut de l'attribut.

Required

Spécifie si l'attribut est obligatoire.

Method-signature

Signature de la méthode pour un attribut de type action « MethodExpression ».
Les classes des paramètres doivent être qualifiées.
Si l'attribut « type » est présent, ce paramètre est ignoré.
Exemple : <composite:attribute name="do" method-signature="java.lang.String doSomething()"/>.

Type

Un élément (ou plusieurs) du composant expose une implémentation de javax.faces.component.ActionSource2

composite:valueHolder

Interface utile pour gérer une valeur locale ainsi qu'accéder aux données d'un modèle tiers par une expression et convertir un type String avec un type natif différent (converter).

Attribut

Description

Name

Nom de l'attribut. Ce nom peut être utilisé dans un attribut « for » d'un composant graphique. Si l'attribut « target » n'est pas précisé, ce nom représente également l'id du composant cible.

Targets

Liste des composants cibles (séparés par un blanc).

composite:editableValueHolder

Interface dérivée de ValueHolder, ajoutant le support des validators et des événements de changement de valeur (ValueChangeListener).

Attribut

Description

Name

Nom de l'attribut. Ce nom peut être utilisé dans un attribut « for » d'un composant graphique. Si l'attribut « target » n'est pas précisé, ce nom représente également l'id du composant cible.

Targets

Liste des composants cibles (séparés par un blanc).

composite:clientBehavior

Permet à la page utilisatrice de préciser une action Ajax (ou JavaScript) sur un événement.

Attribut

Description

Name

Nom de l'attribut. Ce nom peut être utilisé dans un attribut « for » d'un composant graphique. Si l'attribut « target » n'est pas précisé, ce nom représente également l'id du composant cible.

Targets

Liste des composants cibles (séparés par un blanc).

Event

Nom de l'événement géré.

Default

Si « true », la page utilisatrice pourra omettre l'attribut « event ».

composite:actionSource

Permet au composant d'exécuter une action définie par la page utilisatrice.

Attribut

Description

Name

Nom de l'attribut. Ce nom peut être utilisé dans un attribut « for » d'un composant graphique. Si l'attribut « target » n'est pas précisé, ce nom représente également l'id du composant cible.

Targets

Liste des composants cibles (séparés par un blanc).

II-B - Définition de l'implémentation

La partie implémentation représente la partie visible du composant.

On y retrouve des éléments HTML ou d'autres composants de bibliothèques graphiques comme Primefaces, Richfaces, etc.

L'implémentation aura accès aux attributs de l'interface au travers de l'expression : #{cc.attrs.nom_attribut}

Un composant simple pour afficher une image associée à un objet java.lang.Boolean pourrait ressembler à ceci

<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:composite="http://java.sun.com/jsf/composite"
xmlns:c="http://java.sun.com/jsp/jstl/core"
xmlns:p="http://primefaces.org/ui">

<composite:interface>
<composite:attribute name="value" required="true" type="java.lang.Boolean"/>
</composite:interface>

<composite:implementation>
<center>
<h:graphicImage value="/resources/images/yes.png" rendered="#{cc.attrs.value.booleanValue() == true}" />
</center>
</composite:implementation>
</html>

Même si ce composant peut paraître inutile, il a l'avantage d'abstraire la représentation d'une valeur booléenne dans toutes les pages où on en aurait besoin.

Ainsi, sans avoir autre chose à modifier que le composant, on pourrait décider dans un premier temps que seule la valeur « true » serait représentée (cas de l'exemple).

Une autre règle plus tardive dans le cycle de développement pourrait faire qu'il faut représenter la valeur « false » également.

III - Utilisation d'un composant dans une page

Maintenant que nous avons vu comment concevoir des composants, reste bien sûr à les utiliser.

Pour ça, il suffit que la page utilisatrice référence le/les composants de l'application par leur namespace.

En fonction de la structuration utilisée, le référencement pourra être différent, mais la racine sera toujours la même xmlns:un_nom="http://java.sun.com/jsf/composite".

Exemple (avec template) utilisant un sous-répertoire dédié « component »

1. <ui:composition xmlns="http://www.w3.org/1999/xhtml"

2. xmlns:ui="http://java.sun.com/jsf/facelets"

3. xmlns:h="http://java.sun.com/jsf/html"

4. xmlns:f="http://java.sun.com/jsf/core"

5. xmlns:util="http://java.sun.com/jsf/composite/component"

6. xmlns:p="http://primefaces.org/ui" template="/template/template.xhtml">

7. </ui:composition>

Dans cet exemple, à chaque fois que la page aura besoin d'un de nos composants, elle le référencera via <util:nom_composant>.

Le nom_composant est en pratique le nom du fichier de définition sans l'extension xhtml.

Dans la bibliothèque de composants de notre exemple (joint), on peut voir deux définitions :

- foreignKey-Constr.xhtml ;

- graphicBoolean.xhtml.

On les référencerait dans les pages par :

1. <util:graphicBoolean attribut1="valeur1">

2. <util:foreignKey-Constr attribut1="valeur1"  attribut2="valeur2">

Les valeurs des attributs sont soit des constantes, soit des expressions

attribut1="#{monManagedBean.unAttribut"
attribut2="150"

IV - Étude de cas complexe : les clés étrangères

IV-A - Présentation

Pour approfondir et voir le grand intérêt des composite-components, nous allons réaliser un composant de gestion de clé étrangère.

En effet, dans nombre d'applications dites de « gestion » se pose la question de la centralisation et la matérialisation d'une référence externe (clé étrangère ou foreign-key), ou plus généralement, d'une entité applicative.

Un article, par exemple, sera référencé dans beaucoup de tables (stock, nomenclature, catalogue constructeur, etc.), il en va de même pour un constructeur, un client, un fournisseur, etc.

Partout où nous ferons référence à ces éléments se poseront les questions :

- je le choisis comment ?

- j'affiche quoi ?

Un autre aspect lié à ce composant, en fonction des cas, nous voudrons :

- qu'il ne soit pas modifiable ;

- qu'on ait accès qu'aux informations de décodification (sur une ou plusieurs lignes) ;

- qu'on puisse lui appliquer des contrôles différents en fonction de l'appel ;

- qu'on puisse agrandir ou rétrécir la zone de sélection et/ou la zone décodification.

Le contrat de base est déjà bien compliqué, mais nous verrons que le composite-component est tout à fait capable de pallier tout ceci.

IV-B - La base de données

Pour simplifier la compréhension au maximum, nous prendrons l'exemple d'un composant lié à un constructeur. Ce constructeur sera utilisé pour sélectionner des articles.

La base de données se limitera donc à deux tables :

Scripts de création

1. CREATE TABLE CONSTR (

2. UID            INTEGER AS IDENTITY NOT NULL,

3. CODE            VARCHAR(10) NOT NULL,

4. NOM            VARCHAR(80),

5. ADRESSE1        VARCHAR(128),

6. ADRESSE2        VARCHAR(128),

7. ADRESSE3        VARCHAR(128),

8. CP             VARCHAR(80),

9. VILLE        VARCHAR(128),

10. PRIMARY KEY (UID)

11. )

13. CREATE TABLE ARTICLE (

14. UID            INTEGER AS IDENTITY NOT NULL,

15. CODE            VARCHAR(10) NOT NULL,

16. DESIGNATION     VARCHAR(80),

17. UID_CONSTR        INTEGER,

18. PRIMARY KEY (UID),

19. CONSTRAINT FK_ARTICLE_REL_CONSTR_1

20. FOREIGN KEY (UID_CONSTR)

21. REFERENCES CONSTR (UID) ON DELETE RESTRICT

22. ON UPDATE RESTRICT

23. )

IV-C - L'aspect du composant

Notre composant ressemblera à ceci (en vert, délimitation du composant) :

Lorsque l'utilisateur cliquera sur le bouton, une liste de sélection multicritère sera affichée, son apparence sera la suivante :

Si l'utilisateur connaît le code de son constructeur (qui représente une clé unique), il pourra la saisir directement dans la zone « clé » et le composant décodifiera sa valeur.

IV-D - Partie interface

Pour notre contrat (interface), nous aurons donc besoin :

- d'un attribut Constr (représentant le constructeur) ;

- d'un attribut Boolean pour définir si le composant est en lecture seule ;

- d'un attribut Boolean pour définir si nous voulons uniquement la décodification ;

- d'un attribut String pour définir la largeur de la partie clé ;

- d'un attribut String pour définir la largeur de la partie décodification.

Comme nous aurons besoin d'agir sur la modification du constructeur, nous ajouterons :

- un élément clientBehavior pour l'événement « change ».

Nous aurons également besoin d'affecter et récupérer la valeur Constr et de lui appliquer un contrôle de validité au besoin, nous ajouterons :

- un élément editableValueHolder lié à la partie clé.

Comme notre composant gère trois parties distinctes :

- saisie directe d'une clé constructeur ;

- bouton d'appel d'une liste de sélection ;

- label associé au constructeur (décodification),

nous associerons notre composant à une classe spécialisée nommée foreignKeyConstrComponent, nous y reviendrons par la suite.

Notre interface sera donc la suivante :

1. <composite:interface componentType="foreignKeyConstrComponent">

2. <composite:attribute name="value" required="true" type="test.ejb.client.entity.Constr"/>

3. <composite:attribute name="readOnly" default="false" type="java.lang.Boolean"/>

4. <composite:attribute name="labelOnly" default="false" type="java.lang.Boolean"/>

5. <composite:attribute name="keyWidth" default="100px"/>

6. <composite:attribute name="labelWidth" default="300px"/>

7. <composite:clientBehavior name="change" event="change" targets="key" />

8. <composite:editableValueHolder name="key" targets="key"/>

9. </composite:interface>

IV-E - Classe spécialisée du composant

Tel qu'est défini notre composant, avec ses trois parties distinctes (clé, bouton, label), nous pourrons utiliser cette structure dans beaucoup de cas (sinon tous).

Seuls les éléments réagissant avec notre classe devront être référencés ici, le bouton ne servant qu'à ouvrir la liste, nul besoin de l'associer.

Il paraît intéressant de factoriser ces éléments dans une classe abstraite ainsi que certaines fonctions génériques comme :

- l'envoi de message à l'application ;

- le traitement des validators associés (s'il y en a) ;

- l'invalidation suite à une erreur,

ce qui permettra de se concentrer uniquement sur les traitements spécifiques dans chaque composant.

IV-E-1 - Classe abstraite de factorisation

1. public abstract class AbstractForeignKeyComponent extends UIInput implements NamingContainer

2. {

3. public final Logger logger = Logger.getLogger(getClass().getSimpleName());

4. protected UIInput key;

5. protected UIOutput lbl;

7. /*

8. * ----- getter / setter à placer ici

9. */

11. public abstract void formatValue();

12. public abstract void updateValue(AjaxBehaviorEvent event);

15. @Override

16. public String getFamily()

17. {

18. return UINamingContainer.COMPONENT_FAMILY;

19. }

21. /**

22. * Début de l'encodage du composant

23. */

24. @Override

25. public void encodeBegin(FacesContext facesContext) throws IOException

26. {

27. logger.log(Level.FINEST, "encodeBegin(FacesContext)");

28. formatValue();

29. super.encodeBegin(facesContext);

30. }

33. /**

34. * Envoyer un message d'application

35. * @param target

36. * @param message

37. */

38. public void sendFacesMessage(String target, FacesMessage message)

39. {

40. if (message != null)

41. {

42. FacesContext facesContext = FacesContext.getCurrentInstance();

43. facesContext.getExternalContext().getFlash().setKeepMessages(true);

44. facesContext.addMessage(target, message);

45. }

46. }

48. /**

49. * Validation (si nécessaire)

50. */

51. @Override

52. public void validate(FacesContext facesContext)

53. {

54. logger.log(Level.FINEST, "validate(FacesContext)");

56. /*

57. * On traite tous les validators enregistrés

58. */

59. for (Validator validator : getValidators())

60. {

61. try

62. {

63. validator.validate(facesContext, this, getValue());

64. }

65. catch (ValidatorException e)

66. {

67. invalidValue();

68. sendFacesMessage(null, e.getFacesMessage());

69. }

70. }

71. }

73. /**

74. * Valeur incorrecte

75. */

76. public void invalidValue()

77. {

78. logger.log(Level.FINEST, "invalidValue()");

79. if (getKey().getValue() != null)

80. {

81. setValid(false);

82. key.setValid(false);

83. }

84. }

85. }

Quelques explications :

- elle implémente NamingContainer : un composite-component doit toujours le faire pour définir sa famille et ainsi éviter des conflits et doublons dans le conteneur. En pratique, la famille du composant sera UINamingContainer.COMPONENT_FAMILY ;

- elle étend UIInput : dans notre cas, le composant gère des éléments d'entrées/sorties, nous allons donc spécialiser un composant existant prévu à cet effet javax.faces.component.UIInput ;

- elle contient une propriété « key » de type UIInput : pour gérer la valeur clé de notre objet géré (pour l'exemple, un Constr). Le formatage sera réalisé par la classe d'implémentation spécifique via la fonction formatValue() ;

- elle contient une propriété « lbl » de type UIOutput : pour afficher la décodification de l'objet géré. Le formatage sera réalisé par la classe d'implémentation spécifique via la fonction formatValue().

Les méthodes de notre classe

- encodeBegin(FacesContext) : elle est appelée à la création du composant. Dans notre cas, il faut lancer le traitement d'affectation de la valeur en cours aux différents éléments de notre composant (la clé et la décodification) si besoin. Ceci est réalisé par la méthode formatValue().

- (abstract) formatValue() : méthode abstraite à définir par la classe d'implémentation qui servira à affecter la partie clé de l'objet géré à notre champ d'entrée « key » et la décodification au champ de sortie « lbl ».

- (abstract) updateValue(AjaxBehaviorEvent event) : méthode abstraite à définir par la classe d'implémentation qui servira à positionner la valeur sélectionnée. L'origine de cette valeur est soit la liste de sélection, soit la saisie de la clé directement.

- sendFacesMessage(String target, FacesMessage message) : elle envoie un message à l'utilisateur, elle ne fait rien de particulier.

- validate(FacesContext facesContext) : elle est appelée pour valider un changement de valeur ou la valeur en cours lors de la soumission du formulaire de la page. Tous les validators liés au composant sont appelés, en cas d'erreur, nous invalidons la valeur par la méthode invalidValue() et nous envoyons un message à l'utilisateur par sendFacesMessage(...).

- invalidValue() : elle signale visuellement à l'utilisateur que la valeur est incorrecte. Dans notre exemple, la couleur de la bordure de l'élément « clé » passe en rouge.

IV-E-2 - La classe d'implémentation de notre composant

Il ne reste plus qu'à implémenter les deux méthodes spécifiques liées à l'objet géré (Constr) et à enregistrer notre composant sous un nom par l'annotation @FacesComponent.

ce nom doit être identique à l'attribut componentType de la balise <composite:interface componentType="foreignKeyConstrComponent"> de notre définition de composant (page xhtml).

Voici le code de notre classe :

1. /**

2. * Composant : Clé externe

3. * @author Olivier BUTTERLIN

4. */

5. @FacesComponent("foreignKeyConstrComponent")

6. public class ForeignKeyConstrComponent extends AbstractForeignKeyComponent

7. {

9. /**

10. * La valeur change, mise à jour des composants

11. * @param event

12. */

13. public void updateValue(AjaxBehaviorEvent event)

14. {

15. try

16. {

17. logger.log(Level.FINEST, "updateValue(AjaxBehaviorEvent) ");

18. if (event instanceof SelectEvent)

19. {

20. Constr constr = (Constr) ((SelectEvent) event).getObject();

21. setValue(constr);

22. RequestContext.getCurrentInstance().execute("callChangeFunction('" + key.getClientId() + "')");

23. }

24. else

25. {

26. if (key.getValue() != null && key.getValue().toString().trim().length() > 0)

27. {

28. String keyValue = (String) key.getValue();

29. Constr constr = FKComponentEJBLocator.getInstance().getConstrFacadeLocal().getConstrParCode(keyValue);

30. setValue(constr);

31. }

32. else

33. {

34. super.setValue(null);

35. updateModel(FacesContext.getCurrentInstance());

36. formatValue();

37. }

38. }

39. }

40. catch (Exception e)

41. {

42. logger.log(Level.SEVERE, e.toString());

43. }

44. }

47. /**

48. * Formattage de la valeur

49. */

50. public void formatValue()

51. {

52. Constr constr = null;

53. if (getValue() instanceof Constr)

54. {

55. constr = (Constr)getValue();

56. }

58. String label = "";

59. if (constr != null)

60. {

61. key.setValue(constr.getCode());

62. label = constr.getNom();

63. }

64. else

65. {

66. key.setValue(null);

67. }

69. lbl.setValue(label);

70. }

71. }

Les méthodes de notre classe

- updateValue(AjaxBehaviorEvent event)

Cette méthode peut être appelée de deux manières :

1. Lors de la sélection d'une ligne dans la liste de sélection ;

2. Lors de la modification de la partie « clé » de notre composant.

Pour distinguer les deux cas, on se base sur le type de l'événement reçu. S'il s'agit d'un événement de type SelectEvent, nous venons de la liste de sélection.

Cas 1

Notre liste gérant des objets de type Constr, il suffit d'affecter au composant l'objet passé en paramètre.

Pour forcer l'événement « change » du composant (la page utilisatrice peut avoir défini une action particulière), nous appelons une méthode JavaScript par la ligne

RequestContext.getCurrentInstance().execute("callChangeFunction('" + key.getClientId() + "')");

Cette méthode mériterait d'être retravaillée, mais pour l'instant, je n'ai pas trouvé mieux…

key.getClientId() représente l'id unique du composant UIInput « key » de notre composant. Le code de cette fonction est très simple, il suffit de l'inclure à la page utilisatrice ou plus simplement au template de pages de l'application.

function callChangeFunction(id)
{
try
{
var el = document.getElementById(id);
$(el).change();
}
catch (e) {}
}

Cas 2

La partie « clé » du composant est une chaîne de caractères représentant le code d'un constructeur, il faut aller chercher l'objet Constr (s'il existe) depuis la base de données et affecter cet objet au composant.

- formatValue()

La méthode getValue() nous renvoie théoriquement un objet de type Constr, mais aucune certitude n'est possible à ce niveau d'où le test instanceOf.

Si l'objet retourné est du bon type et non null, il suffit de formater en fonction de nos besoins la chaîne de caractères qui représente la décodification du constructeur et de l'affecter au composant UIOutput « lbl ».

IV-F - Partie implémentation

Il s'agit maintenant d'implémenter la représentation graphique de notre composant qui est définie par la balise <composite:implementation>. Dans l'exemple, nous distinguons deux blocs distincts :

1. L'affichage de la clé, le bouton et la décodification ;

2. La liste de sélection.

IV-F-1 - Partie affichage

<!-- Affichage complet -->
<p:panelGrid rendered="#{!cc.attrs.labelOnly}">
<p:row>
<p:column styleClass="ui-foreignKey-column">
<p:inputText id="key" binding="#{cc.key}"
disabled="#{cc.attrs.readOnly}"
style="width:#{cc.attrs.keyWidth}">
<p:ajax event="change"  listener="#{cc.updateValue}"
process="@this" update="key btn txt"/>
</p:inputText>
</p:column>
<p:column styleClass="ui-foreignKey-column" rendered="#{!cc.attrs.readOnly}">
<p:commandButton id="btn" immediate="true" binding="#{cc.btn}" icon="ui-icon-search"                                 update="selectConstrDialog"
oncomplete="PF('selectConstrListWidget#{cc.clientId}').show()"/>
</p:column>
<p:column styleClass="ui-foreignKey-column3">
<h:panelGroup id="txt">
<h:outputText binding="#{cc.lbl}" escape="false"
styleClass="ui-foreignKey-label"
style="width:#{cc.attrs.labelWidth}"/>
</h:panelGroup>
</p:column>
</p:row>
</p:panelGrid>

<!-- Affichage uniquement du label -->
<h:panelGroup rendered="#{cc.attrs.labelOnly}">
<h:outputText value="#{cc.lbl.value}" escape="false"/>
</h:panelGroup>

Nous avons vu que la classe spécialisée contenait deux objets, un UIInput pour gérer la saisie et afficher le code et un UIOutput pour afficher la décodification.

Pour associer ces objets à notre vue, l'astuce consiste à utiliser le binding. L'expression #{cc} représente le composant, nous avons donc accès à toutes les propriétés et toutes les méthodes du composant par elle.

<p:inputText id="key" binding="#{cc.key}".../> et <h:outputText binding="#{cc.lbl}".../>

Il est inutile à notre classe d'instancier quoi que ce soit, elle récupère les instances de la page.

Le champ « clé » permet de saisir directement un code constructeur, il faut donc pouvoir gérer une modification de sa valeur. C'est pourquoi lui est associée une action Ajax sur l'événement « change » rattachée à la méthode updateValue(…) de notre composant.

IV-F-2 - Partie liste de sélection

1. <!-- Liste de sélection -->

3. <p:dialog id="selectConstrDialog" widgetVar="selectConstrListWidget#{cc.clientId}"                             dynamic="true" rendered="#{cc.attrs.readOnly == false}"

4. header="Selection d'un constructeur">

5. <p:panelGrid>

6. <p:row>

7. <p:column>

8. <h:outputText value="Code"/>

9. </p:column>

10. <p:column>

11. <p:inputText value="#{foreignKeyConstrDataModel.filtreCode}" style="width:100px"/>

12. </p:column>

13. <p:column>

14. <h:outputText value="Nom"/>

15. </p:column>

16. <p:column>

17. <p:inputText value="#{foreignKeyConstrDataModel.filtreNom}" style="width:300px"/>

18. </p:column>

19. </p:row>

21. <p:row>

22. <p:column>

23. <h:outputText value="Code postal"/>

24. </p:column>

25. <p:column>

26. <p:inputText value="#{foreignKeyConstrDataModel.filtreCp}" style="width:100px"/>

27. </p:column>

28. <p:column>

29. <h:outputText value="Ville"/>

30. </p:column>

31. <p:column>

32. <p:inputText value="#{foreignKeyConstrDataModel.filtreVille}" style="width:300px"/>

33. </p:column>

34. </p:row>

36. <p:row>

37. <p:column colspan="2">

38. <p:commandButton value="Rechercher" action="#{foreignKeyConstrDataModel.loadData()}"                                 update="selectConstrList" />

39. </p:column>

40. </p:row>

41. </p:panelGrid>

44. <p:dataTable var="item" id="selectConstrList"

45. value="#{foreignKeyConstrDataModel.list}"

46. style="width:700px;padding-top:10px"

47. rowKey="#{item.code}"

48. emptyMessage="Aucun enregistrement"

49. paginator="true"

50. rows="10"

51. selectionMode="single">

53. <p:ajax event="rowSelect" listener="#{cc.updateValue}"

54. update=":#{cc.clientId}:key :#{cc.clientId}:btn :#{cc.clientId}:txt" oncomplete="PF('selectConstrListWidget#{cc.clientId}').hide()"/>

56. <p:column headerText="Code" width="80">

57. <h:outputText value="#{item.code}"/>

58. </p:column>

60. <p:column headerText="Nom">

61. <h:outputText value="#{item.nom}"/>

62. </p:column>

64. <p:column headerText="CP">

65. <h:outputText value="#{item.cp}" width="100"/>

66. </p:column>

68. <p:column headerText="Ville">

69. <h:outputText value="#{item.ville}" />

70. </p:column>

71. </p:dataTable>

72. </p:dialog>

La liste de sélection sera affichée par une boite de dialogue chargée à la demande afin d'éviter d'alourdir inutilement la page utilisatrice et de ralentir le rendu global.

La première partie de la page représente les critères de sélection, suivie de la liste de sélection.

La gestion de cette liste est confiée à un ManagedBean standard nommé foreignKeyConstrDataModel et placé dans un scope ViewScoped.

Cette page ne contient rien de particulier excepté la méthode Ajax sur la sélection d'une ligne (event rowSelect) rattachée à la méthode de notre composant updateValue(…)

Dans notre exemple, à chaque fois que la liste de sélection est appelée, les critères de sélection sont réinitialisés.

Certains pourraient vouloir récupérer les précédentes valeurs, ça dépendra des besoins, et pour le faire, il suffira de placer les critères dans un ManagedBean de scope SessionScoped et d'utiliser une référence dans le ManagedBean foreignKeyConstrDataModel.

V - Conclusion et remerciements

Nous avons vu que la création de composants était plutôt simple et qu'il était facile de les utiliser partout où nécessaire dans les pages de l'application, de la même manière que toutes les bibliothèques de composants graphiques (Primefaces, Richfaces, etc.).

D'un point de vue plus général, il serait très intéressant de coder ces modules en dehors des projets « utilisateurs ». Il suffirait alors d'intégrer le jar des composants dans la partie /WEB-INF/lib du projet web pour les utiliser.

Il suffira de créer un projet Java et d'inclure dans son répertoire /META-INF notre répertoire « resources ».

Ce répertoire contiendra, en plus des pages xhtml de définition des composants, un fichier faces-config.xml pour les ManagedBean. Ceux-ci seront alors automatiquement inclus à votre application utilisatrice.

Si vous utilisez des fichiers de propriétés (.properties) pour vos messages ou constantes, il faudra passer par un ManagedBean spécifique à votre projet. En effet, le ClassLoader de l'application utilisatrice n'est pas connu, il faut donc gérer ces éléments par une ressource liée au ClassLoader des composants.

Ensuite, vous exporterez votre projet sous forme de jar et vous n'aurez plus qu'à inclure celui-ci là où vous en avez besoin.

Je tiens à remercier Mickael Baron pour la mise au gabarit et ClaudeLELOUP pour sa relecture avisée.