Groupe 3F (CMS) |
Date de création : | 10 novembre 2004
Dernière modification : | 7 avril 2005
Diffusion : | internet

# Installation du rendu Cocoon inJac V2.1

Configuration utilisée :

- j2sdk1.4.2_04(Sun Microsystems)

- jakarta-tomcat-5.0.28(Apache project)

- cocoon-2.1.5.1(Apache project)

- Docbook stylesheets 1.66.1(Oasis project)

Ce document a pour but de décrire l'installation de l'application Cocoon du rendu d'inJac, la personnalisation du rendu, et certains aspects de configuration avancée tels que l'accès à une base de donnée, ou le paramétrage de l'utilisation mémoire.

Les sources sont disponibles sur le CVS dans le module Injac/applications/Cocoon, le package peut être téléchargé dans l'espace de téléchargement.

Pré-requis

Dépendances

Installation

Personnalisation du rendu

Configuration avancée

## Pré-requis

Le rendu Cocoon nécessite l'installation préalable de Cocoon 2.1.5.1(pour la V1 et V2), ou de Cocoon 2.1.x à partir de la V2.1, téléchargeables sur le site Apache.

## Dépendances

Le rendu Cocoon d'inJac V2 est le rendu d'un espace de publication Webdav, il dépends donc d'Esup-Portail et du Canal de Stockage (V3 ou plus) et du serveur Webdav (V2 ou plus). En outre, l'accés authentifié nécessite l'installation d'un serveur CAS(CAS server with CAS GH ou CAS QuickStart). Tous sont disponibles sur l'espace de téléchargement , respectivement dans les sections 'Espace de Stockage' et 'SSO'.

## Installation

### A. Installer Cocoon dans un moteur de JSP/Servlet (exemple : Tomcat)

1. Télécharger Cocoon à l'adresse http://cocoon.apache.org/mirror.cgi

2. Dezipper le paquet pour obtenir le répertoire des sources.

3. Compiler Cocoon en se plaçant à la racine du répertoire des sources, taper :

   - build

   - build war

4. Copier/coller le fichier cocoon.war depuis le sous répertoire build\cocoon-2.1.5.1\ vers le répertoire webapps de Tomcat.

5. Si votre serveur est en mode autodeploy il n'y a plus qu'à attendre que le .war se déploie, sinon le déployer à l'aide de l'outil de management de Tomcat.

### B. Déployer Injac-Cocoon

1. Dezipper l'archive injac

Editer le fichier build.properties avant de lancer la commande "ant deploy", pour déployer l'arborescence dans Cocoon.
Ce fichier comporte principalement le chemin de déploiement de Cocoon :

deploy.cocoon.home = E:/TestJava/jakarta-tomcat-5.0.28/webapps/cocoon

### C. Configuration

Edition du fichier iconf.xml

<webdav> et <anon-webdav>

Avant toute chose, vous devez définir les url du serveur Webdav, ainsi que l'url de votre application Injac. Pour gérer les deux mode d'accés, public et avec identification, deux url distinctes sont nécessaires, avec deux hostname différents, un pour chaque mode. Ces hotsname doivent correspondre à ceux définis dans les filtres "TRUSTED" et "ANON" du serveur Webdav(fichier web.xml de l'application Slide) :

<filter>
<filter-name>authenticationRouter</filter-name>

...

<!-- TRUSTED -->
<init-param>
<param-name>org.esupportail.filter.authenticationRouter.destinationHostTRUSTED</param-name>
<param-value>saroumane.enseeiht.fr:8081</param-value>
</init-param>

<!-- UNAUTHENTICATED -->
<init-param>
<param-name>org.esupportail.filter.authenticationRouter.destinationHostUNAUTHENTICATED</param-name>
<param-value>anon.enseeiht.fr:8081</param-value>
</init-param>

...

</filter>

A ces URLs doivent correspondre celles définies dans iconf.xml :

<!-- Webdav URL (serveur + collection) authentificated mode -->
<webdav>saroumane.enseeiht.fr:8081/slide/files/injacRoot</webdav>
<!-- URL Webdav (serveur + répertoire) public mode -->
<anon-webdav>anon.enseeiht.fr:8081/slide/files/injacRoot</anon-webdav>

<upnode> nom de la collection de l'espace inJAC racine

<display-upnode> nom affiché pour la collection de l'espace inJAC racine

<logoutURL>

Cet élément correspond à l'URL pour clore une connexion identifiée auprés du serveur CAS.

<logoutURL>https://cas.enseeiht.fr:8443/cas/logout?service=http://saroumane.enseeiht.fr:810/cocoon/injac</logoutURL>

La partie en bleu correspond à l'URL de la servlet de logout du serveur CAS, et la partie en rouge à l'élément <localURI> défini plus bas dans le fichier.

Les autres paramètres du fichier iconf.xml concernent le stockage des ressources, les métadonnées utilisées, et l'emplacement des ressources internes:

<trustedpw> : Mot de passe TRUSTED pour la connexion au serveur Webdav

<docmd> : Noms des métadonnées du serveur Webdav concernant un document

<rendermd> : Noms des métadonnées du serveur Webdav concernant la personnalisation du rendu

<typemd> : Noms des métadonnes déterminant le type de la collection et les fichiers par défaut associés(espace et document)
<defaultstyle> : nom de la feuille de style par défaut(obsoléte à partir de la version 2 du Canal de Stockage, où l'utilisateur choisit la feuille parmis une liste établie dans le fichier injac.xml, élément <Renderings> )

<defaultskin> : fichier de skin par défaut(voir personnalisation du rendu)

<localURI> : URL de l'application Cocoon-Injac

<errorsheet> : feuille xsl pour afficher les erreurs. Il y a une feuille pour le deboggage(avec affichage des détails des exceptions) et une feuille pour le fonctionnement en production(plus concise).
<localResource> : Booléen déterminant l'emplacement des ressources.

<webdavresources>emplacement des ressources dans le cas de [localResource=false]

Par défaut, localResource est à true, et les ressources du rendu (logos, icones, CSS) sont définies localement, dans le répertoire media pour les graphiques,stylesheets/css four les feuilles CSS, et xml/skins pour les skins. Si l'on veut que ces resources soient modifiables à distance, on a la possibilité, en positionnant localResource à false, de spécifier un emplacement webdav avec l'élément webdavresources. L'emplacement des graphiques devient alors ${webdavresources}/media, celui des feuilles CSS, ${webdavresources}/css et les skin, ${webdavresources}/skins.

> Note : pour personnaliser le rendu, se reporter au chapitre suivant.

Configuration du filtre CAS

L'accés authentifié se fait par l'intermédiaire d'un filtre java, à l'aide d'un jeu d'URL qui se paramètrent dans le fichier web.xml de Cocoon :

<!-- CAS FILTER -->
<filter>
<filter-name>Filtre CAS</filter-name>
<filter-class>edu.yale.its.tp.cas.client.filter.CASFilter</filter-class>
<init-param>
<param-name>edu.yale.its.tp.cas.client.filter.loginUrl</param-name>
<param-value>https://cas.enseeiht.fr:8443/cas/login</param-value>
</init-param>
<init-param>
<param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name> <!--serviceValidate-->
<param-value>https://cas.enseeiht.fr:8443/cas/serviceValidate</param-value>
</init-param>
<init-param>
<param-name>edu.yale.its.tp.cas.client.filter.proxyCallBackURL</param-name>
<param-value>https://saroumane.enseeiht.fr:8443/injac/CasProxyServlet</param-value>
</init-param>
<init-param>
<param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
<param-value>saroumane.enseeiht.fr</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>Filtre CAS</filter-name>
<url-pattern>/injac/auth/*</url-pattern>
</filter-mapping>
<!-- CAS FILTER -->

En rouge figure le hostname de l'application CAS, en bleu celui où est déployé Injac.

Niveau de débogage

Le niveau de débogage peut être modifier en éditant le fichier WEB-INF\classes\log4j.properties.

Les niveaux disponibles sont : debug, info, error, du plus prolixe au plus concis.

Catalogue de résolution d'entités.

Note : à partir de la version 2.1, cette configuration n'est plus nécessaire.

> Il faut modifier de façon appropriée le chemin vers les catalogues de résolution d'entités, dans le fichier cocoon/WEB-INF/classes/CatalogManager.properties :

> catalogs=E:/Java/jakarta-tomcat-5.0.28/webapps/cocoon/injac/dtd/sdocbook.cat

> de façon à les faire pointer sur votre répertoire de déploiement d'Injac.

### D. Naviguez

##### Lancez un naviguateur et essayer l'URL {TOMCAT-URL}/cocoon/injac.

Vous arrivez alors à la page représentant l'espace racine que vous avez défini dans iconf.xml, en mode anonyme.

Important : Pour que ce mode soit opérationnel, il faut que l'espace racine soit défini en lecture publique dans le Canal de Stockage. Vous pouvez alors naviguer dans les espace WebDAV publics, afficher différents types de documents, et les convertir au format PDF.

Pour accéder à des espaces et documents protégés, cliquez sur le lien "s'identifier" en haut à droite(dans le rendu par défaut), et vous pourrez alors étendre votre navigation en fonction de vos droits en lecture (qui sont définis par l'administrateur de l'espace dans le Canal de Stockage).

## Personnalisation du rendu

A partir de la version 2, la personnalisation se fait à travers deux fichiers associés :

> -un fichier de skin, définissant des options du contenu du rendu(liens, logos, recherche), qui se place dans le sous-répertoire injac/xml. Le fichier skin.xml sert de modèle auquel se réferrer pour construire d'autres fichiers.

> -une feuille CSS, qui gère l'aspect graphique du rendu (couleurs, disposition...), située dans le sous-répertoire injac/stylesheets/xsl.

Pour chaque fichier de contenu(skin), on doit donc avoir au moins une feuille CSS correspondante, mais on peut en avoir également plusieurs, pour varier l'apparence d'un même contenu.

C'est à travers l'edition des metadonnées lors de la création ou de l'administartion d'un espace par le Canal de Stockage que l'administrateur d'espace choisit le skin et la feuille de style. Dans la version V3 du canal de Stockage, seule la feuille est paramétrable, le skin utilisé étant alors celui définit par défaut dans iconf.xml. Une liste de ceux-ci doit donc être renseignée dans le fichier de configuration du Canal, properties/injac/injac.xml, sous la forme :

    <RENDERINGS>

    	<RENDERING
    		url="ma-feuille.css"
    		label="Mon rendu"
    	/>

    </RENDERINGS>

A partir de la version 4.0 du Canal de Stockage, la feuille CSS sera remplacée par le fichier de skin, et la configuration sera du type :

    	<RENDERING
       label="Rendu 1"
       skinFile="skin1.xml"
      />

Pour plus d'information sur l'installation et la configuration du Canal de Stockage, se rendre à la documentation adéquate.

### 1. Le skin

Le skin est un fichier xml qui permet de définir l'aspect du rendu d'un espace inJac, et ce à travers trois types d'éléments:

1. le style : les couleurs, effets svg, fontes.
2. la disposition : les coordonnées et tailles des éléments
3. le contenu : les images et liens que l'ont veut rajouter, les éléments optionnels tels que recherche, RSS, contenus isssus de base de données...

##### Structure de la page de rendu :

##### Cette image montre la correspondance entre les éléments de la page de rendu, le fichier de skin, et les éléments CSS utilisés par les balises HTML :

#####

Légende | Element skin (XPath) | Element(s) CSS générés
(1) | header/gensvg | .genheader
(2) | header/framesvg | #headerFrame, #headerXX
(3) | header/logos/logo[position()=0] | #[logo/@id]
(4) | header/links/link[position()=0] | #[link/@id]
(5) | navpan/gensvg | .gennavpan
(6) | navpan/framesvg | #navpanFrame, #navpanXX
(7) | tools/tool[@type='lucene'] | #lucenetool-title, #iToollucene

#### 1.1 Eléments principaux :

Voici un squelette de fichier skin, montrant les éléments de type contenu(qui contiennent dans leurs attributs des éléments de style et de layout):

    <skin>
     		<header>
     			<logos/>
    			<links />
     		</header>
     		<navbar>
     		<navpan>
     			<view/>
     			<navpan-title/>
    		</navpan>
     		<doc>
     			<doc-title/>
      		<doc-element/>
     		</doc>
     		<tools>
     			<tool/>
     		</tools>
     		<footer>
     			<validators>
    				<validator/>
     			</validators>
     		</footer>
     </skin>

Voici une description des éléments principaux (pour une description détaillée, se reporter au fichier de skin fournis et à la DTD skin-v1.dtd, dans le répertoire injac/dtd) :

logos : permet d'ajouter des images au rendu, en ajoutant un élément logo.

> - id permet d'établir une correspondance avec la feuille CSS en étant l'identifiant de la balise générée dans le rendu HTML.

> - name est le nom alternatif de l'image

> - src est le nom du fichier de l'image(cf. accés au ressources)

links : permet d'ajouter des liens au rendu, en ajoutant un élément link.

> - id permet d'établir une correspondance avec la feuille CSS en étant l'identifiant de la balise générée dans le rendu HTML.

> - name est le nom affiché du lien

> - href est l'URL absolue de la page.

navbar : barre de navigation(chemin courant)

navpan : panneau de navigation

doc : document(espace d'affichage également utilisé pour la recherche avancée et les résultat de recherche)

doc-title : pour définir le style des titres de documents

doc-element : pour définir le style des éléments du document

tools : permet d'ajouter des éléments optionnels comme un formulaire de recherche, un flux RSS, ou des liens issus d'une base de donnée : Annonces d'un canal uPortal, par exemple).

> - type permet de choisir quel type d'outil on veut ajouter : lucene, rss, ou dblinks.

> En fonction du type choisi, les attributs à renseigner changent :

> pour type=lucene :

> > - text : champs texte précédent la zone d'edition

> > - approx : nombre flottant entre 0 et 1, indique le degré d'approximation de la recherche par rapport au terme, du plus tolérant au moins tolérant. La valeur par défaut est 0.5.

Note : pour les attributs "id", il est conseiller de choisir des identifiants suffisamment spécifiques pour qu'il n'y ait pas de risque de collisions avec d'autres identifiants.

#### 1.2 Elements SVG

Deux éléments spécifiques SVG sont utilisés pour la génération d'images automatique, avec arrondis, effets de flou et d'ombre portée (d'autres suivront) :

- gensvg : produit une image JPEG.

ex. :

    <navpan (...) >
    	<gensvg width="150" height="32" gfilter="ompor" x="0"
       bgcolor="#FAEBD7" color="#FFBD05" stroke="#BE5332" stroke-width="5" filter="blur2"/>
    </navpan>

--> Style CSS produit :

    .gennavpan {
           width: 150px;
           height: 32px;
           background-image: url(../../gen/skin-1N/navpan.jpeg);
    }

- framesvg : produit un ensemble de neuf images JPEG pour un cadre redimensionnable, avec arrondis, effets de flou et ombre portée.

ex. :

    <header (...) >
    	<framesvg z-index="0" left="5" top="25" width="full"
     	 height="60" rx="10" ry="10" bgcolor="#FAEBD7"
     	 color="#E6E6FA" stroke="#000000" stroke-width="3" filter="blur1"/>

--> Style CSS produit(extrait) :

    #headerFrame{
    }

    #headerLT{
            position:absolute;
            top:25px;
            left:5px;
             width: 15px;
            height: 15px;
    	background-image: url(../../frame/skin-1N/header/LT.jpeg);
    }
    #headerXX ...

### 2. Le style CSS

Le skin permet de générer automatiquement une feuile de style CSS. Toutefois, pour une personnalisation encore plus poussée, on peut redéfinir les éléments CSS utilisés avec une feuille de style de son propre cru, éditable avec n'importe quel outil de conception Web. Cette feuille de style doit juste être placée dans le répertoire des feuilles CSS(local ou webdav, voir config. iconf.xml), et porter le même nom que le skin, mais en changeant l'extension :

ex.: pour un skin nommé skin1.xml --> skin1.css

Pour faciliter la création d'une telle feuille CSS, on peut également partir de la feuille générée, la copier, la renommer comme décrit précedemment, et la modifier.

##### réutilisation d'une feuille CSS générée :

L'URL pour obtenir la feuille de style générée automatiquement est : injac/genskin/gencss/[nom du fichier de skin].css

ex.: pour un skin nommé skin1.xml --> injac/genskin/gencss/skin1.xml.css

#### 3. Principaux éléments CSS pour balises <div> :

iHeader(header-title, headerLinks)
iNavBar
iNavPan | iDocRender(iDocToPdf, doc-title)
iTools

Exemple:

On souhaite ajouter une image d'arrière-plan(background.png) à l'espace de rendu du document.

1. placer l'image dans le repertoire des ressources(injac/media si l'option localResources est à true)

2. editer la feuille de style et modifier l'élément iDocRender :

#iDocRender

{

position:relative;

top:140px;

left:150px;

width:55%;

background-image: url(_images/background.png);

}

Note: toute url pour les ressources graphiques internes à inJac doit inclure le chemin _images devant le nom de l'image, et ce que l'emplacement des ressources soit défini en local ou non(cf iconf.xml). Cette url sert à différencier les pipelines du sitemap inJac.

## Configuration avancée

## A. Configuration de Tomcat et Cocoon

##### 1. Options de rechargement de Cocoon ou du sitemap

Une url permet forcer le rechargement de Cocoon aprés par exemple une modification de xconf.conf :

http://localhost:8080/cocoon?cocoon-reload=true

Note: Chaque fois que je l'ai testée, elle a fait planter la servlet.

En mode développement ce n'est pas gênant, mais en production, il ne faut pas oublier de le désactiver dans cocoon/WEB-INF/web.xml:

    <!--
       Allow reinstantiating (reloading) of the cocoon instance. If this is
       set to "yes" or "true", a new cocoon instance can be created using
       the request parameter "cocoon-reload"
    .-->
    <init-param>
      <param-name>allow-reload</param-name>
      <param-value>no</param-value>
    </init-param>

En outre le rechargement du sitemap peut aussi être configuré dans cocoon.xconf à la dernière ligne :

<sitemap file="sitemap.xmap" reload-method="asynchron" check-reload="yes"/>

##### 2. Configuration mémoire de Tomcat

Cocoon nécessite un minimum de 128M pour fonctionner correctement, sachant que rien qu'au lancement 75mo sont utilisés, et le maximum reste dépendant du nombre d'utilisateurs. Il faut donc indiquer à la jvm que le servlet container doit se lancer avec les options -Xms128m -Xmx256(min et max de mémoire) :

Dans le répertoire {$CATALINA_HOME}/bin, editer le fichier catalina.bat et/ou catalina.sh, et chercher la variable CATALINA_OPTS, et lui rajouter les options -Xms128m -Xmx256 :

catalina.bat :

set CATALINA_OPTS=-Xms128m -Xmx256m -server -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000

catalina.sh :

CATALINA_OPTS="-Xms128m -Xmx256m $CATALINA_OPTS"

## B. Connecter une base de données

Pour utiliser des résultats de requêtes SQL dans un pipeline Cocoon, voici les étapes nécessaires, avec pour illustrer l'exemple d'une connection à la base « uportal » sous MYSQL :

##### 1. Placer l'archive jar contenant le driver jdbc dans cocoon\WEB-INF\lib

Ex. : mysql-connector-java-3.0.10-stable-bin.jar

##### 2. Editer le fichier web.xml et rajouter les lignes en rouges (dans cocoon\WEB-INF)

Ex.:

<init-param>

<param-name>load-class</param-name>

<param-value>

<!-- For parent ComponentManager sample:

org.apache.cocoon.samples.parentcm.Configurator -->

<!-- For IBM WebSphere:

com.ibm.servlet.classloader.Handler -->

<!-- For Database Driver: -->

org.hsqldb.jdbcDriver

<!-- For Mysql Database: -->

com.mysql.jdbc.Driver

</param-value>

</init-param>

##### 3. Editer le fichier cocoon.xconf (dans cocoon\WEB-INF):

Dans l'élément <datasources>, ajouter un élément <jdbc> décrivant la connexion :

Ex. :

<jdbc logger="core.datasources.anouncement" name="anouncement">

<pool-controller max="10" min="5"/>

<auto-commit>true</auto-commit>

<dburl>jdbc:mysql://localhost:3306/uportal</dburl>

<user>uportalU</user>

<password>azerty</password>

</jdbc>

Dans l'élément <autoincrement-modules>, choisissez la ligne qui va bien :

Ex. :

<component-instance class="org.apache.cocoon.components.modules.database.MysqlAutoIncrementModule" logger="core.modules.auto" name="auto" />

##### 4. Faire un fichier de requête xml (exemple :cocoon\injac\queries\cat_anouncement-sql.xml) :

Ex. :

<?xml version="1.0"?>

<anouncement xmlns:sql="http://apache.org/cocoon/SQL/2.0">

<execute-query xmlns="http://apache.org/cocoon/SQL/2.0">

<query>

select TITLE, DESCRIPTION from upc_cu_ann_topic limit 5

</query>

</execute-query>

</anouncement>

##### 5. Dans le sitemap :

Ajout d'un pipeline utilisant SQLTransformer

ex.:

<map:match pattern="Anouncement" >

<map:generate src="cat_anouncement_sql.xml" />

<map:transform type="sql">

<map:parameter name="use-connection" value="anouncement"/>

</map:transform>

<map:serialize/>

</map:match>

Création : 10 novembre 2004 - François JANNIN(ENSEEIHT) |
Modifications : 10 novembre 2004 - François Jannin (ENSEEIHT) - Modifications v1.0 7 avril 2005 - François Jannin - Modifications v2.1