We apologize for untranslated text, you can use the Google Translation button to get an automatic translation of the web page in the language of your choice.

Export PDF plugin

Description

This plugin allows to download a content as a PDF file.

Behavior

A user can ask for a PDF export from a Publication's full display.

The plugin requires installation of phantomjs on the application server.

ExportPdfPlugin - schéma d'architecture

Step 1 : user asks for a Publication PDF

Step 2 : JPlatform queries PhantomJS to generate a PDF by passing:

  • the identifier of the publication to export
  • the member that performs the action
  • the print portal to use
  • the rendering customization options
  • the path of the PDF file to save on

Step 3 : PhantomJS gets the HTML page of the publication displayed in the specified portal.

Step 4 : PhantomJS generates a screen capture of this HTML page in PDF format, and saves it at the location specified by JPlatform (in the OS temp directory).

Step 5 : Browser downloads the PDF

Options

  • set the compatible Content types
  • PDF rendering light customization

This plugin aims to replace this tool ( Génération de PDF à la volée). Bug tracker : https://issues.jalios.com/browse/EXPORTPDF


Installation

PhantomJS installation

  • Download and install phantomJS (http://phantomjs.org/)
    • Note: due to zoo factor bug #12685, we recommand to install latest1.9.x.
  • Note absolute path to executable
    • Windows ex: C:\bin\phantomjs-x.y.z-windows\bin\phantomjs.exe
    • UNIX ex: /bin/phantomjs
  • the system user that runs JPlatform must have rights call this executable

Plugin installation

  • Unzip the plugin and restart JPlatform

Plugin setup

  • in the plugin properties, set the phantomjs absolute executable's path
  • Save
    • check for bad setup in JPlatform logs

 

Installation validation

We will try to create a PDF file from a JPlatform Publication : 

  • Publish a new article, and display its Full Display
  • in the Publication actions menu, check there is a new action called "Export as PDF". If not:
    • check for errors in JPlatform logs
    • check installation path of phantomjs
    • refresh JPlatform properties, or restart JPlatform
    • display article again
    • check for export pdf action
  • click on "Export as PDF"
  • check that the PDF file has been downloaded and saved by the client browser
  • open the PDF to check its rendering

FAQ

1. What is PhantomJS?

PhantomJS (wikipedia) is a scripted, headless browser used for automating web page interaction.

PhantomJS is used as rendering engine because it supports CSS, JS, canvas, and SVG.

Therefor, a web page capture generated with PhantomJS will have quite the same rendering as if the web page were displayed in a normal web browser.

2. What can be exported to PDF?

Technically, every web page could be exported in PDF.
Functionnaly, export pdf action is only provided when on a Publication's Full display.
Following conditions must be met:

  1. the Content type is compatible (see plugin properties)
  2. the Content Full Display must provide the Publication actions menu (right menu), so that the "Export as PDF" action is also provided. Else, you will need to provide the export link yourself.
3. How to define compatible types?

The plugin allows to define for what Content types export PDF will be available. (by default, on Article, Smallnews, on WikiPage).
This is defined in the plugin properties.

4. Is PDF Export 100% reliable?

No. Indeed, quality and accuracy of export PDF depends on PhantomJS tool, or its components.

You may encounter some differences between a generated PDF from:

  • JPlatform
  • the print function of your browser

See PhantomJS bugtracker here: https://github.com/ariya/phantomjs/issues

Jalios is not responsible of PDF rendering issues related to PhantomJS.

5. Are there constraints?
  • phantomjs binary must be installed on the same server than JPlatform
  • PDF export is only available for logged users
  • application server must allow use of cookie (especially if site is private)
  • J2EE cookie name must be standard, that is "JSESSIONID"
  • an authentification issue may happen if site is accessed with domain "localhost". In this case, prefer use of "127.0.0.1"
  • there is a known bug (https://github.com/ariya/phantomjs/issues/10196, bound to this bug of the QT component), which makes some hyperlinks are not clickable in the PDF
6. How to customize PDF render by Content types?

PDF render can be customized in several ways:

  1. override the print portal
  2. override the print options by content types
  3. override the PDF Driver

Print portal

By default, publication is displayed in JPlatform default print portal (property channel.default-printportal)
You can set a custom print portal (see plugin properties).

Print options

List of print options :

  • page size (format). Example: A3, A4, etc...
  • Page orientation. Example: portrait, landscape
  • Page header:
    • display sitename : yes / no
    • display page number : yes / no
  • Page footer:
    • display sitename : yes / no
    • display page number : yes / no

Those options can be overrided by Content types.

Default values:

jcmsplugin.exportpdf.generate-pdf.render.default.format: A4
jcmsplugin.exportpdf.generate-pdf.render.default.orientation: portrait
jcmsplugin.exportpdf.generate-pdf.render.default.display-header-sitename: true
jcmsplugin.exportpdf.generate-pdf.render.default.display-header-numerotation: false
jcmsplugin.exportpdf.generate-pdf.render.default.display-footer-sitename: false
jcmsplugin.exportpdf.generate-pdf.render.default.display-footer-numerotation: true

Those default values will be used if no specific are found for a given Content type.

To customize PDF render for a given Content type, follow this syntax described in the plugin.prop:

jcmsplugin.exportpdf.generate-pdf.render.{MyType}.{option-name}: overrided value

Taking JGuide as an example, a possible customization would be:

# Customization for JGuide content type:
jcmsplugin.exportpdf.generate-pdf.render.JGuide.format: A3
jcmsplugin.exportpdf.generate-pdf.render.JGuide.orientation: landscape
jcmsplugin.exportpdf.generate-pdf.render.JGuide.display-header-sitename: false
jcmsplugin.exportpdf.generate-pdf.render.JGuide.display-header-numerotation: true
jcmsplugin.exportpdf.generate-pdf.render.JGuide.display-footer-sitename: true
jcmsplugin.exportpdf.generate-pdf.render.JGuide.display-footer-numerotation: false

Override the PDF Driver

As a last resort, you can use your own PDF generator (by default, PhantomJS).
To do so, you must:

  • create a class that implements interface com.jalios.jcmsplugin.exportpdf.PDFDriver, ex com.acme.exportpdf.MyCustomPDFDriver
  • declare it in the site properties:
    1. name of the driver to use
    2. path for this driver

Default behavior :

# Driver name to use:
jcmsplugin.exportpdf.generate-pdf.driver: phantomjs
# Class of the driver:
jcmsplugin.exportpdf.generate-pdf.phantomjs.clazz: com.jalios.jcmsplugin.exportpdf.impl.PhantomJSDriver

Override exemple:

# Driver name to use:
jcmsplugin.exportpdf.generate-pdf.driver: customdriver
# Class of the driver:
jcmsplugin.exportpdf.generate-pdf.customdriver.clazz: com.acme.exportpdf.MyCustomPDFDriver
7. Are PDF kept on server?

For rights purpose, a generated PDF file is deleted after it has been downloaded by the client.

8. How to debug?

Enable JPlatform logs

  • enable ALL trace level in package com.jalios.jcmsplugin.exportpdf
  • ask for a Publication PDF export
  • see logs (will indicate the command line for the call of PhantomJS)

 

Identify PhantomJS version

~$ phantomjs -v
2.1.1

 

Identify Webkit version embedded by PhantomJS

From documentation : http://phantomjs.org/faq.html

Q: Which WebKit version is used by PhantomJS?

A: If you want to know HTML5/CSS3/other features supported by PhantomJS, using WebKit version is not a good idea. See Supported Web Standards documentation page for details.

If you really like to get the WebKit version, find it via the user agent, run the examples/useragent.js. The actual version depends on the libraries with which PhantomJS was compiled.

/bin/phantomjs-2.1.1-linux-x86_64/ $ phantomjs examples/useragent.js 
The default user agent is Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/538.1 (KHTML, like Gecko) PhantomJS/2.1.1 Safari/538.1

Where examples/useragent.js script is in the PhantomJS directory.
In this example, Webkit version is 538.1.

Information

Version
  • 1.0
Stability
  • Stable
Compatibility
  • JPlatform 10 SP2
    JCMS 9
Certified by Jalios
  • Yes
Price
  • Module payant
Support
  • Jalios Support
Author
  • Jalios SA
License
  • Jalios
Size
  • 119.64 KB
Updated
  • 7/25/16
Download
  • 37