Create a new portlet

The Lutece pages are composed of portlets. It is possible to define new types of portlet which will then be available for building pages and enrich with new features. The new portlets must be packaged with optional administrative features, in the form of Plugins [HOWTO - Les plugins].

This document intends to describe the main steps in order to create a new portlet. The modifications needed concern the entire application; java ,database, templates, xsl, jsp

We will refer the notation <type> to indicate the name of a new type of portlet.

The JAVA classes to be defined

The addition of a new portlet type implies the creation of three business class :Portlet.java, PortletHome.java, PortletDAO.java belonging to the fr.paris.lutece.portal.business.portlet and also a bean for web display : PortletJspBean.java belonging to the package fr.paris.lutece.plugins.<myplugin>.web.portlet which is described as the following :

<type>Portlet.java

It must derive from the abstract class : Portlet which itself implements the interface :XmlContent (package fr.paris.lutece.plugins.<myplugin>.business).

Declaration :
public class Portlet extends Portlet

This inheritance imposes the <type>Portlet class to implement two methods :

  • public String getXml();
  • public String getXmlDocument();
  • which return the portlet content in xml format.

Also, it inherits the accessors (getters and setters ) on the properties representing a portlet which are grouped in the Portlet class and in constants (tags), defined in the XmlContent interface.

Finally ,two more methods need update on the portlet :

  • public void update()
  • public void remove()
  • which call for the update methods found in the corresponding DAO and also for the accessors of the new portlet type.

<type>PortletHome.java

It must be derived from the abstract class :PortletHome which itself implements the interface : PortletHomeInterface.

Declaration :
public class MyPortletHome extends PortletHome

It must thus implement the two methods :

  • public InterfaceDAO getDAO() : returns the unique PortletDAO instance described below
  • public int getPortletTypeId() : reurns the identifier of a portlet type stored in the database

This class operates like a singleton; the method :

  • public static PortletHome getInstance() is necessary to access the unique instance.

<type>PortletDAO.java

It must implement the interface InterfaceDAO.

Declaration :
public class PortletDAO implements InterfaceDAO

It must implement the data access methods as described below :

  • public void insert( Portlet portlet ) throws AppException;
  • public void delete( int nPortletId ) throws AppException;
  • public void store( Portlet portlet ) throws AppException;
  • public Portlet load( int nPortletId ) throws AppException;

Apart these essential methods, the developer is free to add to this class any data access methods required to manage a new portlet.

<type>PortletJspBean.java

It must derive from the class : PortletJspBean which itself implements the PortletJspBeanInterface interface.

Declaration :
public class PortletJspBean extends PortletJspBean

This implies implementing the following methods for managing the portlet forms :

  • public String getCreate( HttpServletRequest request ); : Displays of the creation portlet form
  • public String doCreate( HttpServletRequest request ); : Processes the creation of the portlet
  • public String getModify( HttpServletRequest request ); : Displays of the modification form
  • public String doModify( HttpServletRequest request ); : Processes the portlet (must call to the update method of the class <type>Portlet)
  • public String getPropertiesPrefix(); : Returns the prefix of properties of the portlet defined in the configuration file : lutece.properties

These different methods are called by the JSPs responsible for the creation and modification on a portlet. They are described below :

Also, <type>PortletJspBean inherits various methods of PortletJspBean allowing it to fetch the properties of the forms to display.

Finally, this class can contain other methods for portlets requiring further processing (for example, the saving process of a file in a Download type : DownloadFilePortlet)

Please notice that the processing of the deletion of a portlet must not be managed by the developer because it is controlled by AdminJspBean which calls the delete method redefined in the <type>Portlet.

The processing is thus the same for all portlet types.

JSP

The four important JSPs in the management of a new portlet are :

  • CreatePortlet<type>.jsp
  • DoCreatePortlet<type>.jsp
  • ModifyPortlet<type>.jsp
  • DoModifyPortlet<type>.jsp

They call to the <type>PortletJspBean described before :

JSP Method of <type>PortletJspBean class
CreatePortlet<type>.jsp public String getCreate( HttpServletRequest request )
DoCreatePortlet<type>.jsp public String doCreate( HttpServletRequest request );
ModifyPortlet<type>.jsp public String getModify( HttpServletRequest request );
DoModifyPortlet<type>.jsp public String doModify( HttpServletRequest request );

These JSP must also handle authentification and administration.

Example of JSP used for display : CreatePortlet<Type>.jsp

<%@ include file="../PluginAdminHeader.jsp" %>
<jsp:useBean id="<type>Portlet" scope="session" class="fr.paris.lutece.portal.web.portlet.Portlet<Type>JspBean" />
<jsp:useBean id="user" scope="session" class="fr.paris.lutece.portal.web.user.UserJspBean" />
<%
    if( user.check( "DEF_ADMIN" ) )
    {
    %>
        <%= <type>Portlet.getCreate( request ); >
    <%
    }
    else
    {
        response.sendRedirect( user.getUrlAccesRefuse() );
    }
%>
<%@ include file="../../AdminFooter.jsp" %>

Example de JSP used for processing : DoCreatePortlet<Type>

<%@ include file="../PluginAdminHeader.jsp" %>
<jsp:useBean id="<type>Portlet" scope="session" class="mdp.portail.web.rubrique.Portlet<Type>JspBean" />
<jsp:useBean id="user" scope="session" class="mdp.portail.web.user.UserJspBean" />
<%
    if( user.check( "DEF_ADMIN" ) )
    {
         response.sendRedirect( <type>Portlet.doCreate( request ) );
    }
    else
    {
         response.sendRedirect( user.getAccessDeniedUrl() );
    }
%>
<%@ include file="../../AdminFooter.jsp" %>

The other files

XSL style sheets

Many style sheets are developed by the management of the display of a new portlet type.

A first category corresponds to the displaying of the portlet. By convention, name name is :

portlet_<type>_<suffixe>.xsl where <suffixe> specifies the style sheet (for example : portlet_html_no_title.xsl).

The second category is used to display in administration mode. Each style sheet from the first category must have a corresponding to a style sheet in administration. The style sheet is used for preview of the portlet in administration module. By convention, its name is :

portlet_<type>_<suffixe>_adm.xsl. It is a copy of portlet_<type>_<suffix>.xsl to which must be added buttons ‘Modify this portlet’, ‘Delete this portlet’.

All these style sheets must be stored in database from the administration interface (cf Database paragraph )

HTML Templates

The HTML forms of a new portlet and its modification are seperated files :

  • create_portlet.html et modify_portlet.html : contains corresponding common code for data entry forms and portlets modification.
  • Portlet's own templates correponds to data entry forms by adding corresponding to fields and javascripts.

    These templates must be added to each new portlet in the folder : WEB-INF/templates/admin/plugins/<type>/et must be specified in the plugin's properties file:

Property Description
portlet.<type>.create.title Title of the form for adding portlet of type <type>
portlet.<type>.create.url Url of the jsp which manages addtion of a portlet of type <type>
portlet.<type>.create.script Javascript used in the form to add portlet of type <type>.
portlet.<type>.create.specific The name of the template which contains specific code for portlet of type <type>
portlet.<type>.create.specificform Name of file template which contains code from another form to add next to the existing one, used to create a portlet of type <type>..
portlet.<type>.modify.title Title of portlet type modification form <type>
portlet.<type>.modify.url Url of a jsp which handles update of a portlet type <type>
portlet.<type>.modify.script Specific javascript used by the update form of portlet type <type>.
portlet.<type>.modify.specific Template which contains specific code specific to the portlet type <type>
portlet.<type>.modify.specificform Name of file template which contains code from another form to add next to the existing one, used to modify a portlet of type <type>..

Only the properties : portlet.<type>.create.title, portlet.<type>.create.url, portlet.<type>.modify.title and portlet.<type>.modify.url are mandatory.

Nevertherless, the javascript Submit() method must be defined as it is required for form validation.

To achieve this, the developer can proceed as follows :

-use the standards respected by most portlets : script_create_portlet.html and script_modify_portlet.html (in the Web-inf/templates/admin/portlet/ folder )

- or define the method in the specific form (contrarily to HTML portlet).

Database

The modification in the database concerns 4 tables :

Table portlet_type :

Name of the field Description
id_portlet_type Portlet identifier.
name Portlet's type label(label that will be displayed in scrolling menus)
url_creation Url of the JSP which displays input form of the portlet
url_update Url of the JSP which displays the update form of the portlet
home_class Complete Name (package included) in the class <type>PortletHome of the new Portlet type

Example record : HTML Portlet

id_portlet_type name url_creation url_update home_class
1 Normal text or HTML CreatePortletHtml.jsp ModifyPortletHtml.jsp fr.paris.lutece.plugins.html.business.portlet.HtmlPortletHome

The data is initialised in the database during installation.

The configuration of the plugin will thus contain information in the form

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

Table style :

A style corresponding to the new portlet type must e defined. This is done by using Lutece administration : : Style Management.

Tables stylesheet and style_mode_stylesheet :

Administration interface of Lutece :XSL stylesheets management allows definition of new styles and to link them to those stored into the database. All the stylesheets developed according to paragraph : XSL stylesheets must be stored by using this interface.