To send a script or other data to another application, you must create and configure a BridgeTalk message object. This object contains the data to be sent (generally a script to be executed in the target application), and also specifies how to handle the response.
This simple example walks through the steps of sending a script from Adobe Bridge CS4 to Photoshop CS4, and receiving a response.
Step 1: Check that the target application is installed
Before you can actually send a message, you must check that the required version of the target application is installed. The function getSpecifier(), available in the global namespace through the BridgeTalk class, provides this information.
For example, this code, which will send a message to Adobe Bridge CS4 as part of a script being executed by Photoshop CS4, checks that the required version of Adobe Bridge is installed:
var targetApp = BridgeTalk.getSpecifier( "bridge-3.0"); if( targetApp ) {
// construct and send message }
When you send the message, the messaging framework automatically launches the target application, if it is not already running.
Step 2: Construct a message object
The next step is to construct a message to send to the application. You do this by creating a BridgeTalk message object, and assigning values to its properties. You must specify the target application and the message body, which is usually a script packaged into a string.
Scripts sent in messages can be very complex, and can use the full DOM of the target application. This example defines a message script that accesses the Adobe Bridge DOM to request the number of files or folders found in a specific folder:
CHAPTER 5: Interapplication Communication with Scripts Communicating through messages 165
var bt = new BridgeTalk;
// send this msg to the Adobe Bridge CS4 application var targetApp = BridgeTalk.getSpecifier( "bridge-3.0"); bt.target = targetApp;
// the script to evaluate is contained in a string in the "body" property bt.body = "new Document(’C:\\BridgeScripts’);
app.document.target.children.length;"
Step 3: Specify how to handle a response
If you want to handle a response for this message, or use the data that is returned from the script’s evaluation, you must set up the response-handling mechanism before you send the message. You do this by defining the onResult callback in the message object.
NOTE: The message callbacks are optional, and are not implemented by all message-enabled applications.
The response to a message is, by default, the result of evaluation of the script contained in that message’s
body property. The target application might define some different kind of response; see “Receiving messages” on page 166.
When the target has finished processing this message, it looks for an onResult callback in the message object it received. If it is found, the target automatically invokes it, passing it the response. The response is packaged into a string, which is in turn packaged into the body property of a new message object. That
message object is the argument to your onResult callback function.
This handler, for example, processes the returned result using a script-defined processResult function. bt.onResult = function(returnBtObj)
{ processResult(returnBtObj.body); }
If you want to handle errors that might arise during script processing, you can define an onError callback in the message object. Similarly, you can define a timeout value and onTimeout callback to handle the case where the target cannot process the message within a given time. For more information, see “Handling responses from the message target” on page 167.
NOTE: If you define callbacks to handle a response, you must store the message in a variable that still exists
when the response is received. Otherwise, JavaScript might garbage-collect the message object, and the response would be lost.
Step 4: Send the message
To send the message, call the message object’s send method. You do not need to specify where to send
the message to, since the target application is set in the message itself.
bt.send();
You can optionally specify a timeout value, which makes the call synchronous; when you do this, the method waits for a response from the target application, or for the timeout value to expire, before returning. When a timeout is not specified, as in this example, the call is asynchronous and the send()
method returns immediately.
A second optional parameter allows you to specify launch parameters, in case the target application is not currently running, and the messaging framework needs to launch it.
The complete script looks like this:
// script to be executed in Photoshop CS4 #target "photoshop-11.0"
var targetApp = BridgeTalk.getSpecifier( "bridge-3.0"); if( targetApp ) {
// construct a message object var bt = new BridgeTalk;
// the message is intended for Adobe Bridge CS4 bt.target = targetApp;
// the script to evaluate is contained in a string in the "body" property bt.body = "new Document(’C:\\BridgeScripts’);
app.document.target.children.length;" // define result handler callback
bt.onResult = function(returnBtObj) {
processResult(returnBtObj.body); } //fn defined elsewhere // send the message asynchronously
bt.send(); }