JavaScript Support

The PDF specification includes JavaScript support based on JavaScript version 1.5 of ISO-16262 (formerly known as ECMAScript).

PDF JavaScript is currently supported on our iOS and Android SDKs. Support for other platforms, such as Web and Windows, is coming in 2019.

See also: How to Program a Calculator in a PDF

Usage

There are many places in a PDF where JavaScript can be used.

  • Document-Level Scripts: These scripts are executed when the document is open. To add a new document-level script in Adobe Acrobat, go to Tools and search for Document JavaScripts. A dialog box will open where you can add a new document-level script to the PDF file:

You can get access to the document in a document-level script by accessing the event.target property, like this:

1
2
3
var document = event.target;
var textField = document.getField('MyTextField');
// Do things with textField

This code snippet will get a reference to the form field with the name MyTextField in the document.

Document-level scripts are very useful for reusing information and functions that will be accessed from several action scripts. For more information about document-level scripts, read the Doc/Open subsection on page 363 of the JavaScript™ for Acrobat® API Reference guide.

  • Action Scripts: Form fields and annotations can be extended with JavaScript actions. A JavaScript action is represented by the class JavaScriptAction. You can initialize a JavaScriptAction with a script and associate it with a form element and a particular trigger event. For more information about PDF actions, read our PDF actions guide.

You can set regular action scripts in Adobe Acrobat too. Open the Prepare Form tool and double-click on a form field. Click on the Actions tab and choose Run a JavaScript from the Select Action dropdown box.

One interesting set of JavaScript actions is that of the format, validation, and calculation actions. A format action modifies the appearance of a form element so that its contents are shown in a particular way (like a date or time, number of decimal places, etc.). A validation action validates the contents of a form field, ensuring they are always correct. A calculation action is invoked after certain events, like setting a form field value, and lets you establish relationships between form elements and perform calculations.

Disable JavaScript

JavaScript can be disabled per document via the following call. Set this before the document is displayed:

1
document.javaScriptProvider.setJavaScriptEnabled(false)
1
document.getJavaScriptProvider().setJavaScriptEnabled(false);

By default, JavaScript is automatically executed in PdfFragment. It can be disabled in PdfConfiguration via the following call:

1
2
3
val builder = PdfConfiguration.Builder()
...
builder.setJavaScriptEnabled(false);
1
2
3
PdfConfiguration.Builder builder = new PdfConfiguration.Builder();
...
builder.setJavaScriptEnabled(false);

If you are using PdfActivity, JavaScript can be disabled by using the same property in PdfActivityConfiguration.

Supported Features

PSPDFKit has basic support for the most common JavaScript API methods and properties:

App

  • alert, launchURL, viewerVersion

Console

  • println

Doc

  • getField, mailDoc, getNthFieldName, resetForm, print

  • numFields, pageNum, info

Util

  • printx, printd, printf

Color

  • transparent, black, white, red, green, blue, cyan, magenta, yellow, dark gray, gray, light gray

Event

  • value, rc, selStart, selEnd, willCommit, target, change, name, type

Field

  • getArray, checkThisBox, isBoxChecked, getItemAt, setItems, clearItems, setItems, insertItemAt, deleteItemAt, setAction, buttonImportIcon

  • name, value, textColor, fillCollor, strokeColor, readonly, exportValues, currentValueIndices, multipleSelection, commitOnSelChange, numItems, hidden, editable, type, page, borderStyle, rotation, defaultValue, doNotSpellCheck, userName, alignment, rect, doc, required, display, calcOrderIndex, comb, doNotScroll, richText, multiline, fileSelect, password, charLimit

Various functions for formatting, validation, and calculation are also supported. You can read Adobe’s documentation to learn more about them:

Number formatting

  • AFNumber_Format, AFNumber_Keystroke, AFMakeNumber

Percent formatting

  • AFPercent_Format, AFPercent_Keystroke

Date formatting

  • AFDate_Format, AFDate_FormatEx, AFDate_Keystroke, AFDate_KeystrokeEx, AFTime_Format, AFTime_FormatEx, AFTime_Keystroke

Special formatting

  • AFSpecial_Format, AFSpecial_Keystroke, AFSpecial_KeystrokeEx

Simple formatting

  • AFSimple, AFSimple_Calculate

Range validation

  • AFRange_Validate

JavaScript support is an experimental feature, and methods might be incomplete or return unexpected results. You are advised to test your JavaScript-enabled documents thoroughly. Please ping us if you have a document that isn’t quite working, and we’ll see what we can do.

Debugging

If there is a problem with the JavaScript in a document, it’s a good idea to first check that the scripts do not contain syntax or logic errors. To see all JavaScript code that is used in a document, open Adobe Acrobat, click on Tools, select Prepare Form, click the small down arrow on the sidebar, and then choose All JavaScripts. The screenshots below show how the All JavaScripts window appears in Adobe Acrobat.

JavaScript logs

If JavaScript is enabled, PSPDFKit will log errors to the console if there’s a problem with the JavaScript code. We tried to make diagnostics as specific as possible to help you debug your documents more easily. For example, the following error message is logged if the script creator mistakenly writes this.getField(4);:

Copy
1
PSPDFCatalog[58188:7996163] [JavaScript] [Error] Error: Argument name 'cName' has wrong type. Argument has type number, but expected string.

As you can read in the API documentation, getField’s cName argument must be a string.

In this other example, the script contains one API property that we currently don’t support:

1
PSPDFCatalog[58188:7996163] [JavaScript] [Error] TypeError: undefined not callable (property 'notSupportedAPI' of [object global])

Learn More