JavaScript for applications

Introduction

The Adobe Creative Suite applications (Acrobat, Photoshop, Illustrator and InDesign) can be extensively scripted through JavaScript (a scripting language interpreted and executed by the application). All four applications offer a similar overall interface for working with JavaScript, although each application offers a different set of JavaScript functions to actually control the application's functionality

The JavaScript programming interface for each application is documented in the application's software development toolkit which can be found on the Adobe web site. The Adobe Creative Suite bundle includes the "ExtendScript Toolkit" application which is extremely useful for developing and debugging JavaScript scripts for Adobe Creative Suite applications.

The Switch configurators for the four applications mentioned above allow posting a JavaScript script to the application for execution. Combined with Switch's built-in capabilities this provides powerful control of the Adobe Creative Suite applications.

Note:

In the remainder of this topic "application" means one of the four Adobe Creative Suite applications mentioned above, and "configurator" means the Switch configurator that controls the application under consideration.

Stages

A configurator defines the action to be executed by its corresponding application in the form of three consecutive stages:

Open the file and make it the currently active document.
Perform a command on the currently active document.
Save the currently active document and close it.

The desired action for each stage is defined independently, and can be selected from:

One of the built-in actions listed by name.
A user-provided script (which is specified by browsing to a JavaScript text file).

Depending on the selected action a number of subordinate properties are shown to further configure the action. In other words, each choice has its own set of properties.

The properties for the "Use script" choice are described below; those for built-in choices are described for each configurator separately.

Properties for specifying a user script

The following set of properties is shown for an action stage if the "Use script" option is selected for the stage.

Property	Description
Script file	The text file that contains the JavaScript script to be executed by the application for this stage
Argument 1	The first argument to be passed to the script (or empty)
Argument 2	The second argument to be passed to the script (or empty)
Argument 3	The third argument to be passed to the script (or empty)
Argument 4	The fourth argument to be passed to the script (or empty)
Argument 5	The fifth argument to be passed to the script (or empty)

There are always five arguments because there is no mechanism to determine how many arguments are actually needed by the script.

Writing a user script

To write a user script, simply provide the JavaScript statements that should be executed in the main body of the script file. If your script encounters an error, it should set the $error variable to the appropriate error message; otherwise it should leave the $error variable alone. See below for a typical coding pattern.

The following special global variables are defined before your script executes, and thus their value can be used in your script; in some cases (noted in the variable's description) your script should also set or update the contents of the variable.

Variable	Description
$arg1	The first argument passed to the script (or the empty string if there is none)
$arg2	The second argument passed to the script (or the empty string if there is none)
$arg3	The third argument passed to the script (or the empty string if there is none)
$arg4	The fourth argument passed to the script (or the empty string if there is none)
$arg5	The fifth argument passed to the script (or the empty string if there is none)
$infile	The absolute path of the input file, including name and extension; this is used mostly in a script attached to an "open" action
$doc	The currently active document, that is, the document that was opened by the "open" action; $doc is null for a script attached to an "open" action (or when the "open" action failed) Important note: use $doc instead of "this" to refer to the currently active document
$outfolder	The absolute path of the folder in which to place the output; this is used mostly in a script attached to a "save" action
$filename	The filename (without extension) of the input (and output) file
$extension	The filename extension of the input file, or if it does not have one, the filename extension corresponding to the Mac file types of the input file
$outfiles	The incoming value of this variable is irrelevant If your script is attached to a "save" action, it should set the contents of this array variable to the absolute paths of the output files generated by the script
$jobfolder	The incoming value of this variable is irrelevant If your script is attached to a "save" action, it should set the contents of this variable as follows: The empty string: each output file is moved along the outgoing connection as a separate job The desired name of the job folder: all output files are placed inside a single job folder with the specified name
$error	If an error occurred during the execution of an earlier stage, or while preparing for the execution of this stage, this variable contains an appropriate error message: otherwise its value is null (NOT the empty string; an empty string signifies that an error indeed occurred but no meaningful error message was generated -- this is considered bad practice but it may happen) If your script encounters an error, it should set the $error variable to the appropriate error message (that is, a non-empty string); otherwise it should leave the $error variable alone.

Error handling

Here's a typical coding pattern to correctly handle errors in a user script attached to the command action:

if ($error == null) 
{ 
    try 
    { 
        // statements to be executed by this script 
        // $doc.ApplicationDependentFunction(); 
    } 
    catch( e ) 
    { 
        $error = e.description; 
        $doc.closeDoc( Application Specific Parameters ); 
        // close any other resources used in the try block 
    }
}

Here's a typical coding pattern to correctly handle errors for Adobe Acrobat application:

// Acrobat is used to make a summary of the annotations resulting in a file that shows you the page 
// content and the annotations per page.
// No arguments are required.

if($error == null)
{
	
	try
	{
		var title = $doc.documentFileName + " summary"
		$outfile = $outfolder + '/' + $filename + "_summary.pdf";
		$doc.ANsummarize($doc, title, ANSB_Page, null, $outfile, null, false, true, false, false, false, false);
		$outfiles.push($outfile);
	}
	catch(theError)
	{
		$error = theError;
		$doc.closeDoc( {bNoSave : true} );
	}
}

$error