XWiki Multipage PDF Export

Last modified by Admin on 2024/07/08 00:09

cogAPI for exporting multiple pages in the wiki to a PDF, with various options.
TypeJAR
Category
Developed by

Anca Luca

Active Installs124
Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Compatibility

tested on XEM 3.5.1 and on XE 4.2-milestone-2

Installable with the Extension Manager

Description

This extension provides a service to allow exporting multiple xwiki documents in a pdf file, with various options. The service is available under the name of pdfexporter.

An extension that uses this Api and provides an interface to do exports of the pages in a space is the Hierarchy based space export. Other applications can be built, this is only one of them.

There are 3 export functions available, with various parameters:

/**
* @param name the title of the document to export, the name of the file will be computed from this title replacing
* whitespace with underscores
* @param docs the list of pages to export
* @throws Exception if something goes wrong during the export
*/

void export(String name, List<String> docs) throws Exception;

/**
* @param name the title of the document to export, the name of the file will be computed from this title replacing
* whitespace with underscores
* @param docs the list of pages to export
* @param multiPageSequence whether each page should be exported in its own page sequence, with its own header and
* footer. If this parameter is true, all new documents will also start on recto). If you need a different
* behaviour, use the 4 parameters version of this function (
* {@link #export(String, List, boolean, boolean)}).
* @throws Exception if something goes wrong during the export
*/

void export(String name, List<String> docs, boolean multiPageSequence) throws Exception;

/**
* @param name the title of the document to export, the name of the file will be computed from this title replacing
* whitespace with underscores
* @param docs the list of pages to export
* @param multiPageSequence whether each page should be exported in its own page sequence, with its own header and
* footer.
* @param alwaysStartOnRecto used in conjunction with multiPageSequence, whether each page sequence (each wiki
* document) should always start on recto. If {@code multiPageSequence} is false, this parameter is
* ignored.
* @throws Exception if something goes wrong during the export
*/

void export(String name, List<String> docs, boolean multiPageSequence, boolean alwaysStartOnRecto) throws Exception;

Note that the export functions will directly write the resulted pdf as the HTTP response for the request during which they're called.

Options

OptionDescriptionHow to useDefault value
multiPageSequenceif activated, each XWiki document will be exported in its own pdf sequence of pages, it will start on a new page and the information in the header and footer will be specific to this document (e.g. for displaying document title in the pdf header)use the 3 or 4 parameters export function and pass the appropriate value to the parameterfalse
alwaysStartOnRectocan only be used when the multiPageSequence option is activated and allows to configure each exported XWiki document to start on a recto page, meaning an odd page. To achieve this, the previous page sequence (wiki document) will be padded with empty pages until the odd page is reacheduse the 4 parameters export function and pass the appropriate value to the parameterfalse
pageBreakBeforeDocumentinsert page breaks before between documents when multiPageSequence is falseuse with first 2 parameters set on false false
pdfcoverconfigures whether the exported pdf has a cover or notpass pdfcover=1 or pdfcover=0 request parameter to the request for which the pdf should be provided as responsetrue (1)
pdftocconfigures whether the exported pdf has a table of contents or notpass pdftoc=1 or pdftoc=0 request parameter to the request for which the pdf should be provided as responsetrue (1)

Example

The following will export the pages Blog.BlogIntroduction, Sandbox.WebHome and Sandbox.TestPage1 in a pdf where each of the exported documents has individual header and footer but they don't start on an odd page.
{{velocity}}
#set($docsToExport = ['Blog.BlogIntroduction', 'Sandbox.WebHome', 'Sandbox.TestPage1'])
$services.pdfexporter.export("My test pdf", $docsToExport, true, false)
{{/velocity}}

Whether the exported pdf has a cover and or a table of contents depends of the values of the pdftoc and pdfcover request parameters of the page where the above code is executed.

Customization of the exported PDF

Note that, in order to export with the multiPageSequence option activated, this extension is using a custom xhtml2fo-multipage.xsl, which is found in this jar (and on github at https://github.com/xwiki-contrib/multipagepdfexport/blob/master/src/main/resources/xhtml2fo-multipage.xsl ), so if you need to customize the pdf export by modifying the xhtml2fo file, you should customize this xsl as well.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Release Notes

v1.2.1

v1.2

Dependencies

Dependencies for this extension (org.xwiki.contrib:xwiki-multipagepdfexport 1.2.1):

  • org.xwiki.platform:xwiki-platform-oldcore 6.4.8
  • org.xwiki.platform:xwiki-platform-security-api 6.4.8

Get Connected