JavaScript Contexts

Overview

JavaScript in Revu executes from three distinct contexts, each with its own purpose and scope:

1. Event-Level Scripts - Code that runs in response to user actions
2. Document-Level Scripts - Code that loads when a PDF opens
3. Folder-Level Scripts - Code stored externally that's available to all PDFs

Understanding where to place your code and what each context can access is fundamental to PDF scripting in Revu.

Event-Level Scripts

Event-level scripts are the most common type of JavaScript in PDF documents. They execute when users interact with form fields, buttons, and other interactive elements.

Accessing Event Scripts

In Revu, you add event scripts through the Properties panel:

1. Select a form field or button
2. Open the Properties panel
3. Navigate to the Actions tab
4. Choose the trigger event (Mouse Up, On Focus, Validate, etc.)
5. Select "Run a JavaScript" as the action
6. Enter your JavaScript code

The 'this' Object

In event-level scripts, this refers to the Doc object of the current PDF:

// In a button's Mouse Up event
console.println(this.numPages)  // Number of pages in the document
var field = this.getField("TextField1")  // Access a form field
this.print()  // Open the print dialog

The 'event' Object

Event scripts have access to a special event object containing information about the current interaction:

// In a text field's Keystroke event
console.println(event.value)  // Current field value
console.println(event.change)  // The keystroke being entered
event.rc = false  // Cancel the event

Document-Level Scripts

Document-level scripts execute automatically when a PDF opens. They're ideal for initialization code and defining functions that will be used throughout the document.

Accessing Document Scripts

In Revu, create document-level scripts through:

1. Go to Forms > JavaScript
2. Select "Document JavaScript" from the dropdown
3. Click "Add" to create a new script
4. Name your script
5. Enter your JavaScript code

Purpose

Document-level scripts typically:

• Define reusable functions for the entire document
• Initialize form field values
• Create document-wide variables
• Set up the document environment

The 'this' Object

In document-level scripts, this also refers to the Doc object:

// Document-level script
console.println("Document: " + this.documentFileName)

// Define a function available to all events in this document
function formatCurrency(value) {
    return "$" + Number(value).toFixed(2)
}

// Initialize a field
this.getField("DateField").value = util.printd("mm/dd/yyyy", new Date())

Scope

Variables and functions defined in document-level scripts are available to all event scripts within that document:

// Document-level script
var taxRate = 0.08

function calculateTax(amount) {
    return amount * taxRate
}

// Any event script in the same document can use these
var tax = calculateTax(100)
console.println("Tax rate is: " + taxRate)

Folder-Level Scripts

Folder-level scripts are JavaScript files stored outside of PDFs, making their functions available to all PDFs opened in Revu.

Location

Folder-level scripts are stored in:

C:\ProgramData\Bluebeam Software\Bluebeam Revu\21\Revu\JavaScript

Any .js file in this directory loads automatically when Revu starts.

Purpose

Folder-level scripts provide:

• Utility functions used across multiple PDFs
• Company-wide standards and validations
• Shared libraries of common functions
• Trusted functions for privileged operations

The 'this' Object

In folder-level scripts, this is undefined, not a document. To work with documents, you must pass them as parameters:

// Folder-level script (utilities.js)
// 'this' is undefined, not a document

// Global function available to all PDFs
function globalFormatDate(date) {
    return util.printd("yyyy-mm-dd", date)
}

// Function that accepts a [Doc](../chapter_5/Doc.md) object as parameter
function countFieldsInDocument(doc) {
    // Must receive the document explicitly
    return doc.numFields
}

Using folder-level functions from a PDF:

// In a PDF's event script
var formatted = globalFormatDate(new Date())  // Call global function
var fieldCount = countFieldsInDocument(this)  // Pass 'this' (the Doc) explicitly

Context Interaction

The three contexts work together to create complete solutions:

// Folder-level: Define utility
function calculateInterest(principal, rate, time) {
    return principal * Math.pow(1 + rate, time)
}

// Document-level: Add document-specific logic
var defaultRate = 0.05

function getLocalPayment() {
    var amount = this.getField("Amount").value
    return calculateInterest(amount, defaultRate, 5)
}

// Event-level: Use both in response to user action
var payment = getLocalPayment()
this.getField("Result").value = payment

Loading Order

1. Folder-level scripts load when Revu starts
2. Document-level scripts load when a PDF opens
3. Event-level scripts run when triggered

This means folder functions are always available, document functions are available after the PDF loads, and event scripts can use both.

Quick Reference

Where to place code:

• Folder-level: Shared utilities across multiple PDFs
• Document-level: PDF-specific functions and initialization
• Event-level: User interaction responses

How 'this' works:

• Folder-level: this is undefined
• Document-level: this is the Doc object
• Event-level: this is the Doc object

Moving Forward

Understanding these three contexts provides the framework for JavaScript in Revu. The next section explores security.