XWiki Multipage PDF Export
 | API for exporting multiple pages in the wiki to a PDF, with various options. |
| Type | JAR |
| Category | |
| Developed by | |
| Active Installs | 107 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Compatibility | tested on XEM 3.5.1 and on XE 4.2-milestone-2 |
Table of contents
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
| Option | Description | How to use | Default value |
|---|---|---|---|
| multiPageSequence | if 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 parameter | false |
| alwaysStartOnRecto | can 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 reached | use the 4 parameters export function and pass the appropriate value to the parameter | false |
| pageBreakBeforeDocument | insert page breaks before between documents when multiPageSequence is false | use with first 2 parameters set on false | false |
| pdfcover | configures whether the exported pdf has a cover or not | pass pdfcover=1 or pdfcover=0 request parameter to the request for which the pdf should be provided as response | true (1) |
| pdftoc | configures whether the exported pdf has a table of contents or not | pass pdftoc=1 or pdftoc=0 request parameter to the request for which the pdf should be provided as response | true (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
