Exploring the RPC Debugger panel

In conjunction with this article, I have created a new extension for Fireworks that helps debug XML commands that are destined for the RPC server. Below are instructions for installing the panel, followed by a description of how to use the panel and its features.

To install the RPC Debugger panel extension:

1. Download the RPC Server Debugger ZIP file linked to at the beginning of Part 2 and extract the MXP file inside it.
2. Install the debugger by double-clicking the FW_RPCServer_Debugger.mxp file. You must have the Extension Manager for automatic installation.
3. To open the debugger, launch Fireworks and then select "RPC Debugger" from the Window menu.

Using the panel requires only two steps:

1. Type single XML client calls into the Input (top) window of the debugger.
2. Click the Test button.

The debugger sends the call to Fireworks. The Output section (bottom text area) of the debugger returns your command, along with its RPC server reply. If the XML call is valid, you will be able to watch any changes to Fireworks objects as they happen.

Although each call should be typed and tested separately, sequences of calls can be collected in the Output area to help record server reply values, such as object IDs. The XML Debugger can then help you understand how to access objects effectively in Fireworks for later RPC server calls.

For instance, if you want to test the XML code for opening a new document, type <func name="createDocument" obj="fw" /> and then click the Test button to send the code through the debugger. This code sample opens a new document in Fireworks with default settings. The panel writes your XML client call and any XML RPC server reply in the Output window of the panel (see Figure 1).

Figure 1. RPC Debugger output of a sample XML client call to open a new document

Note: Objects ID numbers may be different for each file, type of object, and RPC server session. The IDs you receive when testing code in the debugger will likely be different than the ID numbers you see in the sample figures.

You should erase or type over old calls in the Input window of the debugger when you are ready to try new ones. Information in the Output window does not have to be erased to try a new call, and may be helpful to building future calls. This enables you to look up IDs and other values you may need, or check previous mistakes. When you are ready to clear the Output window, just click the Clear Replies button at the bottom of the debugger.

The next example uses the information in the Output window and introduces the Parse for Value button to try a new XML call. If you want to access the width of the new document object programmatically, try a <get> call using the ID number in the value attribute of the RPC server's return tag.

Click the Parse for Value icon (the pink upward arrow) to insert the value of the last RPC server reply automatically, instead of copying and pasting it—or manually typing it—into the next call.

To access the document width of the previous example:

• Delete the first <func> call that is in the Input window.
• Type <get name="width" obj="" />
• Insert your cursor between the obj attribute quotes.
• Click the Parse for Value icon.

The information from the value attribute of the last RPC server reply (in this case, "9727") is inserted where your cursor is, thus finishing the call.

Testing this call returns the width of the new document in a new RPC server reply (see Figure 2). This sample returns the width of 16, meaning 16 pixels. Clicking the Parse for Value icon for a subsequent call inserts the value 16 in a new XML trial.

Figure 2. Debugger results from testing a second XML client call

If the last RPC server reply contains an error code, or does not contain a value, then clicking the Parse for Value icon inserts the word "undefined."

The RPC Debugger can help catch syntax errors when XML calls are incorrect. For instance, Figure 3 shows a sample call that produces a reply with an error code.

Figure 3. Result of an XML client call that recieves an errorr from the RPC server

You can easily access error code descriptions by clicking the Error Codes icon (yellow triangle). A window with a list of error codes appears inside the panel (see Figure 4). Click the red Close button at the bottom of the error list to hide it.

Figure 4. RPC server error codes

In the sample code, the RPC server reply indicates an error code of 4. Looking up 4 in the error codes table indicates that HistoryPalette, as typed in this example, is not a property of the Fireworks object. Properties are case-sensitive, and by looking up the properties of the Fireworks object in the Extending Fireworks 8 document or the Fireworks Help menu, you will see that "history" should be lowercase. Retesting with <get obj="fw" name="historyPalette" /> should give a non-error reply in the Output window.

Note: Because the debugger is running inside Fireworks, it is not using an actual socket connection. The debugger is simulating only the socket connection and disconnection every time the Test button is clicked. For this reason, the <release /> node is the only node that cannot be truly tested with the debugger. These are not valid from within the Fireworks application.

The RPC Debugger offers a way to test XML calls for the RPC server within the Fireworks application. But the Fireworks RPC server's advantage is its ability to communicate with applications running outside Fireworks, such as from a SWF playing in a browser. Any language that can create a socket connection and send text over the socket can potentially communicate with the RPC server, and thus access functionality in Fireworks. The next section provides just one example of how this could be achieved, using an ASP.NET web page.

Page 2 of 5

Previous Page

Next Page