Nov 29, 2019 10:53:22 PM Thomas Dumont avatar   3143

Lutece plugins


Introduction

Plugins are components that can be added to Lutece to extend its functionality. They are intended to integrate different types of features by respecting the same mode of installation. The common step of installing a plugin is as follows :

  • Stop the Webapp
  • Unzip the plugin binary distribution in the webapp directory
  • optional Execute the scripts for creating and / or initializing the tables associated with the plugin (see below to locate these scripts in different distributions)
  • optional Configure plugin properties file
  • optional Configure the Lutece db.properties file to add a new specific connection pool to the plugin
  • Restart the Webapp
  • Log in ad Admin and go to the Manage plugins function
  • The new plugin should appear not installed in the list of plugins. Click on Install.
  • optional Select the connection pool that may be used by the plugin.

Extensions brought by the plugins

Several types of extensions are planned :

A plugin can contain one or more of these types of extensions. By example, it can introduce a new type of portlet and two administration functions to handle this type of portlet.

Plugins and databases

A plugin can access two databases. he can access the Lutece database through the class AppConnectionService, but it is also possible to assign a specific connection pool to it, declared in the db.properties configuration file.

Loading plugins

The plugins are loaded at the start of the webapp by the service PluginService that searches all XML files in the /WEB-INF/plugins directory. To not load a plugin, just remove the XML file from this directory.

Information about the local status of plugins (status installed/uninstalled, specific connection pool, ...) are saved in the plugins.dat file located in the same directory.

If a plugin has a properties file, it must be found in the directory /WEB-INF/conf/plugins. The properties of this plugin will be automatically loaded and added to the properties of the application. They will then be accessible through the class AppPropertiesService.
All properties of a plugin must be prefixed by the name of the plugin to avoid especially any conflict.

The plugin files

A plugin may require a fairly large set and various files. Here are the directories designated for hold these files :

File Type Directory
JSP administrative functions /jsp/admin/plugins/<plugin_name>/*.jsp
Accessible JSPs from the portal /jsp/site/plugins/<plugin_name>/*.jsp
Administration function images /images/admin/skin/plugins/<plugin_name>
Presentation images of the application /images/local/skin/<plugin_name>/*.*
Images managed as plugin data /images/local/data/<plugin_name>/*.*
Plugin properties file /WEB-INF/conf/plugins/<plugin_name>.properties
The plugin definition file /WEB-INF/plugins/<plugin_name>.xml
Administrative function templates /WEB-INF/templates/admin/plugins/<plugin_name> .properties
Application templates accessible from the portal /WEB-INF/templates/skin/plugins/<plugin_name>.properties
The jar file containing the plugin classes /WEB-INF/lib/plugin_<plugin_name>_<version>.jar
SQL scripts for installing and initializing plugin tables (binary distribution) /WEB-INF/sql/plugins/<plugin_name>/*.sql

The organization of the source files is also the following

File Type Directory
Java source files for the business layer /src/java/en/lutece/plugins/<plugin_name>/business/*.java
Java source files from the service layer /src/java/en/lutece/plugins/<plugin_name>/service/*.java
Java source files of the presentation layer /src/java/en/lutece/plugins/<plugin_name>/web/*.java
Message type resources in different languages ​​/src/java/en/lutece/plugins/<plugin_name>/resources/*.properties
SQL scripts for installing and initializing plugin tables (source distribution) /src/sql/plugins/<plugin_name>/*.sql
Documentation in XML format for Maven /src/site/xdoc/[en/]/xdoc/plugins/<plugin_name>/*.xml

The plugin configuration file

The configuration file of a plugin is an XML file like :

<?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>

    <db-pool-required>1</db-pool-required>

    <!-- CSS Stylesheets -->
    <css-stylesheets>
        <css-stylesheet>myplugin/myplugin.css</css-stylesheet>
        ...
    </css-stylesheets>

    <!-- JavaScript Files -->
    <javascript-files>
        <javascript-file>myplugin/myplugin.css</javascript-file>
        ...
    </javascript-files>

    <!-- Administration Features-->
    <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-->
    <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 -->
    <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 Services -->
    <content-services>
        <content-service-class>fr.paris.lutece.plugins.myplugin.service.MyContentService</content-service-class>
        ...
    </content-service>

    <!-- Insert Services -->
    <insert-services>
        <insert-service>
            <insert-service-id>my_insert_service</insert-service-id>
            <insert-service-name>myplugin.insertService.name</insert-service-name>
            <insert-service-label>myplugin.insertService.label</insert-service-label>
            <insert-service-bean-class>fr.paris.lutece.plugins.myplugin.web.MyInsertServiceJspBean</insert-service-bean-class>
        </insert-service>
        ...
    </insert-services>

    <!-- Servlets-->
    <servlets>
        <servlet>
            <servlet-name>myServlet</servlet-name>
            <url-pattern>/servlet/plugins/myplugin/myServlet</url-pattern>
            <servlet-class>fr.paris.lutece.plugins.myplugin.web.MyServlet</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>

A plugin DTD is available in the directory /WEB-INF/plugins of the Lutece Webapp.

Modules

Some plugins may have their own plugins. These are called modules. Plugins such as mylutece, formengine, codewizard have modules.

The rules for the modules are as follows :

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