How jQuery.windowName.plugin works

I wanted to share a bit on how the window.name transport plugin for jQuery works, so developers in the crowd can find their way around the code and that you can understand what is going on and where can it break.

How it works

The plugin hijacks the $.ajax function and will do its magic when you’re POSTing to a foreign (domain not same as domain of document) domain or you specify settings.windowname to force it. If these conditions are not met it will use the default ajax function to create the request.

The script first creates an iframe that will be the target of its request. If the request is of type GET it will open the location with the specified data as querystring in the iframe, if it’s a POST request it will first create a form with hidden fields that represent all data being sent. To allow sending of method, target, action and submit some magic is done (those override some important form object stuff) after which the form is posted to the iframe. This is readyState 2.

After the posted file is loaded (meaning it should have now set the window.name) an onload event is fired that loads an empty local file into the iframe. The empty local (same domain as the page) file can be set in the settings (settings.localfile) – if it isn’t the script will first try loading /robots.txt and /crossdomain.xml (two files commonly found in the root that are small) and if both fail it will load the page it’s on. All this is done only on IE where 404 doesn’t count as local. This is readyState 3.

When the local file is loaded and it is surely local we can read the text from the window.name. If it’s a string and it isn’t our default we set status to 200 and set the string as responseText, otherwise we set a 502 status. We can now cleanup which means removing the form, the iframe and all references we created in the global space.

The whole thing is written in such a manner that it will return a fully qualified XMLHttpRequest object with all methods and properties. You can abort the request and it will cancel loading and clean up, you can access readyState, responseText and everything else you’d do to an XHR object. It does however not implement features that cannot be used due to the fact that it’s an ordinary form submit – setting headers and such.

Interesting use

I’ve found that window.name transport is ideal for saving files – you can force the window.name transport to a url that will return a file with an Content-disposition: attachment; header. When the file loads you’ll get a popup to save it and the frame will disappear automatically. It’s even more convenient if you’re creating the file with a POST request.

Download

You can download the plugin here or you can go to the jQuery plugins page to get it

Reblog this post [with Zemanta]

Leave a Reply