This is an advanced guide on how to customize the output generated by the ContuttoPDF WordPress plugin. If you just want to install the plugin, please visit the main tutorial.

Basic customizations

Since version 0.2.1, ContuttoPDF handles multiple themes. So if you wish to modify your theme, go to wp-content/pdf-themes and make a copy of the directory default. This will then be your theme folder.

If you use a modified Kubrick theme on screen, you can replace the the background images from the ContuttoPDF plugin with your own ones. Note that they have other dimensions than the original Kubrick images, they are a bit wider. You can also edit the files pdf.php and comments.pdf.php in order to modify the standard phrases or the footer.

If you want further customizations, please read the following two sections before modifying the HTML structure or the CSS.

Adapting the output

While installing the plugin is fairly easy, modifying the PDF can be tough. One problem is that you can’t just use WordPress’ template tags, the other is the rendering engine (see below). For the PDF generating to work, all output must be redirected into a variable. This is because PHP usually writes everything to the client directly, while we need to catch this output and process it into a PDF. When customizing the PDF template, you must think about this.

Before we start working, let’s set the “debug mode”: In the file contuttopdf.php in the ContuttoPDF plugin folder, go to the position where it says contutto_output( $pdf_output, true ); (somewhere near the bottom) and change true to false - for outputting XHTML instead of PDFs while we’re working.

First some notes on how to create the $pdf_output container variable from WordPress content:

  • Every chunk of code that would be streamed to the client must be appended to this variable; be it pure HTML, or PHP-generated strings. Plain HTML can be appended like this:
    $pdf_output .= '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">'; and so on. (Note the dot before the equals sign.)
  • For the PHP generated output (which will generally come from WordPress or plugins), check how they can be called to return instead of printing their content. For example:
    • bloginfo() can be replaced with get_bloginfo(), which does the same and takes the same arguments.
    • Many other WordPress template tags also have a such a corresponding function, or they provide own parameters to have the content returned instead of echoed.
    • The the_content() tag seems not to offer this option. But there is the $post class, and $post->post_content is a property that contains your content, so you can append that instead. (Same with the $comment. You can insert a print_r() of them somewhere inside the post/comment loops to see what’s available.)
    • The gettext echoing function _e() can be replaced with the gettext returning function __().
    • Many template tags can be skipped, as they are just useless in a PDF.
    • For other techniques, have a look at the default template.
  • While modifying the template file, respect the functional structure. This means especially to preserve control structures. Spare those little ifs and whiles. ;-)
  • You can try to incorporate plugins, but you might be out of luck; if they don’t provide a return option, you can either modify them, or you must leave them out for the PDF.

When you finished customizing the output, go to your browser and reload your page again with ?output=pdf attached. If you get a PHP error, fix it. If you get a proper page, check that there is no HTML before your DOCTYPE definition; if it is, you forgot to attach it and had it echoed instead.

You can of course also perform very deep modifications of the PDF template. This can be very tough; unfortunately, DOMPDF is a bit quirky, and creating a suitable HTML template file can take quite long, especially as DOMPDF gives very vague debugging output. And although it does interpret most CSS 2.1 properties, it lacks support for two very important ones: position and float. This means, if you would just use your screen theme, it would be pretty messed up. This is why the next part will be about optimizing your template for PDF output with DOMPDF. Remember that you can always switch between HTML and PDF output at the bottom of contuttopdf.php.

Unfortunately, there is no general way to create a suitable template. You may of course make heavy use of the demo theme: It’s known to work, and you can base your own theme on it. However, there can occur errors that seem quite irrational, so I’ll just give a list of hints, and the try’n'error will be on you. ;-) You will have to revise your HTML and CSS, and keep in mind the following points:

  • For all template building, refer to the DOMPDF documentation! There also is a discussion forum and a bug tracker at Sourceforge.
  • You can use table-based layouts, but I experienced certain difficulties, including fatal errors with large images inside table cells.
  • Be sure to use valid and strict (X)HTML as well as valid CSS 2.1 (this is a necessary, yet not sufficient condition).
  • If you get a Frame not found in cellmap error, some of your HTML or CSS is not processed correctly (even though your HTML/CSS may be valid). This annoying error will certainly hit you more than once, and it can be caused by missing or inadequate height and width specifications, by too large images, by unlogical though technically valid CSS statements, by some HTML elements that DOMPDF doesn’t seem to understand, and some others. You’ll sure find out! ;-)
  • Remove all screen related definitions from your CSS.
  • Debugging output is very slim; it doesn’t indicate points of failure. If you don’t have an idea where it could be, comment out large parts of your HTML/CSS and uncomment little by little, until you found the quirk. You won’t believe what sort of constellations can cause DOMPDF to fail… just weird, trust me. ;-)
  • If you can’t solve something with XHTML/CSS, use inline PHP and draw your objects directly to the canvas. This is not very comfy, but it might do the trick.
  • When you found a good looking and working layout for one page, be sure to test it with as much as possible others, too. Especially run tests on all different types of pages (single, static, search, …).

It’s possible that you will have to rebuild and test very often. You will often get errors, and you will often get ugly output. But after a while, you will get a layout that will please you. This is the moment for a big Hooray!!! - because now you finished the hardest part. You now have a template that will create customized, beatiful PDFs from all your content!

If you face problems while customizing the PDF template, you are welcome to discuss them below.

That’s it! Have a lot of fun with the Advanced Search plugin!

In case you need individual, advanced support: Contutto also provides professional support for this software and its integration on your website (as well as WordPress support in general). Please don’t hesitate to contact us and ask about our services.

15 comments on “Customizing your template for the ContuttoPDF WordPress plugin”

  1. Nicholas Orr on October 23, 2006 at 11:11 #

    omg what a pain in the butt this is….
    I’m slowly getting there though, thanks for the tips they’ve helped a lot ;)

  2. Alex Günsche on October 23, 2006 at 12:20 #

    Yeah, tell me about it. But it’s cool that you dare to give it a try.

    If you should have problems, don’t hesitate to post here. Maybe I can give you a useful hint which I didn’t mention above.

    And if you’re happy with the result one day, and you might want to publish it… I wouldn’t mind either. :-D

  3. KJ on December 18, 2006 at 17:41 #

    Is it possible to use a completely different style to the web version of the page? For example i have a theme for a page but for the pdf output i’d like to use a different theme. Is that possible?

    Thanks

  4. Alex Günsche on December 18, 2006 at 19:43 #

    Hi KJ,

    it is not only possible, it’s the only way to go. ;-) The PDF themes are independant from the screen themes. In fact, there’s only one available theme so far (which is derived from WP’s default theme Kubrick). But with the above instructions, you can design your own PDF theme or apply modifications to the default PDF theme.

  5. ben on June 8, 2007 at 21:10 #

    Has anyone had luck in setting up a 2-column grid? With no float, i’ve tried a giant, 2 column 1 row table but that seems to break DOMPDF beyond one page..

  6. Alessandro Ronchi on June 13, 2007 at 01:03 #

    Is it possible to make a single pdf of last 10 posts of a category?
    I need to create a weekly pdf report of my most important articles, but I cannot understand how to do it.

    thanks in advance for any hints.

  7. Alex Günsche on June 13, 2007 at 15:40 #

    You could create a custom Loop with query_posts() in the template page.

  8. Mikael on June 16, 2007 at 09:59 #

    Is there any reasonably easy way to make the numbered lists and bullets work?

    Right now all the list items are indented poorly, and numbered items are shown as bullets. Any ideas? Thanks!

  9. Alex Günsche on June 17, 2007 at 11:49 #

    The indentation can be adjusted via the respective CSS properties. As for the ordered lists problem, I don’t know how to solve it in HTML either. I had solved it before by creating a PHP loop with an iterating variable, and printed it at the position where I wanted the number to appear.

  10. Mikael on June 17, 2007 at 21:05 #

    Thanks for the quick reply! I will see what I can come up with.

  11. Bob K. on October 4, 2007 at 21:48 #

    Is it possible to individually set the widths of images on the page? The width from the post is maintained in the xhtml output, but appears to be lost in the pdf. Thanks!

  12. Alex Günsche on October 5, 2007 at 12:58 #

    It should be possible with inline CSS, but I can’t tell for sure. Please try yourself.

  13. Bob K. on October 8, 2007 at 21:19 #

    Thanks for the tip, I’ll see if I can get inline CSS to work (the Wordpress Mu I’m running uses kses.php which unfortunately appears to strip off any colon values).

  14. TuxPirate on December 15, 2007 at 14:51 #

    Is this intended to work in WP2.3? I apologize for not looking more into the problem but I don’t have time to wrap my head around how your plugin functions.

    This is an example: single post PDF by ContuttoPDF

    I only link to PDF format of pages on single posts and I only want the post’s content. I don’t mind and actually prefer if there’s no fancy design in its background.

    Information is key, along with a link anchor to the post used to generate the PDF.

    Thanks for your help.

  15. TuxPirate on January 22, 2008 at 05:53 #

    No support for this plug-in.

Please support our OpenSource developments. Donate some bucks! Use the form in the upper right of this page, and get a backlink!

Comment on this article

 (not published)


Comments can be revised for 30 minutes after publishing.