This article demonstrates how to use Allaire's XML serialization technique, Web Distributed Data eXchange (WDDX [described at www.wddx.org]), to transfer CFML data structures from the server to the client, and into JavaScript and back. Generally WDDX's approach is to interchange data of all types (including complex data types such as nested structures, n-dimensional arrays, record sets, or even binary data) between different programming platforms.

Overview of WDDX
WDDX is simply a way of describing data in a text-based form. Technically it's an XML DTD (Document Type Definition) of XML tags that describes simple and complex data types, such as the contents of a nested structure. Many major Web programming platforms are adopting WDDX; it's currently available in CFML, Java, ASP, PHP, and Perl for the server-sided, platform-independent exchange of data. In addition to transferring data between different server platforms, WDDX is also available in client-sided programming environments such as JavaScript. This article focuses on the latter, but first I'd like to continue with the WDDX overview.

You can use WDDX to serialize some ColdFusion data into a WDDX package:

The result: a WDDX package that represents the content of #myComplexArray# as an XML string is stored in #my- WddxPackage#. It's possible to deliver this WDDX package over the Web using text-based protocols, such as HTTP or SMTP, since the WDDX string is XML and therefore plain vanilla text. This is even true when serializing binary data, which automatically escapes and unescapes to a BinHex64 text representation.

This mechanism allows us to interchange (syndicate) data between different Web applications (even when they're written in different languages). Basically the CFML developer doesn't need to think about the XML stuff, since serialization and deserialization are encapsulated into the tag (or the WDDX-SDK on other language platforms). Deserialization from a WDDX package (obtained from a or access, for example) back into a CFML data type is as easy as this:

The WDDX package that's held in #myWddxPackage# is now deserialized into the CFML variable #myNewData#.

Transferring WDDX Between Server and Client
To provide you with a nice example of how to use WDDX on the client with JavaScript and how to transfer data back to the server, I decided to implement an offline browser for ini files. ini files are simply text files that contain sections and entry-value pairs of configuration settings for some applications. To learn more about the ini style see the CF Studio Help on ColdFusion's SetProfileString() and GetProfileString() functions. I also describe how to grab such a file into WDDX and transfer it as an array of structures to the client where it can be viewed, edited, and extended offline, as well as how to commit these changes back to the server in one step for the whole data set. This example enables us to do offline browsing and editing of ini files residing on the server.

Note that this functionality can also be implemented on a stateful online connection with a step-based editing process involving several action pages (such as loading all the sections, the entries of a specific section, and its value, and writing each one back in its own step). However, the goal of this article is to introduce client-sided usage of WDDX using the ini file as an example of structured data that can be transferred at once to the client and back.

Let's look at what our example does. After entering a server-sided path in an ini file (you can also use the demo ini file provided with this example), you'll see two list boxes and an input field (see Figure 1). In the first list box choose a section within that ini file; in the second, a specific entry within that section while the text field shows the value of the selected entry. Also, you can change the values using the button "Update Value" or add entries or even whole new sections using the "New Entry" and "New Section" buttons (see Figure 2). This is all done on the client using JavaScript. There's no backprocessing to the server, not even for adding new sections and entries. Selecting the "Store data back into ini file on server" button immediately sends all data, including the changes and additions, to the server. WDDX serializes the data (see Figure 3), which results in an update of the ini file.

Theoretically you could connect to your server, open an ini file within the offline browser, close the online connection (go offline), change and/or add data to the ini file browser, and finally go online again and commit all changes at once to your server. This is the concept of a simple offline data browser. Note that we're not dealing with concurrent updates, deletes, commits, and rollback statements here, since the goal of this article is to show you how to use WDDX to transfer complex data types between the server and client (and back), not how to implement a perfect offline data browser, which is clearly out of this article's scope. For a nice offline data browser with single-record updating and other interesting features, I recommend Ben Forta's ( www.forta.com) book Advanced Cold-Fusion Application Development (Que).

Looking at the Code Details
So far I've explained the concept of using WDDX on the client, but to make this article worth reading it's time to introduce and explain the code behind it. First I'd like to demonstrate how to transfer a CFML array to JavaScript with only a few lines of code:

Before using all the WDDX objects (for example, the WddxRecordSet or WddxSerializer object) within JavaScript, you have to include the above line to import the WDDX SDK for JavaScript in your page. If you use "/" CF mapping, you don't have to worry about which path ColdFusion used to place the wddx.js file. After the WDDX-JavaScript SDK is imported to your page, you can transfer any CFML variables directly into JavaScript. Theoretically this is done with two invocations of the tag, as you first have to serialize the CFML data with to WDDX, and then deserialize it with into a client-sided JavaScript variable. However, as Allaire's intention is to minimize any coding overhead and to make things as nice and easy as possible, they created a shortcut to this process that resulted in only a single invocation of

These few lines transfer a complex CFML array (held in #myCfArray#) into a JavaScript array (stored in myJsArray) for client-side usage. To test the code, the length of the JavaScript array is shown in an alert popup box. You can now access all the array elements within JavaScript using myJsArray[index]. But be aware that in JavaScript array elements start at index 0, whereas in CFML they start at index 1. It's also possible to transfer other complex data types, such as record sets or structures, to the client that way. As we're using an array of structures to hold the ini file's sections, note that when accessing structures within JavaScript (coming through WDDX) all keys have to be written in lowercase:

After this basic WDDX-JavaScript introduction, let's look at the source files for this article. (They can be found on the CFDJ Web site, www.sys-con.com/coldfusion/sourcec.cfm.) Although the example consists of four files (index.cfm, top.cfm, main.cfm, and update.cfm), I'll explain only two of them (main.cfm and update.cfm) since the other two open up only the frame set (Listing 1: index.cfm) and the filename entering form (Listing 2: top.cfm).

The file main.cfm (see Listing 3) is invoked after entering the path and filename of the ini file, which is submitted as FORM.filename. After checking if the file really exists on the server, its content is read completely and transferred into an array of structures through some string-parsing code. This code only reads the ini file structure into a data type that represents the sections and entries of the ini file and has nothing to do with the actual topic of this article. The code is necessary to dynamically read the ini file content and can also be encapsulated into a custom tag, so you don't have to worry about it when you're working with WDDX and JavaScript. I won't discuss this parsing code here but will continue the in-depth analysis of the actual WDDX and JavaScript code in main.cfm.

After the ini file has been parsed, its content is available as an array of structures that holds each section, its name, a nested array of structures for each entry, and its corresponding value within the section. This is all stored in the CFML #Profiles# variable, which is transferred through WDDX to the JavaScript ProfilesArray variable. Next you'll see eight JavaScript functions that handle the data on the client side, including the dynamic representation logic and the adding and/or changing of the values, entries, and sections, which I'll discuss in detail later.

In the HTML code there's a

• Figure 1
• Figure 2
• Figure 3