Latest News

Feb. 10th 2008

Released: JSMX v2.6.4 (Code Enhancements)

Feb. 6th 2007

Released: JSMX v2.6.3 (UTF-8 support)

Mar. 25th 2006

New! JSMX Forum (google)

About JSMX

What is JSMX?top

JSMX is an Ultra Lightweight - Language Agnostic - Ajax Framework. It is by far the easiest way to integrate Ajax into any Web Application. What separates JSMX from most other Ajax Frameworks is that the JSMX API runs entirely on the client and has no Server Side Components to install. Given this fact plus the fact that you can pass back JavaScript, XML, JSON, or WDDX makes JSMX a truly Universal Ajax API.

Originally designed for ColdFusion developers by leveraging ColdFusion's native ability to quickly build server-side generated JavaScript it became (and still is) a very efficient choice as an Ajax API for the ColdFusion Community.

But ColdFusion developers aren't the only ones who can take advantage of this small but powerful API. JSMX has been extended to support XML, JSON, and now WDDX while remaining completely backward compatible to it's original user base. With no Server Side Modules to install and with so many data-exchange options, JSMX is now the perfect choice for fast Ajax integration for ANY language.

How Does JSMX Work?top

The beauty of this API is its simplicity and its straight forward syntax. It consists of just one file (engine.js) which marshals requests between the client and the server via the http() function (which is the only function you need to know about in order to use JSMX).

We can see a diagram of the JSMX API in Figure 1 below. You simply place the engine.js file in your display page. You then write two functions within JavaScript for each call to the server, a request function and a callback function. The request function makes either a "GET" or "POST" to the server by calling the http() function (which resides in the engine.js file). The server fires off the request and returns JavaScript, XML, JSON, or WDDX to engine.js which in turn converts the response into a valid JavaScript Object/Variable and returns it to the callback function in your display template.

Figure 1JSMX Communication Diagram

Making the Requesttop

Let’s take a look at how to make requests to the server using JSMX. As mentioned above we do this via the http() function. Below is the basic syntax.

Syntax: http( verb , url , callback [, params] )

ARGUMENTS:
verb (required) "Get" or "Post"
url (required) "any server-side file (cfc, cfm, php, aspx, jsp, etc...)"
callback (required) "reference to any function you want the response passed to"
params (optional) "used to pass parameters to the server when verb = 'POST'"
A simple "GET"
  function my_request(){
	http( "GET" , "test.cfc?method=dosomething" , my_callback );
  }
  

Parameters can be passed to the server in any one of the following three formats:

As a QueryString Delimited List
  function my_request(){
	params = "attribute1=value1&attribute2=value2";
	http( "POST" , "test.cfc?method=dosomething" , my_callback , params );
  }
  
As a JavaScript Object()
  function my_request(){
	params = new Object();
	params.attribute1 = "value1";
	params.attribute2 = "value2";
	http( "POST" , "test.cfc?method=dosomething" , my_callback , params );
  }
  
As an HTML Form
function my_request(){
	params = document.myForm;
	http( "POST" , "test.cfc?method=dosomething" , my_callback , params );
  }
  

Handling the Responsetop

Now that you understand how to send requests to the server, let’s look at the response. The callback function that you reference in your request will run when the server finishes sending the response to the engine.js file. This callback function will always take one argument which will contain the response sent by the server. The response itself will differ from call to call and can be anything from a simple or complex JavaScript variable to a full XML node. Below are a couple of examples of what a callback function might look like.

Returning an Array
function my_callback(result){
  	for( var i=0 ; i < result.length ; i++ ){
	   ... logic ...
	}
  }
  
Returning an Associative Array (Structure, Hash Table, Dictionary, etc...)
function my_callback(result){
  	for( x in result ){
	   ... logic ...
	}
  }
  

As stated earlier on this page you can return your data from the server using any one of four options —JavaScript, XML, JSON, WDDX—. So, which method is best? The answer to that question depends on several factors including

  1. what server language you are using
  2. what data-exchange methodologies are you most familiar with
  3. will your server-side code be consumed by Ajax only, or will it also be consumed by other external processes such as Flash Remoting Application or a Web Service.

Below is a brief comparison of each option. You can also navigate to the examples page to get a better idea of how to use JSMX.

JavaScript (Classic Mode)

Using JSMX in Classic Mode simply means building pure JavaScript strings on the server and passing them back in your response. This is the most efficient method of returning data when using JSMX with ColdFusion because ColdFusion offers some very convenient ways of generating the JavaScript on the server. In most cases the easiest way to accomplish this is through the use of the ColdFusion function ToScript() or the ColdFusion tag <CFWDDX> (where action="cfml2js"). The ToScript() function was introduced in ColdFusion MX7 whereas the <CFWDDX> tag has been around since ColdFusion 4.0. However, both conventions can be thought of as interchangeable as they will produce the same results where JSMX is concerned.

Now, that being said, using either one of the above mentioned conventions can be an easy way of creating your JavaScript but neither convention is required by JSMX in order to take advantage of Classic Mode. You can also pass back a static JavaScript string or even manually loop over a complex data-structure to create your JavaScript. This will actually be a better solution when you want to return a simple value or a Boolean: i.e.: <cfoutput>r = true;</cfoutput>

When using one of the ColdFusion conventions for generating JavaScript Strings there are a few things to keep in mind.

  1. Booleans and numbers are treated as strings in. This means ToScript(true,"r") will produce r="true"; NOT r=true;
  2. All variables will be passed back in lowercase regardless of the case used in ColdFusion: myStruct.customerId will become mystruct.customerid
  3. Query Objects are returned as WddxRecordsets(); This is a non-native JavaScript Data Object and requires the inclusion of the wddx.js file in order to be parsed. The wddx.js file ships with ColdFusion and can be found in the [cfide root]/scripts/ directory of the ColdFusion Administrator. An example of including this exists (but has been commented out) in the JSMX engine.js file.

If you are programming in a language other then ColdFusion and want to use JSMX in Classic Mode you are welcome to do so, but this might not be the most efficient method for exchanging data. Unless your language has it’s own equivalent of the ToScript() function thereby allowing you to generate JavaScript natively you may want to consider passing back JSON.

XML

XML is probably the most standards compliant method for returning data to JSMX. It is globally understood and has built-in native support in practically every programming language you can imagine, including JavaScript. This means when an XML document is returned from the server, you can work with it directly in JavaScript with no extra parsing required. When passing XML to the JSMX engine.js file, a W3C complaint XML Document Node will be passed as the argument to your callback function. If you are comfortable with working with the XML DOM this could be a good choice for you.

One very important rule to remember when returning XML to JSMX (or any Ajax API) is to make sure the Content Type of the document returned is "text/xml" and preferably setting the charset to "utf-8". If you return a document with a content type of "text/html" the JavaScript XML object will always be "null", even if the XML itself is well formed and perfectly valid. Furthermore, setting the charset to "utf-8" will prevent special characters from causing problems.

JSON

If you are already familiar with JSON and prefer working with it over XML then you are in luck because JSMX will handle JSON with no problem. The JSMX engine will accept your JSON string, eval() it into a JavaScript Variable, and return it to your Callback Function flawlessly.

For those unfamiliar with JSON, it has been dubbed, "a lightweight alternative to XML" and rightly so. JSON or (JavaScript Object Notation) is a data-interchange format that – like XML -- allows you to parse server variables and objects into "strings" that can be passed around between servers and languages and then reassembled back into objects on the other end. Although it has not become a W3C standard yet, it is widely supported in that you can download the encode/decode classes for nearly every language you can think of. For more information on JSON or to download the Classes for your language of choice, visit www.json.org. On a final note, not only is JSON a lightweight alternative to XML but it also tends to generate the smallest footprint of all JSMX data exchange options.

WDDX

WDDX or (Web Distributed Data eXchange) is an XML based specification which allows you to exchange data. Like JSON it is not a W3C standard, but it is an open source methodology and is natively supported in ColdFusion as well as being supported by several other languages such as PHP, JSP, Pearl, Visual Basic, etc…. Of all the Data-Exchange options within JSMX, WDDX is probably the most verbose, but it does have its advantages. To learn more about WDDX or to download the SDK, visit www.openWDDX.org

One advantage worth noting applies to ColdFusion developers using ColdFusion Components. When calling a function inside of a component directly through a URL (such as how you would call it using JSMX), ColdFusion will automatically return the data to you as a WDDX packet if you return your data via the <CFRETURN> tag. This means, JSMX can consume the same functions exposed to a Flash Remoting application or Web Service already existing on your ColdFusion Server, without the need of building a "proxy" function.