Discovering the Fireworks RPC server – Part 1: XML and socket communication

RPC XML fragments

Detailed information on building and reading the XML fragments sent in a RPC transaction is found in the Fireworks 8 – Extending Fireworks document linked to at the beginning of this article. This article also gives an overview of the topic, while providing additional XML tag examples, sequences of commands, and helpful tips. I have included a short ActionScript 2.0 example to help you try XML calls to Fireworks. Part 2 of this article offers a new way to test your XML tags and catch errors by including a simple debugger panel for Fireworks.

XML tags representing JavaScript commands are at the heart of RPC server communication. The RPC XML calls can be designed to both get and set properties of Fireworks objects, call methods that are exposed in the Fireworks JavaScript API, and release objects from memory. This XML consists only of XML fragments, generally between one and five tags per call, and does not contain any XML declarations, DTD, or schema information.

There may be two parts to the XML tags, the outer node or <envelope> </envelope>, and inner <parameter /> tags. The RPC server accesses Fireworks through objects, so each envelope must contain an object ID as an attribute of the tag. All except release nodes have a name attribute.

There are only four types of envelope tags you can send. Here they are with their corresponding attributes or parameters:

• get <get obj="ID" name="" />
• set <set obj="ID" name="">< 1 parameter /></set>
• func <func obj="ID" name=""><varied parameters /></func>
• release <release obj="ID" />

Parameters are named after their data types, like string, and contain an order attribute for the RPC server. For example: <string order="0" value="a value here" />.

All XML input sent to Fireworks will have an XML output sent back from the server in the form of a <return /> node. If the XML fragments sent to the server do not start with get, set, func, or release, or the XML fragment is not configured correctly, the response will have an error attribute with a numeric value. The server reply may also contain important object IDs or information requested in the initial call, like a file path.

The following sections detail each of the four envelope tags and the Server reply node.

<func /> nodes

The JavaScript API is a set of functions that allows developers to extend Fireworks functionality and control documents and objects in those documents.

Since the RPC server is accessing the JavaScript API, the <func> tag specifies which JavaScript function when one is needed.

JavaScript API functions are divided into three categories:

• Document functions dom.functionName()
• Fireworks functions fw.functionName()
• History Panel functions fw.HistoryPanel.functionName()

You can find these categories and their methods in the Fireworks menu (Help > Extending Fireworks > Fireworks JavaScript API) as well as the Fireworks 8 – Extending Fireworks document.

When you build XML nodes for the RPC server, it will be easier if you know what type of function you want to use. Some functionality can be accessed by both a document function and a Fireworks function, such as saving a file (dom.save() / fw.saveDocument()), while others are specific to one type.

Fireworks functions are simpler to write because they always reference the fw object, while document functions require you to have an object ID so that you can tell Fireworks specifically what object to access, such as a file, layer, or shape. (The RPC server's replies, in the forms of return nodes, will always contain the object IDs for any objects it manages on your behalf.)

For example, here is code for opening a document with a Fireworks function call. In JavaScript it might look like this:

fw.openDocument("file:///C|/Box2.png", false, false)

Here is the same JavaScript function written as XML for sending to the Fireworks RPC server:

<func name="openDocument" obj="fw">
    <string order="0" value="file:///C|/Box2.png" />
    <bool order="1" value="false" />
    <bool order="2" value="false" />
</func>

You can see that in the XML version, the envelope node is <func> and the name of the method is the same as in the JavaScript version (openDocument). Since it is a Fireworks function call, the object ID is fw or the Fireworks object. This will generally be the same for all Fireworks functions, as long as you are attempting to conduct actions on the currently opened document.

Note: The obj and name attributes of the envelope tag may be in any order inside the tag, and may be shown in different orders throughout examples in this article or in different reference materials.

Whether you are accessing the openDocument method via RPC calls or inside Fireworks with more direct JavaScript, the openDocument function takes three parameters (the first two being optional). RPC XML then needs a parameter tag for each parameter you wish to set.

Parameters for <func> nodes can be different data types, and are referred to as data nodes. For instance, the first parameter for setting fileURL in the openDocument example should be a string data type, while the last two are Boolean data types. The XML parameter tags then have one String data node and two Boolean data nodes.

What makes the XML parameters slightly different is the addition of an order attribute for each data node, or tag. This allows the RPC server to know that the String data node <string order="0" value="file:///C|/Box2.png" /> is the first parameter to process and the Booleans are second and third. The parameters can be sent in a different position (<Boolean />, <Boolean />, <string />) as long as the order attribute is correct for the function (order="1", order="2", order="0").

RPC server data types—and thus node names—do not exactly map to their JavaScript DOM data type counterparts. DOM data types that contain multiple values, like points that have x and y coordinates, will become a <dict> or dictionary node in XML. You will see an example of this soon.

Note: Some function parameters, even if optional, may need to be set in the XML, while other parameters have limited use when used in RPC server calls. For instance, in the dom.importSymbol() function, if the bAllowUI parameter is set to true, Fireworks will open the Import Symbols dialog box so users can choose which symbol to import. If called from outside of Fireworks, further RPC server communication will stall while the dialog box waits for input.

RPC server replies: <return /> nodes

<return><obj value="12905" class="DocumentClass"></obj></return>

In this case, the server is able to find and open the file Box2.png, and returns the Fireworks-assigned object ID number (12905) for that file. If you disconnected from the server and tried the call again, the object ID may or may not be the same. The server also returns the class name of the object. So, if you want to access additional properties of the same file in our example, you can look at the Document object to find them.

Note: You need to store any object IDs sent to you from the server so that they can be released from memory when you are done using them. This is called memory management. When a connection to the RPC server is closed, all objects are released from memory and the server is free to reuse those IDs again.

If the client request is unsuccessful, there are a number of possible RPC server responses based on the error. There are nine error codes the server may include in the <return> tag. Table 1 shows the error codes.

Most typos in the XML will get the following response:

<return error="1"></return>. The error code "1" is an unknown, generic error. If the server can pinpoint the error, it will send a more specific code.

If the ID is wrong or unknown, the server sends <return error="2"></return>. If the method name is mistyped, including the wrong case—like "opendocument" instead of "openDocument"—the response would be <return error="3"></return>.

Sometimes you may not get an error code when there is a problem. For instance, if the string parameter filename in our example was wrong and the server was unable to find the file, the response would be:

<return><null></null></return>

IDs and document functions

If the RPC server is accessing a Fireworks object, that object receives an ID for the duration of the connection. Document functions access the DOM and they operate on the specific object's ID. You can get an object's ID through the <return /> node replies sent by the RPC server. If you wanted to add programmatically a new text box to the opened document from the previous example, you would need to use the Document function dom.addNewText(boundingRectangle, bInitFromPrefs).

To add a new, blank text box in the XML , you can use the Fireworks ID sent to you in the server response after the file was opened.

Here is the previous client call again, along with the server response:

<func name="openDocument" obj="fw">
    <string order="0" value="file:///C|/Box2.png" />
    <bool order="1" value="false" />
    <bool order="2" value="false" />
</func>
<return><obj value="12905" class="DocumentClass"></obj></return>

Below is only the envelope tag for a second client call to add a new, blank text box to the opened Box2.png file. This Document function call uses the object ID number sent by the server so that the box will be added to the right object:

<func name="addNewText" obj="12905">
</func>

Here is the full call with some parameters set for the text box size:

<func name="addNewText" obj="12905">
    <dict order="0">
        <int key="left" value="10" />
        <int key="top" value="15" />
        <int key="right" value="50" />
        <int key="bottom" value="30" />
    </dict>
    <bool order="1" value="true" />
</func>

Notice that the corner locations must be set with a Dictionary data node and integer tags for the pixel locations, whereas the JavaScript version would look like this:

fw.getDocumentDOM().addNewText({left:10, top:15, right:50, bottom:30}, true);

<get /> and <set /> nodes

The <get> envelope tag does not have any parameters. It can contain only name and obj attributes. If you wanted to size your text box based on the width of the open file, you would need to send a <get> tag and later extract the response from the server's return value, which in the sample below is 500 pixels.

Client call:

<get obj="12905" name="width" />

Server response:

<return><int value="500"></int></return>

The <set> envelope tag takes an additional one parameter with the correct data node for the value being set. These next tags set a new resolution of 96ppi for the opened file.

Client call:

<set name="resolution" obj="12905">
    <double order="0" value="96" />
</set>

Server response:

<return><void /></return>

<release /> nodes

In all the calls discussed so far, each envelope (func, get, and set) used an obj attribute with an object ID to specify the Fireworks object on which the call should execute. The release node also uses an object ID but as its only attribute.

The purpose of the release node is to let the RPC server know that the client is done working with the object referenced by the ID, and that the server should release the object from memory. When an object is released, its ID may be reused.

Here is a sample release of an object with the server reply:

Client call:

<release obj="54517" />

Server response:

<return><void /></return>

To manage memory effectively, all object IDs sent back from the server should be stored (for instance in an array object) and released when no longer needed. By default, all objects retained on your behalf during the session are released when the socket connection is ended.

History functions

History functions are similar to Fireworks functions, except that they require an extra step to access the History palette before palette functions can be called.

Client call 1 below asks the RPC server for the current ID of the History palette object, which Server reply 1 includes. Client call 2 then uses that ID to replay a past action in Fireworks.

To access past actions stored in the palette via XML, you can use an Array data node with an integer parameter indicating a specific step. Because this array is zero-based, you use 0 to access the first step, 1 to access the second step, 2 for the third step, and so on. Server reply 2 returns the JavaScript associated with the History palette's replayed action. The user events in the History palette change to reflect the actions taken since a file was opened. In this example, the drawing of a line happened to be the third step stored in the palette.

Note that the cases are different between the client call for the "historyPalette" and the server reply about the "HistoryPalette" object.

Client call 1:

<get obj="fw" name="historyPalette" />

Server reply 1:

<return>
    <obj value="11661" class="HistoryPalette">
    </obj>
</return>

Client call 2:

<func name="replaySteps" obj="11661" >
    <array  order="0">
        <int value="2" />
    </array>
</func>

Server reply 2:

		
<return>
    <string value="fw.getDocumentDOM().addNewLine({x:41.5, y:6.5}, {x:41.5, y:62.5});"></string>
</return>

In the next section, you can try implementing some XML calls to the Fireworks RPC server from Flash.

Page 3 of 4

Previous Page

Next Page