Comment créer votre propre modèle PDF

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 : une page PDFClass, une page PDF Template, et une page wiki à exporter au format PDF.

J'ai créé un exemple de page pour cet article, nommé Mon Rapport. Vous verrez comment personnaliser l'apparence des titres, des macros de messages (info, boîte, avertissement, erreur, succès, code), d'un diagramme, d'une image dans une macro de galerie, d'un graphique et de tableaux dans un PDF exporté depuis votre wiki.

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. 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 :

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.
• cover : si vous souhaitez modifier la couverture de votre exportation PDF.
• header : si vous souhaitez ajouter un texte ou une image spécifique sur l'en-tête de chaque page de votre exportation PDF.
• footer : si vous avez besoin d'un contenu spécifique dans le pied de page, comme les coordonnées de votre entreprise.
• (optionnel) 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.
• (optionnel) fopxsl : contient la transformation XSL du FOP qui remplacera celle par défaut. Cette propriété ne sera pas utilisée dans notre exemple.

Lorsque vous modifiez la page PDFClass en mode classe, assurez-vous de définir les types de contenu et d'éditeur appropriés pour les propriétés que vous ajoutez. Dans mon exemple, j'ai utilisé :

• pour style j'ai utilisé l'option TexteBrut pour les métadonnées de type Éditeur et Contenu.
• pour cover, header et footer j'ai choisi l'option Syntaxe Wiki dans les métadonnées du type de contenu, et TexteBrut pour les métadonnées de type Éditeur.

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

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 référencer facilement dans le style ajouté dans la page Modèle PDF.

Par exemple, pour un tableau, j'ai ajouté en mode éditeur de source ~ au-dessus du tableau souhaité. J'ai également ajouté des classes aux sections d'en-tête, car je veux également leur ajouter du style. Ensuite, sur les macros, sur certaines d'entre elles (comme les macros info, warning, galerie) vous pouvez ajouter une cssClass directement lors de leur ajout sur la page ou plus tard, lors de l'édition des macros ou également en mode éditeur de sources.

Sur les images de la galerie ci-dessous, vous pouvez voir la page qui sera exportée en PDF éditée en mode Source et les classes des sections qui seront ciblées par le CSS ajouté dans l'objet style du modèle de rapport PDF.

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

Créez une nouvelle page terminale (par exemple Modèle Rapport PDF) avec XWiki comme parent, enregistrez-la puis éditez-la en mode "Object" (par exemple https:~/~/votreserveur/xwiki/bin/edit/XWiki/ModeleRapportPDF?editor=object). Ajoutez-y l'objet PDFClass nouvellement créé. Dans la section de la propriété "style", vous pourrez ajouter le style souhaité en ciblant vos pages que vous souhaitez exporter en tant que fichier PDF.

J'ai ensuite commencé à remplir la propriété style avec du code CSS. J'ai placé dans cet snippet le CSS complet utilisé pour l'exportation PDF de cet article.

Ces lignes de code ont ensuite été placées dans les propriétés suivantes : couverture, en-tête et pied de page :

• dans la propriété cover, j'ai ajouté une image qui était attachée à la page Modèle Rapport PDF et un titre

``
{{velocity}}
{{html}}
<img src="$xwiki.getAttachmentURL("XWiki.ModeleRapportPDF", "undraw_prog.png")" width="400"/>
<div class="covertitle">Mon Rapport</div>
{{/html}}
{{/velocity}}
``

• dans la propriété de header, j'ai ajouté une image plus petite qui a été attachée à la page du modèle de rapport PDF et le même titre que sur la cover

``
{{velocity}}
{{html}}
<img src="$xwiki.getAttachmentURL("XWiki.ModeleRapportPDF", "chart.png")" width="50" class="page-logo"/>
<div class="page-title">Mon Rapport</div>
{{/html}}
{{/velocity}}
``

• dans la propriété du pied de page, j'ai ajouté le numéro de page, une adresse e-mail pour le contact, un site web, et une ligne décrivant sur quel type d'instance XWiki l'exemple a été fait.

``
{{velocity}}
{{html}}
<table class="footer-table" style="padding-bottom: 10px">
<tbody>
$msg.Page <span class="page-number"></span>
<tr>
<td>Email: <a href="mailto:contact@xwiki.com">contact@xwiki.com</a></td>
<td style="text-align: right;">Site web: <a href="/fr/">www.xwiki.com</a></td>
</tr>
</tbody>
</table>
<div style="padding-bottom: 20px; font-size: 8px;">
Cet exemple d'exportation PDF a été réalisé sur XWiki Jetty 13.4.5. N'hésitez pas à l'essayer sur votre propre wiki.
</div>
{{/html}}
{{/velocity}}
``

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". 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), puis je clique sur le bouton Exporter. Vous obtiendriez un look ordinaire, sans aucune personnalisation.

Il existe actuellement deux façons de prendre en compte le style qui a été ajouté dans le fichier Modèle Rapport PDF :

• L'une d'elles serait d'ajouter dans l'URL du fichier exporté le nom du modèle PDF avec le nom de l'espace qui permet de localiser le modèle. Lors de l'exportation sans la couverture, la table des matières, l'en-tête et le pied de page, l'URL serait la suivante :

//https:~/~/votreserveur/xwiki/bin/export/Main/monrapport/WebHome?pdftemplate=XWiki.ModeleRapportPDF\&format=pdf//
et avec la table des matières, la couverture, l'en-tête et le pied de page sélectionnés pour l'exportation, l'URL sera la suivante :
//https:~/~/votreserveur/xwiki/bin/export/Main/monrapport/WebHome?pdftemplate=XWiki.ModeleRapportPDF\&format=pdf\&pdfcover=1\&pdfcover=0\&pdftoc=1\&pdftoc=0\&pdfheader=1\&pdfheader=0\&pdffooter=1\&pdffooter=0//

• 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. Cependant, veuillez noter que l'extension n'a pas été entretenue au fil des ans.

Documentation et exemples utiles

Voici la page de documentation décrivant comment personnaliser l'aspect et la convivialité de votre PDF exporté (en référence à l'ancien PDF Export présent sur les versions de XWiki antérieures à 14.10), avec un aperçu avancé de chaque composant et de son fonctionnement. Vous remarquerez qu'il existe 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 :

• Ajoutez des bordures de tableau à votre PDF
• Ajoutez une apparence complète à votre modèle de PDF personnalisé (le style CSS utilisé pour l'exportation PDF de Mon Rapport de cet article)

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

{{pdfviewer file="MonRapport.pdf"/}}

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.