Document Level Scripts
A Common Question
When I started learning JavaScript for Adobe Acrobat Pro more than 20 years ago, and using it to program fillable forms and paperwork automation solutions, I was frequently led to the same place: The JavaScript forum at AcrobatUsers.com. Solutions and sample scripts were shared freely by true professionals, and masters of their craft.
It wasn’t long before I started answering questions myself and quickly moved into the expert rank. I got really busy with my business and the Acrobat Users website changed something procedurally in a negative way - I can’t even remember what it was - so I stopped answering questions. I recently started answering questions again.
A lot of answers start with "Create a document level script…" and it’s not long before the inevitable follow-up question "where does the document level script go?" surfaces. So here we go.
Acrobat JavaScript Locations
There are several locations to insert and run JavaScript:
The JavaScript console: runs immediately when executed from the console.
The Action Wizard (formerly "Batch Process"): runs when an action runs.
Folder level script: runs every time the Acrobat program starts.
Document level script: runs every time a PDF opens.
Page action: runs when the user enters or exits a PDF page.
Document action: runs during one of the following events: before the user saves the document, after the user saves the document, before the user prints the document, after the user prints the document.
Form field: runs when user interacts with the form field, or when the value of another field changes.
Purpose
The most common use of the document level script is to set a function that will be used elsewhere in the document. The function script runs when the PDF is opened so it can be "called" from anywhere in the document (see the last 3 bullet points above). If the function has to be corrected or rewritten it only has to happen in one place, instead of every place it might be called from within the document (keep reading for a specific example).
A document level script can also be used to set variables, so they don’t have to be repeated everywhere they’re used in the document. A variable representing an array that is a long list of names, is an example.
Another use of the document level script is for a popup warning message or dialog to collect information from the user. These scripts run once, every time the PDF is opened. Many programmers make the mistake of putting these types of scripts as a page open action in the first page of the document. This is fine for a one-page document because it will appear once when the documents opens. But it can be really annoying on a multi-page document because it will run every time the user returns to page one.
Function Example
This example is very simplistic to illustrate the point. Suppose you need to apply the same math equation to a number of fields. And this equation multiplies two field values together. You can write the function like this:
function multiply_by(fld1, fld2)
{
event.value = this.getField(fld1).value * this.getField(fld2).value;
}multiply_by is the name of the function. fld1 and fld2 are variables representing the names of the two fields. The function would be inserted as a document level script. Then you can easily add a script as a custom calculation to any text field and its value will be calculated as the product of two fields. The two field names in quotes will replace fld1 and fld2 like this:
multiply_by("otherField1","otherField2");The function can be called in any text field as custom calculation, and any two fields can used:
multiply_by("Text1","Text2");Why would you write a function when you can simple select the two fields under Value is the product of… in the custom calculation tab? What if you needed to change the formula?
Time Saver
Now suppose you have a form and you have added the function to 50 fields, and it is working well. Suppose you need to change the formula so that it adds 100 to the product of the two fields. The good news is you don’t have to edit 50 custom calculation scripts like you would had you not written a function in a document level script. All you have to do is edit the function in one place like this:
function multiply_by(fld1, fld2)
{
event.value = this.getField(fld1).value * this.getField(fld2).value + 100;
}Your formula will instantly change for all 50 fields. This simple example becomes a lot more useful when applying more complex formulas and calculations across multiple fields.
How Do You Add A Document Level Script
In Acrobat Pro, search JavaScript in the Tools tab search field then click Document JavaScripts:
Because I use this tool so much I used Organize Quick Tools to add it to my regular toolbar button:
Once you select Document JavaScripts a window will open where you can name your script and add the function:
In the example above, "Script" is the name of the script, not the name of the function. You can edit the function by click the Edit button. If you have five functions you don’t need five named scripts. You can put them all under the same named script, or you can name them separately. They will run in the order they appear every time the document opens. They will also run when you close the window pictured above so you can immediately start testing without having to close and reopen the document.
Your script does not have to be a function, as discussed in the Purpose section above. When you first open the Document JavaScripts window and name the script, it will use that name as a function in default text. You can simply delete that text:
