Utilisation de plantumlAuteur : Julien Gauchet le 21/11/2017 (1 revision)

Cette page permet de présenter de fonctionnement de différents outils pour améliorer l'aspect du site documentaire ou pour générer du contenu

1. Intégration de prism

1.1. Présentation de l'outil

Prism est un outil qui permet de coloriser le code (Java, SQL, R) des pages web. Il est basé sur JQuery et sur une CSS. C'est l'outil utilisé dans ce site pour coloriser le code.

Pour accéder à la documentation de l'outil prism : Site de prism

Il n'est pas possible d'intéger prism directement dans un maven-site :

  • La CSS prism est basée sur des classes qu'il n'est pas possible de générer avec Doxia
  • Il serait possible d'utiliser le format xhtml mais celà rendrait le code de notre site moins lisible, qui plus est, la génération des balises <code> pose problème.

1.2. Intégration dans un maven-site

L'objectif est d'intégrer prism dans les fichiers Doxia et d'utiliser JQuery afin de modifier la page pour appeler le plugin Prism

1.2.1 Le code dans un fichier apt

Le format que nous allons choisir est de présener le code à insérer dans un texte pré-formaté qui commencera par (code=langage). Par exemple :

----
(language=sql)
CREATE TABLE etat_enquete (
  id text,
  libelle text,
  CONSTRAINT etat_enquete_pkey PRIMARY KEY (id)
);
INSERT INTO etat_enquete VALUES ('N', 'Enquête non débutée');
INSERT INTO etat_enquete VALUES ('E', 'Enquête en cours');
INSERT INTO etat_enquete VALUES ('T', 'Enquête terminée');
----

De cette manière, si javascript n'est pas activé (ou si une erreur survient), le code sera tout de même présenté dans un format satisfaisant.

La présentation sous forme de texte pré-formaté est la seule alternative existante pour la présentation de code, le fonctionnement n'est donc pas dégradé.

Aspect du site sans javascript

1.2.2 Intégration du javascript Prism

Créer le dossier src/site/resources/js (s'il n'existe pas) et déposer le fichier Prism.js téléchargeable sur le site de Prism. Vous pouvez également le récupérer ici : Prism

Créer le fichier apater-prism.js dans le même dossier et coller dans ce fichier le code suivant :

$.each([ "markup", "css", "clike", "javascript", "c", "bash", "batch", "cpp", "csharp", "git", "ini", "java", "json", "latex", "less", "makefile", "markdown", "matlab", "pascal", "perl", "php", "sql", "properties", "python", "r", "jsx", "sas", "scala", "plsql", "textile", "wiki" ], function( index, value ) {
	$("pre:contains('language="+value+"')").each(function() {
		$(this).text($(this).text().replace(/ *\( *language=[^ ]* *\) *\r*\n/, ""));
		$(this).wrapInner("<code class='language-"+value+"'></code>");
	});
});

Ce code permet d'adapter la structure de la page au code Prism.

Le lien vers Prism doit se faire après le chargement de la page ce qui présente une difficulté supplémentaire. La solution que j'ai trouvée est de placer l'appel de Prism dans le footer de site.xml

<body>
	...
	<footer>
		<![CDATA[
			<a href='#'>Haut de page</a> | <a href='index.html'>Accueil</a>
			<script src="https://gforge.insee.fr/www/tourisme3/js/adapter-prism.js" type="text/javascript"></script>
			<script src="https://gforge.insee.fr/www/tourisme3/js/prism.js" type="text/javascript"></script>
		]]>
	</footer>
</body>

Notez que les liens vers les scripts js pointent vers gforge. L'objectif est de se passer des chemins relatifs vers le dossier js qui sont tous différents en fonction du dossier dans lequel on se situe. Il faudra donc faire un premier site:deploy avant que cela ne fonctionne en local comme sur gforge

1.2.3 Intégration de la CSS Prism

Coller le contenu de la css prism dans le fichier site.css. Cette css est téléchargeable sur le site de prism et il est possible de la récupérer ici CSS Prism

2. Créer un fil d'ariane (breadcrumb)

2.1. Présentation de l'outil

Un fil d'ariane est une aide à la navigation sous forme de signalisation de la localisation du lecteur dans un document

Il est possible de créer un fil d'ariane avec le plugin maven-site mais celui-ci est le même pour l'ensemble des pages du site et ne présente donc pas vraiment d'intéret. Cet outil a plutôt été prévu pour assurer la navigation entre un site parent et les sites des modules d'un projet.

On peut cependant créer un fil d'ariane à la main. C'est un peu pénible pour les pages écrites à la main mais pour les pages générées, cela n'a aucune indicence ou presque.

2.2. Intégration dans un maven-site

2.2.1 Modification des pages apt

Le fil d'ariane sera écrit sous forme d'une liste décrivant les différents écrans à parcourir pour arriver à la page. Tous les éléments seront cliquables sauf la page elle même. Nous allons donc générer ce genre de liste au tout début du document :

  * {{{../index.html}Accueil}}

  * {{{./index.html}Dictionnaire des données}}

  * adresses

[]

Titre page

2.2.2 Modification de la CSS

Pour modifier l'aspect de cette liste, ajouter le code suivant à la css du site

div#bodyColumn > ul  + div.section h2 {
	margin-top:0;
}
#bodyColumn > ul{
	margin:0;
	margin-top: 3px;
    list-style: none;
}
#bodyColumn > ul li {
    display: inline;
}
#bodyColumn > ul  li+li:before {
    padding: 0 8px 0 8px;
    color: black;
    content: ">";
}
#bodyColumn > ul  li a {
    color: rgb(3, 121, 183);
    text-decoration: none;
}
#bodyColumn > ul li a:hover {
    color: #01447e;
    text-decoration: underline;
}