Plus loin avec le Maven Site
Fabian Piau | dimanche 4 avril 2010 - 22:29Introduction
Si votre projet est mavenisé (comprenez sous Maven), il serait vraiment dommage de ne pas utiliser toutes les possibilités du Maven Site.
Bien configuré, il peut devenir rapidement la « vitrine » de votre projet en centralisant ses informations les plus utiles tout en gardant un effort de maintenance très faible. Les sites Maven sont de plus en plus utilisés dans les projets open source.
Cela peut être des informations générales sur le projet (description, équipe, dépendances…), des sous-rapports spécifiques (Checkstyle, PMD, Javadoc, SureFire, Cobertura…), une FAQ (Frequently Asked Questions) sur le projet, bref ce que vous voulez…
Ce tutoriel va vous apprendre à personnaliser le site de base généré par Maven.
Prérequis : Maven doit être installé sur votre machine.
Version utilisée : 2.0.9. Suivant les versions, les commandes peuvent être différentes.
Création du projet
Tout au long du tutoriel, nous allons utiliser un projet Maven 2 de test généré grâce au plugin Archetype.
Dans un terminal, tapez :
Choisissez le modèle « maven-archetype-site ». Il permet de générer une structure complète de site.
Archetype vous demande plusieurs informations :
- Le groupId du projet :
demo.mavensite.personalization; - L’artifactId :
maven-site-personalization; - La version : Appuyez directement sur Entrée, la version
1.0-SNAPSHOTnous convient; - Le package où mettre les classes : Par défaut, il reprend l’artifactId. C’est parfait, appuyez donc sur Entrée.
Un récapitulatif s’affiche, validez vos choix en appuyant sur Entrée une dernière fois.
Le projet est maintenant créé.
Parcours rapide du projet créé
Un dossier a été créé portant le nom « maven-site-personalization » .
Voici son architecture :
Un dossier « fr »? Et oui! Le Maven Site supporte l’internationalisation. Par défaut, celui généré par Archetype est disponible en anglais (langue par défaut) et en français.
Voici une description des différents fichiers créés.
site.xml: Le descripteur de site. Il définit le site dans son ensemble (la bannière, le menu à gauche, les liens disponibles). C’est en quelque sorte le point d’entrée de la génération;site_fr.xml: Le descripteur pour la version française;- Tous les autres fichiers représentent une page du site. Pas d’HTML ici, les pages sont écrites dans des formats spécifiques à Maven qui serviront ensuite à générer du HTML.
Le site d’exemple reprend les 3 différents formats possibles (APT, Xdoc et FML).
- Format Xdoc : C’est un format XML, ce format est disponible depuis les versions 1.x de Maven;
- Format APT « Almost Plain Text » : Désigné remplaçant du Xdoc, ce format de type wiki est beaucoup moins verbeux;
- Format FML : C’est le format utilisé pour créer des FAQ.
Génération du site
Après cette analyse de structure, nous allons générer le site à l’aide de la commande :
ou
pour le lancer en local avec le serveur Jetty.
Le site généré est disponible dans /target/site/index.html (ou http://localhost:8080 si vous avez choisi Jetty)
Le Maven Site généré
Il s’agit du site par défaut. Pour accéder à la version française modifiez le chemin par /site/fr/index.html (ou http://localhost:8080/fr).
Un peu contraignant ce changement de langue, n’est-ce pas?
Nous allons voir juste après comment ajouter des liens pour naviguer facilement entre les 2 langues.
Ajout d’une page
Pour ajouter une nouvelle page au site, il suffit d’ajouter un fichier dans un des 3 dossiers
( « apt », « fml » ou « xdoc » ).
Par exemple, j’ai ajouté le fichier « my_new_category.apt » contenant un texte bien formaté dans le dossier « apt ».
Il faut ensuite le référencer dans le descripteur de site.
<?xml version='1.0' encoding='ISO-8859-1'?>
<project name='Maven'>
<bannerLeft>
<name>Maven</name>
<src>http://maven.apache.org/images/apache-maven-project.png</src>
<href>http://maven.apache.org/</href>
</bannerLeft>
<bannerRight>
<src>http://maven.apache.org/images/maven-small.gif</src>
</bannerRight>
<body>
<links>
<item name='Apache' href='http://www.apache.org/' />
<item name='Maven 1.0' href='http://maven.apache.org/'/>
<item name='Maven 2' href='http://maven.apache.org/maven2/'/>
</links>
<menu name='Maven 2.0'>
<item name='APT Format' href='format.html'/>
<item name='FAQ' href='faq.html'/>
<item name='Xdoc Example' href='xdoc.html'/>
<item name='My new category' href='my_new_category.html'/>
</menu>
</body>
</project>
Relancez la génération du site
et un nouvel item apparait dans le menu dirigeant vers votre nouvelle page.
Ajout d'une nouvelle page
J’en ai profité pour vous montrer les différentes fonctionnalités d’ATP (tableaux, liste, titres, formatage de texte…)
Internationaliser son site facilement
Nous allons ajouter des liens pour changer la langue.
Dans site.xml :
<project name='Maven'>
[...]
<body>
[...]
<menu name='Other languages'>
<item name='Français' href='/fr/index.html'/>
</menu>
</body>
</project>
Dans site_fr.xml :
<project name='Maven'>
[...]
<body>
[...]
<menu name='Autres langues'>
<item name='English' href='../index.html'/>
</menu>
</body>
</project>
Internationalisation du site
Par défaut, l’anglais est la langue principale. Pour modifier cela, il faut modifier le POM du projet.
Le français est la seule langue disponible.
L’anglais est la langue par défaut, le français est disponible.
Le français est la langue par défaut, l’anglais est disponible.
Le site est multilingue, disponible également en espagnol et en allemand.
Ajouter les rapports par défaut
Comme on peut le constater, il est très simple d’ajouter des pages et de modifier la structure du site.
Vous remarquerez que les différents rapports Maven par défaut (informations générales sur le projet) ne sont pas inclus dans le site.
Il vous suffit d’ajouter la balise :
<project>
[...]
<body>
[...]
<menu ref='reports'/>
</body>
</project>
Les rapports par défaut
Autres modifications du contenu
Il existe d’autres possibilités de personnalisation en modifiant uniquement le descripteur :
- Ajouter des liens dans la bannière;
- Changer le titre de la fenêtre;
- Modifier la position de la date de publication;
- Modifier le logo « Built by Maven », les images dans la bannière…;
- Afficher la version du logiciel (dans notre cas, la 1.0-SNAPSHOT);
- etc.
Vous pouvez consulter toutes les informations sur le descripteur de site.
Changer le design du site avec des « skins »
Il est également possible de changer l’interface graphique générale du site.
Pour cela, il suffit (une fois de plus) de modifier le descripteur du projet (pas le POM) en ajoutant :
<project>
[...]
<skin>
<groupId>org.apache.maven.skins</groupId>
<artifactId>maven-stylus-skin</artifactId>
<version>1.2</version>
</skin>
[...]
</project>
Malheureusement, peu de thèmes sont disponibles. A l’heure où j’écris cet article, 3 thèmes officiels seulement existent.
- maven-classic-skin (ancien thème, version 1.0);
- maven-default-skin (thème par défaut, version 1.0);
- maven-stylus-skin (thème utilisé par le site officiel, version 1.2).
Classic-site-skin
Default-site-skin
Stylus-site-skin
En recherchant un peu sur internet, vous réussirez à en trouver quelques autres.
En plus du contenu, il est tout à fait possible d’avoir des skins différents pour les versions française et anglaise (car 2 descripteurs de site différent).
Aller plus loin dans la personnalisation
Pour obtenir un site à votre image, il est possible d’aller encore plus loin en modifiant soit même le design.
Il est possible d’ajouter vos propres images, vos fichiers de style CSS respectant votre charte graphique, vos liens spécifiques sur le projet… et ainsi à ne pas vous limiter aux fonctions de base.
Ensuite et si le résultat vous convient, vous pourrez packager vos modifications et les rendre disponibles sous forme de skin.
Voici une sélection de designs que j’ai pu apprécier. Il faut dire que le résultat est plutôt réussi pour certains. On en oublierait presque qu’il s’agit d’un Maven Site…
 |
 |
 |
 |
 |
 |
 |
 |
