Lewis' Blog Tales from the trenches of information technology

24Jun/1312

WP Post to PDF Enhanced

This is a support page for my WordPress plugin, WP Post to PDF Enhanced, based on WP Post to PDF by Neerav Dobaria, which renders posts & pages as downloadable PDFs for archiving and/or printing.

The WordPress support page for the plugin is located here.

Please note: This page refers to the 1.0.x branch of the plugin, and not the current 1.1.x branch (released April, 2015). I will be updating this page with new screenshots and updated descriptions in the near future.

Overview

WP Post to PDF Enhanced is a PDF generator for WordPress posts and pages. Unlike many (most?) other plugins (such as PrintFriendly), WP Post to PDF Enhanced does not utilize any third party rendering to generate the PDF; that is to say, that it is not necessary to redirect the reader offsite to some unknown provider to convert the content. Instead, WP Post to PDF Enhanced relies on the TCPDF class to render the PDF. This makes WP Post to PDF Enhanced a completely self-contained PDF-generating plugin.

This incarnation of the plugin grew out of Neerav Dobaria's initial work, and my subsequent unofficial releases through version 2.4.0. In fact, version 1.0.0 of WP Post to PDF Enhanced is functionally equivalent to my unofficial release of WP Post to PDF 2.4.0.

License

WP Post to PDF Enhanced bears the GPLv2 license. Included works bear their own licenses.

The TCPDF class bears the GPLv3 (and above) license. There are also separate licenses included for the following:

Third party fonts:

This library may include third party font files released with different licenses.

All the PHP files on the fonts directory are subject to the general TCPDF license (GNU-LGPLv3), they do not contain any binary data but just a description of the general properties of a particular font. These files can be also generated on the fly using the font utilities and TCPDF methods.

All the original binary TTF font files have been renamed for compatibility with TCPDF and compressed using the gzcompress PHP function that uses the ZLIB data format (.z files).

The binary files (.z) that begins with the prefix "free" have been extracted from the GNU FreeFont collection (GNU-GPLv3). The binary files (.z) that begins with the prefix "pdfa" have been derived from the GNU FreeFont, so they are subject to the same license. For the details of Copyright, License and other information, please check the files inside the directory fonts/freefont-20120503 Link : http://www.gnu.org/software/freefont/

The binary files (.z) that begins with the prefix "dejavu" have been extracted from the DejaVu fonts 2.33 (Bitstream) collection. For the details of Copyright, License and other information, please check the files inside the directory fonts/dejavu-fonts-ttf-2.33 Link : http://dejavu-fonts.org

The binary files (.z) that begins with the prefix "ae" have been extracted from the Arabeyes.org collection (GNU-GPLv2). Link : http://projects.arabeyes.org/

These included licenses appear to be compatible - in terms of allowing bundling, at least - with the GPLv3 license which covers TCPDF (though as a disclaimer, I am not an attorney, and this does not and should not be construed as legal advice in the US or anywhere else).

Installation

If installing an official version, you may do so from the normal Plugins page in your WordPress site admin area, or download the package, extract it to /wp-content/plugins/, and activate it.

Upgrading

If upgrading from a prior release of WP Post to PDF Enhanced, no special considerations are required. I recommend upgrading through the WordPress Plugins page in your site admin area. Newer releases should be fully backward-compatible or will be able to migrate settings upon upgrading.

Migrating from the original WP Post to PDF

Presently, there is no automated way of migrating options from one plugin to the other.

If you have database access, before installing WP Post to PDF Enhanced, create a new row in the wp_options table. Assign a unique option_id value, set the option_name to 'wpptopdfenh', and copy the contents of the wpptopdf option_value field to the new wpptopdfenh option_value field. You may need to edit any path references referencing /wp-post-to-pdf to /wp-post-to-pdf-enhanced.

If you do not have database access, note all of the options you have set for WP Post to PDF before disabling/uninstalling it, so that you may re-enter them upon activating WP Post to PDF Enhanced.

Be sure to copy any custom images from the /wp-post-to-pdf paths to /wp-post-to-pdf-enhanced paths (e.g., wp-content/uploads/wp-post-to-pdf-logo.png -> wp-content/uploads/wp-post-to-pdf-enhanced-logo.png).

Finally, if you have used any manual placement tags for the PDF icon in your theme(s), you'll need to edit these manually, e.g.:

<?php if (function_exists("wpptopdf_display_icon")) echo wpptopdfenh_display_icon();?>

needs to be edited to read:

<?php if (function_exists("wpptopdfenh_display_icon")) echo wpptopdfenh_display_icon();?>

and so forth.

Settings

The Settings page is divided into three distinct groups:

  • Accessibility Options (include/exclude content types, posts, pages)
  • Presentation Options (PDF icon appearance)
  • PDF Formatting Options (output tuning)

Accessibility Options (include/exclude content types, posts, pages)

Accessibility Options

Allowed Custom Post Types Post, Page, Attachment, or any combination where you want to be able to generate PDFs.
Non Public Only Select this if you only want logged-in users to be able to generate PDFs.
Only on Single Select this if you only want individual articles (posts, pages, attachments) PDF-enabled; otherwise, PDFs may be generated from, say, a page of posts.
Exclude/Include Set the toggle for the list of posts/pages to specifically include or to specifically exclude (presently, there is no option for both a whitelist and a blacklist), then list the post/page IDs separated by commas.
Exclude/Include from Cache Set the toggle for the list of posts/pages to specifically include or to specifically exclude from cache 1 (presently, there is no option for both a whitelist and a blacklist), then list the post/page IDs separated by commas.

Presentation Options (PDF icon appearance)

Presentation Options

Icon Position

Before or After content, Both, Manual 2; Left, Right aligned.

 

PDF Download Link

This can be any HTML you'd like. For the default icon, just copy the provided text.

PDF Formatting Options (output tuning)

PDF Formatting Options

Other Plugins Select if you want (formatting) changes applied by other plugins to impact the rendering of the PDF.
Process Shortcodes Select if you want shortcodes processed in the rendering of the PDF.
Display Author Detail None, Username, Display Name, Nickname - sets the format (or visibility) of the author name in the PDF.
Display Post Category List Select if you want to include the post's/page's category list in the PDF.
Display Post Tag List Select if you want to include the post's/page's tag list in the PDF.
Display Post Date Select if you want to include the post's/page's date in the PDF.
Display Featured Image Select if you want to include the featured image in the header of the PDF.
Image Scaling Ratio Enter desired image scaling ratio (applies to all images; default is 1.25). Note that this decimal entry refers to the relative size of the web view (the antecedent) as compared to the PDF view (the consequent, which is always 1).
Header All Pages Select if you want the header information on all pages of the PDF (otherwise, this information will only appear on the first page of a multi-page PDF).
Header Logo Image Select if you want a logo image displayed in the header. Replace the default placeholder image with your own, per the displayed path.
Header Logo Image Factor This factor is applied to the header logo image to provide some buffer space around the image. Some experimenting may be required to get the factor just right to provide enough room around the image without abnormally expanding the overall header area (default: 14).
Custom CSS Enter your desired CSS in the text box to be applied to all PDFs (hint: Firefbug or Chris Pedrick's Web Developer Extension is your friend). Check the option to apply the CSS (unchecking the option will not remove your styles from the database, so toggling and editing should be fairly easy).
Header Font Select desired font for the header from the dropdown (default: Helvetica).
Header Font Size Enter the size in points of the header font (default: 10).
Footer Font Select desired font for the footer from the dropdown (default: Helvetica).
Footer Font Size Enter the size in points of the footer font (default: 10).
Content Font Select desired font for the content from the dropdown (default: Helvetica).
Content Font Size Enter the size in points of the content font (default: 10).

Included Fonts

Al Arabiya
Furat
Arial Unicode
Courier
Courier Bold
Courier Bold Italic
Courier Italic
DejaVu Sans
DejaVu Sans Bold
DejaVu Sans Bold Italic
DejaVu Sans Condensed
DejaVu Sans Condensed Bold
DejaVu Sans Condensed Bold Italic
DejaVu Sans Condensed Italic
DejaVu Sans Extra Light
DejaVu Sans Italic
DejaVu Sans Mono
DejaVu Sans Mono Bold
DejaVu Sans Mono Bold Italic
DejaVu Sans Mono Italic
DejaVu Serif
DejaVu Serif Bold
DejaVu Serif Bold Italic
DejaVu Serif Condensed
DejaVu Serif Condensed Bold
DejaVu Serif Condensed Bold Italic
DejaVu Serif Condensed Italic
DejaVu Serif Italic
Free Mono
Free Mono Bold
Free Mono Bold Italic
Free Mono Italic
Free Sans
Free Sans Bold
Free Sans Bold Italic
Free Sans Italic
Free Serif
Free Serif Bold
Free Serif Bold Italic
Free Serif Italic
Helvetica
Helvetica Bold
Helvetica Bold Italic
Helvetica Italic
Times Roman
Times Bold
Times Bold Italic
Times Italic

Shortcodes

Shortcodes have been introduced with version 1.0.1. There are currently two shortcodes available (wrap these in []):

wpptopdfenh Use this within your content to generate the default PDF icon and associated link. Note that page/post exclusions do not apply to this shortcode, so even pages listed to be excluded from the "automatic" icon will display the shortcode-generated one.
wpptopdfenh_break This shortcode sets a manual page break within the PDF.

Presently, disabling the processing of shortcodes will render the manual page break shortcode unusable. Look for an enhancement to strip all but the above shortcodes when shortcode processing is disabled (see workaround, below).

Tips & Tricks

Adding Manual Page Breaks (without the shortcode)

If you'd like to add a manual page break to your PDF, but have processing of shortcodes disabled, simply edit the HTML source of your post or page, and place the following HTML tags where you'd like the break to occur:

<tcpdf method="AddPage"></tcpdf>

(Note that while self-closing tags are fine for XHTML, it is likely that your WordPress editor will simply strip the tag completely, so stick with the open and close tags, above.)

Unicode Fonts (necessary for non-English characters)

First, realize that Arial (as used in TCPDF) is not a unicode font. In fact, Arial is actually mapped to Helvietica, so if you select Arial, the actual core font you will get is Helvetica (selecting Helvetica renders exactly the same way). Next, Arial (here) is not a unicode font. Thus, if you have non-English characters, you'll need to select a unicode font in order to have them render as something other than "?" in the PDF. A good suggestion is one of the DejaVu variants.

Image Alignment

If you are finding that your images simply are not aligning as you have the img tags set, try setting the text alignment as you want the image to be aligned. For example, put a right-aligned image in a right-aligned paragraph. It's not a perfect workaround, but usually gets the job done. Expect a real fix for this in a future release.

Acknowledgements

Kudos to Neerav Dobaria for his excellent work on the original plugin. Without his contribution, I would have certainly had a much harder time getting off the ground. Likewise, without Nicola Asuni's amazing work on TCPDF, WP Post to PDF Enhanced would surely look and act differently than it does now. Finally, thanks to all of the users who have posted reviews and salient comments/questions at wordpress.org for their kind words - especially to me - and suggestions for improving the functionality of WP Post to PDF Enhanced.

I'd also like to thank the folliowing people (in no particular order) from the WordPress community for their time and helpful feedback, encouragement, and overall good humor:

elarson
ajg-cal
McKSuse
jennybeaumont
david1103
2020media

...and a number of other people who should likely be mentioned... Thank you all very, very much.

Getting Support

Support may be requested either on the WordPress plugin support page or by registering for a login on this site and posting a comment to this post. I'm sorry to require registration if all you'd like to do is ask a question, but I find that it's the best way to curtail comment spam. I promise that I won't utilize your email address or other requested information for any purpose other than identifying you on this site, nor will I ever sell or otherwise knowingly disclose your information to any third party without a court order.

Giving Support

If you would like to contribute something monetarily, you have my thanks, and I will be sure to see that some portion of your donation gets to Nicola Asuni's TCPDF project. Also, please consider contacting me with some IT consulting issue or even about web hosting (Rosenthal & Rosenthal's hosting fees are quite reasonable, as are our domain registration fees). Alternatively, contribute something to Warpstock either directly or via an Amazon purchase, or consider giving to your local Humane Society or some legitimate organization which provides support for America's troops and/or veterans (or to such an organization for one of our allies). In truth, there is no amount which can ever repay those who fight - and who have fought - for Freedom.

To donate to me directly for WP Post to PDF Enhanced, please click the button below:


 

  1. Normally, PDF content is cached, so that once a PDF is generated - by any valid user - that same PDF is presented to a subsequent user, so long as the cache has not expired.
  2. Insert the following into your theme's functions.php:

    <?php if (function_exists("wpptopdfenh_display_icon")) echo wpptopdfenh_display_icon();?>