Editing and Adding JavaScript

(Advanced feature of Nitro PDF Pro)

JavaScript is used in Nitro PDF Pro to create custom functions or actions in PDF forms. Javascript commands can be applied to form fields for calculations, formatting, validations, and many other things. Advanced knowledge of JavaScript programming is required to edit existing scripts or add new scripts. Resources that can assist with general or Adobe-specific JavaScript programming are available online through w3schools.com, pdfscripting.com, Adobe, and many other sources.

Note: Nitro PDF Pro only supports JavaScripts for Acroform PDF forms. It does not support JavaScripts for LiveCycle (XFA) documents.

JavaScript is an object-oriented computer programming language. It is commonly used to create interactive effects within web browsers and provides a powerful way to customize PDFs.

Nitro PDF Pro allows you to view, add, delete, or edit existing JavaScripts through a scripting window. JavaScripts in a document lists as either Document scripts or Page scripts. There are generally four types of JavaScript:

Document scripts: document level scripts are scripts at the top of a PDF document’s scripting hierarchy. These scripts are the first ones executed when a document loads in Nitro PDF Pro. Document scripts are used to set up operations, perform top-level environment testing, or define certain functions and variables used by other scripts in the document.

Document actions: document actions are events prompted by an activity such as closing, saving, or printing a document. Document “actions” allow form designers to change the document before or after any of those activities. There are usually five document actions:

• Will Close: prompted before closing a PDF. This action is primarily used to clean up—such as shutting something off—if a document includes advanced interactive multimedia like videos.
• Will Save: prompted before saving a PDF. This action is primarily used to make automatic changes to distinguish the saved version of the document.
• Did Save: prompted after saving a PDF. This action is primarily used to restore changes made in the “Will Save” action.
• Will Print: prompted before printing a PDF. This action is primarily used to make visual changes to a document, such as making visible a header or stamp on a PDF.
• Did Print: prompted after adding to the PDF to the print queue. This action is primarily used to restore changes made to the document in the “Will Print” action.

Page actions: Page-level actions are events triggered at the page level, such as opening and closing. For example, “opening” a page refers to when the document's specific page is both fully visible, and its associated page number is reflected in the Toolbar. “Closing” a page refers to when the specific page of the document is both no longer fully visible and its associated page number is no longer reflected in the Toolbar. These actions are generally useful for managing pages containing interactive multimedia such as timers, videos, or animations, which Nitro PDF Pro currently may not support.

Annotation actions: Annotation actions are events at the page level associated primarily with form elements for form fields. These actions enable custom functions or formatting for specific annotations. Users will be able to edit or add specific formatting, calculations, or validations for form fields. Form field scripts include two major types of scripts: “Widget scripts” and “Form-value scripts.” Widget scripts are actions performed on a field. Form-value scripts are actions that occur when a form field’s value changes.

• Enter: widget script executes when a cursor enters the form field.
• Exit: widget script executes when a cursor leaves the form field.
• Focus: widget script executes when the form field attains keyboard focus.
• Blur: widget script executes when the form field loses keyboard focus.
• Mouse up: widget script executes when a mouse/cursor hovers over the form field, and a user clicks the button.
• Mouse down: widget script executes when a mouse/cursor hovers over the form field and the mouse button is released.
• Page opened: see Page actions.
• Page closed: see Page actions.
• Format: form-value script will run after the Validate script if the Validate script is true.
• Validate: form-value script will run when associated field values in the document change.
• Calculate: form-value script will run when the document’s field values change.
• Keystroke: form-value script will run when keystrokes are entered in a text field.

Note: Users will be able to view all scripts available at both the Document and Page levels. However, while all scripts are technically editable, Nitro PDF Pro may not support all JavaScripts. As an example, Nitro PDF Pro currently does not support certain multimedia such as interactive videos. However, the application does support general JavaScripts such as alerts, calculations, formatting, and validation.

Before JavaScript can run in a document, it must be enabled in Preferences. (User Preferences).

Enable JavaScript:

1. From the menu bar, choose Nitro PDF Pro> Preferences from the dropdown menu.
2. Select the General tab in the Preferences dialog.
3. Check the option to “Enable JavaScript.”

The Script window in Nitro PDF Pro allows you to view and edit a document’s JavaScript. If multiple documents are simultaneously open in Nitro PDF Pro, the Script window will display the document's scripts you are actively editing.

1. From the menu bar, choose Window > Scripts from the dropdown menu to display the Script window.
2. All JavaScripts currently included in the document are listed in the left pane. Document scripts are listed on top. Page scripts found on each page are listed below.
3. Click to select an item in the left pane to display the JavaScript in the script editor pane on the right.
4. Click inside the script editor pane to begin editing the script.
5. Changes made to scripts will save automatically.

Note: Adobe JavaScripts are usually characterized by the prefix “AF.”

The Script window allows you to delete JavaScripts in a PDF. JavaScripts currently included in the document are listed in the left pane.

1. From the menu bar, choose Window > Scripts from the dropdown menu to display the Script window.
2. All JavaScripts currently included in the document are listed in the left pane. Document scripts are listed on top. Page scripts are listed below for each page.
3. Click to select an item in the left pane to display the JavaScript in the script editor pane on the right.
4. Click the minus - located at the bottom left corner of the Script window to delete a script.
5. Changes made to scripts will save automatically.

The Script window allows you to add new scripts to the PDF.

1. From the menu bar, choose Window > Scripts from the dropdown menu to display the Script window.
2. JavaScript actions currently included in the document are listed in the left pane. Document scripts are listed on top. Page scripts are listed below for each page.
3. Click the plus + located at the bottom left corner of the Script window to add a new script.
4. In the Add a script dialog, select a script type from the Select script type dropdown menu.
5. If adding an Annotation Action to a form field, select an action from the "Choose action" dropdown menu. For information on adding form field calculations, see Creating Forms.
6. Click inside the editing pane and replace the default text "// type your script here" with a new script.
7. Changes made to scripts will save automatically.

Note: To add an Annotation Action to a specific form field, you must have the form field selected before clicking the plus + to add a script. If you do not have a specific annotation selected, you can only add Document or Page scripts.

There are a couple of ways to test your JavaScript. To execute scripts line by line, use the JavaScript window.

1. Hold down the Option (or Alt) key.
2. Choose Window > JavaScript Console.
3. Type or paste scripts in the Console.
4. Click Execute.

To test your form with calculations, you will need to switch to the Select Text Tool

(Command+1) in order to try out your form. Switch back to the Edit Tool

(Command+2) in order to edit the appearance of elements you've placed in your form.

Note: JavaScripts will only execute successfully if:

• The script is correct.
• The script is supported by your PDF version.
• The script is supported by Nitro PDF Pro.