Customizing the PDF export Look & Feel

Have you started exporting XWiki pages as PDFs? You might have wondered why the resulted PDF is looking so different from the source XWiki page. In short, it's because you would need to customize the look of your PDF exports with your own templates.

You'll need 3 main items: a wiki page to be exported as a PDF (you might have that covered already ), a PDFClass page and a PDF Template page.

Check out the stages presented below to learn how you could get from the standard PDF export 

[adding screenshot here]

to a customized result.

[adding screenshot here]

Adding classes in the wiki page

On the wiki page that you are planning to export, it would be useful to add some classes to the elements of your page in order to easily target them in the style added later in the PDF Template page. For example, your wiki page Projects.MyReport contains a table, you have to edit it in "Wiki" mode, or while in "WYSIWYG " mode within Source and add a class as shown below, above the table:

Extra tip: 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/wiki mode.

Adding the PDFClass page

As an advanced user in the wiki, you can edit pages in object mode and also 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 syntax.

At this step, consider if you'd like to add some extra elements to your PDF export, such as a: cover, header or footer. If yes, make sure that you set the suitable Content and Editor types for these properties, based on what you would add in these sections later on. 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.

Adding customizations in a 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.

Start 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. You can also override the default PDF cover and footer by editing the skin class. Check the PDF cover process here and the PDF footer one here.