Normes de développement Liferay - vdd.coe.int Web viewND_Normes-Developpement- ... Aucun...

Direction Générale de l'AdministrationDirection des Technologies de l'Information

NORMES

NORMES DE DÉVELOPPEMENT LIFERAY

Type de document : de travail en cours de validation approuvé à diffuser

Référence : document.docx

Objectif du document

Ce document a pour objectif de décrire les normes de développement d’une application Liferay au CoE.

NB : Tout non-respect des normes ou pratiques décrites dans ce document doit être signalé par le prestataire avant le début des travaux et validé par le Conseil de l’Europe (DIT).

Ce document est la propriété du Conseil de L’Europe.Il ne peut être reproduit ou communiqué sans accord préalable de l’auteur.

document.docx [Normes]

Dernière modification 10 juin 2013 à 13:14:00

Auteur DIT Version : 1.1 / 28

NormesNormes de développement Liferay

Sommaire

OBJECTIF DU DOCUMENT .......................................................................................................................... 1 SOMMAIRE ............................................................................................................................................... 2 1 INTRODUCTION ............................................................................................................................... 4

1.1 Objectifs ................................................................................................................................... 4

1.2 Signalétique .............................................................................................................................. 4

1.3 Documentation référencée .......................................................................................................4

2 BONNES PRATIQUES DE DÉVELOPPEMENT SUR LIFERAY PORTAL ..................................................... 5 2.1 Généralités ............................................................................................................................... 5

2.1.1 Normes de développement Liferay ....................................................................................................5

2.1.2 Sources communes de la plateforme web .........................................................................................5

2.1.3 Limitations de la plateforme Web .......................................................................................................5

2.1.4 ............................................................................................................................................................... 6

Version de Liferay utilisée ..............................................................................................................................6

Environnement technique utilisé ....................................................................................................................6

2.1.5 Traitements applicatifs lourds ............................................................................................................7

2.1.6 Utilisation de bases externes .............................................................................................................7

2.1.7 Thème, gabarit, css ...........................................................................................................................9

2.2 Utilisation des métadonnées .....................................................................................................9

2.3 Surcharge des JSP (validation DIT nécessaire) .....................................................................10

2.4 Quand utiliser l’environnement EXT ? (validation DIT nécessaire) .........................................10

2.5 Utilisation du fichier portal-ext.properties ................................................................................12

2.6 Utilisation du fichier portal-INSTANCE_WEB_ID.properties ...................................................13

2.7 Extension de la base liferay ....................................................................................................14

2.8 Développement de thème ......................................................................................................14

2.8.1 Nomenclature ...................................................................................................................................14

2.9 Développement de Layout ......................................................................................................14

2.9.1 Nomenclature ...................................................................................................................................14

2.10 Développement de template de contenu web .......................................................................14

2.11 Plugin SDK liferay ................................................................................................................. 15

2.12 Développement d’un plugin de type portlet ...........................................................................15

2.13 Organisation des portlets dans le SDK .................................................................................16

2.14 Mise en place des traductions ..............................................................................................17

2.14.1 Traduction du portail ......................................................................................................................17

2.14.2 Traduction d’une portlet .................................................................................................................17

2.15 Définir des règles de nommage pour les propriétés des portlets ..........................................17





2.16 Préférence utilisateur des portlets ........................................................................................19

2.17 Définir une règle de Nommage des custom attributes ..........................................................19

2.18 Localisation et règles de nommage ......................................................................................20

2.19 Utilisation du Service Builder / Base de données .................................................................21

2.20 Utilisation des loggers ..........................................................................................................22

2.21 Règle de gestion des messages dans le fichier de logs .......................................................22

2.22 Divers ................................................................................................................................... 23

2.23 Intégration javascript au sein d’une portlet ...........................................................................23

2.23.1 Chargement des CSS propre au portlet .........................................................................................23

2.23.2 Chargement des fichiers Javascript propre au portlet ...................................................................23

2.23.3 Niveau de chargement des ressources .........................................................................................23

2.24 Sources contenues dans le gestionnaire de sources ...........................................................24

2.25 Mise en place d’une compilation spécifique ..........................................................................24

OBJECTIF DU DOCUMENT 1 SOMMAIRE 3 1 INTRODUCTION 5

1.1 Objectifs 5

1.2 Signalétique 5

1.3 Documentation référencée 5

2 BONNES PRATIQUES DE DÉVELOPPEMENT SUR LIFERAY PORTAL 6 2.1 Généralités 6

2.1.1 Normes de développement Liferay 6

2.1.2 Sources communes de la plateforme web 6

2.1.3 Limitations de la plateforme Web 6

2.1.4 Version de Liferay utilisée 6

2.1.5 Environnement technique utilisé 6

2.1.6 Traitements applicatifs lourds 6

2.1.7 Utilisation de bases externes 7

2.1.8 Thème, gabarit, css 7

2.2 Utilisation des métadonnées 7

2.3 DEVELOPPEMENT DE PLUGIN DE PORTLETS AVEC LE PLUGINS SDK 8

2.4 Surcharge des JSP (validation DIT nécessaire) 8

2.5 Quand utiliser l’environnement EXT ? (validation DIT nécessaire)8

2.6 Utilisation du fichier portal-ext.properties 10

2.7 Utilisation du fichier portal-INSTANCE_WEB_ID.properties 11

2.8 Extension de la base liferay 12

2.9 Développement de thème 12





2.9.1 Nomenclature 12

2.10 Développement de Layout 12

2.10.1 Nomenclature 12

2.11 Développement de template de contenu web 12

2.12 Plugin SDK liferay 13

2.13 Développement d’un plugin de type portlet 13

2.14 Organisation des portlets dans le SDK 14

2.15 Mise en place des traductions 15

2.15.1 Traduction du portail 15

2.15.2 Traduction d’une portlet 15

2.16 Définir des règles de nommage pour les propriétés des portlets 15

2.17 Préférence utilisateur des portlets 16

2.18 Définir une règle de Nommage des custom attributes 17

2.19 Localisation et règles de nommage 18

2.20 Utilisation du Service Builder / Base de données 19

2.21 Règle de gestion des messages dans le fichier de logs 19

2.22 Divers 20

2.23 Intégration javascript au sein d’une portlet 21

2.23.1 Chargement des CSS propre au portlet 21

2.23.2 Chargement des fichiers Javascript propre au portlet 21

2.23.3 Niveau de chargement des ressources 21





1 INTRODUCTION

1.1 OBJECTIFS

Ce document présente les normes à appliquer dans le cadre du développement d’une application basée sur Liferay pour le Conseil de l’Europe.

Toutes les règles décrites dans ce document doivent être scrupuleusement respectées, et seront vérifiées lors de chaque livraison.

Veuillez-vous référer au document décrivant les standards du système d'information au Conseil de l'Europe inclus dans la valise du développeur pour connaître les standards à respecter pour la réalisation d'une application.

Le non-respect des normes et standards du Conseil de l'Europe pourra donner lieu à un rejet de la livraison.

1.2 SIGNALÉTIQUE

Tout au long de ce document, les pictogrammes ci-dessous sont utilisés afin de souligner des points ou des notions importantes.

Information importante

Risque face à un paramétrage ou à une action spécifique

Action à éviter

Action obligatoire

1.3 DOCUMENTATION RÉFÉRENCÉE

Les documentations ci-dessous présentes dans la valise du développeur sont à prendre en compte impérativement dans le cadre des développements :

Documentation JS/CSS/HTMLDocumentation SVNDocumentation J2EEGuide graphique





2 BONNES PRATIQUES DE DÉVELOPPEMENT SUR LIFERAY PORTAL

2.1 GÉNÉRALITÉS

2.1.1 NORMES DE DÉVELOPPEMENT LIFERAY

Tout développement spécifique doit être réalisé dans le respect des normes de développement Liferay.

2.1.2 SOURCES COMMUNES DE LA PLATEFORME WEB

Aucune modification ne doit être réalisée sur des sources communes de la plateforme web Liferay, qu’il s’agisse de fichiers sources « standard » Liferay ou de fichiers sources liés à des développements réalisés spécifiquement dans le cadre de la mise en œuvre d’une solution mutualisée.

Dans le cas où la modification de ces sources communes semble absolument nécessaire une validation doit impérativement être demandée à la DIT.

2.1.3 LIMITATIONS DE LA PLATEFORME WEB

De manière globale, toutes les limitations communes de la plateforme web doivent être acceptées par défaut et respectées. Ces limitations sont les suivantes :

- Aucun document (word, pdf, etc.) n’est stocké dans la librairie documentaire Liferay : la gestion documentaire doit être faite via les outils Document Management System (DMS) et Record Management System (RMS).

- Les images peuvent être stockées dans la librairie documentaire Liferay à condition qu’elles ne dépassent pas 1 Mo. Les images de plus de 1 Mo doivent être stockées dans la photothèque du Conseil de l’Europe.

- Aucune vidéo n’est stockée dans la librairie documentaire Liferay : les vidéos doivent être déposées sur le serveur de stockage dédié du Conseil de l’Europe.

- Les structures et templates de webcontent ne sont modifiables que par les administrateurs de la plateforme. :

o En casToute demande d’ajout, ou de modification une demande d’intervention devra être effectuéedoit faire l’objet d’une demande auprès de la DIT.

o Les structures et templates sont versionnés dans le gestionnaire de sources (dossier templates_structures)

Toute dérogation à ces limitations doit faire l’objet d’une validation de la DIT.

1.1.1.1. Gestion des rôlesLes rôles mis en placeutilisés sur la plateforme Liferay du Conseil de l’Europe n’utilisene sont pas les rôles de base Liferay, sauf pour guest, user, site member, site owner et et les administrateursadministrator de la plateforme (DIT). Le rôle « administrator » n’est affecté qu’au support technique de la plateforme web (DIT).

Les autres utilisateurs se verront affecter des rôles principaux rôles génériques mis en place sur la plateforme web sont décrits succinctement dans le tableau ci-dessous.





Ces rôles spécifiques sont des « rôles de site ».

Pour une description détaillée des droits des différents rôles, veuillez-vous référer au document LIEN A DEFINIR

Les droits affectés à chaque rôle peuvent encore être sujet à modification.

Nom du rôle Description0 – Guest Utilisateur du site non authentifié qui peut juste naviguer sur

les pages publiques des sites du CoE.1 – User (USR) Utilisateur authentifié qui peut naviguer sur les pages

publiques des sites du CoE et par défaut participer à l’ensemble des outils collaboratifs (forum, wiki, blogs, commentaires, …) sauf restriction spécifique.

2 – Contributor (CTB) Permet de créer du contenu web (articles) et de modifier du contenu web (articles).

3 – Reviewer (RVW) Permet de valider les contenus web (articles) soumis à validation et la désactivation des contenus web (articles).

4 – Editor (EDT) Permet de créer, modifier des pages.Permet également l’affectation de layouts,l’ajout et la suppression d’applications.Accède / ajoute / administre les applications suivantes :

5 Publisher (PBL) Permet de publier/dépublier des pages, les contenus des pages, un site. Permet également la suppression de pages.Accède / ajoute / administre les applications suivantes :

6 Site admininstrator (SAM) Permet de gérer les accès utilisateurs.Accède / ajoute / administre les applications suivantes :

- Asset publisher- Blog et Recent bloggers- Forum- Calendar- Iframe- Page Comments- Page Flags- Page RatingsTag admin- Polls- Wiki- XSL Content

7 Super Site Administrator (SSA) Permet de gérer l’ensemble des sites d’une instance8 Administrator Administrateur global de l’application et de l’ensemble des

sites.

Ces rôles spécifiques sont des « rôles de site ». Les droits et permissions affectés à chaque rôle peuvent être sujet à modification.

Pour une description détaillée des droits des différents rôles, veuillez-vous adresser au coordinateur du projet DIT.

Tout besoin spécifique pour la mise en place de nouveaux rôles doit être validé par la DIT.

[2.1.4] TOUTE DÉROGATION À CES LIMITATIONS DOIT FAIRE L’OBJET D’UNE VALIDATION DE LA DIT.




HUBER David, 17/04/13,

TODO


VERSION DE LIFERAY UTILISÉE

Actuellement la version de Liferay utilisée est : 6.1.1020-ee-ga1ga2

[2.1.5] UN PASSAGE À LA VERSION 6.1.20-EE-GA2 EST ENVISAGÉ PROCHAINEMENT.

ENVIRONNEMENT TECHNIQUE UTILISÉ

Les choix suivants ont été faits en ce qui concerne l’environnement technique de Liferay

- Machine virtuelle Java : 1.6.0_26- Serveur d’application : Tomcat 7.0.26- Serveur de base de données : MySQL 5.1.63

2.1.4[2.1.6] TRAITEMENTS APPLICATIFS LOURDS

Il est déconseillé de mettre en place des traitements applicatifs lourds au niveau de la plateforme internet.Les traitements des types suivants doivent être réalisés dans un environnement dédié (Application à part entière, traitement en tâche de fond…)

- Génération de rapports- Traitements en tâche de fond important- …

2.1.5[2.1.7] UTILISATION DE BASES EXTERNES

L’accès aux bases externes se fera en lecture seule, on privilégiera l’utilisation de web services pour la récupération de données externes. A défaut il faudra créer des vues sur la base de données.

1.1.1.2. Utilisation d’une connexion SQL1.1.1.2.1. Récupération de la connexionSi l’on souhaite accéder directement à une base de données, il faut passer par la mise en place d’un pool de connexion à cette base. Les accès directs aux bases de données sont interdits.

Il est recommandé d’effectuer les requêtes grâce à des vues ou bien à des procédures stockées. Dans tous les cas, si des adaptations des vue ou des procédures stockées sont nécessaire il faudra les reporter dans les sources du projet gérant la base de données visée.

Exemple de mise en place : Les fichiers de configuration devront être intégrés dans le processus de compilation afin de pouvoir être paramétrés (cf 2.25 Mise en place d’une compilation spécifique)

Règle de nomenclature du nom de la ressource

NOMDELAPORTLET_NOMDELABDD

Déclaration de la ressource dans le contexte

Dans votre projet il faut rajouter le fichier suivant : /docroot/META-INF/context.xml





<Context reloadable="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>

Déclaration de la ressource dans la webapp

Dans le fichier web.xml, il faut rajouter cette partie

<resource-ref> <res-ref-name>jdbc/XXXXXXXX</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> </resource-ref>

Récupération de la datasource

Context envContext = new InitialContext();DataSource ds = (DataSource)JNDIUtil.lookup(envContext,"jdbc/XXXXXX");con = ds.getConnection();

1.1.1.2.2. Libération de la connexionLes connections SQL doivent être fermées correctement dans un bloc finally

Un utilitaire pourra être mis en place afin de simplifier l’écriture du bloc finally

Exemple :

try { //utilisation de la connexion } 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.6[2.1.8] THÈME, GABARIT, CSS

Tout ajout / modification de thème, gabarit de pages, CSS doit être validée par la Direction de la Communication.

Tout besoin spécifique concernant le thème doit être traité de la manière suivante :

- en cas de modification mineure sur le thème standard fourni par la Direction de la Communication (ex : ajout d’un paramétrage spécifique), si possible appliquer la modification sur le thème standard après avoir fait valider cette modification par la Direction de la Communication (dans le cas où cette modification pourrait être mutualisée pour l’ensemble des sites du Conseil de l’Europe) ;

- en cas de modification du thème standard n’ayant pas pour vocation à être mutualisée pour l’ensemble des sites, réaliser une extension du thème standard existant ;

- en cas de besoin très spécifique, créer un nouveau thème en extension du thème classique Liferay.

2.2 UTILISATION DES MÉTADONNÉES

Les métadonnées communes du Conseil de l’Europe seront mises à disposition sur chaque instance Liferay. Il conviendra d’utiliser cette source de données si ces listes doivent être utilisées pour des besoins spécifiques.Les services Liferay suivants permettront d’accéder à ces informations :

//récupération d'une catégorie (valeur d'une métadonnée)AssetCategory category =





AssetCategoryLocalServiceUtil.getAssetCategory(categoryId);//récupération d'un vocabulaire (métadonnée)AssetVocabulary vocabulary = AssetVocabularyLocalServiceUtil.getAssetVocabulary(category.getVocabularyId());

DEVELOPPEMENT DE PLUGIN DE PORTLETS AVEC LE PLUGINS SDK

Un plugin permettant de développer des portlets a été créé par Liferay. Ce plugin de développement fournit des scripts ANT permettant la compilation, la construction de war et le déploiement. Pour chaque version stable du produit, Liferay fournit (en téléchargement) le kit de développement adéquat afin de personnaliser le produit et développer de nouveaux plugins pour répondre aux différentes exigences fonctionnelles.

2.3 SURCHARGE DES JSP (VALIDATION DIT NÉCESSAIRE)

Il est recommandé de suivre les étapes suivantes si le projet nécessite la surcharge de certains fichiers JSP de portlets natives de liferay

Copier le fichier de la portlet depuis les sources de Liferay : webapps/ROOT/html Ajouter à chaque fichier un entête comme dans l’exemple ci-dessous :

<%* Nom du projet : COE* Version de liferay : Liferay 6.1.x* Modification: Ajout d’un bouton de prévisualisation dans la portlet blog * Auteur : nom prénom%>

Si la page à modifier contient beaucoup de personnalisation, il est préférable de mettre ces personnalisations dans un fichier séparé et l’inclure dans la page originale par un « include » comme l’exemple ci-dessous :

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

2.4 QUAND UTILISER L’ENVIRONNEMENT EXT ? (VALIDATION DIT NÉCESSAIRE)

Il est recommandé de ne faire du développement dans l’environnement d’extension de liferay que lorsque cela est nécessaire comme les cas suivants (il faut redémarrer le serveur après déploiement de EXT) :

Personnaliser le portail Liferay (apparence, organisationnel, surcharge de classes, connexion SSO, LDAP, etc.)

Déployer le portail Liferay dans son serveur d'application.

L'environnement d'extension fourni un ensemble de tâches ANT permettant d'automatiser le déploiement vers le serveur d'application:





Surcharge de la phase d'authentification (SSO, LDAP, NTLM, etc.) Surcharge de la synchronisation LDAP, Création de classes métier complétant les objets Liferay natifs, Création de WebServices Liferay pour communiquer avec d'autres applications, Customisation du portail (Groupes par défaut, compression des javascripts, etc.), Modification des actions Struts de liferay Modification de la config Spring de liferay Ajout de filtre dans web .xml Utilisation de dépendance .jar partagé entre plusieurs ressources portlets, hooks… Ajout / configuration du fichier Portal-ext.properties Etc.

L'arborescence de l'environnement d'extension est la suivante :

"ext-impl" : classes java et fichiers de configuration de surcharge de Liferay, "ext-lib/portal" : ces bibliothèques sont déployées dans le répertoire "WEB-INF/lib" du web app

Liferay. Elles sont donc visibles par le portail.





"ext-lib/global" : ces bibliothèques sont déployées dans le "common/lib/ext" de Tomcat par exemple.

"ext-service" : classes générées par le service builder (remote ou local services) "ext-web" : Surcharge de la partie web de Liferay.

En synthèse, les dossiers importants sont :

"ext-impl" "ext-web"

Les fichiers de surcharge principaux sont :

"/ext/ext-impl/classes/portal-ext.properties" : ce fichier est utilisé pour surcharger la valeur des propriétés du fichier source "portal.properties".

"/ext/ext-impl/classes/system-ext.properties" : ce fichier est utilisé pour surcharger la valeur des propriétés du fichier source "system.properties".

"/ext/ext-impl/classes/content/Language-ext.properties" : ce fichier est utilisé pour surcharger la valeur des clefs NLS ou en créer d'autres. Des fichiers spécifiques à chaque langue peuvent être créés. Exemple pour l'espagnol : Language-ext_es.properties.

Les différents scripts ANT disponibles dans l'environnement d'extension permettent le déploiement de tout ou partie du portail.

"clean" : efface toute trace de compilation et de déploiement, "deploy" : permet la compilation, le merge des fichiers et le déploiement de tous les modules, "deploy-impl-jar" : permet la compilation, la construction du jar et le déploiement des classes

d'implémentation de Liferay "deploy-properties" : fusionne et déploie uniquement les fichiers de propriétés de Liferay "deploy war" : déploie le war déjà construit.

Les fichiers "build.xml" situés dans les dossiers "ext-impl", "ext-service" et "ext-web" sont des sous tâches ANT plus fines.

2.5 UTILISATION DU FICHIER PORTAL-EXT.PROPERTIES

Le fichier de paramétrage « portal-ext.properties » permet de surcharger le fichier de référence portal.properties. Ce dernier contient TOUS les paramètres, avec leur valeur par défaut. Dans ce fichier, d’autres paramètres spécifiques au projet peuvent être définis (Url dans une portlet,




paramètres, taille d’une ressource, valeur par défaut…). Le fichier de paramétrage « portal-ext.properties » doit être placé sous /webapps/ROOT/WEB-INF/classes/.

En cas d’utilisation de paramètres spécifiques à l’environnement (adresse SMTP, adresse IP du serveur, serveur apache….), il est conseillé de séparer les 2 fichiers :

portal-ext.properties dans : /webapps/ROOT/WEB-INF/classes/ : il contient les paramètres qui ne dépendent pas de l’environnent ;

portal-ext.properties dans : TOMCAT_HOME : il contient les paramètres spécifique l’environnent.

Cette solution permet de simplifier le déploiement, le même livrable pour les différents environnements.

Pour ajouter des clés-valeurs dans le fichier 'portal-ext.properties”, ci-dessous un exemple :

#My properties keysmy.properties=une propriete perso

La configuration est située dans le fichier de contexte du portail : <Tomcat>/conf/localhost/liferay.xml.

Il suffit alors de configurer le bon type de base de données. Par exemple :

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

/>

Le "driver" utilisé doit être placé dans le dossier "ext-lib/global" afin d'être visible au niveau du serveur d'application qui gère la source de données "jdbc/LiferayPool".

2.6 UTILISATION DU FICHIER PORTAL-INSTANCE_WEB_ID.PROPERTIES

Le fichier de paramétrage « portal-INSTANCE_WEB_ID.properties » permet de surcharger le fichier de référence portal.properties pour une instance donnée. Attention, l’ensemble des propriétés Liferay n’est pas compatible avec ce mode de fonctionnement.


2.7 EXTENSION DE LA BASE LIFERAY

Les tables Liferay peuvent être étendues afin de personnaliser le portail côté persistance. Cette manipulation reste complexe mais peut s'avérer utile. Elle nécessite d'être suivie rigoureusement afin de faciliter les changements de version du portail :http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Extending+Liferay+Tables+in+Another+DatabaseIl est possible de créer des requêtes additionnelles pour compléter les services Liferay. Pour ce faire, suivre le tutorial :http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/How+to+create+a+custom+query+in+ext+for+Liferay+models

2.8 DÉVELOPPEMENT DE THÈME

2.8.1 NOMENCLATURE

Les projets de type theme doivent être nommé de la manière suivante NOM_DU_PROJET-theme

2.9 DÉVELOPPEMENT DE LAYOUT

Un layout est une grille utilisée pour disposer les portlets sur la page. La configuration du layout par défaut lors de la création d’une page est paramétrable dans le fichier « portal-ext.properties ». Il suffit d’ajouter la ligne suivante pour avoir le layout d’une colonne.

layout.default.template.id=1_column

2.9.1 NOMENCLATURE

Les projets de type layout doivent être nommé de la manière suivante NOM_DU_PROJET-layouttpl

2.10 DÉVELOPPEMENT DE TEMPLATE DE CONTENU WEB

Un template de contenu web permet de gérer l’affichage du contenu web avec lequel il est associé. L’accès aux services Liferay est autorisé sur la plateforme, cependant leur utilisation est limité aux seuls accès en lecture. Il ne faudra pas utiliser de méthode permettant l’ajout, la modification, la suppression au sein des templates.A des fins d’historisation et de sauvegarde, ces templates ainsi que leur structure associée doivent être sauvegardés dans le dépôt SVN, un répertoire « templates_structures » à la racine de celui-ci est prévu à cet effet.Exemple d’utilisation d’un service Liferay

#set ($DLFileEntryService = $serviceLocator.findService("com.liferay.portlet.documentlibrary.service.DLFileEntryLocalServiceUtil"))<div class="article">

<h3>$title.getData()

</h3>#set ($uuid = $httpUtil.getParameter($data,

"uuid",false))




http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/How+to+create+a+custom+query+in+ext+for+Liferay+models

http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/How+to+create+a+custom+query+in+ext+for+Liferay+models

http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Extending+Liferay+Tables+in+Another+Database

http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Extending+Liferay+Tables+in+Another+Database


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

#set( $Integer = 0 )#set ($fileEntry =

$DLFileEntryService.getFileEntryByUuidAndGroupId($uuid, $Integer.parseInt($groupId)))

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

2.11 PLUGIN SDK LIFERAY

La création de portlet peut être facilitée par l'utilisation du plugin de développement de Liferay. Ce plugin est un projet avec des scripts ANT permettant la compilation, la création de fichiers war, le déploiement des portlets, etc.Le fichier de propriétés "build.properties" peut être surchargé par chaque développeur localement en le copiant et le renommant "build.[Nom].properties".

Les 3 principales fonctions du "build.xml" sont de compiler, créer les war et déployer les thèmes, layouts et portlets dans le portail.Chaque sous-dossier dispose de scripts ANT ayant des tâches plus fines.

Certaines erreurs classiques et problèmes de déploiement avec le plugin sont référencés à l'URL : http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Plugin+Deployment+Troubleshooting

De même pour le déploiement à chaud des portlets et thèmes : http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Hot%20Deploy%20Troubleshooting

2.12 DÉVELOPPEMENT D’UN PLUGIN DE TYPE PORTLET

Pour le développement d’un plugin de type portlet le framework à utiliser est MVC portlet. Un modèle sera utilisé pour créer toutes les portlets, cela permet d’avoir une cohérence entre les portlets et de simplifier la maintenance. Si une ressource est partagée entre les portlets, la ressource doit être placée dans le dossier lib de tomcat.

Il faut organiser les portlets de la façon suivante :

"html" : dossier regroupant toutes les fichiers "jsp", "css", "js", etc. de la portlet, "src" : sources java de la portlet fichiers descripteurs de la portlet




http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Hot%20Deploy%20Troubleshooting

http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Plugin+Deployment+Troubleshooting


Si le projet nécessite la création de plusieurs portlets ayant le même périmètre fonctionnel, il est recommandé de les regrouper dans le même projet. La liste des portlets est définie dans liferay-portlet.xml.

Il ne faut pas copier des ressources / dépendances des .jar de liferay dans les portlets.

2.12.1 NOMENCLATURE Il existe un nom « technique » pour la portlet et un nom d’ « affichage » pour laune portlet. LCes deux noms doivent respecter des règles de nommage similaires.

Le nom technique doit avoir le format suivant : coe[-site/service][-fonctionnalité]

Par exemple :

coe-search : pour la portlet de recherche commune (on aura des noms de ce type pour les développements mutualisés)

coe-fej-calendar : pour le calendrier spécifique dau site du FEJ

Le nom qui s’affiche pour les utilisateurs (en back office ou en front office) doit respecter la même nomenclature : CoE[ site/service][ fonctionnalité]

Par exemple :

CoE Search : pour la portlet de recherche commune (on aura des noms de ce type pour les développements mutualisés)

CoE FEJ Calendar : pour le calendrier spécifique dau site du FEJ





Le nom technique de la portlet est défini dans le fichier portlet.xml dans la balise portlet-name.Le nom d’ « affichage » est défini dans le fichier portlet.xml dans la balise display-name et dans les fichiers de traductions associés à l’aide de la propriété javax.portlet.title

2.13 ORGANISATION DES PORTLETS DANS LE SDK

Le dossier "portlet" contient toutes les portlets à développer du projet. Il est constitué de différentes portlets exemples permettant d'offrir une base et un support concret au développeur.

2.14 MISE EN PLACE DES TRADUCTIONS

2.14.1 TRADUCTION DU PORTAIL

Nous préconisons de mettre toutes les traductions dans un seul hook de traduction :

Nom du hook : nomProjet-traductionportail-hook l’exemple de liferay-hook.xml (ici, en version 6.0):

<?xml version="1.0"?>

<!DOCTYPE hook PUBLIC "-//Liferay//DTD Hook 6.0.0//EN" "http://www.liferay.com/dtd/liferay-hook_6_0_0.dtd">

<hook>

<language-properties>/localized/resources/Language_en.properties</language-properties>

<language-properties>/localized/resources/Language_fr.properties</language-properties>

</hook>

2.14.2 TRADUCTION D’UNE PORTLET





Nous préconisons de mettre les traductions dans la portlet. Il faut créer un fichier de langue par entrée dans le fichier portlet.xml.Une exception peut être tolérée dans le cas où l’on a dû créer plusieurs portlets qui remplissent un même besoin pour des questions d’affichage.

2.15 DÉFINIR DES RÈGLES DE NOMMAGE POUR LES PROPRIÉTÉS DES PORTLETS

Il est conseillé d’avoir une règle de nommage des propriétés des portlets dans un projet. Pour récupérer une variable dans une portlet, les 2 méthodes suivantes peuvent être utilisées :

1. Fichier portal-ext.properties :a. Déclaration de propriété dans le fichier portal-ext.properties

i. Avantage : la variable est disponible pour l’ensemble du portail.ii. Inconvénient : il est nécessaire de redémarrer le serveur pour que la variable

soit prise en compte.b. Ces propriétés ont l’avantage d’être disponibles dans l’ensemble du portail et donc

utilisables par l’ensemble des portlets.c. Mode de récupération :

2. Variable du portail Liferay :

a. Déclaration de « custom attributes »i. Avantage : aucun redémarrage du serveur.ii. Inconvénient : la variable peut être modifié/ supprimé par un administrateur, il

faut donc tester dans la portlet si la variable existe pour éviter que la portlet ne soit indisponible.

b. Ajouter un attribut personnalisé pour une organisation et donner le droit en lecture pour le rôle guest

c. Mode de récupération :

User user;Organization organization ;ExpandoBridge bridge = ExpandoBridgeFactoryUtil.getExpandoBridge(user.getCompanyId(), Organization.class.getName(), organization.getPrimaryKey());String customerID = (String)bridge.getAttribute("nomDeLaVariable");




String nomDeLaVariable = "com.coe.nomProjet.context.snomDeLaVariable";String value = PropsUtil.get(nomDeLaVariable);


d. Modification de la variable :

Les propriétés déclarées doivent respecter un nommage défini comme par exemple :Pour les portlets : com.coe.projet.{NOM DE LA PORTLET}.{NOM DE LA VARIABLE}Pour les structures : com.coe.projet.{NOM DE LA PORTLET}.structure.{NOM DE LA VARIABLE}

Les propriétés déclarées doivent être commentées avec, à minima, les informations ci-dessous :

1. Portlet de référence2. Auteur3. Date de création

Exemple :

2.16 PRÉFÉRENCE UTILISATEUR DES PORTLETS

Il faut systématiquement, lors de l’utilisation de préférences utilisateur dans une portlet, ajouter une initialisation des préférences avec une valeur par défaut dans le fichier portlet.xml du portlet comme présenté dans l’exemple ci-dessous :

<portlet-preferences><preference>

<name>largeur</name><value>100%</value>

</preference><preference>

<name>scrolling</name><value>no</value>

</preference></portlet-preferences>

2.17 DÉFINIR UNE RÈGLE DE NOMMAGE DES CUSTOM ATTRIBUTES

prefixe_nomprojet_{NOM DE LA PORTLET ou du hook etc…}_{NOM DE LA VARIABLE}Ci-dessous un exemple d’utilisation des « custom attributes », il faut systématiquement tester les développements avec des comptes simple USER et Admin pour s’assurer que les développements fonctionnent correctement dans tous les cas de figure.

//// Ajout d'une table de custom attribute et/ou ajout du custom attribute :protected void addCustomAttribute(String pAttribut, String pValue, long pUserId) throws Exception {

ExpandoTable table = null;try {

table = ExpandoTableLocalServiceUtil.addTable(User.class.getName(), "BIBLIOCOMGPM_PTL");




ExpandoBridge bridge = ExpandoBridgeFactoryUtil.getExpandoBridge(user.getCompanyId(), Organization.class.getName(), organization.getPrimaryKey());bridge.setAttribute("nomDeLaVariable","valeureLaVariable");

@portlet MyPortlet@author Prénom NOM@date 12/01/2010


} catch (DuplicateTableNameException dtne) {table = ExpandoTableLocalServiceUtil.getTable(User.class.getName(),

"BIBLIOCOMGPM_PTL");}try {

ExpandoColumnLocalServiceUtil.addColumn(table.getTableId(), pAttribut, ExpandoColumnConstants.STRING);

} catch (DuplicateColumnNameException dcne) {ExpandoValueLocalServiceUtil.deleteValue(User.class.getName(),

table.getName(), pAttribut, pUserId);}ExpandoValueLocalServiceUtil.addValue(User.class.getName(), table.getName(), pAttribut,

pUserId, pValue);}

//// Récupération du custom attribute :protected Serializable getCustomAttrBiblioComGpm(String pAttribut, String pTableName, long pUserId) throws SystemException {

Serializable value = null;/* * Récupération de la valeur du custom attribute */try {

value = ExpandoValueLocalServiceUtil.getData(User.class.getName(), pTableName, pAttribut, pUserId);

} catch (Exception pe) {if (_log.isErrorEnabled())

_log.error("PortalException ----- " + pe);}return value;

}///Exemple d'appel de la méthode d'ajout :

try{

addCustomAttribute("biblioComGpmAttr_" + instanceId, attribute.toString(), themeDisplay.getUserId());

addCustomAttribute("biblioComGpmSaveFilter_" + instanceId, saveFilter.toString(), themeDisplay.getUserId());

} catch (Exception e) {if (_log.isErrorEnabled())

_log.error(e);}

///// Exemple d'appel de la méthode de récupération :Serializable custom = getCustomAttrBiblioComGpm("biblioComGpmAttr_" + instanceId,

"BIBLIOCOMGPM_PTL", themeDisplay.getUserId()));

2.18 LOCALISATION ET RÈGLES DE NOMMAGE

Ci-dessous un exemple de règle de nommage à respecter pour tous les nouveaux projets au COE.

Les traductions doivent être intégrées dans les fichiers globaux du portail, et doivent respecter la sémantique suivante :

Pour les libellés : com.coe.projet.{Nom du portlet}.{Nom de la variable}





Pour les messages d’erreurs : com.coe.projet.error.{Nom du portlet}.{Nom de la variable}

A minima l’ensemble des portlets doivent être localisés dans la langue par défaut du portail dans le fichier de traduction du portail. L’implémentation des langues (supported-locale) ne doit pas être intégrée dans le fichier portlet.xml.

Le fichier de traduction par défaut du portail doit être maintenu au même niveau de traduction que celui de la langue par défaut.

Les variables de traduction doivent être commentées avec, à minima, les informations ci-dessous :

1. Portlet de référence2. Auteur3. Date de création

Exemple : ## @portlet MyPortlet ## @author Prénom NOM ## @date 12/01/2010

Les variables doivent être enregistré dans les fichiers de traduction du Hook sur /hooks/TraductionPortail. Utiliser le code suivant dans la vue pour afficher les messages qui se doivent se trouver dans les fichiers de traductions du portail :

<spring:hasBindErrors name="preferences"> <span class="portlet-msg-error"> <p><liferay-ui:message key="com.coe.lbl.preferences-error" /></p> <ul> <spring:bind path="preferences.*"> <c:forEach items="${status.errorMessages}" var="error"> <li><liferay-ui:message key="${error}" /></li> </c:forEach> </spring:bind> </ul> </span></spring:hasBindErrors>

Les packages intégrés aux portlets doivent être préfixés par : com.coe.{projet}.{Nom de la portlet}

Ce préfixe sera utilisé dans le reste du document par {PREFIX}.

L’arborescence des packages Java dans la portlet doit respecter le schéma suivant :

{PREFIX}.domaino contient l’ensemble des classes du domaine (Values Object, PoJos)





{PREFIX}.serviceo Contient l’ensemble des classes d’accès aux services (web service, service applicatif

sous-jacent type Liferay) {PREFIX}.web

o Contient les contrôleurs de vue {PREFIX}.validator

o Contient les validators {PREFIX}.util

o Contient l’ensemble des classes Utils {PREFIX}.exception

o Contient l’ensemble des exceptions du portlet

2.19 UTILISATION DU SERVICE BUILDER / BASE DE DONNÉES

Les tables en base de données doivent être créées depuis une portlet de service « service builder » et doivent respecter le pré-fixage suivant : nomProjet_{Nom de la portlet}_{Nom de la table}Attention à la casse, les noms de table doivent être impérativement en minuscule, le séparateur sera un « _ » et il ne doit y avoir aucun espace.

Les scripts SQL, s’il y en a, devront être livrés dans un fichier nommé script{Nom du portlet}.sql, chaque instruction sql devra être commentée.

2.20 UTILISATION DES LOGGERS

Les loggers Liferay sont les seuls à être autorisés,. lLa récupération du logger lors de sa déclaration se fait avec la classe com.liferay.portal.kernel.log.LogFactoryUtil

2.21 RÈGLE DE GESTION DES MESSAGES DANS LE FICHIER DE LOGS

Les messages d’erreurs inscrits dans les logs du portail doivent, autant que possible, être traduit en message « Métier » et n’afficher la pile d’erreur que dans d’extrême mesure ou en mode DEBUG. Pour exemple, prenons le cas d’une portlet qui affiche des données depuis un flux externe, si ce flux n’est pas disponible, au lieu de logger l’exception il faut logger un message contenant par exemple « [portlet] flux XXX indisponible ». Ce mode de fonctionnement permet d’identifier plus rapidement les erreurs rencontrées et allège grandement le fichier de log. En mode DEBUG, nous devons trouver le message d’erreur métier et la pile d’erreur.

Exemple d’utilisation de l’objet de log :

private static Log _log = LogFactoryUtil.getLog(NomDeLaClass.class);try { _log.debug("Message :" + message); _log.info("Information :" + infos);}catch (Exception e){ _log.fatal("Erreur " + e);





}

Le niveau de log est défini dans le fichier Log4j.properties, par exemple :

log4j.rootCategory=ERROR,stdout# sortie par défautlog4j.appender.stdout=org.apache.log4j.ConsoleAppenderlog4j.appender.stdout.layout=org.apache.log4j.PatternLayoutlog4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %-5p [%c{1}:%L] %m%n

Il suffit de changer le niveau de ERROR par DEBUG pour passer le portlet en mode debug.

Niveau de log par plateforme :

Intégration : DEBUG Recette : ERROR Pré-production : ERROR

2.22[2.21] DIVERS

Un fichier de configuration dédié par environnement doit être créé ; Donner la possibilité à l'utilisateur de modifier ces paramètres en utilisant les préférences de

la portlet ou des paramètres du portail ; Développement de l’IHM, il faut privilégier les outils fournis par Liferay (Liferay IDE /

Developer Studio), il est déconseillé d’utiliser des outils du type TIBCO General Interface Builder ou autre, le retour d’expérience sur ce type de générateur n’est pas concluant ;

Ne jamais utiliser les System.out.println pour écrire dans les fichiers de logs ; Sur le principe, ne jamais utiliser le niveau de log ERROR ou FATAL dans une méthode

render (méthode d’affichage d’une portlet), sous peine de surcharger les logs de production de manière abusive. Lui préférer le niveau WARN, à moins qu’il ne s’agisse réellement d’un cas d’erreur ;

P our les méthodes ayant un fort impact sur les performances, les concaténations peuvent avantageusement être remplacées par un appel à la classe StringBundler, sur le principe d’équivalence suivant :

a+b (new StringBundler(2)).append(a).append(b).toString()

2.23[2.22] INTÉGRATION JAVASCRIPT AU SEIN D’UNE PORTLET

2.23.1[2.22.1] CHARGEMENT DES CSS PROPRE AU PORTLET





Il n’est pas conseillé d’intégrer du code de mise en forme au sein des portlets, mais de les mettre dans le thème.

2.23.2[2.22.2] CHARGEMENT DES FICHIERS JAVASCRIPT PROPRE AU PORTLET

Les appels de traitements métier Javascript au chargement de la page doivent systématiquement être fait dans les jsp des portlets avec :

jQuery.ready() ; (http://api.jquery.com/ready/ )

Il faut préfixer systématiquement les variables javascript avec le nom de la portlet, pour éviter des conflits entre les variables.

2.23.3[2.22.3] NIVEAU DE CHARGEMENT DES RESSOURCES

Les ressources statiques de type JS et CSS peuvent être chargées soit dans l’en-tête soit dans le pied de page. En fonction des besoins les deux chargements peuvent être utilisés.Il est à noter que ces ressources doivent être chargées uniquement depuis les instructions du fichier liferay-portlet.xml en aucun cas elles doivent être chargées « en dur » dans les vues JSP.

Exemple d’instruction Liferay :

<header-portlet-css>/css/jquery-ui-1.8.6.custom.css</header-portlet-css> <footer-portlet-javascript>/js/jquery-ui-1.8.6.custom.min.js</footer-portlet-javascript>

2.24[2.23] S OURCES CONTENUES DANS LE GESTIONNAIRE DE SOURCES

Les sources déposées dans le gestionnaire doivent :

- ne pas contenir de sources compilées- ne pas contenir de fichier .bak ou historique similaire- ne pas contenir de fonctionnalités qui ne sont pas à livrer- ne pas contenir d’écriture sur la sortie standard et la sortie erreur- être en UTF-8 sans BOM

2.25 MISE EN PLACE D’UNE COMPILATION SPÉCIFIQUE

Certaines portlets auront besoin d’avoir une configuration spécifique dans le fichier portlet.properties, ou d’autres fichiers de configuration, suivant l’environnement.

Voici la marche à suivre dans le cas d’une compilation spécifique :.

A la racine de la portlet (au niveau du fichier build.xml) créer l’arborescence ant/files Dans ant/files ajouter les « templates » des fichiers de propriétés

Les données pouvant changer d’un environnement à l’autre sont remplacées par des « tags » qui vont être mis à jour au moment du build. Ces tags sont de la forme suivante @NOM_DE_LA_VARIABLE@





Exemple de contenu de fichier « template »

portlet.webservice.url=@MYPROJECT_WEBSERVICE_URL@

Ensuite pour remplacer les variables, il faut mettre à jour le fichier de build (build.xml) de la manière suivante

<?xml version="1.0"?><!DOCTYPE project>

<project name="my-project-portlet" basedir="." default="deploy"> <import file="../build-common-portlet.xml" />

<target name="override-portlet-properties"> <property file="../../../ant/env/${build.env}.properties" /> <echo>Overriding portlet.properties for my project</echo> <copy file="ant/files/portlet.properties" tofile="docroot/WEB-INF/src/portlet.properties" overwrite="true" />

<replace file="docroot/WEB-INF/src/portlet.properties" value="${myproject.webservice.url}"> <replacetoken>@MYPROJECT_WEBSERVICE_URL@</replacetoken> </replace> </target></project>

Et en finEnfin lors de la livraison, il faut spécifier les clefs à rajouter/modifier dans le fichier de configuration du build, dans l’exemple, il s’agit de la variable myproject.webservice.url.

On préfixera les noms de variable par le nom de la portlet.

2.26 LIMITATION DE LA VISIBILITÉ DES NOUVELLES PORTLETS

2.26.1 PORTLET VISIBLE UNIQUEMENT EN BACKOFFICE Dans le fichier liferay-portlet.xml, il suffit de rajouter la ligne suivante dans la configuration de la portlet

<system>true</system>

2.26.2 PORTLET VISIBLE AU NIVEAU D’UNE INSTANCE Il faut effectuer un test spécifique dans la classe qui contrôle l’affichage de la portlet. Cette classe doit être rajoutée dans la configuration de la portlet dans liferay-portlet.xml

<control-panel-entry-class>com.coe.obs.portlet.simulatedpurchase.SimulatedPurchaseControlPanelEntry</control-panel-entry-class>

Exemple:





public class SimulatedPurchaseControlPanelEntry extends BaseControlPanelEntry {

public boolean isVisible(PermissionChecker permissionChecker, Portlet portlet) throws Exception { return "obs.coe.int".equals(CompanyLocalServiceUtil.getCompanyById(portlet.getCompanyId())); }

}

2.26.3 PORTLET VISIBLE AU NIVEAU D’UN OU DE PLUSIEURS SITES Il faut effectuer un test spécifique dans la classe qui contrôle l’affichage de la portlet. Cette classe doit être rajoutée dans la configuration de la portlet dans liferay-portlet.xml

<control-panel-entry-class>com.coe.portlet.job.management.JobManagementControlPanelEntry</control-panel-entry-class>

Exemple :

public class JobManagementControlPanelEntry extends BaseControlPanelEntry {

/* * (non-Javadoc) * * @see * com.liferay.portlet.BaseControlPanelEntry#isVisible(com.liferay.portal * .model.Portlet, java.lang.String, com.liferay.portal.theme.ThemeDisplay) */ public boolean isVisible(Portlet portlet, String category, ThemeDisplay themeDisplay) throws Exception { boolean isVisible = super.isVisible(portlet, category, themeDisplay);

String webId = PortletProps.get("context.webid"); String siteName = PortletProps.get("context.site");

Company c = CompanyLocalServiceUtil.getCompanyByWebId(webId); Group g = GroupLocalServiceUtil.getGroup(c.getCompanyId(), siteName);

Group g2 = themeDisplay.getScopeGroup();

if (g.hasStagingGroup() && g2.getGroupId() != g.getStagingGroup().getGroupId()) { isVisible = false; }

return isVisible;





}

public boolean isVisible(PermissionChecker permissionChecker, Portlet portlet) throws Exception {

boolean isVisible = false;

if (PortletPermissionUtil.contains(permissionChecker, portlet.getPortletId(), ActionKeys.ACCESS_IN_CONTROL_PANEL)) { isVisible = true; }

return isVisible; }

}

FIN DU DOCUMENT




Normes de développement Liferay - vdd.coe.int Web viewND_Normes-Developpement- ... Aucun...

Documents

Transcript of Normes de développement Liferay - vdd.coe.int Web viewND_Normes-Developpement- ... Aucun...