💡 Ce tutoriel est utile uniquement pour les instances qui utilisent une version de XWiki plus récente que la 14.10.
💡 Pour les versions antérieures à 14.10, voir ce tutoriel.
Vous souhaitez améliorer la façon dont vos pages XWiki sont exportées au format PDF ?
Que vous gériez de la documentation technique, des wikis internes ou des bases de connaissances publiques, la personnalisation de vos modèles PDF en XWiki vous permet de créer des documents professionnels de marque prêts à être partagés, archivés ou imprimés.
Dans ce tutoriel, vous apprendrez étape par étape à créer et à personnaliser un modèle PDF dans XWiki : mise en place de la structure du modèle à l'aide de Velocity et de XHTML, stylisation avec CSS et ajout d'informations dynamiques.
Tutoriel vidéo couvrant tout ce qui suit
Dans le tutoriel suivant, nous allons créer un modèle PDF moderne avec une couverture de marque.
Comment créer un modèle PDF dans XWiki
Vous pouvez créer un modèle PDF à partir de n'importe quelle page de votre wiki. Une bonne pratique serait de garder tous vos modèles PDF liés à un sujet sous une page relative à ce sujet. Cela vous permettra de les retrouver plus facilement plus tard.
#1 Cliquez sur Créer dans le coin supérieur droit de n'importe quelle page.
#2 Attribuez un nom au modèle que vous souhaitez créer. Par exemple, je nommerai le mien « Rapport de l'équipe de développement ».
\#3 Sélectionnez à droite, dans la section des modèles, le type de page intitulé « PDF Template » (Modèle PDF).
#4 Cliquez sur Enregistrer. Vous serez dirigé vers la page du modèle PDF. Ce que vous voyez n'est pas exactement ce à quoi ressemblera le document lorsque vous l'exporterez avec ce modèle PDF. Nous pouvons le modifier afin d'y ajouter des informations et des éléments de style. Pour cela, voir la section suivante.
Comment rendre votre modèle PDF utilisable dans XWiki
Maintenant que vous avez créé votre modèle PDF, vous voudrez probablement voir comment il se présente par défaut pour vous faire une idée de votre point de départ.
Si vous allez sur une page et choisissez de l'exporter au format PDF, vous ne trouverez pas le modèle PDF que vous venez de créer.
Pour le retrouver, vous devez ajouter le modèle PDF créé dans la liste des modèles PDF utilisables de votre wiki. Pour le tutoriel, voir la vidéo suivante de cette page.
Faisons-le ensemble :
#1 Allez dans Administrer le wiki (Administration globale) > Contenu > PDF Export (Exportation PDF).
#2 Dans la section Configuration, cliquez sur le champ Templates.
Dans ce champ multi-sélection, vous trouverez déjà le modèle par défaut.
Dans la liste déroulante qui s'est ouverte, sélectionnez votre modèle récemment créé. Dans mon cas, il s'agit de Rapport de l'équipe de développement.
\\#3// //\\Faites défiler la page vers le bas et cliquez sur Enregistrer.
Votre modèle PDF est maintenant utilisable. ✅
Comment exporter une page au format PDF
Maintenant que vous pouvez utiliser votre modèle PDF récemment créé, vous pouvez aller sur n'importe quelle page que vous souhaitez exporter au format PDF.
#1 Ouvrez le menu de la page en cliquant sur les 3 points dans le coin droit.
#2 Cliquez sur Exporter.
#3 Choisissez PDF parmi les formats disponibles.
#4 Sélectionnez les pages que vous souhaitez inclure dans l'exportation.
#5 Cliquez sur le bouton Exporter.
#6 Dans le champ Template (Modèle), choisissez le modèle que vous souhaitez.
Peut-on éditer un modèle PDF dans XWiki ?
TL;DR, oui.
Dans l'étape précédente, vous avez rendu votre modèle utilisable et vous avez exporté une page pour voir votre modèle.
Bien sûr, ça fonctionne, mais ajoutons un peu plus d'infos et une touche de magie avec l'image de marque de l'entreprise. ✨
#1 Accédez à la page de votre modèle PDF et cliquez sur Modifier.
Lorsque vous entrez dans le mode d'édition de votre modèle, vous pouvez modifier le code Velocity :
- De la couverture du modèle
- De la table des matières
- De l'entête
- Du pied de page
Je sais que la phrase « modifier votre code Velocity » semble un peu effrayante si vous n'êtes pas un développeur mais je vous le promets, c'est simple. Vous pourrez éditer du HTML et ajouter des informations dynamiques très facilement à l'aide de la section suivante.
Comment ajouter des images à mon modèle PDF dans XWiki
| Le HTML Incluez le code suivant dans votre code Velocity (en mode édition de votre modèle PDF, dans votre couverture par exemple). La classe CSS « image » peut être renommée comme vous le souhaitez, assurez-vous simplement d'utiliser le même nom lorsque vous définissez votre classe CSS. Remplacez le « # » par le lien vers l'image dont vous avez besoin. | Le style //Vous pouvez ajouter/modifier ce CSS en suivant les étapes de cette section du tutoriel.// |
|---|---|
| <img class="image" src="#"> | .image { border-radius: 20px; height: 200px;} |
Comment ajouter des informations dynamiques à la couverture de mon modèle PDF dans XWiki
| Cas d'utilisation | Le HTML et Velocity Incluez le code suivant dans votre code Velocity// (en mode édition de votre modèle PDF, dans votre couverture par exemple). La classe CSS « name-classe » peut être renommée comme vous le souhaitez, assurez-vous simplement d'utiliser le même nom lorsque vous définissez votre classe CSS//. Le texte en gras est le code Velocity. |
|---|---|
| Afficher le titre du document. (présent dans le modèle par défaut) | <h1 class="name-class"> $escapetool.xml($tdoc.plainTitle) </h1> |
| Afficher le nom (pretty name) du document sur le wiki. | <div class="author-cover"> $services.wiki.getCurrentWikiDescriptor().getPrettyName() </div> |
| Afficher le nom complet du créateur du document. | <div class="author-cover"> #displayUser($tdoc.authorReference {'useInlineHTML': true}) </div> |
| Afficher la date de création du document. | <div class="date-cover">$xwiki.formatDate($tdoc.getCreationDate(), "MMMM, yyyy")</div> |
| Afficher la date de la dernière modification du document. | <div class="name-class"> $xwiki.formatDate($tdoc.date, "MMMM, yyyy") </div> |
Comment ajouter une image de marque ou un style à la couverture de mon modèle PDF dans XWiki
Nous devons accéder à la partie stylistique de la page de modèle PDF.
Allez dans la barre URL en haut de la fenêtre de votre navigateur.
#2 Supprimez les « » de la fin de votre URL et ajoutez à la fin : ?editor=object
#3 Votre nouvel écran devrait ressembler à ceci (enfin, sans les explications) :
Qu'est-ce que Objects of type XWiki.PDFExport.TemplateClass ?
La partie Velocity. C'est ici que nous définissons la structure et le contenu non stylisé de la couverture, de la table des matières, de l'en-tête et du pied de page du modèle. Vous l'avez déjà vu dans le mode Édition, mais dans une interface légèrement différente. En ouvrant la section située juste en dessous (PDFExport.TemplateClass 0 : ~{~{velocity}}...), vous pouvez éditer chaque élément séparément.
Qu'est-ce que Objects of type XWiki.StyleSheetExtension ?
C'est l’endroit où sont stockées les feuilles CSS, et c'est là où la magie opère. Chaque modèle de PDF est accompagné d’une feuille CSS par défaut qui aide à la mise en forme de base.
Pour ajouter du style, nous aurons besoin des deux.
- La partie Velocity pour ajouter des classes à chaque élément HTML que nous intégrons à la structure.
- La partie CSS pour définir chacune des classes que nous avons ajoutées.
Tout centrer
| Le code HTML et Velocity | Le style |
|---|---|
| Placez toutes vos divs dans une grande div dans le code Velocity de votre modèle PDF. | La grande div peut avoir la classe suivante : {display:flex; flex-direction:column; justify-content:center;} Chaque div de cette grande div sera centrée, mais si elles ont leurs propres éléments, ceux-ci doivent être centrés dans leur propre div. En savoir plus sur la CSS flexbox. |
Ajouter des colonnes sur votre couverture
Utilisez la CSS flexbox ou les grilles pour créer des colonnes.
Autres cas d'utilisation rapides pour styliser votre couverture
- Mettre en gras des éléments de texte : Ajouter font-weight : bold ou, si cela ne fonctionne pas, c'est parce qu'une autre classe l'écrase et que vous pouvez simplement ajouter <b></b> autour de l'élément html que vous souhaitez mettre en gras
- Mettre le texte en majuscule : Ajouter text-transform : uppercase
- Modifier de la taille du texte : Ajouter font-size : 50px
- Modifier l'espacement entre les éléments : Ajouter margin-top : 20px ; pour plus d'espace vers le haut ou margin-bottom : 20px ; pour plus d'espace vers le bas
- Modifier la couleur du texte : Ajouter color : red
- Afficher le nom d'utilisateur sans l'avatar : . user-avatar{ display:none ; }
- Afficher les liens sans le style de lien : a {text-decoration : none ; color:black ; }