File paths in Acrobat JavaScript
By Thom Parker – February 12, 2009
Scope: All Acrobat versions
Skill Level: Beginner
Prerequisites: Familiarity with JavaScript
File paths are a common part of using any software application. Programs typically provide file-browser dialogs for loading and saving files, thus hiding the details of how the paths are actually handled. However, when writing software, we have to be aware of any special file-path requirements and Acrobat JavaScript is no exception. Acrobat JavaScript contains many functions that require a file path, for example, app.openDoc() and doc.saveAs().
On the surface, file paths seem straightforward, but in fact they are not always so simple. The challenge for Acrobat JavaScript is to be compatible across three platforms; Windows, Macintosh and UNIX. This means the file paths must be compatible across these platforms as well. To work around the inherent platform dependencies, Acrobat uses a simple character substitution called the Device Independent Path specification, shown in the table below.
| Platform | Local Platform Path | Acrobat Device Independent Path |
| Windows | C:\MyFolder\MyFile.pdf | /C/MyFolder/MyFile.pdf |
| Macintosh | MyDisk:MyFolder:MyFile.pdf | /MyDisk/MyFolder/MyFile.pdf |
| UNIX | /user/me/MyFolder/MyFile.pdf | /user/me/MyFolder/MyFile.pdf |
From the table, we can see that a Device Independent path is formed by simply replacing the path separator with a forward slash character, “/”. A leading forward slash means the path is an absolute path, i.e., it contains all path components from the root of the hard drive, through the intervening folders, to the file name. If a path does not contain a leading forward slash, then it is a relative path. A relative path is one that assumes a starting point, usually the path to the current document. A relative path includes only those path components between the starting path location and the target location.
Unfortunately, switching out path separators does not necessarily make a path platform independent. From the table above, we can see that each platform has its own, and very different, root-drive specification. The solution to getting around this issue is to use relative paths whenever possible. Every Document Object function that utilizes a path input uses the document’s own path to anchor a relative path. Relative paths work quite well when working with groups of related files. For example, the following code exports an FDF file to a folder one directory level up from the current document.
this.exportAsFDF("../MyData.fdf");
In cases where a relative path cannot be used, an absolute path can be built from the path of an already open document, using the doc.path property, or from a path acquired from the app.getPath() function. This function returns a number of standard Acrobat related paths on the user’s system.
Path-use restrictions
All Acrobat JavaScript functions that write a file to the user’s local disk pose a security risk, so there are some restrictions placed on their use. These functions include doc.saveAs() and all of the data export functions, like doc.exportAsFDF().
Acrobat provides us with two modes of operation for these functions--with a path and without a path. If no path parameter is provided to the function, Acrobat displays a file-browser dialog. The file browser dialog gives users control over how data is saved to their systems. If a path is provided to the function, then no dialog is displayed and the operation is handled silently, i.e., the user is not necessarily aware that data has been saved to their hard drive. This is a security problem, so to use one of these functions in silent mode, the function must be executed from a privileged context. This means the code must reside in a trusted location. For example, code executed from the Console Window, a Batch Process or a certified PDF is privileged. When any of these functions are used with a path parameter and executed in a non-privileged context, Acrobat will throw an exception. The reasoning behind this restriction is, if the code can’t be trusted, then the user has to specifically select the file location.
Another restriction on saving data to the user’s system is that the path specification must be a Safe Path. A safe path is one that doesn’t point to a restricted location on the user’s hard drive or one that might pose a security risk. Examples of these restricted locations are the system folder and the root folder of any hard drive. Other folders that might be restricted are dependent on the operating system and the sensibilities of the Acrobat developers. Neither is well documented, so it’s best to use these functions carefully.