How to create your own PDF Template

02 Mar 2020 5 min read
Written by Andreea Chirica, Communications and Support Specialist

Have you considered to personalize the look of your PDF exported wiki pages? Let's say you'd like to export a purchase order that you created for your client who just bought your services. Or, you'd need to export a monthly report for the management team wanting to explore financial evolution measurements, which would help skyrocket your sales. Your original page contains a table, a diagram, a chart, and an infobox where you highlight services details. Apart from this, you'd like to make your exported PDF even more professional, so you'd like to add to it cover page, a table of content and a footer section with your company details. This is all possible with XWiki with a little bit of help from a more tech-savy colleague.

What do you need for your PDF export?

You'll need 3 main ingredients: a wiki page to be exported as a PDF, a PDFClass page and a PDF Template page.

I created an example of a page for this article, named MyReport. It includes a table, an infobox, a warning box, a diagram, a chart, and some other elements.

Do I need to add anything special in my wiki page?

The answer is yes, but no need to panic. It would simply be a need to add some classes to elements of your page in order to easily target them in the style added in the PDF Template page. For example, for a table, I added in source editor mode (% class="mytable" %) above the desired table. The info message and the warning message macros bring the possibility to add a cssClass directly when adding them on the page or later on, when editing the macros or also in source editor mode.

How to add the PDFClass page?

Firstly, make sure you are an advanced user in the wiki, by going to your user profile, the preferences section and selecting the Advanced type of user. After that, you will be able to edit pages in object mode or to create terminal pages. Create a new terminal page which you would need to name "PDFClass", with "XWiki" as parent of the page. This will represent the object containing the customization properties that will then be added to your PDF template. After you create and save this new page, edit the page in "Class" mode (e.g. http://yourserver/xwiki/bin/edit/XWiki/PDFClass?editor=class) and add the following TextArea properties: 

  • style: contains the CSS rules used to render the content as PDF. 
  • xhtmlxsl: contains the XHTML2FO XSL transformation into HTML, text, or other XML document types, which will override the default one. Note that you can also use velocity in this field (useful to get the content of an attached .xsl file, which comes in very handy when you need to fill in a big file, since the limit of textarea properties is of 60 000 characters).
  • fopxsl: contains the FOP XSL transformation that will override the default one.

Note that the css that would be added in the style property will override the default pdf.css values. However, by default, there won't be a pdf.css file on your filesystem, but you can create it in the folder \webapps\xwiki\templates\ or add it in your skin page from the administration of your wiki, the Look and Feel section, the Themes tab. Also the xhtmlxsl and the fopxsl properties are not mandatory, as these would be needed only if you would want to override existing values.

For each property added, make sure to set the Content Type and the Editor property metadata to PlainText/PureText in order to not get the WYSIWYG editor which would make it complex to enter HTML/XML/XSL.

In my example, I added some more properties to help me customize the exported PDF look even further: cover, header, footer. Make sure that you set the suitable Content and Editor types for these properties. For my example, I used the option Wiki Syntax for the cover and header in the Content Type metadata, and PlainText for the Editor metadata, while for the footer I used the PlainText option for both Editor and Content Type metadata.

How to add the PDF Template page?

Create a new terminal page (for example "ReportPDFTemplate") with XWiki as its parent, save it and then edit it in "Object" mode (e.g. http://yourserver/xwiki/bin/edit/XWiki/ReportPDFTemplate?editor=object). Add the newly created PDFClass object to it. In the "style" property section you will be able to add the desired styling targeting your pages that you want to export as a PDF file.

I then started to fill in the style property with CSS code, the cover and the header ones each with a link through an image initially attached to the ReportPDFTemplate page, and the footer section with a table using HTML syntax.

How to use the new PDF template?

There is already a possibility to export your XWiki pages as PDFs. Let's consider my example of a wiki page named My Report created in the Sandbox space. I click on the Export option, select the PDF one, pick the sections that I want to export along with the page (e.g. cover, table of contents, header, footer, comments, image attachments), and then I click on the Export button. There are two current ways to get the styling added in the ReportPDFTemplate file. One would be to add in the URL of the exported file the name of the PDF template with the space name that locates the file: e.g http://yourserver/xwiki/bin/export/Space/Page?pdftemplate=XWiki.ReportPDFTemplate&format=pdf&language=en. A second option would be to use an extension that was build for the purpose to pick from multiple PDF templates when exporting a page.

Useful Documentation and Examples

Here is the current documentation page describing how to customize the look and feel of your exported PDF. You'll notice there more advanced methods to customize your exported PDF: modifying the skin of your wiki or overriding the xhtml2fo.xsl file with specific rules to your desired to-be-exported page. 

Check out the snippets containing two examples of styling, the second of which referring to the styling used for the My Report example from this article: 

Here is the exported PDF of My Report

What would you like to add in your customized PDF export? Let us know in the comments below or on social media. We can gladly share with you how you could contribute with more styling scenarios or guide you to get the right services, depending on your needs.
Did you know you can also display PDF files in XWiki?

Check out the PDF Viewer Macro which allows users to load and view PDF files inside a wiki page. The Viewer supports a double full screen mode: first going full screen in your browser and then going full screen on your computer if your browser supports that mode. The PDF location could be the current wiki page, another wiki page or an external URL.

You may also be interested in: