The document file browser - Part 4 of 5

Learn how to create a useful, general purpose file browser dialog.

By Thom Parker – September 4, 2006

 

Part 4 of 5

by Thom Parker, Software Developer/Adventurer, WindJack Solutions, Inc.

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

Part 3 of this series introduced the Document File Browser function, app.browseForDoc(). While useful and a relatively easy to use function, it will only browse for PDF files and cannot be used from a document script. In this tip, a much for useful, general purpose file browser dialog is introduced. Unfortunately, it is also more complex to use.

The Browse for File Dialog (Part 4 of 5)

This file browser dialog has been around since Acrobat 5.0. Given the name of the function, browseForFileToSubmit(), it was probably intended to aid in using a PDF to encapsulate (embed) and transport (email) other file types. Another characteristic probably related to this intended usage is the odd manor in which the browser is activated. It is a function of the Field Object, field.browseForFileToSubmit(). This is very different from the Browse for Document dialog (discussed in Part 3), which is a member of the App Object. Being a Field Object function makes this dialog awkward to use in Folder Level scripts (for Acrobat automation).

To use this browser dialog, do the following:

1. Create a new PDF or open an existing PDF.
2. Add a Text Field to the document.
3. Change the fileSelect property of the field to true.
   1. From the Field Properties Panel – set the Scroll long text and Field is used for file selection check boxes.
4. Call the browseForFileToSubmit() function. This function takes no input arguments and does not return a value.
5. The selected file path is assigned to the text field.

Usually the browseForFileToSubmit() function is called from the MouseUp event of either the Text Field itself, or a Button. However, it is not necessary for the Text Field to be visible, so this function can be part of a larger, behind the scenes process initiated by some other user action.

While this dialog is a document based function (since it’s attached to a document form field), with a little more code it’s possible to do all of these steps from a Folder Level script. For the example, run the following code from the JavaScript Console. In order to work these lines have to be run all at once, not line by line.

// Create new temporary document, 
// we'll never look at it so size is unimportant 
var tmpDoc = app.newDoc(0,0); 

// Create the Text Field 
var fld = tmpDoc.addField("tmpTxt","text",0,[0,0,0,0]); 

// Set up the Text field so the file dialog can be called 
fld.fileSelect = true; 

// Display File Open Dialog 
fld.browseForFileToSubmit(); 

// save the selected file path to a local variable 
// so it can be used later 
var filePath = fld.value; 

// Close Document without saving 
tmpDoc.closeDoc(true); 
console.println(filePath); 
 

The file path string uses the Acrobat Device Independent format, so a path returned from a Windows system would look like:

 /c/documents and settings/me/testfiles/sample.pdf

The first part of this script calls app.newDoc(). Since this is a privileged function the code has to be wrapped in a trusted function for it to work in a menu item or toolbar button created by a Folder Level script.

The Acrobat security model requires explicit user intervention when it comes to searching the local file system. Part 3 of this series discussed a relatively easy to use, but limited Application Level function for browsing PDF files, app.browseForDoc(), but the file browser dialog discussed in this tip, field.browseForFileToSubmit(), is the only way for an Acrobat JavaScript to acquire general purpose file system information, i.e., browse for all file types. Unfortunately, because the function is a Field Object member it is a bit awkward to use.