Advanced HTML-to-PDF JavaScript

Our PDF engine partner, Prince, offers the most powerful PDF conversion library available, and is a big reason why we believe DocRaptor is the best HTML to PDF API. Part of their unique offering is the advanced, PDF-specific JavaScript functionality they’ve added on top of standard JavaScript (we have a separate documentation page for enabling and working with regular JavaScript).

This page is merely a review of the more interesting JavaScript capabilities that Prince offers and is not intended to replace Prince’s own documentation. For detailed information on any of these functions, please see Prince’s documentation.

Generated Content Script Functions

Prince allows you to define JavaScript functions that can be referenced via CSS. For example, you could insert a timestamp into a header with code like:

<style>
@page {
 @top {
    content: prince-script(insert_datestamp)
  }
}
</style>

<script>
function insert_datestamp() {
  return (new Date()).toString();
}
Prince.addScriptFunc("insert_datestamp", insert_datestamp);
</script>

The Prince documentation also includes an example for implementing custom counter values on lists with JavaScript.

Multi-Pass Rendering

Sometimes, the only way to ensure the PDF is rendering correctly is to check it after it has been rendered. This rare situation normally involves very complex layouts, text fitting, or line height adjustments. With Prince, DocRaptor is the only HTML to PDF API to offer this capability.

To enable multi-pass rendering, register your JavaScript function via Prince.registerPostLayoutFunc(func). Your function will be called after the document is rendered. If that function changes the document in any way, it will be rerendered (and your function will be called again).

It is important to stop making changes at some point or the document will remain in a rerendering loop and timeout. For safety, you can set the prince_options[max_passes] parameter to a specific number of rendering passes.

PDF Box Access

The core of the HTML to PDF conversion process is turning HTML elements into PDF box elements. Every element in a PDF is a box of some kind, including text. Prince allows you to directly access and modify these PDF elements. This functionality is usually used in combination with multi-pass rendering.

PDF Object Access

While every relevant PDF setting (such as metadata or passwords) can be defined with CSS or API parameters, with Prince you can also access PDF settings via JavaScript.

JavaScript Execution in the PDF

PDF Actions

While not JavaScript, is possible to run PDF action commands when a document is opened or clicked on. These actions include things like printing the document or navigating to the first pages.

PDF Scripts

With the -prince-pdf-script CSS property, you can include actual JavaScript in your document. It is up to the PDF viewer to execute the JavaScript though. In many cases, it may only work in Adobe Acrobat products.