How to create your own PDF Template

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?
• How to add the PDFClass page?
• Do I need to add anything special in my wiki page?
• How to add the PDF Template page?
• How to use the new PDF template?
• Advanced Documentation and Examples
• Here is the exported PDF of My Report

What do you need for your PDF export?

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

I created an example of a page for this article, named My Report. You will see how to personalize the look of headings, message macros (info, box, warning, error, success, code), of a diagram, an image in a gallery macro, a chart and of tables in a PDF exported from your wiki.

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. https://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. 
• cover: if you want to modify the cover of your PDF export.
• header: if you'd like to add a specific text or image on the header of each page of your PDF export.
• footer: if you need a specific content on your page footer, such as contact details of your company.
• (optional) 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).
• (optional) fopxsl: contains the FOP XSL transformation that will override the default one.

While editing the PDFClass page in class mode, make sure that you set the suitable Content and Editor types for the properties that you add. For my example, I used:

• for the style I used the PlainText option for both Editor and Content Type metadata.
• for the cover, header and footer I picked the option Wiki Syntax in the Content Type metadata, and PlainText for the Editor metadata

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. I added classes to the heading sections as well, because I want to add style on them as well. Then, on the macros, on some of them (like the info, warning, gallery macros) you can add a cssClass directly when adding them on the page or later on, when editing the macros or also in source editor mode.

On the images from the gallery below you can see the page that will be exported as a PDF edited in Source mode and the classes of the sections that will get targeted by the CSS added in the style object of the Report PDF Template.

How to add the PDF Template page?

Create a new terminal page (for example "Report PDF Template") with XWiki as its parent, save it and then edit it in "Object" mode (e.g. https://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. I placed in this snippet the complete CSS used for the PDF export from this article.

These code lines were then placed in the following cover, header and footer property:

• in the cover property, I added an image that was attached to the Report PDF Template page and I set a title

• in the header property, I added a smaller image that was attached to the Report PDF Template page and the same title as on the cover

• in the footer property, I added the page number, an email address for contact, a website and a line describing on which type of XWiki instance the example was done

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. 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), and then I click on the Export button. You would obtain a regular look, without no personalization.

Here is how to get the styling added in the ReportPDFTemplate page:

• 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. When exporting without the cover, table of contents, header and footer the URL would look like:
  https://yourserver/xwiki/bin/export/myreport/WebHome?pdftemplate=XWiki.reportPDFtemplate&format=pdf 
  and with the table of contents, cover, header and footer selected for export the URL would look like:
  https://yourserver/xwiki/bin/export/myreport/WebHome?pdftemplate=XWiki.reportPDFtemplate&format=pdf&pdfcover=1&pdfcover=0&pdftoc=1&pdftoc=0&pdfheader=1&pdfheader=0&pdffooter=1&pdffooter=0
• 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. However, please note that the extension has not been maintained throughout the years.

Advanced Documentation and Examples

Here is the documentation page describing how to customize the look and feel of your exported PDF (referring to the old PDF Export present on XWiki versions before 14.10) with an advanced look on each component and how they work. 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:

• Add table borders to your PDF
• Add a complete look for your customized PDF template (the CSS style used for the PDF export of My Report 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.