XWiki Standard 9.8.1 Documentation » Programming Overview » Customize the Look and Feel of the PDF and RTF Export

Customize the Look and Feel of the PDF and RTF Export

Customize the PDF Export Look & Feel

You can customize 4 aspects of the PDF export:

  • the PDF templates located on your filesystem in the folder \webapps\xwiki\templates\:
    • pdf.vm
    • pdfhtmlheader.vm
    • pdfheader.vm
    • pdffooter.vm
    • pdftoc.vm
    • pdfcover.vm

These templates can be overridden in the skin page.

  • the CSS rules used to render the content as PDF
  • the XHTML2FO XSL transformation
  • the FOP XSL transformation

Override the PDF Templates

Customize the PDF Footer

By default, the PDF footer will display the page number, the last author and the date of the last modification. In order to also display a customized message, the template pdffooter.vm must be overridden. To do that, edit the Skin class (/xwiki/bin/view/XWiki/XWikiSkins?editor=class) and add a "Text Area" property named pdffooter.vm:

OverridePDFFooter.png

Next, edit the skin page (/xwiki/bin/edit/XWiki/DefaultSkin) and add the following code to the pdffooter.vm property:

$msg.Page <span class="page-number"></span> - $services.localization.render('lastmodifiedby')
$xwiki.getUserName($tdoc.author, false)
$services.localization.render('lastmodifiedon')
$!xwiki.formatDate($tdoc.date)
<div>
<p>XWiki SAS. All rights reserved. Confidential and proprietary document. Printed Copies are not controlled.</p>
</div>

To see the changes, just export any wiki page:

OverridePDFFooterFinal.png

Customize the PDF Cover

This could be useful when you want for instance to add the company logo to the PDF cover. In order to do this, the template pdfcover.vm must be overridden. Just like for the PDF header, a "TextArea" property named pdfcover.vm must be added to the "XWiki.XWikiSkins" class (/xwiki/bin/view/XWiki/XWikiSkins?editor=class).

OverridePDFCover.png

Next, edit the skin page (/xwiki/bin/edit/XWiki/DefaultSkin) and add the following code to the pdfcover.vm property:

<img src="$xwiki.getSkinFile("logo_badge.png")"/>
<div style="text-align: center; width: 100%;">
<h1>
#set ($title = "$!pdfdoc.display('title', 'rendered', '', $pdfobj)")
#if ($title == '')
  $escapetool.xml($!tdoc.plainTitle)
#else
  $escapetool.xml($title)
#end
</h1>
<br />
<br />
<p class="author">$!xwiki.getUserName($tdoc.author, false)</p>
<br />
<p class="date">$!xwiki.formatDate($tdoc.date)</p>
</div>

The last step consists of attaching the image "logo_badge.png" to the skin.

OverridePDFCoverFinal.png

Another way of overriding the templates "pdffoofter.vm" and "pdfcover.vm" is to modify them locally, then to attach them to the skin page. This approach does not require adding properties to the class "XWiki.XWikiSkins". 

Override the CSS rules

In order to use your own template when exporting a page as PDF, you need to create a class in the "XWiki" space and name it "PDFClass". Next, edit the page in "Class" mode (e.g. /xwiki/bin/edit/XWiki/PDFClass?editor=class) and add the following TextArea properties:

  • style which contains the CSS rules that will override the default pdf.css values. 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 specify it in your skin page
  • xhtmlxsl which contains the XHTML2FO XSL transformation that will override the default one
  • fopxsl which contains the FOP XSL transformation that will override the default one

CreatePDFClass.png

Next, create the wiki page for which your want to customize the PDF export (e.g. "XWiki.PDFClassTemplate") and add a "XWiki.PDFClass" object to it.

Supposing your wiki page contains a table, you edit it in "Wiki" mode and add a style parameter as shown below:

(% class="mytable" %)
|=Column 1|=Column 2
| data|data

Next, edit the page in "Objects" mode and write your own CSS rules in the "style" property:

CreatePDFTemplate.png

In case you would want to use multiple xhtmlxsl files, not just the one provided by default, you may attach them to the PDF template page. Next, edit the document in "Objects" mode and add the line below in the "xhtmlxsl" field:

$xwiki.getDocument('XWiki.PDFClassTemplate').getAttachment('xhtml2fo.xsl').contentAsString

Because no template is used by default, you need to explicitly specify the pdftemplate parameter in the URL in order to use your own template: /xwiki/bin/export/XWiki/PDFClassTemplate?format=pdf&pdftemplate=XWiki.PDFClassTemplate.

CustomizedPDF.png

The available URL parameters for the PDF export are:

  • pages: you can use it several times, each parameter representing a page to be exported.
  • includechilds: its numeric value specifies the depth of children pages to include in the PDF export; for instance, if you type &includechilds=2 in the URL, you will include all the children pages of the page to export (all the pages having this page as parent) and all the children's children.
  • includelinks: its numeric value specifies the depth of linked pages to include in the PDF export; for example &includelinks=2 will include all the pages linked from the page to export and the links in those pages.
  • pagebreaks: if its value is set to 1 then a page break will be inserted between all the exported pages.
  • comments: if its value is set to 1 then the comments will also be exported.
  • attachments: if its value is set to 1 then the attached images will also be exported.

Customize the RTF Export Look & Feel

The customization of the RTF export is done just like for the PDF export. The only difference is in the format specified in the URL: /xwiki/bin/export/XWiki/RTFTemplate?format=rtf&pdftemplate=XWiki.RTFTemplate

The available URL parameters for the RTF export are the same as for the PDF export.

     

Related Pages

Search this space

 

Most popular tags

Failed to execute the [groovy] macro
  1. access rights
  2. activity stream
  3. annotation
  4. attachment
  5. comment
  6. Document Tree Macro
  7. export
  8. Extension Manager
  9. Flamingo skin
  10. global user
  11. Groovy event listener
  12. group
  13. nested page
  14. search
  15. skin
  16. syntax
  17. user
  18. user profile
  19. velocity macros
  20. wiki
  21. wysiwyg
  22. XWiki Applications
  23. xwikiattachment_archive table
  24. xwikiattachment table
  25. xwikiattrecyclebin table
  26. xwikiproperties table

[Display all tags from this space]