Folder Level Scripts
These custom scripts run when the PDF application starts.
Document level scripts run when a PDF is opened, as described in my last article. Folder level scripts run every time the PDF application starts. This is essential for creating custom toolbar buttons and custom menu items.
As I continue to rail against the "new experience" in Acrobat and Reader and hope they never to decide to eliminate Hamburger Menu => Disable New Acrobat, I'll add two more reasons to the stack. The "old experience" menu had File, Edit, View, E-Sign, Window, and Help. Since they jammed all but Help somewhere in the hamburger menu, custom menu items created for some of the other menu parents will no longer function (File, for example). The add-on tools (custom toolbar buttons) work, but the icons have been replaced with pink cartoonish bricks.
Since the menu items and toolbar buttons are created with a script, this script must run when the application opens.
Privilege
If you’ve spent any time in the Acrobat JavaScript reference guide, you'll discover that many methods and functions are "privileged", meaning they can only function within a specific context, like console events, actions, or trusted functions in folder level scripts.
Any method that accesses the user's file system "silently" (that is, without further user interaction) or bypasses a user interface to perform "silently" is usually privileged. Without privilege, these would be security risks. Can you imagine opening a thousand-page PDF you downloaded or received as an email attachment and it sends every page to your default printer, or begins sending out emails from your email address, or starts manipulating files on your computer, all without your knowledge? These are some of the tasks that can be scripted to automate your Acrobat work flow - but only from a privileged context. The idea is that there is no security risk when users intend to do these things. Creating and running an Action can’t be done without user interaction. Ditto for creating and running a script from the console. To call a trusted function from a folder level script, the JavaScript file must first be put into the folder.
Creating A JavaScript File
It’s not difficult to create a JavaScript file that will run when Acrobat starts. All you have to do is write the script in a plain text editor like Notepad and save the file with a .js file extension.
In Windows, the resulting file icon will look like this:
Moving The File
The file should be move to the application JavaScripts folder. It can be dragged and dropped, or copied and pasted to the folder. If Acrobat or Reader is running when the file is installed, the script will not run until the application is restarted. To determine the location of the application JavaScripts folder, simply run the following script in the console:
app.getPath("app","javascript");I created a free PDF downloadable tool to help locate the folder, as well as three other folders. The PDF simply opens the console for you and instructs you to run the code. Since Reader does not have a user interface method for opening the console, this tool is especially useful for Reader.
Trusted Functions
In my last article on document level scripts I described how to write a function:
function alertFunct(/*variables*/message)
{
//script that runs when the function is called
app.alert(message,1);
}If you copy the script above, paste it into the console, then run the script, the function will be available for the session. The function is run like this:
alertFunct("This is my message!");When the function is run it will display a popup warning with whatever is between the quotes:
alertFunct("This is a warning message.");
This is a very simple function that you would probably never write because in this case it's easier to type the method out in full:
app.alert("This is a warning message.", 1);than it is to write a function and call it. Notice there is no “JavaScript Warning” message in the popup. This is because the script was run in a trusted context (the console). If you were to enter the function as a document level script in a PDF and call the function in a form field, the popup would look like this:
The Warning: JavaScript Window message is meant to be a security feature, but it scares a lot of people. Sometimes when I'm tasked to create a form with a warning message I'm asked if there's a way to not display the JavaScript Window message. It can't not be displayed if all of the code is within that form. However, if the function is written as a trusted function, the file is saved as a JavaScript file and placed in the application JavaScripts folder as described above, and the function is called from a button in the form, the popup will look like the one that was run from the console without the warning message. This goes for other types of popup windows as well like app.response and app.execDialog.
The structure of the trusted function is very similar to the regular function:
alertFunct = app.trustedFunction( function (/*variables*/message)
{
app.beginPriv();
//script that runs when the function is called
app.alert(message,1);
app.endPriv();
})There is no difference in how the two functions are called:
alertFunct("This is a warning message.");The app.alert method is not privileged so it does not need a trusted function. In this case, the trusted function will remove the JavaScript Window warning from the popup. Trusted functions are normally used for methods and functions that are privileged, like accessing the file system silently for example. If a method or function does not require a privileged context, it can still be placed inside a trusted function.
By the way, /*variables*/ and //script that runs when the function is called are comments in the script to instruct you. They are not required and will be skipped over by the JavaScript engine. Some readers might ask why I am describing something so “basic” and “obvious”. I taught myself JavaScript from web searches, reading through forums, reading the Acrobat JavaScript reference guide and reading a Core JavaScript book. It took me years to realize what those two commenting methods were and how to use them. I don’t want that to happen to anyone else.
Try It! Create, Install, and Test A Folder Level Script
This script adds a menu item, HIGHLIGHTER, to the Help menu that turns field highlighting on or off (NOTE: Field highlighting is turned on or off for the entire application, not just the form that is open at the time). Copy and paste the following script to a Notepad file then following the directions under Creating a JavaScript File and Moving The File above:
function HL_fields()
{
if(app.runtimeHighlight)
{app.runtimeHighlight=false;}
else
{app.runtimeHighlight=true;}
}
app.addMenuItem({
cName:"HIGHLIGHTER",
cParent:"Help",
cExec:"HL_fields();",
nPos:0});The first thing you should always do after installing a folder level script and restarting the application is check the console for errors.