Liferay Development Standards

Standards

LIFERAY DEVELOPMENT STANDARDS

STANDARDS

LIFERAY DEVELOPMENT STANDARDS

Document type:

working

 validation in progress

 approved for distribution

Reference: ND_Normes-Developpement-Liferay.docx

Purpose of the document

The purpose of this document is to describe the standards for developing aLiferay application at the CoE.

NB: Any non-compliance with the standards or practices described in this document must be reported by the supplier prior to the start of works and validated by the Council of Europe (DIT).

This document is the property of the Council of Europe.

It may not be reproduced or communicated without the prior agreement of the author.

Contents

Purpose of the document

Contents

1Introduction

1.1Purpose

1.2Warning signs used in this document

1.3Reference documentation

2Good practices for Liferay Portal developments

2.1General points

2.1.1USE of Transversal Tools

2.1.2Normes - Liferay development standards

2.1.3Common sources of the web platform

2.1.4Structures and Templates

2.1.5Management of roles

Liferay version used

Technical environment used

2.1.6Heavy processing

2.1.7Using external bases

2.1.8Theme, template, css

2.2Using metadata

2.3JSP overloading (DIT validation required)

2.4When to use the EXT environment? (DIT validation required)

2.5Using the portal-ext.propertiesfile

2.6Using the portal-INSTANCE_WEB_ID.propertiesfile

2.7Extending the Liferay base

2.8Developing a theme

2.8.1Naming

2.9Developing a Layout

2.9.1Naming

2.10Developing a webcontent template

2.11Liferay plugins SDK

2.12Developing a portlet plugin

2.12.1Naming

2.13Organisation of portlets in the SDK

2.14Adding translations

2.14.1Translation of the portal

2.14.2Translation of a portlet

2.15Defining naming rules for portlet properties

2.16User preferences for portlets

2.17Defining a naming rule for custom attributes

2.18Location and naming rules

2.19Using the Service Builder / database

2.20Using loggers

2.21Rule for managing messages in the log file

2.22Miscellaneous points

2.23Javascript integration within a portlet

2.23.1Loading the CSSs specific to the portlet

2.23.2Loading the Javascript files specific to the portlet

2.23.3Resources loading level

2.24Sources contained in the sources manager

2.25Setting up a specific compilation

2.26Restricting the visibility of new portlets

2.26.1Portlet visible only in backoffice

2.26.2Portlet visible at the level of an instance

2.26.3Portlet visible at the level of one or more sites

1Introduction

1.1Purpose

This document sets out the standards to be applied when developing a Liferay-based application for the Council of Europe.

All the rules described in this document must be scrupulously complied with, and corresponding checks will be made on each delivery.

For the standards governing implementation of applications in general, please refer to the document describing the Council of Europe information system standards enclosed with the developer's toolkit.

Failure to comply with the standards and norms of the Council of Europe may result in a delivery being rejected.

1.2Warning signs used in this document

The following pictograms are used throughout this document to emphasise important points or ideas.

/ Important information
/ Risk relating to parametering or a specific action
/ Action to be avoided
/ Action mandatory

1.3Reference documentation

/ It is imperative that the following documentation, contained in the developer's toolkit, be taken into account for developments:
JS/CSS/HTML documentation
SVN documentation
J2EE documentation
Graphic charter

2Good practices for Liferay Portal developments

2.1General points

2.1.1USE of Transversal Tools

The Council of Europe has implemented a number of transversal tools to meet the Organisation’s needs:

-Recordsmanagement (RMS – Records Management System)

-Document management (DMS)

-Photolibrary

-Videolibrary

-Meta directory

-Enterprise search

-CAS-SSO

The tools listed above must be used for any new solution implementing one or many of the functionalities already covered by these tools unless written derogation from the DIT.

2.1.2Normes - Liferay development standards

Any specificdevelopment must be carried out in compliance with the Liferay development standards.

2.1.3Common sources of theweb platform

No changes must be made to the common sources of the Liferaywebplatform, whether to Liferay "standard"source files or to source files linked to developments carried out specifically for the implementation of a shared solution.

Should modification of these common sources be considered to be absolutely necessary, it is imperative to request validation by the DIT.

2.1.4Structures and Templates

The structures and templates are versioned in the source control tool (templates_structures folder).

The structures and templates must be validated by DIT to avoid any conflict with existing structures and templates.

2.1.5Management ofroles

Therolesused onthe Council of Europe's Liferay platform are not thebasic rolesof Liferay, except for guest, user,site member, site owner and administrator. The"administrator"roleis allocated only to those providing technicalsupport for the web platform (DIT).

The maingeneric rolesestablished on theweb platformare briefly described in the table below.

Name ofrole / Description
0 – Guest / Unauthenticated site user who can just browse the public pages of CoE sites.
1 – User (USR) / Authenticated user who can browse the public pages of CoEsites and, by default, participate in the use of all thecollaborative tools(forum, wiki, blogs, comments etc)unless a specific restriction applies.
2 – Contributor (CTB) / Has permissions to create webcontent (articles) and edit webcontent (articles).
3 – Reviewer (RVW) / Has permissions to validatewebcontent (articles) submitted for validation and to disable webcontent (articles).
4 – Editor (EDT) / Has permissions tocreate and edit pages.
Also has permissions to assign layouts and to
add and delete applications.
Can access / add / administrate the applications below:
5 Publisher (PBL) / Has permissions to publish/unpublish pages, the contents of pages or a whole site. Also has permissions to delete pages.
Can access / add / administrate the applications below:
6 Site administrator (SAM) / Has permissions to manage user access.
Can access / add / administrate the applications below:
-Asset publisher
-Blog and Recent bloggers
-Forum
-Calendar
-Iframe
-Page Comments
-Page Flags
-Page RatingsTag admin
-Polls
-Wiki
-XSL Content
7 Super Site Administrator (SSA) / Has permissions to manage all the sites of a given instance
8 Administrator / Overall administrator of the application and all the sites.

These specific roles are"site roles". The rights and permissions assigned to each role may be subject to modification.

For a detailed description of the rights of the differentroles, please ask the DIT project coordinator.

Any specific need regarding the setting up of new roles must be validated by the DIT.

Liferay version used

The Liferay version used at present is: 6.2.10 EE

Technicalenvironment used

The following choices have been made with regard to theLiferaytechnical environment

-Javavirtual machine: 1.7.0_91

-Application server: Tomcat 7.0.42

-Database server: MySQL 5.4.42

2.1.6Heavy processing

You are advised not to incorporate heavy application processing at the level of the internet platform.

The following types of processing must be carried out in a dedicated environment (full application, background processing etc)

-report generation

-major background processing

-…

2.1.7Using external bases

Access to external bases will be read-only, and web services will be the preferred means of retrieving external data. Otherwise, views will have to be created on the database.

2.1.7.1.Using an SQL connection

2.1.7.1.1.Retrieving the connection

Ifaccessto adatabase is required, a connection pool must be set up for that base.

Directdatabase accessis prohibited.

It is recommendedthat views or stored procedures are used forqueries. In all cases, if adaptations of views orstored proceduresarenecessary, they will have to be carried over in the project sources managingthe database in question.

Exampleof set-up:

The configuration files will have to be integrated in thecompilation processso that they can beparametered (cf 2.25Setting up a specific compilation )

Rule for naming the resource

PORTLETNAME_DATABASENAME

Declaring the resource in the context

In your project you must add thefollowing file: /docroot/META-INF/context.xml

Contextreloadable="true"

Resource

name="jdbc/XXXXXXXXXX"

auth="Container"

type="javax.sql.DataSource"

factory="org.apache.commons.dbcp.BasicDataSourceFactory"

driverClassName="XXXXXXXXXX"

url="XXXXXXXXXX"

username="XXXXXXXXXX"

password="XXXXXXXXXX"

maxActive="100"

maxIdle="30"

maxWait="10000"

validationQuery="select 1"

testOnBorrow="true"

testWhileIdle="true"

timeBetweenEvictionRunsMillis="10000"

minEvictableIdleTimeMillis="60000"

removeAbandoned="true"

removeAbandonedTimeout="60"

logAbandoned="true"

/>

</Context

Declaring the resource in the webapp

In theweb.xml file, you must add this section:

<resource-ref>

<res-ref-name>jdbc/XXXXXXXX</res-ref-name>

<res-type>javax.sql.DataSource</res-type>

<res-auth>Container</res-auth>

</resource-ref>

Retrieving the datasource

Context envContext = new InitialContext();

DataSource ds = (DataSource)JNDIUtil.lookup(envContext,"jdbc/XXXXXX");

con = ds.getConnection();

2.1.7.1.2.Releasing the connection

TheSQL connections must be properly closed in a finallyblock

A utility could be installed to simplify the writing of the finallyblock

Example:

try {

//connection in use

} catch (Exception e) {

logger.error("Error in sql", e);

} finally{

if (rs != null) {

try {

rs.close();

} catch (SQLException e) {

logger.error("SQL Error : Could not close the Result Set");

}

}

if (p != null) {

try {

p.close();

} catch (SQLException e) {

logger.error("SQL Error : Could not close the Query");

}

}

if (con != null) {

try {

con.close();

} catch (SQLException e) {

logger.error("SQL Error : Could not close the Connection");

}

}

}

2.1.8Theme, template, css

Any addition / modification of theme, page template or CSSmust be validated by the Directorate of Communication.

Anyspecific need regarding thethememust be dealt with as follows:

-in the event of a minor change to the standard theme supplied by Directorate of Communication (eg: additional specific settings), if possible apply the change to the standard theme after having had it validated by the Directorate of Communication (where this change can be shared for all the Council of Europe's sites);

-in the event of a change to the standard theme not intended to be shared for all sites, carry out an extension of theexisting standardtheme;

-for a very specific need, create a newthemeas an extension to theclassic Liferaytheme.

2.2Using metadata

The Council of Europe's sharedmetadata will be made availableon each Liferayinstance. This data source should be deployed if these lists must be used forspecific needs.

The following Liferay services will provide access to this information:

//retrieval of a category (metadata item value)

AssetCategory category = AssetCategoryLocalServiceUtil.getAssetCategory(categoryId);

//retrieval of a vocabulary item (metadata)

AssetVocabulary vocabulary = AssetVocabularyLocalServiceUtil.getAssetVocabulary(category.getVocabularyId());

DEVELOPINGPORTLET PLUGINSWITH THEPLUGINSSDK

A plugin fordevelopingportlets has been created by Liferay. Thisdevelopment plugin provides ANT scripts for compilation, building of WAR files anddeployment. For eachstable version of the product, Liferay supplies (via a download) anadequate developmentkit for customising the product anddeveloping newplugins to meet thedifferentfunctional requirements.

2.3JSP overloading (DIT validation required)

It isrecommendedthat you follow the steps below if the project requires the overloading of certainJSPfiles of native Liferayportlets

• Copy the portlet file from the Liferaysources: webapps/ROOT/html
• Add a header to each fileas in the example below:

<%

* Project name: COE

* Liferay version: Liferay 6.1.x

* Modification: Adding previewbuttonin theblog portlet

* Author: surnamefirst name

%>

If the page to be modified contains a lot of customisations, it ispreferable to place thesecustomisations in aseparate file and include it in theoriginal page using an"include"as in the example below:

<%@ include file="/html/portlet/calendar/init.jsp" %>

2.4When to use the EXT environment? (DIT validation required)

It isrecommendedthatdevelopmentbe carried out in the Liferay extension environment only when necessary, as in the following cases(the server must be rebooted after EXT deployment):

• Customising the Liferayportal (appearance, organisation, overloading of classes,SSO connection, LDAP etc)
• Deploying the Liferay portal in its application server.

In all cases, any modification of the EXT environment requires the prior agreement of the DIT (risk of conflict).

The extension environment provides a set of ANT tasks making it possible to automate deployment to the application server:

• Overloading of authentication phase (SSO, LDAP, NTLM etc)
• Overloading of LDAP synchronisation,
• Creation of businessclasses supplementingnative Liferayobjects,
• Creation of Liferay WebServices to communicate with other applications,
• Portal customisation (Groupsbydefault, compression of javascripts etc),
• Modification ofLiferayStruts actions
• Modification ofLiferaySpring config
• Addition of afilterin web.xml
• Use of.jar dependencyshared between severalportletresources, hooks…
• Addition /configuration of the Portal-ext.properties file
• etc.

The tree structure of the extension environment is as follows:

• "ext-impl": Liferay overloadingjavaclassesand configuration files,
• "ext-lib/portal": these libraries are deployed in the "WEB-INF/lib"directory of the Liferay web app. They are therefore visible to the portal.
• "ext-lib/global": these libraries are deployed in the Tomcat "common/lib/ext" for example.
• "ext-service": classes generated by Service Builder (remote or local services)
• "ext-web": overloading of the web part of Liferay.

To summarise, the importantfolders are:

• "ext-impl"
• "ext-web"

The main overloading files are:

• "/ext/ext-impl/classes/portal-ext.properties": this file is used to overload the value of the properties of the "portal.properties" source file.
• "/ext/ext-impl/classes/system-ext.properties": this file is used to overload the value of the properties of the "system.properties"source file.
• "/ext/ext-impl/classes/content/Language-ext.properties": this file is used to overload the value of thelanguagekeys orcreate others. Files specific to each language can be created. Examplefor Spanish: Language-ext_es.properties.

ThedifferentANT scripts available in the extension environment make it possible to deploy all or part of the portal.

• "clean": removes all traces of compilation anddeployment,
• "deploy": is used for compilation, file merging anddeployment of all modules,
• "deploy-impl-jar": is used for compilation, building the jar file and deploymentofLiferay implementation classes
• "deploy-properties": merges anddeploysonly the Liferay propertiesfiles
• "deploy war": deploys the war file already built.

The "build.xml" files located in the "ext-impl", "ext-service" and "ext-web" files aremore specific ANT sub-tasks.

2.5Using the portal-ext.propertiesfile

The "portal-ext.properties"settings file makes it possible to overload the portal.propertiesreference file. The latter containsALLtheparameters, with theirdefault values. Otherproject-specific parametersmay bedefined in this file (Url in a portlet, parameters, size of a resource, default valueetc). The"portal-ext.properties" settings filemust be placed under /webapps/ROOT/WEB-INF/classes/.

If using settingsspecific to the environment (SMTPaddress, IPaddressof the server, apache serveretc), you are advised toseparate the 2 files:

• portal-ext.propertiesin: /webapps/ROOT/WEB-INF/classes/: containing theparametersthat do notdepend on the environment;
• portal-ext.propertiesin: TOMCAT_HOME: containing theenvironment-specific parameters.

This solution allows you to simplifydeployment and have the same deliverable for thedifferent environments.

An example of the adding ofproperties keys to the "portal-ext.properties” is shown below:

#My properties keys

my.properties=mypersonalproperties

The configuration is located in the portal contextfile: <Tomcat>/conf/localhost/liferay.xml.

Simply configure the right type of database, for example:

<!-- Oracle -->

<Resource

name="jdbc/LiferayPool"

auth="Container"

type="javax.sql.DataSource"

driverClassName="oracle.jdbc.driver.OracleDriver"

url="jdbc:oracle:thin:xxxxxxé:1521:SID"

username="user"

password="password"

maxActive="20"

/>

The driver used must be placedin the "ext-lib/global" folder in order to be visible at the level of the application server which manages the "jdbc/LiferayPool"data source.

2.6Using the portal-INSTANCE_WEB_ID.propertiesfile

The "portal-INSTANCE_WEB_ID.properties" settings file makes it possible to overloadthe portal.properties reference file for a given instance. Please note that not allLiferay propertiesare compatible with this operating mode.

2.7Extending the Liferaybase

The Liferay tables can be extended to customise the portal with regard topersistence. This manipulation is complex but may come in handy. It must be very closely followed to facilitateportal versionchanges:

It is possible to createadditional queriestosupplement Liferay services. To do so, follow this tutorial:

2.8Developing a theme

2.8.1Naming

Theme projects must be named as follows:PROJECT_NAME-theme

2.9Developing a Layout

A layout is a grid used toarrange the portlets on the page. The configuration of the default layout when a page is created can be set in the "portal-ext.properties" file. For a column layout, simply add the following line.

layout.default.template.id=1_column

2.9.1Naming

Layout projects must be named as follows:PROJECT_NAME -layouttpl

2.10Developing awebcontenttemplate

Awebcontenttemplate is used to manage the display of webcontentwith which it is associated. Access to Liferay services is authorised on the platform, but their use is restricted to read-only access. You must not use any methods allowing additions, modifications or deletions within the templates.

For logging and backup purposes, these templates and their associatedstructure must be backed up in the SVNrepository, and a"templates_structures"directory on the repository root is provided for this purpose.

Exampleof use of a Liferayservice

#set ($DLFileEntryService = $serviceLocator.findService("com.liferay.portlet.documentlibrary.service.DLFileEntryLocalServiceUtil"))

<div class="article">

<h3>

$title.getData()

</h3>

#set ($uuid = $httpUtil.getParameter($data, "uuid",false))

#set ($groupId = $httpUtil.getParameter($data, "groupId",false))

#set( $Integer = 0 )

#set ($fileEntry = $DLFileEntryService.getFileEntryByUuidAndGroupId($uuid, $Integer.parseInt($groupId)))

<p>?&nbsp;<a class="event-link" href="$image.getData()">$fileEntry.getName() ($fileEntry.getSize())</a</p>

</div>

2.11LiferaypluginsSDK

Portlet creationmay be facilitatedby the use of theLiferay development plugin. This plugin is a project with ANTscriptsfor compilation, creationofWAR files, deploymentof portlets etc.

The "build.properties" file can be overloaded by eachdeveloper locally by copying it and renaming it "build.[Name].properties".

Thethreemainfunctionsof the "build.xml" file are to compile, createWAR files anddeploy thethemes, layouts and portlets in theportal.

Each sub-folder hasANT scripts with more specific tasks.

Some of the classic errors andproblemsindeploymentusing the plugin arereferenced at:

Similarly, for thehot deploy of portlets andthemes:

2.12Developing aportletplugin

The framework to be used todevelop aportlet plugin is MVC portlet. One template will be used to create all the portlets, which makes for consistency between portlets and simpler maintenance. If a resource is shared between portlets, it must be placed in thetomcat lib folder.

Theportlets must be organised as follows:

• "html": folder holding allthe portlet's"jsp", "css", "js" etcfiles,
• "src": portlet's java sources
• file describing theportlet

If the project requires thecreationof several portlets with the samefunctionalperimeter, it is recommendedthat they be grouped in the same project. The list of portlets isdefined in liferay-portlet.xml.

The resources/ dependenciesof theLiferay .jar files must not be copied to the portlets.