JavaScript in pdfToolbox: Custom data objects and methods

Inside pdfToolbox, JavaScript functionality for use in JavaScript Variables and in the form of a "Profile JavaScript" is provided as follows:

  • The JavaScript engine in pdfToolbox is based on Google's V8 JavaScript engine (see https://developers.google.com/v8/ for more information). 
  • pdfToolbox (through the underlying V8 engine) supports the complete set of JavaScript features as defined in ECMAScript is specified in ECMA-262, 5th edition (see http://www.ecma-international.org/publications/standards/Ecma-262-arch.htm)
  • pdfToolbox provides access to custom pdfToolbox controlled data objects, for example data objects representing metadata, file name, page sizes, and so on for the current PDF
  • pdfToolbox provides custom methods, for example for reading a file or parsing XML using XPath
  • pdfToolbox also supports storing data in the app.vars data object which can be accessed for reading and writing throughout execution of a Process Plan, Profile, Check or Fixup
  • The pdfToolbox JavaScript engine comes with a powerful runtime evaluation architecture, that ensures that JavaScripts present in several JavaScript variables possibly relying on each other's execution do work in a predictable manner without the user having to define execution order. 
  • The pdfToolbox JavaScript engine supports only very limited access to the outside world (i.e. accessing web services, data bases or arbitrary services through whatever protocol are mostly not supported); one exception is a possibility to read data from the local file system.
  • pdfToolbox currently does not offer the possibility to reference JavaScript files, as is often used to incorporated JavaScript modules; where such modules are to be incorporated anyway, the JavaScript code for such modules must be included in the JavaScript code for a given script variable (or in the JavaScript for a "Profile JavaScript").

Details about the Google V8 version used in pdfToolbox

Note: While Google V8 claims complete support of JavaScript as defined in ECMAScript 262, this is not 100% correct. For example, the import method is not supported in V8, and has to be implemented by the tool or system inside which V8 runs. pdfToolbox will support the import method in a future version.

pdfToolbox specific internal data objects

pdfToolbox defines custom objects: ‘app’, ‘console’, ‘File’ and ‘XML’.

  • The app object contains information about
    • app.doc the current document (read only)
    • app.vars a storage for variables (read/write)
    • app.http access to external resources via REST (read only)
    • app.context allows customization of the ask at runtime dialog 
    • app.env information about the environment (read only)
    • app.name and app.version information about the instance of pdfToolbox (read only)
  • The console object provides a log function that currently only works in the script editor under “Show evaluation results"
  • The File object enables reading of files from the file system
  • The XML object allows parsing of XML data and retrieving values using Path expressions.

pdfToolbox specific methods

The methods listed below are specific to the pdfToolbox JavaScript engine:

  • app.requires
  • app.doc.getPageBox()
  • app.doc.hasPageBox()
  • app.doc.getPageRotation()
  • app.doc.pages[i].getPageBox()
  • app.doc.pages[i].hasPageBox()
  • app.doc.pages[i].getPageRotation()
  • app.doc.xmp.getProperty(ns,property)
  • app.setTimeout (seconds)
  • app.http.get(url)
  • console.log()
  • console.info()
  • console.warn()
  • console.error()
  • File.read()
  • XML.xpath("expression")
  • XML.registerNamespace("prefix","uri")

Looking up pdfToolbox specific data objects and methods while creating or editing scripts

While creating or editing a JavaScript variable a list of pdfToolbox specific custom data objects and methods can be accessed (for this to work, make sure the text cursor is inside the "Script:" field):

Clicking on the object gives you the description of what the object or the method can do.

Interacting with the outside world

Reading from a file on the file system

Example for reading a file:

Assuming presence of a file "name.json" at the path "/Users/username/test" with the following content:

{
	"firstname": "Ulrich"
}

the following script could determine the value of the key firstname:

let file = new File("/Users/username/test/name.json");
let obj = JSON.parse(file.read());
obj.firstname;

The result of executing the script would then be:

“Ulrich"

Writing log statements to the Console field in the script editor window

Below are two examples of code that create a log statement in the Console field inside the script editor window:

console.log("Hello world!");
console.log(JSON.stringify(app.env,null,'\t'));

Communication with external resources

Here is a short script that returns the Product_ID of the first cartridge on our AWS license server. Important point here is the JSON.parse() to convert the JSON string into a JavaScript object.

let response = app.http.get("http://examaple_amazonaws.com:1234/status/data.json", [^] {timeout: 100} );
let r = JSON.parse(response);
r.cartridges[0].product_id;
Click to copy