Lutece plugins

Lutece features can be extended by adding components called plugins. Their purpose is to integrate the different features but share a common installation mode. The common steps in order to install a plugin are :

  • Stop the Webapp
  • Unzip the binary distribution of the plugin in the webapp folder
  • [ optional] Execute scripts to create and/or initialize the tables associated to the plugin (Cf. below is to locate those scripts in different distribution )
  • [ optional ] Configure the property file of the plugin
  • [ optional ] Configure the db.properties file of Lutece to add a new specific connection pool to the plugin
  • Reload the Webapp
  • Connect to admin and go to the "Plugin Management" feature
  • The new plugin is deactivated in the plugin list. Click to activate proper installation.
  • [ optional ] Selection the connection pool possibly used by the plugin.

The extensions brought by the plugins

Many types of extension are available :

A plugin can contain one or more extension types. For example, it can introduce a new type of portlet and two administrative functions to manage this portlet type.

In summary, a plugin may contain :

  • 0 to n applications
  • 0 to n specific CSS style sheets
  • 0 to n specific Javascript
  • 0 to n back office features
  • 0 to n portlets
  • 0 to 1 content service
  • 0 to 1 indexing link services of type LinkService
  • 0 to 1 insertion services of type HtmlService
  • 0 to n filters
  • 0 to n dashboards

Plugins and databases

The plugin can access to two databases. It can access to the Lutece database through the AppConnectionService class. , but it is also possible to affect a specific connection pool by declaring it in the db.properties during the installation phase.

Plugins loading

The plugins are loaded when starting the webapp by the PluginService which searches for all XML files found in the /WEB-INF/plugins folder. To prevent loading of a plugin, the XML file must be removed from the folder.

The data concerning the local status(state installed/not-installed, specific connection pool, ...) are recorded in the plugins.dat located in the same folder.

If a plugin has a "properties" file, it must be placed into the /WEB-INF/conf/plugins folder. The property files will be automatically loaded and added to all the properties of the application. They will be accessible by means of AppPropertiesService. All plugin properties must be prefixed by the name of the plugin to avoid internal conflict.

Plugin Files

A plugin may need a large set of different file types.Here are the folders designed to contain these files.

File Type Folder
The JSPs used for administrative purpose /jsp/admin/plugins/<plugin_name>/*.jsp
The accessible JSPs from the portal /jsp/site/plugins/<plugin_name>/*.jsp
Images used by the administration features /images/admin/skin/plugins/<plugin_name>
The images used for presentation purpose /images/local/skin/<plugin_name>/*.*
The images managed as data by the plugin /images/local/data/<plugin_name>/*.*
Property file of the plugin /WEB-INF/conf/plugins/<plugin_name>.properties
Definition file of the plugin /WEB-INF/plugins/<plugin_name>.xml
The templates for the administrative features /WEB-INF/templates/admin/plugins/<plugin_name>.properties
The application's templates accessible from the portal /WEB-INF/templates/skin/plugins/<plugin_name>.properties
The jar files containing the classes of the plugin /WEB-INF/lib/plugin_<plugin_name>_<version>.jar
The SQL scripts used to install and initialize tables of the plugin (binary distribution) /WEB-INF/sql/plugins/<plugin_name>/*.sql

The organization of source files is follows :

Type of file Folder
The java source files in the business layer /src/java/fr/lutece/plugins/<plugin_name>/business/*.java
The java source files in the service layer /src/java/fr/lutece/plugins/<plugin_name>/service/*.java
The java source files in the presentation layer /src/java/fr/lutece/plugins/<plugin_name>/web/*.java
The linguistic resources of different message types /src/java/fr/lutece/plugins/<plugin_name>/resources/*.properties
The installation SQL scripts and installation script ofthe plugin tables (source distribution) /src/sql/plugins/<plugin_name>/*.sql
Documentation in XML format for Maven /src/site/xdoc/[fr/]/xdoc/plugins/<plugin_name>/*.xml

Configuration file for a plugin

The configuration file of the plugin is an XML file represented in the following structure :

<?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>Plugin description</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>

    <!-- Does the plugin require a connection pool : 1 - yes, 0 - No -->
    <db-pool-required>1</db-pool-required>

    <!-- Specific CSS style sheets eventually used  -->
    <css-stylesheets>
         <css-stylesheet>myplugin/myplugin.css</css-stylesheet>
    </css-stylesheets>
    
    <!-- Specific scripts eventually used  -->
    <javascript-files>
         <javascript-file>myplugin/myplugin.css</javascript-file>
    </javascript-files>
    
    <!-- List of administrative features eventually intreoduced be the 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>

    <!-- Portlets List eventually added by the 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>

    <!-- Applications made of XPages and evantually by a 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>

</plug-in>

A plugin dtd is availabe in the /WEB-INF/plugins folder from Lutece WebApp.

Modules

Some plugins need their own plugins. These are called modules. The plugins such as mylutece,formengine and codewizard have modules.

The rules concerning the modules are the following :

Type of file Folder
Java source files packages /src/java/fr/lutece/plugins/<plugin_name>/modules/<module_name>/**/*.java
Location of HTML template files /plugins/<plugin_name>/modules/<module_name>/**/*.html
Name and location of XML file of the plugin /WEB-INF/plugins/<plugin_name>-<module_name>.xml
Name and location of the configuration file /WEB-INF/conf/plugins/<plugin_name>-<module_name>.properties