Personnalisation

N.B. : Tous les fichiers modifiés pour la personnalisation de l'application doivent être renseigné dans le paramètre custom.recover.files du fichier build.properties afin d'être récupérés lors d'une mise à jour de l'application.

L'accès aux bases de données

L'accès aux bases de données repose sur Hibernate. De nombreux paramètres peuvent être personnalisé dans les fichiers de configuration :
  • /properties/dao/hibernate/hibernate-jdbc.cfg.xml,
  • /properties/dao/hibernate/hibernate-jndi.cfg.xml,
  • /properties/dao/geisha/hibernate-jdbc.cfg.xml,
  • /properties/dao/geisha/hibernate-jndi.cfg.xml.

Reportez-vous sur la documentation d'Hibernate pour connaitre la signification des différents paramètres.

Les textes

Les textes utilisés dans l'application sont définis dans différents fichiers. Cela concerne aussi bien les textes affichés dans l'interface, les messages d'erreurs envoyés par le serveur ou les patrons de e-mails envoyés.

Les fichiers suivant définissent une partie des textes utilisés :
  • /properties/i18n/bundles/Commons_xx.properties : textes utilisés par le framework esup-commons,
  • /properties/i18n/bundles/Messages_xx.properties : textes spécifiques à l'application.

Ces fichiers ne doivent pas être modifiés. Tous les textes correspondants peuvent être surchargés dans les fichiers de personnalisation /properties/i18n/bundles/Custom_xx.properties (un par langue). Ces fichiers sont récupérés automatiquement par la commande ant recover-config. Il est inutile de les ajouter au paramètre custom.recover.files du fichier build.properties.

D'autre part, l'application utilise pour l'interface la librairie javascript ExtJs. Par défaut l'application utilise le fichier de langue français fourni avec l'application. De nombreux fichiers de langue sont fournis avec cette librairie mais normalement, tous les textes utilisés dans l'interface sont définis dans les fichiers spécifiques à l'application situé dans le dossier /webapp/media/src/geisha/locale. Suivant la configuration du navigateur de l'utilisateur, l'interface sera en français ou en anglais. Vous pouvez personnaliser ces fichiers à votre convenance mais ces fichiers entrent dans le cadre de la personnalisation des sources javascripts. Reportez-vous à cette section pour vous assurez que vos modifications sont correctement pris en compte.

Le style

ExtJs

La quasi totalité du style de l'application provient de la librairie ExtJs. Nous utilisons actuellement la version 3.1.1 de cette librairie. Il est possible d'utiliser des thèmes proposés par la communauté ou d'en créer un soi-même mais assurez-vous de la compatibilité avec la version de la librairie. Un thème gris officiel est disponible et semble complet. Un thème « accessibilité » officiel est également disponible. Je le laisse donc dans le package mais je n'en garantie nullement la fiabilité.

Pour utiliser le thème gris proposé dans le package, il faut :
  • en mode servlet ou quick-start : dans le fichier de configuration /properties/tags/tags.xml, au niveau de la propriété stylesheets, supprimez de la liste le fichier extjs/css/ext-all.css et ajoutez à la place les fichiers ext-all-notheme.css et xtheme-gray.css.
       <property name="stylesheets" >
            <description>
                A list of URLs that will be automatically included in the head part
                of the output document. Absolute URLs are used as-is, relative
                URLs are prefixed by property servletMediaPath.
                Warning: this tag is ignored for portlet installations.
            </description>
            <list>
                <value>extjs/css/ext-all-notheme.css</value>
                <value>extjs/css/xtheme-gray.css</value>
                <value>esup-geisha/esup-geisha.css</value>
            </list>
        </property>
  • en mode portlet : renseignez ces fichiers au niveau des fichiers CSS du portail.

Pour utiliser un thème tiers, ajoutez le fichier du thème choisi (typiquement xtheme-<nom_du_theme>.css) dans le dossier /webapp/media/extjs/css. Ajoutez également les images associées au thème suivant l'arborescence définie par le thème (généralement dans le dossier ../images/<nom_du_theme> par rapport au fichier css). Pour plus d'information, voir la documentation à propos des thèmes sur le site d'ExtJs.

Ces fichiers ajoutés au dossier media sont automatiquement déployés par la commande ant deploy. Toutefois, pour qu'il soit bien pris en compte dans l'application, il faut :
  • en mode servlet ou quick-start : renseignez ces fichiers dans le fichier de configuration /properties/tags/tags.xml. Au niveau de la propriété stylesheets, supprimez de la liste le fichier extjs/css/ext-all.css et ajoutez à la place les fichiers ext-all-notheme.css et xtheme-<nom_du_theme>.css.
       <property name="stylesheets" >
            <description>
                A list of URLs that will be automatically included in the head part
                of the output document. Absolute URLs are used as-is, relative
                URLs are prefixed by property servletMediaPath.
                Warning: this tag is ignored for portlet installations.
            </description>
            <list>
                <value>extjs/css/ext-all-notheme.css</value>
                <value>extjs/css/xtheme-<nom_du_theme>.css</value>
                <value>esup-geisha/esup-geisha.css</value>
            </list>
        </property>
  • en mode portlet : renseignez ces fichiers au niveau des fichiers CSS du portail.

Esup-Geisha

Quelques suppléments de style sont définis dans le fichier /webapp/media/esup-geisha/esup-geisha.css. Cependant, ce fichier est créé à partir du fichier /webapp/media/ressources/esup-geisha.css par la commande ant js-build (voir la personnalisation des sources javascripts).

Les sources javascript

L'interface de l'application est développée en javascript. Les sources sont disponibles dans le répertoire /webapp/media/src. Ces sources ont été compilées par les développeurs avec la commande ant js-build, utilisant l'outil JsBuilder2. L'outil et la commande sont disponibles pour que vous puissiez, au besoin, personnaliser l'interface en modifiant les sources javascript. Cependant, notez que JsBuilder2 nécessite java 6.

La commande ant js-build concatène les fichiers sources en suivant le fichier de configuration /webapp/media/src/esup-geisha.jsb2 pour créer le fichier geisha-debug.js. Puis, ce fichier est minifier en utilisant YUI Compressor pour créer le fichier geisha.js utiliser en production. Enfin, ces deux fichiers ainsi que le contenu du dossier /webapp/media/ressources sont déployés dans le dossier /webapp/media/esup-geisha.

La version minifiée permet d'alléger le fichier. C'est pourquoi ce fichier est utilisé en production. Toutefois, pour tester et déboguer vos modifications, il est conseillé d'utiliser la version geisha-debug.js. Pour cela, indiquez le fichier javascript à utiliser dans le fichier de configuration /properties/tags/tags.xml, au niveau de la propriété scripts :

       <property name="scripts" >
            <description>
                A list of URLs that will be automatically included in the head part
                of the output document as scripts. Absolute URLs are used as-is, relative
                URLs are prefixed by property portletMediaPath or servletMediaPath.
            </description>
            <list>
                <value>functions.js</value>
                <value>extjs/ext.js</value>
                <value>esup-geisha/geisha-debug.js</value>
            </list>
        </property>

N.B. : Il existe un outil très pratique pour vérifier la qualité de votre code javascript : jslint. Cet outil est également disponible sous la forme d'un plugin pour eclipse.

Les sources java

Les sources java sont compilés au déploiement de l'application. L'utilisation systématique d'interfaces permet de remplacer facilement l'implémentation d'une ou plusieurs fonctionnalités. Pour cela, il faut remplacer l'ancienne implémentation par la votre dans les fichiers de configuration du dossier /properties.