Create a new type of Portlet

The pages of Lutetia are composed of portlets. It is possible to define new types of portlets that will be available for page composition and add new functions. New portlets must be packaged, with their associated administrative functions, as Plugins.

This document is intended to describe the steps in the process of creating a new type of portlet. The changes to be expected concern the entire application; java, database, templates html, xsl, jsp.

The standard <type> will be used throughout the document to indicate the name of the new type of portlet.

The classes to be defined in JAVA

In Java, adding a new type of portlet involves creating three business classes: Portlet.java, PortletHome.java, PortletDAO.java belonging to the package fr.paris.lutece.portal.business.portlet and a bean used for the Web display: PortletJspBean.java belonging to the package fr.paris.lutece.plugins. <myplugin> .web.portlet which follows the description:

<type>Portlet.java

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

This inheritance imposes on the <type> Portlet class the implementation of two methods:

• public String getXml();
• public String getXmlDocument(); that return the contents of the portlet in xml format.

Similarly, it inherits accessors (set and get methods) on the properties characterizing a portlet grouped in the Portlet class as well as constants (tags) defined in the XmlContent interface.

Finally, there are two other methods needed to update the portlet:

• public void update()
• public void remove() which call the update methods of the associated DAO class as well as the different accessors that characterize the new type of portlet.

<type>PortletHome.java

It must derive from the abstract class PortletHome which itself implements the interface PortletHomeInterface.

It must therefore implement both methods :

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

The class that must function as a singleton, the method :

• public static PortletHome getInstance() is needed to access the single instance.

<type>PortletDAO.java

It must implement the interface: I <type> PortletDAO .

public class PortletDAO implements I <type> PortletDAO |

It must therefore implement the following methods of data access:

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

In addition to these essential methods, the developer is free to add in this class as many methods of access to data he desires and which are necessary for him to management of the new portlet.

<type>PortletJspBean.java

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

This involves implementing the following methods for handling portlet entry forms :

• public String getCreate( HttpServletRequest request ); : Viewing the Portlet Creation Form
• public String doCreate( HttpServletRequest request ); : Portlet creation processing
• public String getModify( HttpServletRequest request ); : Viewing the Portlet Modification Form
• public String doModify( HttpServletRequest request ); : Portlet modification processing (must call the update method of the class <Type>Portlet)
• public String getPropertiesPrefix(); : Returns the prefix of the portlet properties defined in the lutece.properties configuration file

These different methods will be called by the jsp in charge of creating and modifying a portlet. These are described below.

In addition, <type>PortletJspBean inherits the many methods of the PortletJspBean class to retrieve properties on forms to display.

Finally, this class can accommodate the definition of other methods necessary for portlets that need additional processing (for example, processing the saving of a file in a Download: DownloadFilePortlet portlet).

Note that the deletion processing of a new portlet does not need to be managed by the developer because this is supported by the AdminJspBean bean that calls the delete method redefined in <type>Portlet .

The treatment is analogous regardless of the type of portlet.

JSP

The jsp essential for the management of the new portlet are 4:

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

They use the methods of the class <type>PortletJspBean previously described :

These JSPs must also manage the authentication of the administration.

Example of JSP display : CreatePortlet<Type>.jsp

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

Processing JSP Example: 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

Several style sheets are to be developed for managing the display of the new type of portlet.

A first category concerns the display of the portlet on the site. By convention, his name is:

portlet_<type>_<suffix>.xsl where <suffix> characterizes the specification of the style sheet (for example : portlet_html_no_title.xsl).

The second category is used to display the portlet in administration mode of the site. Each style sheet in the first category must have a corresponding style sheet in the administration. Indeed, this style sheet is used for the preview of the topic in the administration module. By convention, his name is portlet_<type>_<suffix>_adm.xsl.
It's a copy of portlet_<type>_<suffix>.xsl to which you have to add the 'Edit this section' buttons, 'Delete this topic'.

All these stylesheets will have to be stored in base from the administration interface (cf paragraph Database)

HTML templates

HTML forms for entering a new portlet and modification are split into several files:

• create_portlet.html and modify_portlet.html : contain respectively the code common to the data entry and changing the different portlets
• templates specific to the concerned portlet that complete the input form by adding fields and javascript treatments specific to them.

These templates are to be added for each new type of portlet in the directory WEB-INF/templates/admin/plugins/<type>/ and must be specified in the properties file of the plugin :

category of type <type> .. |

change of section of type <type> .. |

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

However, it should be noted that the Submit() method in javascript must be defined because it is called on form validation.

For this, the developer can proceed as follows :

• use the standard scripts used by most topics: script_create_portlet.html and script_modify_portlet.html (in the directory WEB-INF/templates/admin/portlet/)
• either define the method in the specific form (like the html section).

Database

The modifications in the database concern 4 tables :

Table portlet_type :

Registration example: HTML section

This data is initialized in the database when the plugin is installed.

The plugin configuration file should therefore contain this 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 :

You must define the styles associated with this new topic style. For that, it is necessary to use Lutece's administration interface: Styles management.

Tables stylesheet and style_mode_stylesheet : The Lutece administration interface Management of xsl style sheets allows you to define new stylesheets and associate them with stored styles in the base.All style sheets developed in accordance with paragraph: XSL Style Sheets) must be saved in the database via this interface.