Navigation¶

• Main Page
  

• Random Page
• All Pages
• Categories
• Navigation Paths
  

Search the wiki
»

Documentation

How to get started¶

The easiest way to get started is to start with one of the examples found at Demos.

By using the debug version you get access to extensive tracing which should make any debugging easier.
This trace can either be viewed by using tools like Firebug, or by creating an element with 'log' as its id. The test suite and most examples has tracing turned on.

There are two levels of integration, one where you have to upload a file (hash.html) to be hosted by the local domain, and one where you don't.
Both levels are equal as long as the postMessage transport is being used, but for older browser not supporting this, then choosing not to upload hash.html might lead to a less reliable integration.

The following examples sets up a simple HashTransport. If you instead use a BestAvailableTransport, with a complete configuration, the PostMessageTransport would be used when available, then the NameTransport, and lastly the HashTransport, and this is the preferred approach.

Option 1 (the preferred way)¶

With this approach it is guaranteed that the transport is indeed ready when the onready method is called. This requires that the supplied hash.html is present on the local domain (thought the name can be changed).

var transport = new easyXDM.transport.HashTransport({
	local: "/easyxdm/hash.html",
	remote: "http://remotedomain.com/api/"
}, function notifyWhenReady(){
	alert("the easyXDM transport is ready to be used");
});

Option 2¶

With this approach we can utilize any static file present on the local domain, like robots.txt, favicon.ico, some random image or css file. Here we need to supply a readyAfter indicating how many milliseconds we should wait before assuming that the file has been loaded and is ready to be used.

var transport = new easyXDM.transport.HashTransport({
	local: "/robots.txt",
	readyAfter: 1000,
	remote: "http://remotedomain.com/api/"
}, function notifyWhenReady(){
	alert("the easyXDM transport is ready to be used");
});

This approach is similar to the previous one, but here we utilize the hosting page as the local file. This is generally not recommended as it means loading the page twice, something that means quite a big overhead, and a risk for unexpected behaviors on dynamic pages.

if (location.hash!=="#easyxdm") {
	var transport = new easyXDM.transport.HashTransport({
		local: location.href + "#easyxdm",
		readyAfter: 1000,
		remote: "http://remotedomain.com/api/"
	}, function notifyWhenReady(){
		alert("the easyXDM transport is ready to be used");
	});
}

This is also similar to the previous one, but here we use the current instance of the hosting page as the local file. This approach also guarantees that the library is ready for interaction when firing onReady, but the backside is that it modifies the location of the current window, and this might be incompatible with other scripts running on the page, like some history managers.

var transport = new easyXDM.transport.HashTransport({
	local: window,
	remote: "http://remotedomain.com/api/"
}, function notifyWhenReady(){
	alert("the easyXDM transport is ready to be used");
});

All these approaches would work against the same code located at the remote end

var transport = new easyXDM.transport.BestAvailableTransport({
	onMessage: function(message, origin){
		alert("Received '" + message + "' from '" + origin + "'");
	}
});

And you would be able to pass a message to the remote document by doing

transport.sendMessage("this message will be sent to the remote document");

API Documentation¶

A complete API Documentation is built automatically as part of the build process.

Compatibility/requirements¶

easyXDM is designed to not conflict with any other library, and all funcitonality is contained within the easyXDM 'namespace'.

To be able to use the easyXDM.Interface class easyXDM requires a serializer, and it will default to trying to use the global JSON object.

In browsers where this is not available (older browsers), one must be supplied, for instance by including Douglas Crockfords json2 library, or by specifying a custom serializer using your library of choises capabilities.

Gotchas¶

PrototypeJs¶

PrototypeJs extends the native Array's prototype with the toJSON method, and this breaks the native HTML5 JSON objects serializer. To work around this PrototypeJs users should supply a serializer property on the configuration for easyXDM.Interface, mimicking the JSON objects stringify and parse methods.

 
{
	....
	serializer:{
		stringify: Object.toJSON,
	        parse: function(string){
			return string.evalJSON();
		}
	},
	...
}