iText: Converting HTML to PDF with pdfHTML
NOTE: We are continually updating our features- and have some new features that are not included in this eBook yet. You can find a full list of features here.
Introduction
In this tutorial, we'll learn how to convert HTML to PDF using pdfHTML, an add-on to iText 7. If you're new to iText, please jump to chapter 1 immediately. If you've been working with iText in the past, you might remember the old HTML to PDF functionality. If that's the case, you've either been using the obsolete HTMLWorker class (iText 2), or the old XML Worker add-on (iText 5).
The HTMLWorker class was deprecated many years ago. The goal of HTMLWorker was to convert small, simple HTML snippets to iText objects. It was never meant to convert complete HTML pages to PDF, yet that was how many developers tried to use it. This caused plenty of frustration because HTMLWorker didn't support every HTML tag, didn't parse CSS files, and so on. To avoid this frustration, HTMLWorker was removed from recent versions of iText.
In 2011, iText Group released XML Worker as a generic XML to PDF tool, built on top of iText 5. A default implementation converted XHTML (data) and CSS (styles) to PDF, mapping HTML tags such as <p>, <img>, and <li> to iText 5 objects such as Paragraph, Image, and ListItem. We don't know of any implementations that used XML Worker for any other XML formats, but many developers used XML Worker in combination with jsoup as an HTML2PDF converter.
XML Worker wasn't a URL2PDF tool though. XML Worker expected predictable HTML created for the sole purpose of converting that HTML to PDF. A common use case was the creation of invoices. Rather than programming the design of an invoice in Java or C#, developers chose to create a simple HTML template defining the structure of the document, and some CSS defining the styles. They then populated the HTML with data, and used XML Worker to create the invoices as PDF documents, throwing away the original HTML. We'll take a closer look at this use case in chapter 4, converting XML to HTML in memory using XSLT, then converting that HTML to PDF using the pdfHTML add-on.
When iText 5 was originally created, it was designed as a tool to produce PDF as fast as possible, flushing pages to the OutputStream as soon as they were finished. Several design choices that made perfect sense when iText was first released in the year 2000, were still present in iText 5 sixteen years later. Unfortunately, some of these choices made it very difficult –if not impossible– to extend the functionality of XML Worker to the level of quality many developers expected. If we really wanted to create a great HTML to PDF converter, we would have to rewrite iText from scratch. Which we did.
In 2016, we released iText 7, a brand new version of iText that was no longer compatible with previous versions, but that was created with pdfHTML in mind. A lot of work was spent on the new Renderer framework. When a document is created with iText 7, a tree of renderers and their child-renderers is built. The layout is created by traversing that tree, an approach that is much better suited when dealing with HTML to PDF conversion. The iText objects were completely redesigned to better match HTML tags and to allow setting styles "the CSS way."
For instance: in iText 5, you had a PdfPTable and a PdfPCell object to create a table and its cells. If you wanted every cell to contain text in a font different from the default font, you needed to set that font for the content of every separate cell. In iText 7, you have a Table and Cell object, and when you set a different font for the complete table, this font is inherited as the default font for every cell. That was a major step forward in terms of architectural design, especially if the goal is to convert HTML to PDF.
But let's not dwell on the past, let's see what pdfHTML can do for us. In the first chapter, we'll take a look at different variations of the convertToPdf()/ConvertToPdf() method, and we'll discover how the converter is configured.