burst.io.IframeURIRequest Class Reference

Inheritance diagram for burst.io.IframeURIRequest:

List of all members.

---

Detailed Description

Subclass of AbstractURIRequest based on a hidden iframe.

This is not needed in environments supporting XMLHttpRequest; in that case use XmlHttpURIRequest .

Implementation Issues

This implementation relies on the primitive (and stateless) utility functions for iframes in burst.xml.HtmlUtil .

There are several considerations:

• "display: none" is mildly preferable over "visibility: hidden; width: 0; height: 0"), as "display: none" is definitively not going to affect layout. But NS7 and Moz 1.0 will not submit form data or load an iframe src if it has "display: none":
  • Grant Wagner http://groups.google.com/groups?selm=3CDC2D02.66C9E67D%40agricoreunited.com
  • Martin Honnen http://groups.google.com/groups?selm=3D9C7879.4050708%40t-online.de
  This is fixed in Moz 1.1. In my experience, Opera 7 has the same bug, not yet fixed.

• IE5.0 PC does not support createElement("iframe"). Instead it must be done via document.write or innerHTML.

• Mozilla does not support modification of iframe content if the iframe is made by createElement: http://bugzilla.mozilla.org/show_bug.cgi?id=22681

• Load completion is difficult to detect. In theory, an onload handler could be attached to:
  • The body of the parent document, above the iframe element.
    I do not believe this is reliable for iframe children created after the parent document has completed loading, and regardless it is messy to try to successfully wrap any existing body onload handlers.
  • The iframe element itself (in the parent document).
    In IE5.0 PC, the iframe element onload handler is not called: http://support.microsoft.com/default.aspx?scid=KB;en-us;q239638 According to Martin Honnen (http://groups.google.com/groups?selm=3C5BC731.9070803%40t-online.de ) onload will work on the iframe element in IE5.5 and NS6.2 (at least for 'http:' protocol, but perhaps not 'file:')

  • The body element inside the iframe's contents.
    Any example might be onload='parent.done()'. This would require cooperation from the response being returned (unless the Martin Honnen nested iframe hack is used, about which more below).

• In HTTPS, IE requires an initial src attribute or it will give a security warning: http://groups.google.com/groups?selm=Xns91EB70C0BC81Fjocke4uhotmailcom%40130.133.1.4

• Opera 6 (perhaps others), does not allow later change of an iframe src if it isn't set originally: Grant Wagner, http://groups.google.com/groups?selm=3D2DC0BD.8BFEFFCC%40agricoreunited.com

• It is important to use location.replace() rather than other means of setting/changing the iframe's source, to avoid putting the url on the browser's history (and hence affecting the back button and refresh).

• A single iframe can't be used to achieve more than one request at a time. Solutions include queuing through a single iframe serially, maintaining a pool of iframes, or creating a new iframe for each request.

Antecedents

The basic principle is straightforward and has been done many times before. However, the tricky implementation issues above are often not all dealt with, or are not dealt with well.

Furthermore, rampant confusion abounds which conflates iframe element objects, iframe window objects, and iframe document objects.

Some implementations that bear examination are listed below. I note here only some salient distinguishing characteristics, without detailing any criticisms.

• Brent Ashley, JSRS, http://www.ashleyit.com/rs/jsrs/test.htm
  
  • Puts invisible iframe inside span inside body.
  • Relies on returned html to have a body onload which calls a callback function window.parent.jsrsLoaded
  • does pooling.

• Alex Russell, http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/netwindows/netWindows/winScripts/environ_core.js?rev=1.182&content-type=text/vnd.viewcvs-markup
  
  • relies on returned content to use load_page_callback.js
  • deals with createElement("iframe") not working in IE5.0 PC
  • maintains a queue of loading requests to go through a single iframe channel.

• Martin Honnen, http://www.faqts.com/knowledge_base/view.phtml/aid/1272/fid/128/lang/en and http://www.faqts.com/knowledge_base/view.phtml/aid/6773/fid/128/lang/ and http://groups.google.com/groups?selm=38F0C265.E877706A%40t-online.de
  
  • First creates an iframe inside the body. Then cleverly writes html into that iframe which itself has an iframe. The body element sandwich'd in between has an onload event to communicate up.

• Eric Costello, http://www.oreillynet.com/pub/a/javascript/2002/02/08/iframe.html and (with corrections) http://developer.apple.com/internet/javascript/iframe.html#revisionnotes and http://www.oreillynet.com/cs/user/view/cs_msg/8092
  
  • corrections deal with IE5 PC.
  • discusses the importance of location.replace()

• Steve Thames, http://www.faqts.com/knowledge_base/view.phtml/aid/7418
  
  • On NN6, adds load event handler to iframe element.
  • On IE5, polls with setTimeout until readyState is set.

Our Approach

Our approach is:

• In environments that support it, we attach an onload handler to the iframe element (IE5.5+ and NS6.2+).

• In environments that do not support iframe element onload, we use the Martin Honnen nested iframe trick. (An alternative would be polling the readyState, but that is IE-specific and is not as well-performing. Another alternative would be relying on the response to contain javascript to make a callback, but we want to avoid that.)

• We maintain a pool of available hidden iframe children.

iframe element, window, and document

This is a cross-platform morass.

For getting an iframe window from the id or name attribute value of the iframe element:

• both Moz and IE can retrieve a frame by its name attribute:

  
     var iframe_win = window.frames[nameval]
  

  Note that IE has both document.frames and window.frames; Moz has only window.frames.

• IE but not Moz can retrieve a frame by its id attribute:

  
     var iframe_win = window.frames[idval]
  

• both Moz and IE can retrieve a frame by numerical index:

  
     var iframe_win = window.frames[index]
  

  A person could just assume that the last frame is the desired one:

  
     var iframe_win = window.frames[window.frames.length - 1]
  

• If the iframe element is available, it is possible to retrieve the iframe window object via burst.xml.HtmlUtil.iframeContentWindow(iframe_el).

To get the element given the id or name attribute value:

• Moz and IE 5.5 PC (not IE 5.0 or IE Mac) can retrieve the iframe element via getElementById

  
      var iframe_el = document.getElementById(idval);
  

  (IE4+ has document.all[idval] and document.all[nameval], with document.all[nameval] being an Array if there are multiple ones.)

• Moz and IE 5.? can retrieve by getElementsByName:

  
      var iframe_el = document.getElementsByName(nameval)[0]
  

  (recall that IE considers both ID and NAME for getElementsByName, and according to PPK http://www.xs4all.nl/~ppk/js/version5oud.html it doesn't cover all elements. Moz and W3 cover all elements, and consider only name.)

• Moz and IE 5.? can retrieve by getElementsByTagName and numerical index:

  
      var iframe_el = document.getElementsByTagName('IFRAME')[index]
  

  PPK says getElementsByTagName does not work on IE5 PC: http://www.xs4all.nl/~ppk/js/version5oud.html

For going from iframe element to iframe window, see burst.xml.HtmlUtil.iframeContentWindow(iframe_el).

For going from iframe element to iframe document, see burst.xml.HtmlUtil.iframeContentDocument(iframe_el).

Public Member Functions
	IframeURIRequest (Node iframe_el)
	Construct a wrapper object around an iframe Node channel.
Static Public Member Functions
IframeURIRequest	getInstance ()
	Class method to get an instance.
Protected Member Functions
void	destroy ()
	remove the iframe Element from its parent Node, and eliminate any pointers we have.
Static Protected Member Functions
void	register (BU_IframeURIRequest instance)
	Registers the just-created BU_IframeURIRequest instance in the global registry.
BU_IframeURIRequest	acquire ()
	Reconstitute an instance from the pool.
void	release (BU_IframeURIRequest instance)
	Class method called when load callbacks are done.

---

Constructor & Destructor Documentation

burst.io.IframeURIRequest.IframeURIRequest (  Node  iframe_el  )

Construct a wrapper object around an iframe Node channel. You generally want to call the class method getInstance() instead of the constructor directly, so that you can take advantage of instance pooling. If you happen to already have an iframe element on the page that is intended to be used for communication, that may be provided. The actual iframe element is created only on demand; it may already have one if this instance came from the pool. Any constructed object is automatically added to the pool whenever it is done being used. All instances have a state variable which is one of: 'uninitialized' (after constructor call) 'loading' (just after entry to load()) 'complete' (when load() callback first comes back) 'deleted' (when all load() callbacks have finished, and it is put back into the pool) (This mimics microsoft readyState: http://msdn.microsoft.com/workshop/author/dhtml/reference/properties/readystate_1.asp except for the addition of 'deleted'). Parameters: iframe_el  Optional. An iframe element for use. It must have a (unique) name attribute.

---

Member Function Documentation

BU_IframeURIRequest burst.io.IframeURIRequest.acquire (   )  [static, protected]

Reconstitute an instance from the pool. If none are available returns a false value. Sets state from 'deleted' to 'uninitialized'.

void burst.io.IframeURIRequest.destroy (   )  [protected]

remove the iframe Element from its parent Node, and eliminate any pointers we have. used if we are doing pooling.

IframeURIRequest burst.io.IframeURIRequest.getInstance (   )  [static]

Class method to get an instance. This is preferable to calling the constructor directly.

void burst.io.IframeURIRequest.release (  BU_IframeURIRequest  instance  )  [static, protected]

Class method called when load callbacks are done. Sets state to 'deleted'.

---

The documentation for this class was generated from the following file:

• io/IframeURIRequest.java

---