root / dojox / trunk / io / proxy / README

-------------------------------------------------------------------------------
Project Name
-------------------------------------------------------------------------------
Version 0.6
Release date: 01/31/2008
-------------------------------------------------------------------------------
Project state:
experimental
-------------------------------------------------------------------------------
Credits
        James Burke (jburke@dojotoolkit.org)
-------------------------------------------------------------------------------
Project description

The XHR IFrame Proxy (xip) allows you to do cross-domain XMLHttpRequests (XHRs).
It works by using two iframes, one your domain (xip_client.html), one on the 
other domain (xip_server.html). They use fragment IDs in the iframe URLs to pass
messages to each other. The xip.js file defines dojox.io.proxy.xip. This module
intercepts XHR calls made by the Dojo XHR methods (dojo.xhr* methods). The module
returns a facade object that acts like an XHR object. Once send is called on the
facade, the facade's data is serialized, given to xip_client.html. xip_client.html
then passes the serialized data to xip_server.html by changing xip_server.html's
URL fragment ID (the #xxxx part of an URL). xip_server.html deserializes the
message fragments, and does an XHR call, gets the response, and serializes the
data. The serialized data is then passed back to xip_client.html by changing
xip_client.html's fragment ID. Then the response is deserialized and used as
the response inside the facade XHR object that was created by dojox.io.proxy.xip.
-------------------------------------------------------------------------------
Dependencies:

xip.js: Dojo Core, dojox.data.dom
xip_client.html: none
xip_server.html: none (but see Additional Notes section)
-------------------------------------------------------------------------------
Documentation

There is some documentation that applies to the Dojo 0.4.x version of these files:
http://dojotoolkit.org/book/dojo-book-0-4/part-5-connecting-pieces/i-o/cross-domain-xmlhttprequest-using-iframe-proxy

The general theory still applies to this code, but the specifics are different
for the Dojo 0.9+ codebase. Doc updates hopefully after the basic code is ported.

The current implementation destroys the iframes used for a request after the request
completes. This seems to cause a memory leak, particularly in IE. So, it is not
suited for doing polling cross-domain requests.
-------------------------------------------------------------------------------
Installation instructions

Grab the following from the Dojox SVN Repository:
http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/io/proxy/xip.js
http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/io/proxy/xip_client.html

Install into the following directory structure:
/dojox/io/proxy/

...which should be at the same level as your Dojo checkout.

Grab the following from the Dojox SVN Repository:
http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/io/proxy/xip_server.html

and install it on the domain that you want to allow receiving cross-domain
requests. Be sure to read the documentation, the Additional Notes below, and
the in-file comments.
-------------------------------------------------------------------------------
Additional Notes

xip_client.html and xip_server.html do not work right away. You need to uncomment
out the script tags in the files. Additionally, xip_server.html requires a JS file,
isAllowed.js, to be defined. See the notes in xip_server.html for more informaiton.

XDOMAIN BUILD INSTRUCTIONS:
The dojox.io.proxy module requires some setup to use with an xdomain build.
The xip_client.html file has to be served from the same domain as your web page.
It cannot be served from the domain that has the xdomain build. Download xip_client.html
and install it on your server. Then set djConfig.xipClientUrl to the local path
of xip_client.html (just use a path, not a whole URL, since it will be on the same
domain as the page). The path to the file should be the path relative to the web
page that is using dojox.io.proxy.