views_data_export_pdf 7.x-2.0-beta1

This is the first beta release of Views Data Export PDF (VDE PDF) after being heavily overhauled, re-factored, and largely rewritten. Please try it out and don't hesitate to file issues if anything does not seem to be working.

Upgrading from VDE PDF 1.x

Important Note Regarding Tags and Security

In a prior version of this module, links and span tags were stripped out of what was rendered into the PDF. This is no longer the case -- as part of resolving #2930162: URL links are being stripped from the export, we now leave it up to site builders to configure Views to strip the tags they don't want to include in the PDF. If you have views that may render links you don't want to include in PDFs, please ensure that you modify and test your Views Data Export displays appropriately before upgrading to avoid these links being included.

Steps

1. Back-up your site and files. Ideally you should try this upgrade on a staging copy of your site.
2. It's recommended but not required that you upgrade to the latest versions of the following:
   • wkhtmltopdf
   • The phpwkhtmltopdf module (with the patch for #3012861: Fix version detection for newer versions applied)
   • The phpwkhtmltopdf PHP library
   • The php-shellcommand PHP library
   • The php-tmpfile PHP library

   For guidance on versions and where each dependency should be installed, see the "Installation and Usage" section of the wkhtmltopdf renderer README.

3. If you are using File Entity: You must patch File Entity using #8 in #2570377: File Entity overwrites filemime information prepared by other modules, or MIME types won't save properly and background process exports will fail.

4. Run update.php to ensure that the appropriate sub-modules are enabled so that your site continues to function with wkhtmltopdf as it did before with version 1.0.

New Features and Enhancements

Pluggable Rendering Engines + Multiple Renderer Engines Now Supported

This module has a new design that allows different PDF rendering libraries to be dropped-in to the export process. The following renderers are supported out-of-the-box:

• wkhtmltopdf (same rendering engine as in VDE PDF 1.0)
• mPDF
• Hybrid (wkhtmltopdf for body content, mPDF for headers and footers)

If there's a PDF library you'd like to add, contributions are welcome.

Async Rendering via Background Process

All of the renderers listed above run in-process, blocking a request thread until the PDF has generated; but, they can also run asynchronously in a background process if the "Background Process" module and the new "Views Data Export PDF - Background Process" module are installed.

PDF Page Headers and Footers

• View headers and footers now render as the header and footer of every PDF page. All you need to do is configure header and footer areas on the VDE PDF view display.

• It's now possible to include page numbers and other information (section name, time, date, URL, etc.) in PDF page headers or footers. See the "Adding Headers and Footers (with Page Numbers)" section of the appropriate README file for the "rendering engine you're using: wkhtmltopdf or mPDF.

• Page header and footer HTML is now rendered out to a temporary file passed-in to wkhtmltopdf instead of being exposed through an insecure menu path. This also helps to ensure that header and footer HTML is thread-safe (e.g. multiple PDF exports can be running at the same time without impacting each other). This closes #3112949: Header and Footer Generation Doesn't work in Latest Dev.

Styling Improvements

• Nicer Preview Output in Views Admin UI This resolves #3112950: Nicer Preview Output. A preview of the output table now renders while the view is being edited, instead of displaying HTML markup.
• A default stylesheet for the PDF now ships with the module. This stylesheet is based on table styling from the Seven module in core and provides some reasonable default styling that makes tables look good out-of-the-box for most use cases so that we don't have to force site builders to always provide their own stylesheet. The stylesheet can be overridden with a custom one (just as before).
• The default stylesheet applies to page headers and footers. The stylesheet is automatically incorporated into header and footer HTML.
• Headers and table cells now have CSS classes based on the name of the the field they correspond to. This makes it possible to style certain columns to be a certain width, avoid wrapping text, etc.

More Consistent UX/Batch Operation

• For batched exports, the PDF is now generated only a single time during the batch operation. Previously, the PDF was only generated when the user proceeded to download the result of the batched export. This would lead to a disappointing user experience if the PDF took longer than 5 seconds to generate because it would appear to the user as if the download was taking a long time to start, since the user would have expected the PDF to be generated during the batch export operation. The previous design also created several issues for the user if the user tried downloading the results a second time, or refreshed the page after a time-out.
• It is now possible to render the PDF within the browser window instead of always forcing it to be downloaded. If the "Provide as file" option is unchecked, then the PDF will be displayed immediately after export in the browser window. (For the best site builder UX, I recommend applying the patch to VDE from #3112930: UI/UX: "Provide as file" option is confusing so that this setting gets renamed to "Force export to be saved as download", which has a clearer intent).
• The option to render raw HTML for stylesheet development is now controlled by a new option. The option is called "Bypass PDF rendering and export intermediate HTML instead (for development and styling purposes)", and it now distinct from the "Provide as file" option provided natively by Views Data Export.
• Various bits of the PDF display style settings form verbiage were tweaked for clarity. For example, the description of the width and height settings now explains how those settings work when in landscape mode. In addition, "User style sheet path" has become "Custom stylesheet path" since a default stylesheet is included with the module now.

Bug Fixes

• This module now indicates that it requires PHP 7.0+. The 7.x-1.x branch had several changes to code style to use PHP 7's new short array syntax. That's fine, but the module needs to require PHP 7 to avoid syntax errors appearing after installation.
• The table HTML output is now properly formed/complete even when: 1) performing a batch export, while 2) not using grouping. This fixes a regression that was seen only in the 7.x-1.xdev branch of the module that appears to have been introduced in 7b38884. Previously, during a batched export, the opening <table> tag was not being generated because this behavior had been moved into template_preprocess_views_data_export_pdf() which does not get invoked when rendering table bodies in a batch.
• The "Provide as file"/"Force export to be saved as download" option no longer must be set for proper PDF export operation. This is a result of the fact that the option to export raw HTML instead of PDF has been moved to a separate option (described above). This closes #3112923: UI/UX: HTML Output is Generated Instead of PDF Output if "Provide as file" is Unchecked.
• Downloading the output of a batched export no longer results in a PDF containing the raw binary output (garbage data) of the original PDF. This bug is partially fixed by moving the generation of the PDF from the file transfer callback into the batch operation itself (described above), and partially by guarding generation of the PDF with a lock (described below). This addresses issue 1 in #3112947: Re-downloading the Output of a Batched Export Results in a PDF Containing Binary Data.

• For batched exports, refreshing the page (at the end of the batch or after a timeout) no longer causes the same PDF to be generated by multiple concurrent requests.

  The previous design did not guard against multiple requests trying to generate a PDF from the same HTML file. This was easy to cause just by hitting refresh. Further, if the user hit refresh because the original request timed-out, it was very possible that the original request was still running, and refreshing multiple times could crush the server under load.

  A lock is now used to prevent a second request from trying to generate a PDF for the same HTML file for up to 10 minutes. If the batch operation times-out, and the user refreshes the page to resume, the batch will poll the status of the lock until it is released. The MIME type on the file will communicate to the batch whether or not the file was converted successfully from "text/html" to "application/pdf".

  This addresses issue 2 in #3112947: Re-downloading the Output of a Batched Export Results in a PDF Containing Binary Data.

• Failing to invoke wkhtmltopdf no longer results in the raw HTML output being sent back to the browser as if it were PDF output. Instead, the user is now presented with an error message (if possible) that asks them to contact the site administrator. The site administrator should be able to find information on the root cause of the issue in the site logs.

Remaining Known Issues

• "Grouping field Nr.1" option still does not appear in settings for the PDF style plug-in. Although the documentation for this module indicates that it supports grouping, and there is a lot of code in the settings and theme functions of this module for that feature, the option does not appear in Views settings. This release modifies several parts of the theme functions that work with this feature, but the changes were not tested with grouping because the option is missing.

  This bug is being tracked under #3027310: Group by function and may be resolved by patching VDE per #1187712: Grouping?. If you need grouping functionality, please test this out and report back under 3027310.