Tutoriel pour débuter avec Liferay 7, un moteur de portlet Java

Tout d’abord, créons une nouvelle page dédiée à notre FAQ.

Allez dans le panel de gauche, déroulez « Liferay > Navigation », vous verrez « Public Pages » avec trois petits points verticaux, ce dernier représente la racine de votre arborescence de pages. Cliquez sur les trois petits points verticaux pour faire apparaître un minipanel puis cliquez sur « Add Public Page » :

Donnez un nom à votre page (ex. : FAQ), Liferay va utiliser ce nom pour l’URL qu’il va générer à cette page, il sera possible de changer l’URL après avoir créé la page.

Choisissez la disposition de votre page (ex. : 1 Column), cela servira à positionner vos Web Content et portlets sur la page lorsque vous effectuerez un glisser-déposer.

Appuyez sur le bouton bleu « Add Page » en bas de la page, pour valider la création de celle-ci.

La page que vous avez créée apparaît maintenant dans « Navigation » (présent dans le panel d’administration gauche), mais aussi dans le portlet « Navigation Menu » en haut à droite de vos pages.

Un Web Content est composé d’une « structure » et d’un « template », la structure contient vos champs de saisie (champs texte, image, calendrier, etc.).

Créons une structure contenant un champ texte pour le titre de notre FAQ, et un champ WYSIWYG pour du contenu plus élaboré.

Pour cela allez dans le panel de gauche, déroulez « Liferay > Content », vous verrez « Web Content », cliquez dessus et une nouvelle interface apparaîtra. En haut à droite de cette interface vous verrez trois petits points verticaux, cliquez dessus pour faire apparaître un minipanel, cliquez sur « Structures » :

Après avoir cliqué sur « Structures », vous serez redirigé vers l’interface des structures. Cliquez sur le bouton bleu « + » en bas de page pour ajouter une nouvelle structure :

Vous êtes redirigé vers le formulaire d’ajout de structure. Donnez un nom à votre structure (ex. : structure-faq), faites un glisser-déposer des champs que vous désirez (ex. : un champ texte pour le titre et un champ HTML WYSIWYG pour le contenu de notre FAQ), appuyez sur le bouton bleu « Save » en bas de la page pour valider la création de votre structure :

Nous avons créé notre structure, mais il nous manque toujours un template pour gérer la disposition des champs de notre structure.

Le template va contenir du code HTML et CSS (rappel : pas de JavaScript), et va intégrer les éléments de notre structure. La procédure pour créer le template est la même que celle de la structure.

Allez dans le panel de gauche, déroulez « Liferay > Content », vous verrez « Web Content », cliquez dessus et une nouvelle interface apparaîtra. En haut à droite de cette interface vous verrez trois petits points verticaux, cliquez dessus pour faire apparaître un minipanel, cliquez sur « Templates » :

Après avoir cliqué sur « Templates », vous serez redirigé vers l’interface des templates. Cliquez sur le bouton bleu « + » en bas de page pour ajouter un nouveau template :

Vous êtes redirigé vers le formulaire d’ajout de template. Donnez un nom à votre template (ex. : template-faq), déroulez « Details » et cliquez sur le bouton « Select » pour sélectionner la structure à laquelle vous souhaitez lier votre template (ex. : structure-faq), cliquez sur les éléments du champ « Fields » pour que les éléments de votre structure apparaissent dans le bloc de développement HTML/CSS, développez à votre guise*, appuyez sur le bouton bleu « Save » en bas de la page pour valider la création de votre template :

* Voici le code que j’ai utilisé pour le bloc de code (notez que j’ai utilisé l’attribut style, mais qu’il est tout à fait possible d’utiliser les classes CSS de votre site) :

<span style="text-decoration: underline; font-weight: bold">${Textaigw.getData()}</span>
<div>${HTML54xx.getData()}</div>

Nous avons créé notre template et il nous reste plus qu’à ajouter des blocs FAQ dans la page dédiée.

Le « Web Content Display » est un composant graphique générique que nous allons placer sur notre page et auquel nous allons lier notre structure.

Allez dans la page FAQ, déroulez le panel de droite en cliquant sur le « + », déroulez « Applications > Content Management » puis glisser-déposer le Web Content Display sur votre page. Une barre apparaîtra au survol de votre curseur sur le bloc que vous venez d’ajouter, cliquez sur le « + » et un minipanel avec des noms de structure apparaîtra. Cliquez sur la structure structure-faq que nous avons précédemment créée :

Une modale contenant un formulaire apparaît, donnez un titre à votre Web Content, remplissez les champs titre et le contenu de votre FAQ, par défaut le template template-faq est bien lié à la structure structure-faq, mais il est toujours possible de modifier cela, enfin cliquez sur le bouton bleu « Publish » pour valider :

Répétez l’opération jusqu’à avoir plusieurs blocs FAQ et voici le résultat final :

Nous avons vu comment créer un Web Content Liferay en créant une structure et un template, c’est très utile pour ajouter du contenu qui se répète, mais ça reste statique. Ajoutons du dynamisme à notre site, dans la prochaine partie nous attaquerons le vif du sujet avec les portlets.

Pour créer votre premier portlet, allez dans le répertoire où vous placerez vos portlets (je placerais mes projets Portlet dans le répertoire /portlets de mon workspace Liferay) et utilisez la commande ci-dessous :

mvn archetype:generate -Dfilter=liferay

Cette commande va d'abord télécharger des dépendances, puis vous demander quel archétype vous souhaitez utiliser. Saisissez le nombre 10 pour choisir l’archétype « MVC Portlet » :

10: remote -> com.liferay:com.liferay.project.templates.mvc.portlet (Liferay Project Templates MVC Portlet)

Voici un screenshot qui résume les saisies effectuées (voir l’encadré en jaune) :

Nous venons de créer un projet Maven avec les caractéristiques ci-dessous :

L'architecture du projet Maven :

/my-first-portlet
|--- /target
|--- /src
|    `--- /main
|         `--- /java
|         |    `--- /fr/ekinci/portlet/MyFirstPortlet.java
|         |
|         `--- /resources
|              |--- /content/Language.properties
|              |
|              `--- /META-INF/resources
|                            `--- init.jsp
|                            `--- view.jsp
|
|
|--- .gitignore
|--- bnd.bnd
|--- build.gradle
`--- pom.xml

Le projet contient une classe vide MyFirstPortlet qui est annotée de @Component et qui hérite d’une classe LiferayMVCPortlet. MVCPortlet est une implémentation de l’interface Portletet représente le Contrôleur de notre projet.

Diagramme de classe UML :

L’interface Portlet est composée de quatre méthodes abstraites :

L’annotation @Component est un élément OSGi, elle permet d’ajouter des métadonnées qui serviront au déploiement de notre portlet dans le portail Liferay. Retenez juste que le système OSGi permet de déployer vos portlets à chaud, sans que vous ayez besoin de redémarrer le serveur de Liferay.

VIII-C-1. Le Contrôleur▲

Voici le code source de notre contrôleur MyFirstPortlet (cliquez pour dévoiler le spoiler) :

 

Cacher/Afficher le codeSélectionnez

package fr.ekinci.portlet;

import com.liferay.portal.kernel.portlet.bridges.mvc.MVCPortlet;
import org.osgi.service.component.annotations.Component;
import javax.portlet.*;
import java.util.ArrayList;
import com.liferay.portal.kernel.log.Log;
import com.liferay.portal.kernel.log.LogFactoryUtil;

/**
 * @author Gokan EKINCI
 */
@Component(
    immediate = true,
    property = {
        "com.liferay.portlet.display-category=category.sample",
        "com.liferay.portlet.instanceable=true",
        "javax.portlet.display-name=my-first-portlet Portlet",
        "javax.portlet.init-param.template-path=/",
        "javax.portlet.init-param.view-template=/view.jsp",
        "javax.portlet.resource-bundle=content.Language",
        "javax.portlet.security-role-ref=power-user,user"
    },
    service = Portlet.class
)
public class MyFirstPortlet extends MVCPortlet {
    private static final Log LOG = LogFactoryUtil.getLog(MyFirstPortlet.class);
    private static final String LOG_HEADER = "[MY-FIRST-PORTLET]";

    @Override
    public void init (PortletConfig config) throws PortletException {
        String message = "Cette méthode est exécutée à l'initialisation du Portlet dans Liferay";
        LOG.trace(String.format("%s init() -> %s", LOG_HEADER, message));
        super.init(config);
    }

    @Override
    public void render (RenderRequest request, RenderResponse response)
        throws PortletException, java.io.IOException {
        String message = "Cette méthode est exécutée à l'affichage de la page";
        LOG.trace(String.format("%s render() -> %s", LOG_HEADER, message));

        request.setAttribute("name", "Gokan");
        request.setAttribute("age", 28);
        request.setAttribute("favoriteLanguages", new ArrayList<String>(){{
            add("Java");
            add("SQL");
            add("C");
        }});

        super.render(request, response);
    }

    @Override
    public void processAction (ActionRequest request, ActionResponse response)
        throws PortletException, java.io.IOException {
        String message = "Cette méthode est exécutée lors de la réception d'un formulaire";
        LOG.trace(String.format("%s processAction() -> %s", LOG_HEADER, message));
        LOG.trace(String.format("%s Texte du formulaire -> %s", LOG_HEADER, request.getParameter("field1")));
        super.processAction(request, response);
    }

    @ProcessAction(name = "formSentWithAlloy")
    public void formSentWithAlloy (ActionRequest request, ActionResponse response)
            throws PortletException, java.io.IOException {
        String message = "Formulaire Alloy";
        LOG.trace(String.format("%s formSentWithAlloy() -> %s", LOG_HEADER, message));
        LOG.trace(String.format("%s Texte du formulaire Alloy -> %s", LOG_HEADER, request.getParameter("field2")));
        // Ne pas utiliser super.processAction(request, response) lorsque la méthode est annotée avec `@ProcessAction`
    }

    @Override
    public void destroy () {
        String message = "Cette méthode est exécutée lors de la désinstallation du Portlet de Liferay";
        LOG.trace(String.format("%s destroy() -> %s", LOG_HEADER, message));
        super.destroy();
    }
}

Nous avons redéfini les quatre méthodes de l’interface Portletet ajouté une cinquième méthode annotée avec @ProcessAction qui vous sera expliquée dans la partie traitant les formulaires. Ces méthodes contiennent des logs que vous pourrez voir dans la console du serveur, mais avant de voir ces logs vous devez les activer.

Pour activer les logs, allez dans le panel d’administration gauche, déroulez « Control Panel > Configuration », puis cliquez sur « Server Administration ». Une nouvelle interface apparaît, cliquez sur l’onglet « Log Levels », puis sur « Add Category ». Renseignez le champ « Logger Name » avec le nom de votre package Java (ex. : fr.ekinci) et le champ « Log Level » avec le niveau du log désiré (ex. : ALL). Cliquez sur le bouton « Save » pour valider.

Cette méthode pour activer les logs n’est pas persistante, vous devrez répéter l’opération à chaque fois que vous redémarrerez le serveur Liferay.

VIII-C-2. La Vue▲

<%@ include file="/init.jsp" %>

<%-- render() | Mode Scriplet  --%>
<p>
    Salut, je m'appelle <%= request.getAttribute("name") %>, j'ai <%= request.getAttribute("age") %> ans. (Mode Scriplet)
</p>

<%-- render() | Mode EL --%>
<p>
    Salut, je m'appelle ${name}, j'ai ${age} ans. (Mode EL)
</p>

<%-- render() | Boucle JSTL --%>
<p>
    <ul>
        J'affiche mes langages informatiques favoris avec une boucle JSTL :
        <c:forEach items="${favoriteLanguages}" var="favLang">
            <li>${favLang}</li>
        </c:forEach>
    </ul>
</p>

<hr />
<hr />

<%-- Formulaires --%>
<p>
    Deux formulaires basiques :
</p>

<portlet:actionURL name="processAction" var="processAction" />
<portlet:actionURL name="formSentWithAlloy" var="formSentWithAlloy" />

<%-- processAction() | Formulaire HTML --%>
<form method="post" action="<%= processAction %>">
    <label for="field1">Texte du formulaire : </label>
    <input id="field1" name="<portlet:namespace/>field1" type="text" />
    <input type="submit" value="Envoyer formulaire vers `processAction()`" />
</form>

<hr />

<%-- processAction() | Formulaire Alloy UI --%>
<aui:form method="post" action="<%= formSentWithAlloy %>">
    <aui:input name="field2" label="Texte du formulaire Alloy : " />
    <aui:button type="submit" value="Envoyer formulaire vers `formSentWithAlloy()`" />
</aui:form>

@ProcessAction(name="nomDeVotreAction")
public void nomDeVotreMethode (ActionRequest request, ActionResponse response)
    throws PortletException, java.io.IOException {

}

<portlet:actionURL name="processAction" var="processAction" />

Une fois le développement du projet Portlet terminé, il ne reste plus qu’à le déployer.

Lancez la commande mvn package pour générer le JAR dans le répertoire /target de votre projet, puis copiez le JAR dans le répertoire /deploy de votre workspace Liferay. Vous n’avez pas besoin d’arrêter le serveur de Liferay, ce dernier se chargera d’analyser le contenu du répertoire /deploy dès qu’un nouveau JAR y sera placé.

Vous pouvez utiliser divers plugins Maven pour automatiser ce déploiement, comme en utilisant le plugin « maven-jar-plugin », par exemple.

Une fois que vous avez déployé le JAR dans le répertoire /deploy, allez dans le panel d’administration des portlets, déroulez « Applications > Sample » puis glisser-déposer votre portlet sur la page :

Voici ce que m’affiche la console lorsque j’envoie « 123456789 » sur le premier formulaire :

N’hésitez pas à observer vos logs en rafraîchissant votre page ou en cliquant sur les boutons pour envoyer les formulaires (pensez à lire la partie sur le Contrôleur pour activer vos logs).

Gogo Shell est un utilitaire qui vous permet d’analyser les portlets déployés dans Liferay.

Pour lancer Gogo Shell, ouvrez un nouveau terminal, et lancez telnet sur le port 11311 de votre machine :

telnet 127.0.0.1 11311

La commande telnet est par défaut disponible sous Linux, mais pas sous Windows. Utilisez les commandes ci-dessous pour activer/désactiver telnet sous Windows :

Vous pouvez aussi activer/désactiver telnet via l’interface graphique de Windows :

Veuillez attendre plusieurs secondes pour que le service démarre, vous pourrez ensuite utiliser la commande telnet.

Pour lister les portlets déployés dans Liferay, saisissez :

lb

Voici un aperçu :

Pour désinstaller un portlet, utilisez la commande uninstall avec le numéro de votre portlet comme indiqué dans l’image ci-dessus. Lorsque vous exécutez cette commande, la méthode destroy() de votre portlet va s’exécuter.

Si vous rencontrez un bug avec le portlet, que vous n’arrivez pas à le désinstaller, vous pouvez supprimer du contenu dans les répertoires /work et /osgi de votre workspace :

Si vous rencontrez toujours des soucis de désinstallation ou de déploiement, vous pouvez toujours redémarrer le serveur de Liferay.