Actualités

[21/06/2017] Smile dans le top 10 des entreprises où il fait bon travailler !

Smile entre dans le classement très fermé des entreprises où il fait bon débuter sa carrière. Un palmarès publié dans Les échos et réalisé par Meilleures-entreprises.com.

[20/06/2017] Smile classé 1er hébergeur en haute disponibilité depuis 3 mois

Depuis début mars, soit 3 mois consécutifs, Smile est à la tête du Classement des Hébergeurs en haute disponibilité, réalisé par ip-label et le Groupe NextRadio TV (01net, BFM, RMC).

[20/06/2017] Smile remporte l'Extending eZ Award !

Lors de l'eZ Conference 2017 qui s'est tenue du 6 au 8 juin, Smile a remporté l'Extending eZ Award.

Toutes les actualités picto
       

Vous avez besoin de mettre à jour votre Lecteur Flash Flash 7

Guillemet ouvrant l'actualité des solutions
et des technologies open source Guillemet fermant
picto

Réalisez des webflows sous Digital Factory de Jahia

L'objectif est d'apprendre à réaliser des webflows sous Digital Factory de Jahia. Cette présentation nécessite une connaissance des concepts Jahia basiques tels que la création de vues et la contribution.

Webflow dans Digital Factory

Source : GitHub

Introduction

Les webflows sont des formulaires complexes qui se présentent sur plusieurs étapes s'affichant sur plusieurs pages. Webflow n'est pas un nouveau concept mais une solution éprouvée de Spring. Sergiy Shyrkov (de Jahia) nous propose une démo de Webflow qui fera un très bon complément. Jahia nous offre aussi la transcription de la présentation de Sergiy lors de Jahia One 2014.

Cette présentation nécessite une connaissance des concepts Jahia basiques tels que la création de vues et la contribution. L'objectif est d'apprendre à réaliser des webflows sous Digital Factory de Jahia.

La grande force de Digital Factory est qu'elle fait partie des CMS où l'on maitrise 100% du code généré, nous en profiterons pour produire des formulaires accessibles pendant cette présentation.

Présentation

Nous prendrons comme exemple une démarche de mise à jour d'informations de contact de l'utilisateur courant sur plusieurs étapes.

Vue par défaut

Vue par défaut

Modification de l'adresse email

Modification de l'adresse email

Modification de l'adresse email une fois modifiée

Modification de l'adresse email une fois modifiée

Modification du numéro de téléphone fixe

Modification du numéro de téléphone fixe

Modification du numéro de téléphone mobile

Modification du numéro de téléphone mobile

Vérification

Vérification

Confirmation

Confirmation

Vue par défaut modifiée

Vue par défaut modifiée

Annulation

Annulation

Structure d'un webflow

Un webflow fonctionnant sous Digital Factory se définit par plusieurs fichiers.

Structure d'un webflow

Il est important de comprendre le rôle de chacun de ces fichiers:

  1. applicationContext-webflow.xml : webflow faisant partie de la stack Spring, il nécessite un fichier de contexte où définir des beans
  2. flow.xml : ce fichier xml est la définition du webflow, c'est à dire la liste et l'ordre des étapes du webflow ainsi que la définition des beans java utilisés par celui-ci. C'est le cœur de notre webflow.
  3. views.jsp : ces fichiers vont contenir les vues utilisées par les différentes étapes de notre webflow. Dans ces vues il y aura le code HTML des différents formulaires.
  4. Model.java : cette classe Java définit l'objet correspondant aux informations partagées par les différentes étapes du webflow. Dans notre exemple, il y aura les informations du compte telles que l'adresse email, les numéros de téléphone mobile et fixe.
  5. Handler.java : cette classe Java va contenir les traitements métiers appelés par le webflow. Dans notre exemple c'est cette classe qui va modifier un compte à partir des informations recueillies durant le webflow.

Définition du composant Jahia

Pour commencer, nous allons déclarer notre composant ainsi que son namespace dans le fichier definitions.cnd Ce fichier est localisé dans le dossier src/main/resources/META-INF/.

Nous allons créer deux namespaces dans ce fichier, un premier correspondant aux nodes types et un second correspondant aux mixins.

<wfnt = 'http://www.smile.fr/jahia/webflow/nt/1.0'>
<wfmix = 'http://www.smile.fr/jahia/webflow/mix/1.0'>

Ensuite, nous allons créer un mixin héritant de jmix:droppableContent, cela va nous permettre de créer une entrée de menu et de glisser-déposer notre composant dans une page.

[wfmix:webflowContent] > jmix:droppableContent mixin

Finalement, nous allons déclarer notre composant. Celui-ci va hériter de la mixin wfmix:webflowContent pour pouvoir être glissé-déposé, ainsi que du node type jnt:content.

[wfnt:form] > jnt:content, wfmix:webflowContent

Sauvegardez et compilez. Le composant devrait donc apparaître dans la liste des contenus du mode édition de Jahia.

Définition de la vue du composant

Dans le dossier src/main/resources, nous allons créer une arboréscence contenant les différentes vues de notre composant. Tout d’abord il faut créer un dossier correspondant au nom du composant. Le nom de ce dossier se compose de la manière suivante : "namespace du composant" + "_" + "nom du composant en camelCase". Pour notre exemple, nous allons donc nommer ce dossier wfnt_form. Dans ce dossier nous allons créer un dossier html, ce dossier contiendra les vues html.

Mise en place de Webflow

Configuration spring

Premièrement la configuration spring. Dans src/main/resources créer META-INF/spring/applicationContext-webflow.xml avec le contenu suivant:

Configuration spring

Ces deux beans sont les utilitaires basiques lors de l'utilisation d'un webflow. ModuleMessageSource permet l'utilisation des ressources bundles pour l'internationalisation de vos vues. SpringTypeConversionService permet la validation des valeurs renseignées par les utilisateurs au travers de vos formulaires.

Création du webflow

Chaque composant Jahia dispose d'une ou plusieurs vues. En général, les vues sont des jsp. Par exemple, pour le composant wfnt_form, nous pourrions avoir les vues form.jsp (la vue par défaut), form.detail.jsp (la vue détail).

Dans Jahia, webflow est intégré sous forme d'un nouveau type de vue. Pour faire une vue de type webflow, il faut créer un dossier, dont le nom se termine par .flow , contenant la définition du flow ainsi que les jsp utilisées par le flow.

Dans votre dossier de vue du composant wfnt_form, créer un sous-dossier nommé de la manière suivante : nom du composant en camelCase + "." + nom de la vue webflow + ".flow".

Comme la vue de type webflow sera la vue par défaut du composant, le nom de la vue ne doit pas être précisé. L’arborescence devrait donc ressembler à ça src/main/resources/wfnt_form/html/form.flow/.

Ce dossier contiendra d'une part les vues dédiées au webflow et d'autre part sa définition grâce au fichier flow.xml.

Dans le dossier src/main/resources/wfnt_form/html/form.flow/, créez un fichier nommé flow.xml.

Voici le code de base du webflow:

Création du webflow

Chaque étape du webflow sera à inclure dans la balise <flow /> par ce code :

<view-state id="viewName" />

Modèle

Nous allons créer une couche modèle pour manipuler les données durant notre flow.

Créez une nouvelle class Java dans un sous package *.model et nommez la ContactInfo.java par exemple. Cette classe doit implémenter la class Serializable pour pouvoir être stockée par spring webflow.

Créez les champs dont vous aurez besoin, il vous faut une variable pour chaque champ présent dans le formulaire.

Générez les getter et setter correspondant.

Modèle

Maintenant nous allons instancier et rendre disponible cette classe dans flow.xml.

Créez une balise <var /> contenant un attribut name et un attribut class. L'attribut name va correspondre au nom du bean et l'attribut class va correspondre au nom de la classe.

Le code de la balise complète:

<var name="contactInfo" class="fr.smile.jahia.model.ContactInfo"/>

Cette variable sera accessible dans notre flow et dans les vues jsp.

Traitements du webflow

Nous allons créer une classe de traitement chargée d'initialiser les données et de mettre à jour les données de l'utilisateur.

Créez une classe Java dans un package *.handler et nommez la ContactInfoHandler.

Déclarer le bean spring contactInfoHandler dans le fichier applicationContext-webflow.xml.

Traitements du webflow

Dans cette classe, nous allons créer une méthode init pour initialiser le bean contactInfo.

Traitements du webflow

La méthode prend en paramètre l'object ContactInfo déclaré dans le webflow, ainsi que le formNode qui correspond au node courant.

L'objet contactInfo est initialisé au démarrage du webflow dans une action-state de notre flow. Dans cette action, l'expression utilise contactInfoHandler qui correspond à l'identifiant du bean spring déclaré précédemment.

flow.xml

Traitements du webflow

Vues

La première vue présentera un résumé des informations de l'utilisateur connecté et proposera un lien permettant de passer en modification.

Pour cette vue display.jsp, nous pouvons utiliser ce code pour afficher les informations utilisateur :

Vues

Tester le flow

Une fois le module déployée dans Jahia, vous pouvez ajouter le composant wfnt:form sur une page afin de tester le bon fonctionnement de cette vue.

Transitions

Le bouton mettre à jour présent sur la première vue déclenche la transition vers la vue suivante :

<button id="next" class="btn btn-primary" type="submit" name="_eventId_next">

Cette transition est déclarée dans le flow pour la vue display :

<view-state id="display" model="contactInfo">
 <transition on="next" to="modifStep1" bind="false"/>
</view-state>

Il faut faire correspondre le on de la transition au name du boutton submit préfixé par _eventId_.

Pour la première étape de modification, il s'agira d'afficher un formulaire permettant de modifier l'adresse email de l'utilisateur puis de passer à l'étape suivante. Pour cela nous créons la vue modifStep1 dans le flow.xml et la jsp associée modifStep1.jsp dans le sous-dossier form.flow/ :

Transitions

Transition vers la deuxière étape

Pour la séconde étape modification du webflow, il s'agira cette fois de modifier le numéro de téléphone de l'utilisateur. Pour cela nous créons la vue modifStep2.jsp dans le sous-dossier form.flow/ :

Transition vers la deuxière étape

Création des vues et transitions restantes

Nous pouvons finaliser la partie navigation de l'application en ajoutant les vues et transitions manquantes.

L'étape modifStep3 permettra de modifier le numéro de téléphone portable de l'utilisateur et redirigera vers la vue summary. Summary résumera les modifications soumises par l'utilisateur et sur validation redirigera vers la vue success. Success affichera un message de succès et proposera un lien renvoyant sur la vue par défaut.

Création des vues et transitions restantes

Il est aussi intéressant de proposer une étape d'annulation disponible à partir de toutes les vues. On définit une transition globale grâce à la balise <global-transitions>.

Création des vues et transitions restantes

Traitement mise à jour

Dans notre handler, nous allons ajouter la méthode update pour mettre à jour les données saisies par l'utilisateur. Cette méthode va prendre en paramètre l'objet contactInfo.

Il peut également être intéressant de passer les informations du node Jahia courant afin de bénéficier de son contexte.

public void update(final ContactInfo contactInfo, final JCRNodeWrapper formNode)

Il faut ensuite lier la méthode update() à une de vos transitions.

Pour ce faire, dans le fichier flow.xml et à l'intérieur de la balise <transition/> souhaitée, ajoutez une balise <evaluate />. Cette balise doit comporter l'attribut expression qui indique le bean et la méthode à appeler. Ici nous allons modifier la transition finish de la vue summary.

Traitement mise à jour

Complétez le corps de la méthode update pour mettre à jour l'utilisateur Jahia courant.

Validation de formulaire

Webflow permet de mettre en place des mécanismes de validation des champs de formulaire. Cette validation est réalisée en suivant la spécification JSR 303.

Par exemple, pour rendre le champ email requis et devant obligatoirement être au format d'une adresse email, il suffit d'annoter le champ du bean modèle avec org.hibernate.validator.constraints.NotEmpty et org.hibernate.validator.constraints.Email.

ContactInfo.java

@NotEmpty
@Email
private String email;

Si une de ces contraintes n'est pas respectée, l'utilisateur restera sur la même étape et un message d'erreur sera affiché.

Webflow permet une customisation fine de ces message d'erreur. Il suffit d'ajouter au ResourceBundle de l'application une clé de message : nom du modèle + nom du champ en erreur + type d'erreur

Par exemple : contactInfo.email.NotEmpty=L'email ne doit pas être vide contactInfo.email.Email=L'email n'est pas valide

Les deux validateurs proposés proviennent d'Hibernate mais d'autres peuvent être trouvés par exemple dans les packages javax.validation.constraints.* et org.springframework.format.annotation.*.

Conclusion

Ce tutoriel nous a permis de découvrir une manière d'intégrer et de réaliser des IHM complexes dans Jahia avec spring-webflow. L'intégration de spring-webflow dans Jahia permet de réaliser des composants d'interfaces complexes ne se limitant pas à la manipulation de données Jahia.

Alexis Thaveau, Alexandre Gadiou, Antoine Delahay, Ferdinand Goor
picto

Commentaires

Soyez la premiere personne à ajouter un commentaire sur cet article.
Ecrire un nouveau commentaire