The document file browser: Part 3 of 5 on popup windows

Learn how to create PDF file browser dialogs using Acrobat JavaScript.

By Thom Parker – October 7, 2006

Scope: All Acrobat versions
Skill Level: Intermediate
Prerequisites: Familiarity with the Acrobat JavaScript Console

This series of tips introduces the Acrobat JavaScript Popup Boxes. There are a variety of these popup boxes, or dialogs, used both to alert the user to important information and to collect input. In Part 3 and Part 4 of this series we explore the PDF File Browser Dialogs.

File system access is a standard component of most programming environments. Without it, there is no way to load and store file data. So while it is important, in the Acrobat JavaScript programming environment it is also problematic. The Acrobat security environment is sometimes referred to as a sandbox. A set of programming tools are provided inside the sandbox, but there is no communication with the outside of the box. There is no way to search the file system, so there is no possibility of a script in a PDF file acting maliciously. Nice in theory, but to build rich document applications with PDF we really need to be able to open and save files.

Acrobat gets around this restriction in two ways. File open access is allowed if the path to the file is already known. Any other type of access must be with the user’s explicit permission. There are several ways for the user to grant this permission, such as trusted code in a Folder Level script or document certification with a known digital signature. But for general file system access, the user needs to intervene directly, i.e., JavaScript can’t search the file system, but the user can. To this end, Acrobat provides a set of file browser dialogs. This series will look at two of these, the PDF Document Browser (Part 3, this tip) and the more general purpose File Browser (Part 4).

The Browse for Doc Dialog

In Acrobat 7.0, Adobe added a new function to the App Object, app.browseForDoc(). This function displays the standard platform file dialog. This is the same dialog used for opening and saving files in all of your applications. The operating system creates and manages this dialog. Acrobat simply hands off a set of operating parameters to the operating system and makes a request to display it.

Acrobat restricts the file types accessible with the dialog to those with a “.pdf” extension, so the dialog is only good for finding PDF files. A few other dialog characteristics are controlled by the input arguments. The full argument listing is shown here:

app.browseForDoc(bSave,

cFilenameInit, cFSInit);

None of these arguments are required. Try out the following code in the JavaScript Console to see an example of how this function works.

app.browseForDoc();

The first argument to this browser function, bSave, sets the mode of the dialog, either file save or file open (the default). This affects the text displayed at the top of the dialog and one aspect of the dialog’s behavior. In file save mode any text can be entered for the file name. In file open mode, only existing files can be selected. Try the two variations by entering and running each of the following code examples in the JavaScript Console.

// File Save Dialog 
app.browseForDoc(true); 

// File Open Dialog, same as default behavior 
app.browseForDoc(false);

The second argument, cFilenameInit, is the initial file name placed in the dialog. If the “.pdf” file extension is missing, Acrobat automatically adds the extension. If another file extension is used, Acrobat strips this off and replaces it with “.pdf.” This argument cannot be used to set the initial directory, only the file name. The file browser opens in Acrobat’s current directory. Run the following code from the console and see what happens.

app.browseForDoc({cFilenameInit: "MyFileName.jpg");

The final argument, cFSInit, defines the file system where the dialog will be used. An empty string (the default) indicates the local file system. A value of “CHTTP” indicates the file name can be retrieved from a WebDAV server. This does not stop the user from selecting a local file. When this argument is set, the user can browse both the local file system and WebDAV.

The return value from app.browseForDoc() is different from the return values for most other Acrobat JavaScript functions in that it is an object. Normally you’d expect a function like this one to return the selected file path as a string. However, the ability to use an alternate file system, i.e., WebDAV, means more information needs to be returned. This output object includes 3 properties: the file system name, the file path and the file URL. For example:

var oRtn = app.browseForDoc(); 

// File system name 
var myFileSystem = oRtn.; 

// File Path 
var myFilePath = oRtn.cPath; 
// File URL var myFileURL = oRtn.cURL;

Typical file system names returned in the cFS property are “CHHTP”, “DOS”, and “MacOSX.” However, unless you need to tell the difference between a WebDAV path and a local file path, these names are unimportant. Both the cPath and cURL parameters are filled in no matter which file system is used. The only difference between them is the path format. The cPath parameter uses Acrobat Device Independent format. Two examples are shown below.

// Mac OSX 
oRtn.cPath = "/osx/Users/me/Desktop/Sample.pdf"; 

// Windows 
oRtn.cPath = "/c/Document and Settings/me/Desktop/Sample.pdf";

The cURL parameter uses the standard URI format. Two examples are shown below.

 
//Local File System file 
oRtn.cURL = "file://localhost/Users/me/Desktop/Sample.pdf"; 

//WebDAV server 
oRtn.cURL = "http://www.myDocs.com/comments/Sample.pdf";

Typically, the cURL parameter is used for a WebDAV file system and the cPath parameter is used for a local file path

Please see the example file below for a working Folder Level script.

Document Browser Example file
Download [PDF, 24 KB]

One final note, the app.browseForDoc(), function is privileged. In short, this means for security reasons it cannot be executed from a document script, or at least not directly. Its main use is in Folder Level (application level) automation scripts. This limitation doesn’t completely kill it’s usefulness in document applications; it just makes things more difficult.