Comment créer votre propre modèle PDF

03 mars 2020 5 min read
Écrit par Andreea Chirica, Spécialiste Communications et Support

Savez-vous qu'il est possible de personnaliser l'aspect de vos pages wiki exportées en PDF ? Par exemple, exporter un devis mis en page pour un de vos clients, ou un rapport mensuel sur l'activité économique et l'évolution financière de votre entreprise. Tout cela est possible avec XWiki, et nous allons vous le montrer dans cet article. Nous vous proposons de générer des PDF de type professionnels, dotés d'une page de couverture, d'une table des matières et d'un pied de page avec les coordonnées de votre entreprise.

De quoi avez-vous besoin pour votre exportation PDF ?

Vous aurez besoin de 3 ingrédients principaux : un compte utilisateur en mode avancé (à définir dans le profil), une page wiki à exporter au format PDF, une page PDFClass et une page modèle (PDF Template).

J'ai créé un exemple de page pour cet article, intitulé "Mon Rapport". Elle comprend deux messages d'information et d'avertissement, un diagramme, un graphique, un tableau, et quelques autres éléments.

Faut-il ajouter quelque chose de spécial dans ma page wiki ?

La réponse est oui, mais pas de panique. Il suffit d'ajouter quelques attributs de classe aux éléments de votre page afin de les viser facilement dans le style ajouté dans la page Modèle PDF. Par exemple, pour un tableau, j'ai ajouté en mode éditeur de source (% class="mytable" %) au-dessus du tableau souhaité. Les macros de messages d'information et d'avertissement offrent la possibilité d'ajouter une classe CSS directement lors de leur ajout sur la page ou plus tard, lors de l'édition des macros, et même en édition en mode source.
Suivez le code dans les captures d'écran ci-dessous pour ajouter ces éléments dans une page de test sur votre wiki. Éventuellement demandez de l'aide à un collègue ayant quelques connaissances en syntaxe wiki ou en HTML/CSS.

Comment créer la page PDFClass ??

D'abord, assurez vous que votre compte utilisateur est bien en mode "avancé" (option à modifier dans votre profil utilisateur). Puis créez une nouvelle page terminale que vous nommerez "PDFClass", avec "XWiki" comme page parente. Cette page sera donc placée sous la page "XWiki" dans l'arborescence. Et elle contiendra les propriétés de personnalisation qui seront ensuite ajoutées à votre modèle PDF en mode objet. (nous allons voir ça par la suite).
Après avoir créé et enregistré cette nouvelle page, modifiez la en mode "Classe" (dans le menu de page avancé, ou via l'URL : http://votreserveur/xwiki/bin/edit/XWiki/PDFClass?editor=class) et ajoutez les propriétés TextArea suivantes : 

  • style : contient les règles CSS utilisées pour générer votre contenu en format PDF.
  • xhtmlxsl : contient la transformation XHTML2FO XSL en HTML, texte ou autres types de documents XML, qui remplacera celle par défaut. Notez que vous pouvez également utiliser "velocity" dans ce champ (utile pour obtenir le contenu d'un fichier .xsl joint, ce qui est très pratique lorsque vous devez mettre beaucoup de code, puisque les champs TextArea sont limités à 60 000 caractères). Cette propriété ne sera pas utilisée dans notre exemple.
  • fopxsl : contient la transformation XSL du FOP qui remplacera celle par défaut. Cette propriété ne sera pas utilisée dans notre exemple.

Les propriétés xhtmlxsl et fopxsl sont souhaitées uniquement si vous voulez remplacer les valeurs par défaut.
A noter que le code CSS de la propriété style remplacera les valeurs par défaut de XWiki. Vous pouvez également créer un fichier pdf.css sur votre système de fichiers, dans le dossier \webapps\xwiki\templates\ ou l'ajouter dans votre page de skin depuis l'administration de votre wiki, section Look and Feel, et dans l'onglet Thèmes. Ceci permet de personnaliser la génération PDF d'une manière globale, et non suivant un modèle PDF dédié comme nous le faisons dans cet article.

Pour chaque propriété ajoutée, veillez à définir les métadonnées des propriétés "Type de contenu" et "Éditeur" sur Texte brut afin de ne pas obtenir l'éditeur WYSIWYG qui l'écriture de code HTML/XML/XSL plus complexe.

Dans mon exemple, j'ai ajouté quelques propriétés supplémentaires pour personnaliser encore plus l'aspect du PDF exporté : cover (page de couverture), header (en-tête), footer (pied de page). Vérifiez que vous avez défini les bonnes valeurs pour les métadonnées "Type de contenu" et "Éditeur" de ces trois propriétés.
Ici, j'ai sélectionné la syntaxe wiki pour la métadonnée "Type de contenu" de la cover et du header. J'ai sélectionné l'option Texte brut pour la métadonnée "Éditeur". Pour le pied de page (footer), j'ai sélectionné l'option Texte brut pour les deux métadonnées.

Là encore, suivez les captures d'écran ci-dessous pour créer votre page PDFClass :

Comment créer la page du modèle de PDF ?

Créez une nouvelle page terminale (par exemple "ModeleRapportPDF"), ayant "XWiki" comme page parente (comme pour la page PDFClass). Enregistrez-la, puis modifiez-la en mode "Objet" (dans le menu de page avancé, ou via l'URL : http://yourserver/xwiki/bin/edit/XWiki/ModeleRapportPDF?editor=object). Ajoutez-y l'objet PDFClass nouvellement créé. Dans la section "style" de la propriété, vous pourrez ajouter le style souhaité sur les pages qui seront exportées sous forme de fichier PDF. Dans cet exemple, j'ai ensuite commencé à remplir la propriété "style" avec du code CSS, la section "cover" et le "header" avec un lien chez une image initialement attachée à la page ModeleRapportPDF (utilisant la syntaxe XWiki), et la section "footer" avec un tableau en HTML.

Comment utiliser le nouveau modèle de PDF ?

Dès cette étape, il est possible d'exporter vos pages XWiki en format PDF.
Considérons dans cet exemple la page wiki nommée "Mon rapport" créée dans l'espace Bac à sable. Je clique sur l'option Exporter, je sélectionne le format PDF, je choisis les sections que je veux exporter en même temps que la page (par exemple, la couverture, la table des matières, l'en-tête, le pied de page, les commentaires, les images jointes), puis je clique sur le bouton Exporter.
Il existe actuellement deux façons de prendre en compte le style qui a été ajouté dans le fichier "ModeleRapportPDF" :

  • La première consiste à ajouter dans l'URL du fichier exporté le nom du modèle de PDF avec le nom de l'espace qui localise le fichier : par exemple http://votreserveur/xwiki/bin/export/Space/Page?pdftemplate=XWiki.ModeleRapportPDF&format=pdf&language=fr.
  • La deuxième option consiste à utiliser une extension qui permet de choisir parmi plusieurs modèles de PDF lors de l'exportation d'une page.

Documentation et exemples utiles

Voici la page de documentation actuelle décrivant comment personnaliser l'aspect de votre PDF exporté. Vous y trouverez des méthodes plus avancées pour personnaliser votre PDF exporté : par exemple en modifiant le skin de votre wiki ou en remplaçant le fichier xhtml2fo.xsl avec des règles spécifiques pour la page à exporter. 

N'hésitez pas à consultez les snippets contenant deux exemples de style, dont le second se réfère au style utilisé pour l'exemple de page "Mon Rapport" utilisé dans cet article : 

Voici le fichier PDF exporté à partir de la page Mon Rapport

Alors, quelle personnalisation voulez-vous ajouter à vos exports PDF ? Faites-le nous savoir dans les commentaires ci-dessous ou sur les réseaux sociaux. Nous serons heureux de vous donner d'autres exemples de scénarios, et si nécessaire vous conseiller nos offres de services adaptées à vos besoins.

Articles similaires :