How To Browse For A File Or Folder Path

This is part three in a series on popups and browse windows.

Photo by Sincerely Media on Unsplash

Browse For A File

There's a form field method called browseForFileToSubmit that opens a browse window for the user to drill down and select a file. Once the file is selected the value of text field becomes the path to the file, including the file name and extension. I don't believe there are any restrictions on the file type that can be selected because nothing is being done with the file at this point. It's simply a matter of obtaining the file path.

Text Field Properties

The browseForFileToSubmit method is executed on the field object like this:

this.getField("FilePath").browseForFileToSubmit();

While "FilePath" can be the name of any text field you create it must have the fileSelect property set to true or the method will fail.

Acrobat PDF Form With fileSelect Property Set To true

Notice that all other selections except Alignment are disabled. None of them can be used when the field is used for file selection, except Scroll long text, which is mandatory. The Field is used for file selection check box will be disabled until Scroll long text is selected, and Password, Check spelling, Mult-line, Allow Rich Text Formatting, Limit of, and Comb of are unselected.

This becomes very important when automating the creation of a File Selection text field in order to have the user browse for a file path to be used in an automation script.

I have none of the boxes in the image above selected when I create a new text field from the Prepare A Form user interface (UI). That is how I set my default properties for text fields because I prefer to select what I need instead of having to unselect a bunch of boxes for each text field I create. If you don't know how to set form field defaults, go to the following article and scroll down until you see the heading Form Field Defaults:

---

My Acrobat Pro Default Settings

---

Automating File Selection Form Field Creation

In automation projects that require the user to select a file or folder path, the following steps are often used:

1. Create a new document.

2. Create a text field in the new document.

3. Set the fileSelect flag of the text field to true.

4. Activate the browseForFileToSubmit( ) method.

5. Define a variable with the value of the text field (the file path the user browsed to).

6. Close the new document without saving.

These steps happen seamlessly in succession behind the scenes without user interaction except the browseForFileToSubmit method which is all the user sees and interacts with.

Step 3 is often the cause of issues. For one, setting the fileSelect flag is one of the only field properties that requires a privileged context (Action, Console, Trusted Function in a folder level script) to execute with a script. Attempting to change the fileSelect flag outside a privileged context will fail and the error will stop the script.

The aforementioned text field property default settings seem to have no relationship to the creation of a text field with a script. For example, my defaults in the options tab have no check marks. But when I create a text field with a script like this:

var f=this.addField("Test","text",0,[7,787,79,776]);

and open the options tab of the field properties I see this:

Notice the two checkmarks and the check boxes that are disabled? If I try to set the fileSelect flag it will fail without an error:

f.fileSelect=true;
true

browseForFileToSubmit will throw an error because the fileSelect flag is still false - the Field is used for file selection box was not checked. The solution is to first set the doNotSpellCheck flag to true which unchecks the Check spelling box.

No, the last sentence does not contain incorrect information. Setting a field property containing a check box in the UI to true usually checks the box, but in this case the JavaScript property is doNotSpellCheck, while the box label is Check spelling. If doNotSpellCheck is true, Check spelling is not activated (no checkmark). Scroll long text has the same "double negative" effect. The flag for the script is doNotScroll, which needs to be set to false (do not, do not scroll means scroll - Scroll long text box checked).

Putting It All Together

It's good practice to first set the doNotSpellCheck and doNotScroll flags after creating the text field and before setting the fileSelect flag:

var f=this.addField("Test","text",0,[7,787,79,776]);
f.doNotSpellCheck=true;
f.doNotScroll=false;
f.fileSelect=true;

Selecting A Folder Path

browseForFileToSubmit can be used for selecting a folder path by either of the following methods:

1. Having the user copy a specific PDF file to the folder and then having the script remove the PDF file name from the result of browseForFileToSubmit. OR

2. Having the user connect to any file in the folder, then split the file path into an array, pop the last array element out, then rebuilt the file path.

For the first point, assume the PDF file the user is instructed to copy to the folder is called Target and the text field used for file browsing is called FilePath. The script would look like this:

var folder;
var f=this.getField("FilePath");
f.browseForFileToSubmit();
if(!f.value){app.alert("No file selected.",1)} else
{folder=this.getField("FilePath").value.replace("Target.pdf","")};

The second point the script would look like this:

var folder;
var f=this.getField("FilePath");
f.browseForFileToSubmit();
if(!f.value){app.alert("No file selected.",1)} else
{
var aray=f.value.split("\\");
aray.pop();
folder = aray.join("\\")+ "\\";
}

Notice the backslashes in the file path need to be doubled up. That's because a backslash in a string is an escape character which ignores the next character. In other words, all of the backslashes in strings need to be “escaped” or the script will throw an error.

Much Easier Folder Browsing Technique

One would think that Adobe would provide a function to browse for a folder, as well as a file, so the scripts above would not be necessary. Well, here's some good news. There is a method to browse for a folder path, but it's undocumented - meaning it's there, and it works, but for whatever reason Adobe did not include it in the JavaScript reference.

If you look up Callab in the JavaScript reference you will see that it is an object representing collaboration functionality. You will also see three methods listed. A way to find out if there are more properties or methods in this object is to run the following script in the console:

for(i in Collab){console.println(i)}

When I ran the code above in the console it returned a list of 171 results. Looking down the list I noticed browseForFolder. That looks like something that might be what we need so I ran the following script in the console:

Collab.browseForFolder();

Sure enough, the script above opened a browse window and returned the path to the folder that I selected. Next, I tested whether this method required a privileged context by putting the same script in a Mouse Up action of a button field in a form, then clicking the button. Nothing happened and the following error was written to the console:

NotAllowedError: Security settings prevent access to this property or method.
Collab.browseForFolder:1:Field Button6:Mouse Up

That means Collab.browseForFolder( ) is an undocumented method for browsing for a folder that must be executed from a privileged context.

Stay Tuned

Next week in part four of this series on popups and browse windows I will answer the question of how populate a default file name in a Save As window.