Using JavaScript

JavaScript can be used to transform documents by generating tables of contents and indices, sorting tables, rendering charts and graphs, and other tasks that go beyond the scope of CSS.

Scripts can access and modify the input document using the W3C standard DOM (Document Object Model). Prince also supports some additional properties and methods described below.

Document scripts can be run by specifying the --javascript option on the command-line. Prince will then execute all JavaScript found in the HTML script elements in the input document.

External scripts can be run by specifying --script=FILE options on the command-line. These scripts will always be executed, regardless of whether document scripts have been enabled or not.

JavaScript functions can also be called from CSS generated content, by using the prince-script() syntax for referencing Script Functions.

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);

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.profile (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 9.0:

document.write

window.setTimeout
window.clearTimeout
window.setInterval