by Thom Parker of WindJack Solutions.
Copyright © 2004 by WindJack Solutions
 

     Folder (or plug-in)  level scripts are text files containing JavaScript code and having the .js file extension.  Acrobat looks for and loads these scripts on startup from two locations in the file system.  These  locations are system dependent, but can be easily identified by executing the following code from the JavaScript Console Window. 

• app.getPath("app","javascript"); //for locating the global JS folder
• app.getPath("user","javascript"); // for locating the user's local JS folder

     The main difficulty in developing a folder level script is that it is necessary to restart Acrobat when you want to load and test new code, a very time consuming operation.  For this reason it is best to adopt a method that reduces the number of times you will have to restart Acrobat. 
For Example: do your initial testing by entering new code into the JavaScript Console Window.

• Enter the code in as few lines as possible and execute each line individually to find error conditions and test the code's behavior. You can change and re-execute the same line as many times as necessary. 
• You may need several lines of setup code to test the new JS.  Copy this code directly from your JS file into the console window so there is coherence between the final (real) code and your test environment.  You can execute the entire block of setup code by selecting it all, then pressing the Ctrl-Return key combination.
• Then, when you are satisfied with execution of the new JS,  copy it into the JS file.
• Variables defined in the console window remain valid as long as you work in this window, so you don't need to re-execute  the setup code unless it is changed.
• Once you have either completed testing on all the small sections of code you need, or gone as far as you can, restart Acrobat to load and test the whole program.

    In order for folder level code to be used for task automation it must be made available to the user through a UI element. There are two such elements in Acrobat,  Menu Items and Toolbar Buttons.  A Menu Item is by far the simplest to implement since it only requires a single line of code.
For Example:
   app.addMenuItem({cName: "Hello", cParent: "File", cExec: "HelloWorldProc()"});

This line of code places an item named Hello on the File menu in Acrobat.  When this menu item is selected by the user the folder level function HelloWorldProc is called.  In the JavaScript file,  the HelloWorldProc  function is defined first and the app.addMenuItem line is the last one in the file.  Here is the complete file

function HelloWorldProc()
{
    app.alert("Hello World");
}
app.addMenuItem({cName: "Hello", cParent: "File", cExec: "HelloWorldProc()"});

     Toolbar Buttons are a much more desirable UI element because they are easily recognizable and immediately available, i.e. no menu walking. Another advantage specific to JavaScript created Toolbar Buttons is they can be made much larger than the standard Acrobat Toolbar Buttons and are not restricted to a square shape. But they do have two drawbacks. 

First, code executed from a toolbar button has about the same security restrictions as document level JS.  Mostly, this restriction includes operations that might be used in a malicious way, like document, page, and template creation. This situation really isn't that serious since most of the Acrobat JS methods don't require high security and if the code you are writing does require high security, the button could simply act as a front for a menu item, giving you the advantages of both a menu item and a toolbar button together.

The second draw back is that a Toolbar Button requires JS Code to create the  icon to be displayed on the button face.  Specifying this icon is quite difficult and poorly documented in the Acrobat JS documentation.  If you are interested in creating your own Toolbar Buttons you should consider purchasing AcroButtons, which is the only tool currently available for creating and managing JS Toolbar buttons.  It is also very helpful in other ways for developing folder level scripts.  There is another tool, which is not intended specifically for creating JS icon data, but can be used for this purpose.  That tool is PDF CanOpener.

Good luck and send us any comments you have on this article.  thomp@windjack.com