Scripting

JavaScript in Printed Media

Prince is a user agent producing primarily documents meant to be printed, and as such, some limitations are in place that set it apart from most other user agents that support JavaScript.

The most notable difference is the fact that a printed page cannot be interactive, being static in nature: a document cannot be modified after it is deemed to be ready for print. JavaScript can be run twice only: the first time it is run before layout, where it interacts with and modifies the layout (and the DOM structure). Once layout is finished, JavaScript can be run a second time from the complete event handler (see Event handling). However, this time it is only allowed to inspect the layout and cannot modify the DOM. See also The "Two-Pass" Solution.

A consequence of the non-interactive nature of printed media is that any interactive events, such as e.g. onClick, do not make sense, and will never fire.

Prince allows also for scripts to be passed directly to the PDF, to be executed when the PDF file is opened. The prince-pdf-script property is used for this purpose. A common use case is to activate the "Print" dialog automatically. See also PDF Actions.

Logging

The Prince log can be accessed from JavaScript via the Log object (also available as Prince.Log), which has the following methods:

Log.info("message")
Log.warning("message")
Log.error("message")
Log.data("name", "value")

Console access

When running Prince from the command-line, the console object can be used to write messages directly to the terminal:

console.log("Hello, world!")

Note: console access is only supported when running Prince directly from the command-line, and should not be used when calling Prince through a server wrapper or graphical user interface.

Event handling

When the document has been fully parsed and is ready for processing, Prince will fire the DOMContentLoaded and load events on the window object.

These load events can be captured by setting the onload attribute on the body element in HTML documents, or by setting the window.onload property or calling window.addEventListener.

When document conversion has finished, Prince will fire the complete event on the Prince object. This event can be captured by calling Prince.addEventListener, and is useful for logging document statistics.

User interface events such as onclick are not supported by Prince.

Document statistics

The Prince.pageCount property can be accessed after document conversion has finished, then logged as data for the calling process to access:

function logPageCount()
{
    Log.data("total-page-count", Prince.pageCount);
}

Prince.addEventListener("complete", logPageCount, false);

See also The "Two-Pass" Solution for another use of accessing document properties after the document conversion has finished.

PDF properties

The PDF object can be used to specify PDF properties and settings, including attaching extra files to the generated PDF, similar to the --attach command-line argument:

PDF.attachFile(URL, [Description])

PDF.attachFile("data.xls", "Latest sales figures.");

Other PDF properties include:

PDF.embedFonts (boolean)
PDF.subsetFonts (boolean)
PDF.artificialFonts (boolean)

PDF.compress (boolean)

PDF.encrypt (boolean)
PDF.userPassword, ownerPassword (string, can be null)
PDF.allowPrint, allowModify, allowCopy, allowAnnotate (boolean)
PDF.keyBits (40 | 128)

PDF.script (string, can be null)
PDF.openAction (eg. "print")
PDF.pageLayout (single-page | one-column | two-column[-left/right)
PDF.pageMode (auto | show-bookmarks | fullscreen | show-attachments)
PDF.printScaling (auto | none)
PDF.duplex (auto | simplex | duplex-flip-short-edge | duplex-flip-long-edge)
PDF.attachFile(url, description?, filename?)

PDF.profile (string, can be null)
PDF.outputIntent (URL string, can be null)

PDF.title
PDF.subject
PDF.author
PDF.keywords
PDF.creator

Unsupported DOM properties

The following DOM properties are not supported in Prince:

document.write
window.setInterval