May 29, 2014 4:10:10 PM lutece lutece avatar   881    

Les plugins de Lutece

Introduction


Les plugins sont des composants que l'on peut ajouter à Lutèce pour étendre ses fonctionnalités. Ils ont pour vocation d'intégrer différents types de fonctionnalités en respectant le même mode d'installation. La démarche commune d'installation d'un plugin est la suivante :

  • Arrêter la Webapp
  • Dézipper la distribution binaire du plugin dans le répertoire de la webapp
  • [ facultatif] Exécuter les scripts de création et/ou d'initialisation des tables associées au plugin (Cf. ci-dessous pour localiser ces scripts dans les différentes distributions)
  • [ facultatif ] Configurer le fichier properties du plugin
  • [ facultatif ] Configurer le fichier db.properties de Lutece pour ajouter un nouveau pool de connexions spécifique au plugin
  • Relancer la Webapp
  • Se connecter en Admin et se rendre dans la fonction Gestion des plugins
  • Le nouveau plugin doit apparaitre non installé dans la liste des plugins. Cliquer sur Installer.
  • [ facultatif ] Sélectionner le pool de connexions éventuellement utilisé par le plugin.

Les extensions apportés par les plugins

Plusieurs types d'extensions sont prévues :

  • nouveau type de porlet [ Portlets]
  • nouvelle application intégrée [ Application]
  • nouvelle fonctionnalité d'administration [ Fonctions d'administration]
  • nouveau service de contenu [ ContentServices]
  • nouveau service d'insertion de liens [ InsertServices]
  • nouveau service d'inclusions de page [ PageIncludeServices]
  • nouvelle servlet ou filtre de servlet [ PageIncludeServices]

Un plugin peut contenir un ou plusieurs types d'extensions. Par exemple, il peut introduire un nouveau type de portlet et deux fonctions d'administration pour gérer de ce type de portlet.

En résumé, un plugin peut contenir :

  • 0 à n applications
  • 0 à n feuilles de style CSS spécifiques
  • 0 à n scripts Javascript spécifiques
  • 0 à n fonctions d'administration
  • 0 à n portlets
  • 0 à 1 service de contenu
  • 0 à 1 services d'insertion de type LinkService
  • 0 à 1 services d'insertion de type HtmlService
  • 0 à n servlets ou filtres de servlet
  • 0 à n tableau de bord (dashboard)

Les plugins et les bases de données

Un plugin peut accéder à deux bases de données. Il peut accéder à la base Lutece par le biais de la classe AppConnectionService , mais il est également possible de lui affecter un pool de connexions spécifique, préalablement déclaré dans le fichier db.properties , au moment de son installation.

Chargement des plugins

Les plugins sont chargés au démarrage de la webapp par le service PluginService qui recherche tous les fichiers XML se trouvant dans le répertoire /WEB-INF/plugins . Pour ne pas charger un plugin, il suffit de retirer le fichier XML de ce répertoire.

Les informations sur le statut local des plugins (état installé/non-installé, pool de connection spécifique, ...) sont enregistrées dans le fichier plugins.dat situé dans le même répertoire.

Si un plugin dispose d'un fichier properties, celui doit se trouver dans le répertoire /WEB-INF/conf/plugins . Les propriétés de ce plugins seront automatiquement chargées et ajoutées à l'ensemble des propriétés de l'application. Elles seront alors accessibles par le biais de la classe AppPropertiesService . Toutes les propriétés d'un plugin doivent être préfixées par le nom du plugin pour éviter notamment tout conflit.

Les fichiers des plugins

Un plugin peut nécessiter un ensemble assez important et divers de fichiers. Voici les répertoires désignés pour contenir ces fichiers

Type de fichierRépertoire
Les JSP des fonctions d'administration/jsp/admin/plugins/<plugin_name>/*.jsp
Les JSP accessibles du portail/jsp/site/plugins/<plugin_name>/*.jsp
Les images des fonctions d'administration/images/admin/skin/plugins/<plugin_name>
Les images de présentation de l'application/images/local/skin/<plugin_name>/*.*
Les images gérées comme des données du plugin/images/local/data/<plugin_name>/*.*
Le fichier properties du plugin/WEB-INF/conf/plugins/<plugin_name>.properties
Le fichier de définition du plugin/WEB-INF/plugins/<plugin_name>.xml
Les templates des fonctions d'administration/WEB-INF/templates/admin/plugins/<plugin_name>.properties
Les templates de l'application accessibles du portail/WEB-INF/templates/skin/plugins/<plugin_name>.properties
Le fichier jar contenant les classes du plugin/WEB-INF/lib/plugin_<plugin_name>_<version>.jar
Les scripts SQL d'installation et d'initialisation des tables du plugin (distribution binaires)/WEB-INF/sql/plugins/<plugin_name>/*.sql

L'organisation des fichiers sources est par ailleurs la suivante

Type de fichierRépertoire
Les fichiers sources java de la couche métier/src/java/fr/lutece/plugins/<plugin_name>/business/*.java
Les fichiers sources java de la couche service/src/java/fr/lutece/plugins/<plugin_name>/service/*.java
Les fichiers sources java de la couche présentation/src/java/fr/lutece/plugins/<plugin_name>/web/*.java
Les ressources de type messages dans les différentes langues/src/java/fr/lutece/plugins/<plugin_name>/resources/*.properties
Les scripts SQL d'installation et d'initialisation des tables du plugin (distribution sources)/src/sql/plugins/<plugin_name>/*.sql
Les documentations au format XML pour Maven/src/site/xdoc/[fr/]/xdoc/plugins/<plugin_name>/*.xml

Le fichier de configuration du plugin

Le fichier de configuration d'un plugin est un fichier XML se présentant sous la forme suivante :

<?xml version=1.0 encoding=ISO-8859-1?>
<plug-in>
      <name>myplugin</name>
      <class>fr.paris.lutece.portal.service.PluginDefaultImplementation</class>
      <version>1.0</version>
      <description>Description of the plugin</description>
      <provider>Mairie de Paris</provider>
      <provider-url>http://lutece.paris.fr</provider-url>
      <icon-url>../../images/admin/skin/plugins/myplugin/myplugin.gif</icon-url>
      <copyright>Copyright (c) 2001-2008 Mairie de Paris</copyright>

      <!-- Le plugin requiert-il un pool de connexions : 1 - oui, 0 - non -->
      <db-pool-required>1</db-pool-required>

      <!-- Feuilles de style CSS spécifiques éventuelles -->
      <css-stylesheets>
      <css-stylesheet>myplugin/myplugin.css</css-stylesheet>
      </css-stylesheets>

      <!-- Scripts eventuels -->
      <javascript-files>
             <javascript-file>myplugin/myplugin.css</javascript-file>
      </javascript-files>

      <!-- Listes des fonctionnalités d'administration éventuellement introduites par le plugin-->
      <admin-features>
             <admin-feature>
                    <feature-id>MYFEATURE_MANAGEMENT</feature-id>
                    <feature-title>My Feature</feature-title>
                    <feature-description>Description of my feature</feature-description>
                    <feature-level>3</feature-level>
                    <feature-url>plugins/myplugin/ManageMyFeature.jsp</feature-url>
             </admin-feature>
...
      </admin-features>

      <!-- Listes des portlets éventuellement introduits par le plugin-->
      <portlets>
             <portlet>
                    <portlet-class>fr.paris.lutece.plugins.myportlet.business.portlet.MyPortletHome</portlet-class>
                    <portlet-type-name>MyNew Portlet</portlet-type-name>
                    <portlet-creation-url>plugins/article/CreatePortletMyPortlet.jsp</portlet-creation-url>
                    <portlet-update-url>plugins/article/ModifyPortletMyPortlet.jsp</portlet-update-url>
             </portlet>
...
      </portlets>

      <!-- Application à base de pages spéciales introduite éventuellement par le plugin -->
      <applications>
             <application>
                    <application-id>app_page_name</application-id>
                    <application-class>fr.paris.lutece.plugins.myplugin.web.MyPluginApp</application-class>
                    <application-roles>role1,role2</application-roles>
             </application>
      </applications>

      <!-- Content Service -->
      <content-service>
             <content-service-class>fr.paris.lutece.plugins.myplugin.service.MyContentService</content-service-class>
      </content-service>

      <!-- Links Service -->
             <link-service>
                    <link-service-id>mylinkservice</link-service-id>
                    <link-service-class>fr.paris.lutece.plugins.mylinkservice.service.MyLinkService</link-service-class>
                    <link-service-bean-class>fr.paris.lutece.plugins.mylinkservice.web.MyLinkServiceJspBean</link-service-bean-class>
                    <link-service-label>Link to my URIs</link-service-label>
             </link-service>

      <!-- Servlets-->
      <servlets>
             <servlet>
                    <servlet-name>myServlet1</servlet-name>
                    <url-pattern>/servlet/plugins/myplugin/myServlet1</url-pattern>
                    <servlet-class>fr.paris.lutece.plugins.myplugin.web.MyFirstServlet</servlet-class>
             </servlet>
             <servlet>
                    <servlet-name>myServlet2</servlet-name>
                    <url-pattern>/servlet/plugins/myplugin/myServlet2</url-pattern>
                    <servlet-class>fr.paris.lutece.plugins.myplugin.web.MySecondServlet</servlet-class>
             </servlet>
      </servlets>

      <!-- filters -->
      <filters>
             <filter>
                    <filter-name>myFilter</filter-name>
                    <url-pattern>/*</url-pattern>
                    <filter-class>fr.paris.lutece.plugins.myplugin.web.MyFilter</filter-class>
                    <init-param>
                           <param-name>param1</param-name>
                           <param-value>value of param1</param-value>
                    </init-param>
             </filter>
      </filters>

</plug-in>

Une DTD des plugins est disponible dans le répertoire /WEB-INF/plugins de la Webapp de Lutece.

Modules

Certains plugins peuvent avoir leurs propres plugins. Ceux-ci sont appelés modules. Les plugins tels que mylutece, formengine, codewizard disposent de modules.

Les règles concernant les modules sont les suivantes :

Type de fichierRépertoire
Packages des fichiers sources java/src/java/fr/lutece/plugins/<plugin_name>/modules/<module_name>//*.java
Localisation des fichiers templates HTML/plugins/<plugin_name>/modules/<module_name>//*.html
Nom et emplacement du fichier XML du plugin/WEB-INF/plugins/<plugin_name>-<module_name>.xml
Nom et emplacement du fichier de configuration/WEB-INF/conf/plugins/<plugin_name>-<module_name>.properties