File paths in Acrobat JavaScript

Learn how Acrobat uses a simple character substitution called the Device Independent Path specification.

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.



Related topics:

JavaScript

Top Searches:


6 comments

Comments for this tutorial are now closed.

Thom Parker

5, 2014-12-15 15, 2014

Francisco,
First, this question is not related to the topic of the article, so it is an inappropriate post. You would be better served to ask this question on the regular forums. 
Second, it seems that you have a very complex issue. One that does have a simple answered. I can tell you right now that there is no single piece of generic code that will help you. Nor do I think you will find complete answers on the forums. You need training, and/or you need the services of a consultant.

Francisco

3, 2014-12-11 11, 2014

Who may concern,

Acrobat forms;
I am using the pull-down icon with 12 options on it. Each option has a different id. Each id has numbers and check boxes that need to be save for each 12 option, and each option are different. How can I do that?
For example:
On my pull-down menu:  a have; 1Type 1, 2Type2, 3Type3, ect.
On Type1 I have; a check box market active, a 1100, and a 25
On Type2 I have; unchecked not active, 0, and 0. And goes on…
Can you refereed to a place that has some code to do this?

Thank you in advance.

Patty Friesen

3, 2013-01-02 02, 2013

Hi Terrence,

Please post your question in the community Q&A forum:
http://answers.acrobatusers.com/AskQuestion.aspx

Not only will you get a faster answer, but someone else may have the same question and benefit from the answer.

Thanks,

Patty

Terrence

5, 2012-12-28 28, 2012

Hi thom,
you seem very knowledgeable about javascript.
i have a document that has a text input line called “id”
and a saveas button called save.
i would like for the employees to fill in the id, then hit the save button and have it save the file as the id {this.getfield(“id”)}
and place it on the desktop in a new folder that will be named by the date.

as simple as this seems ive spent 3 days researching this. your post was the closest i came to anything.

what would the script for that button be??

Thom Parker

6, 2012-11-12 12, 2012

Please ask this question on the Acrobat forums:
http://forums.adobe.com/community/acrobat

AB Raju

4, 2012-11-12 12, 2012

Hai,

Thanks for the reply

I checked, but it is not working. Can you give the entire command script.

Thom Parker

7, 2012-11-07 07, 2012

This is not an appropiate location for this question. You should have asked it on the forums. But the answer is simple enough.

Here is a calculation script for TextBox4

if(this.getField(“TextBox3”).value == 90)
  event.value = “A”;

Please see this article:
http://acrobatusers.com/tutorials/conditional-execution

AB Raju

6, 2012-11-07 07, 2012

Hi,

I have a small doubt in Adobe Acrobat Pro:

for example:-

I have 4 text boxes and text box 1 value is 20 text box value is 70 and the text box 3 will display text box 1 + Text box 2 (90). Here I need the script in text box 4.
If text box 3 the value is 90 means text box 4 should display A*.

I could not figure out the script.

Can any one help?

Comments for this tutorial are now closed.