Exemple de XPage : Le Plugin HelloWorld

Première implémentation

Voici comment réaliser le plugin le plus simple. L'objet de celui-ci est d'afficher le texte "Hello, world!". Nous allons utiliser pour cela une XPageApplication. Le nom du plugin sera helloworld et celui de la classe d'implémentation de l'application sera HelloWorldApp . En respectant les règles de nommage et de structure des plugins, la classe sera créée dans le package fr.paris.lutece.plugins.helloworld.web .

Voici l'implémentation la plus simple de cette classe

package fr.paris.lutece.plugins.helloworld.web;

import javax.servlet.http.HttpServletRequest;

import fr.paris.lutece.portal.service.plugin.Plugin;
import fr.paris.lutece.portal.web.xpages.XPage;
import fr.paris.lutece.portal.web.xpages.XPageApplication;

public class HelloWorldApp implements XPageApplication
{
     public XPage getPage( HttpServletRequest request, int nMode, Plugin plugin )
     {
          XPage page = new XPage( );
          page.setContent( "Hello, World!" );
          page.setTitle( "Hello, World!" );
          page.setPathLabel( "Hello, World!" );
          return page;
     }
}

Dans cette première implémentation, nous créons notre page en instanciant un nouvel objet XPage pour lequel nous définissons les attributs suivants :

Cette implémentation illustre le fonctionnement de base d'une application XPage, néanmoins elle ne respecte pas certaines règles élémentaires de développement qui veulent que des éléments variables tels que des libellés ou du code HTML ne soient pas écrits "en dur" dans le code Java. Pour corriger cela, nous allons réaliser une nouvelle implémentation utilisant certains services de base de Lutèce.

Packager le plugin

Pour réaliser un plugin opérationnel, il faut à présent créer son fichier de déploiement. Celui doit être créé dans le répertoire WEB-INF/plugins et s'appelera helloworld.xml .

Voici le contenu du fichier :

<?xml version="1.0" encoding="ISO-8859-1"?>
<plug-in>
     <!-- Plugin Informations -->
     <name>helloworld</name>
     <class>fr.paris.lutece.portal.service.plugin.PluginDefaultImplementation</class>
     <version>1.0</version>
     <documentation></documentation>
     <installation></installation>
     <changes></changes>
     <user-guide></user-guide>
     <description>Exemple d'application</description>
     <provider>Mairie de Paris</provider>
     <provider-url>http://lutece.paris.fr</provider-url>
     <icon-url>images/admin/skin/plugins/helloworld/helloworld.png</icon-url>
     <copyright>Copyright 2001-2014 Mairie de Paris</copyright>
     <db-pool-required>0</db-pool-required>

     <!-- Xpage configuration -->
     <applications>
          <application>
	      <application-id>helloworld</application-id>
	      <application-class>fr.paris.lutece.plugins.helloworld.web.HelloWorldApp</application-class>
          </application>
     </applications>
</plug-in>

Il faut également créer une icône pour l'application et l'enregistrer dans le répertoire images/admin/skin/plugins/helloworld .

Voici l'icône de notre application

Deuxième implémentation

Cette deuxième implémentation va déporter le code HTML du contenu de la page dans un fichier template et les libellés du title et du PathLabel dans le fichier de propriété du plugin.

package fr.paris.lutece.plugins.helloworld.web;

import javax.servlet.http.HttpServletRequest;

import fr.paris.lutece.portal.service.plugin.Plugin;
import fr.paris.lutece.portal.service.template.AppTemplateService;
import fr.paris.lutece.portal.service.util.AppPropertiesService;
import fr.paris.lutece.portal.web.xpages.XPage;
import fr.paris.lutece.portal.web.xpages.XPageApplication;
import fr.paris.lutece.util.html.HtmlTemplate;

public class HelloWorldApp2 implements XPageApplication
{
     private static final String TEMPLATE_HELLO_WORLD = "site/plugins/helloworld/helloworld.html";
     private static final String PROPERTY_PAGE_TITLE = "helloworld.pageTitle";
     private static final String PROPERTY_PAGE_PATH_LABEL = "helloworld.pagePathLabel";

     public XPage getPage( HttpServletRequest request, int nMode, Plugin plugin )
     {
          XPage page = new XPage( );

          HtmlTemplate template = AppTemplateService.getTemplate( TEMPLATE_HELLO_WORLD );
          String strPageTitle = AppPropertiesService.getProperty( PROPERTY_PAGE_TITLE );
          String strPagePathLabel = AppPropertiesService.getProperty( PROPERTY_PAGE_PATH_LABEL );

          page.setContent( template.getHtml() );
          page.setTitle( strPageTitle );
          page.setPathLabel( strPagePathLabel );

          return page;
     }
}

cette implémentation nécessite la création d'un fichier HTML helloworld.html dans le répertoire WEB-INF/templates/skin/plugins/helloworld.

Voici le contenu de fichier :

<h1>Hello, World!</h1>

Il faut également créer un fichier helloworld.properties dans le répertoire WEB-INF/conf/plugins .

Voici le contenu de ce fichier :

# fichier de configuration du plugin helloworld

helloworld.pageTitle=Application Hello World
helloworld.pagePathLabel=Hello World

Troisième implémentation (multilingue)

Voici une dernière implémentation qui permettrait de proposer facilement l'application en plusieurs langues. Pour cela, Lutece utilise les fonctions d'internationalisation de Java à travers le service I18nService .

Pour gérer les resources en plusieurs langues il faut créer, dans le package fr.paris.lutece.plugins.helloworld.resources , les fichiers properties correspondants à chaque localisation.

• helloworld_messages.properties - langage par défaut
• helloworld_messages_fr.properties - français
• helloworld_messages_fr_FR.properties - français (France)
• helloworld_messages_fr_CA.properties - français (Canada)
• helloworld_messages_en_US.properties - anglais (Etats-Unis)
• ...

Voici le contenu du fichier helloworld_messages_fr.properties :

# fichier de ressources du plugin helloworld en français

content=Bonjour le Monde !
pageTitle=Application Bonjour le Monde 
pagePathLabel=Bonjour le Monde

Note Le fichier de configuration helloworld.properties ne sera plus nécessaire dans cet exemple.

Voici le nouveau contenu du fichier heloworld.html :

<h1># i18n { helloworld.content }</h1>

Enfin l'implémentation de l'application sera modifiée comme suit :

package fr.paris.lutece.plugins.helloworld.web;

import java.util.Locale;

import javax.servlet.http.HttpServletRequest;

import fr.paris.lutece.portal.service.i18n.I18nService;
import fr.paris.lutece.portal.service.plugin.Plugin;
import fr.paris.lutece.portal.service.template.AppTemplateService;
import fr.paris.lutece.portal.web.xpages.XPage;
import fr.paris.lutece.portal.web.xpages.XPageApplication;
import fr.paris.lutece.util.html.HtmlTemplate;

public class HelloWorldApp3 implements XPageApplication
{
     private static final String TEMPLATE_HELLO_WORLD = "site/plugins/helloworld/helloworld.html";
     private static final String PROPERTY_PAGE_TITLE = "helloworld.pageTitle";
     private static final String PROPERTY_PAGE_PATH_LABEL = "helloworld.pagePathLabel";

     public XPage getPage( HttpServletRequest request, int nMode, Plugin plugin )
     {
          XPage page = new XPage( );

          Locale locale = request.getLocale();
          HtmlTemplate template = AppTemplateService.getTemplate( TEMPLATE_HELLO_WORLD , locale );
          String strPageTitle = I18nService.getLocalizedString( PROPERTY_PAGE_TITLE , locale );
          String strPagePathLabel = I18nService.getLocalizedString( PROPERTY_PAGE_PATH_LABEL , locale );

          page.setContent( template.getHtml() );
          page.setTitle( strPageTitle );
          page.setPathLabel( strPagePathLabel );

          return page;
     }
}

Quatrième implémentation (multilingue + MVC )

Cette dernière implémentation utilise le framework MVC disponible à partir de la version Lutece 4.1

package fr.paris.lutece.plugins.test.web;

import fr.paris.lutece.portal.web.xpages.XPage;
import fr.paris.lutece.portal.util.mvc.xpage.MVCApplication;
import fr.paris.lutece.portal.util.mvc.commons.annotations.View;
import fr.paris.lutece.portal.util.mvc.xpage.annotations.Controller;
import javax.servlet.http.HttpServletRequest; 

@Controller( xpageName = "helloworld" , pageTitleI18nKey = "helloworld.pageTitle" , pagePathI18nKey = "helloworld.pagePathLabel" )
public class HelloWorldApp4 extends MVCApplication
{
    // Templates
    private static final String TEMPLATE_HELLO_WORLD = "site/plugins/helloworld/helloworld.html";
    private static final String VIEW_HELLO_WORLD = "helloWorld";

    @View( value = VIEW_HELLO_WORLD, defaultView = true )
    public XPage viewHelloWorld( HttpServletRequest request )
    {
        return getXPage( TEMPLATE_HELLO_WORLD, request.getLocale(  ));
    }
}