nyeholt / silverstripe-pdfrendition

A module that makes use of the Flying Saucer XHTML renderer project to create PDFs from XHTML pages

PDF Rendition Module

Maintainer Contact

• Marcus Nyeholt [email protected]
• Nathan Glasl [email protected]

Requirements

• SilverStripe 4.1.X
• Tidy (preferably the built in PHP tidy module, otherwise the commandline binary)
• Java 1.8 (the latest version this has been tested against)
  • Important: earlier 1.7 versions cause the PDF to not load Cloudflare specific assets such as images and CSS
  • Important: regardless of the version you end up using, make sure the PDF output is correct on the production server prior to go-live (please see the known issues section below)

Documentation

This module allows users to easily create complex PDF renditions of content by utilising HTML and CSS3 to define page layouts for printing. It provides a simple extension that adds a simple action for automatically generating PDF renditions of a page, and an API for developers to generate more specific PDF renditions.

Please see http://github.com/nyeholt/silverstripe-pdfrendition for more details about specific styling tips

Installation Instructions

composer require symbiote/silverstripe-pdfrendition:~2.0

Usage Overview

• Add Symbiote\PdfRendition\Extension\PdfControllerExtension as an extension to PageController
• Add $PdfLink in your template to insert a link to the PDF version of the page
• To customise the PDF layout, create a 'pdfrendition.css' file in your theme directory, link to it with your preferred method (@import, requirements, etc.) and add styles specifically for your pdf using the @print media query. See the github wiki for some examples of how to do some common PDF based things.

Known Issues / Troubleshooting

• Using HTTPS without a valid certificate can cause the PDF to not render correctly.
• Cloudflare can cause the PDF to not render correctly.
  • This may be due to Java attempting to reference the assets (images and CSS), and being listed as a "bad browser".
    • To resolve this, Cloudflare Page Rules need to be added for those specific assets (or a general /* blanket rule) with Browser Integrity Check set to Off.
  • This may also be due to the Java version (please see above).
  • The PDF output can be tested by intercepting the render process locally and holding onto the xhtml file generated prior to render.
  • Using this, replace the asset URLs with those you want to test and confirm (production for example).
    • The Java Flying Saucer utility will retrieve assets and external sources via links contained in the xhtml source. Ensure these links are fully formed, and are able to be retrieved from within the production server (i.e. outbound firewall restrictions or localised DNS/host definitions could cause issues).
  • Using this /tmp/xhtml, the below should give you a correctly rendered PDF when run from within the production server.
  • If not, Cloudflare and/or Java are likely the issue.

java -classpath '{project}/pdfrendition/thirdparty/xhtmlrenderer/flying-saucer-core-9.0.7.jar:{project}/pdfrendition/thirdparty/xhtmlrenderer/flying-saucer-pdf-9.0.7.jar:{project}/pdfrendition/thirdparty/xhtmlrenderer/itext-4.2.1.jar' org.xhtmlrenderer.simple.PDFRenderer '/tmp/xhtml' '/tmp/output.pdf'

• Make sure you don't define @font-face inside @media print.

Occasionally a page won't correctly render, throwing some kind of junk back to the browser as the PDF rendition process fails. Typically, this is caused by malformed XML being sent to the renderer; for this reason everything is first passed through HTML Tidy, however in some rare cases this can still not correctly convert the raw content.

In these cases, errors will be sent through to your error log files; it will indicate the temporary files that were created, so you should first check these for XML errors. If that does not work, you can also attempt to manually perform the conversion using commandline tidy and the commandline for the PDF rendition to see if there are more verbose errors available for debugging the problem.

silverstripe-pdfrendition's Issues

Fails if Base Tag missing in templates

PDF will not generate if base tag missing from SS template.

PDFRenditionService defaults to /usr/bin/tidy

Testing on MacBook Pro which has default 2006 version of tidy installed. In order to be able to parse HTML5 tags, had to install https://github.com/htacg/tidy-html5 which installs to /usr/local/bin however PDFRenditionService still uses /usr/bin/tidy and results in error despite which tidy returning /usr/local/bin/tidy

Is it possible to be able set tidy bin location in config? Have the following in pdfrendition.yml:

Symbiote\PdfRendition\Service\PDFRenditionService:
  tidy_bin: "/usr/local/bin/tidy"

This does not work... however editing the hard coded public static $tidy_bin = "/usr/bin/tidy"; in PDFRenditionService generates pdf...

Template error when previewing composed PDF

In CMS PDFs admin, create a new composed PDF and select default 'PlainPdf' from template dropdown. Save and preview.

Results in the following error:

[User Warning] None of the following templates could be found: Array ( [0] => app/templates/pdfs/PlainPdf.ss [1] => vendor/symbiote/silverstripe-pdfrendition/templates/pdfs/PlainPdf.ss ) in themes "Array ( [0] => silverstripe/admin:cms-forms [1] => $default ) "
GET /admin/pdfs/Symbiote-PdfRendition-Model-ComposedPdf/EditForm/field/Symbiote-PdfRendition-Model-ComposedPdf/item/1/previewpdf

Same result if I add eg. TestPdf.ss to app/templates/pdfs/ - it appears in available dropdown, but results in the same error on preview. Maybe I'm missing something here...?

Problems with 3.1.2

Trying to use your Advanced Reports module and it looks like it's great and perfect for what i'm looking for i am getting some server errors but no info as to what yet but one issue that is being logged is

Fatal error:  Class 'TableListField' not found in /home/sites/xxxxxxxxxxxx/pdfrendition/code/dataobjects/ComposedPdf.php on line 62

I'm guessing that this now needs to use the gridfield object?

regards

Mick

PHP7.4: Array and string offset access syntax with curly braces is deprecated

Hi, getting some deprecation errors when using PHP 7.4:

Deprecated: Array and string offset access syntax with curly braces is deprecated in ......./vendor/symbiote/silverstripe-pdfrendition/src/Model/ComposedPdf.php on line 184

Deprecated: Array and string offset access syntax with curly braces is deprecated in ......./vendor/symbiote/silverstripe-pdfrendition/src/Service/PDFRenditionService.php on line 196

Ref:
https://github.com/nyeholt/silverstripe-pdfrendition/blob/master/src/Model/ComposedPdf.php#L184
https://github.com/nyeholt/silverstripe-pdfrendition/blob/master/src/Service/PDFRenditionService.php#L196

By the looks in both cases it's a quick fix to [ ] e.g $absPath[ strlen($absPath) - 1 ] $href[ 0 ] and also checking that the array index exists prior.

RFC:
https://wiki.php.net/rfc/deprecate_curly_braces_array_access

Cheers
James