Classes

Namespace $sf.lib.dom.iframes

$sf.lib.dom.iframes Defines helper functions for dealing specifically with IFRAME tags, which is key to SafeFrames tech in a browser.

Method Summary

Method Detail

  • <static> {HTMLElement} $sf.lib.dom.iframes.clone(el, attrs, cssText, cb, xmsgCB)
    Clones an iframe. . . This code creates / clones iframe tags in a very specific way to ensure both optimal performance and stability. We use string buffers to build markup internally, which is typically faster than using all DOM APIs. Also we allow the usage of the "name" attribute as a data pipeline, which in turn allows for synchronous downward x-domain messaging.
    Parameters:
    {HTMLElement/String} el
    An iframe element or id of an iframe element to clone
    {Object} attrs Optional
    A hash map of other attributes to be set on the iframe. Do not set style properties for the frame here, see the next argument for that.
    {String} cssText Optional
    The style string (as in what you would use in HTML markup, e.g. "background-color:red;border:solid 3px blue;"), to use for this iframe
    {Function} cb Optional
    An optional callback function to specify for when the iframe loads.
    {Function} xmsgCB Optional
    An optional call back for receiving messages from the iframe
    Returns:
    {HTMLElement} the iframe node if succesfully created or NULL. Note that this does not insert the iframe into the document for you. . .
  • <static> {HTMLElement} $sf.lib.dom.iframes.make(attrs, cssText, cb, xmsgCB)
    Make a new iframe
    Parameters:
    {Object} attrs
    A hash map of other attributes to be set on the iframe. Do not set style properties for the frame here, see the next argument for that.
    {String} cssText Optional
    The style string (as in what you would use in HTML markup, e.g. "background-color:red;border:solid 3px blue;"), to use for this iframe
    {Function} cb Optional
    An callback function to specify for when the iframe loads.
    {Function} xmsgCB Optional
    An call back for receiving messages from the iframe
    Returns:
    {HTMLElement} the iframe node if succesfully created or NULL. Note that this does not insert the iframe into the document for you. . .
  • <static> {HTMLElement} $sf.lib.dom.iframes.replace(attrs, cssText, parRef, cb, xmsgCB)
    A method to insert or replace an HTML tag with an IFRAME tag, with a new URL and attributes. Used for 3 reasons:
    1. It avoids click sounds on IE.
    2. It allows always resetting the window.name property of the iframes underlying HTMLWindow object, unforunately IE will not let you set this attribute on a clone.
    3. It ensures that event handlers in the underlying document for unloading are executed.
    4. Changing the src attribute directly will result in a browser history update, which we do not want.
    We could just change location.href property or call location.replace, however that is not always possible since the frame could be x-domain.
    Parameters:
    {Object} attrs
    A hash map of other attributes to be set on the iframe. Do not set style properties for the frame here, see the next argument for that.
    {String} cssText Optional
    The style string (as in what you would use in HTML markup, e.g. "background-color:red;border:solid 3px blue;"), to use for this iframe
    {HTMLElement|String} parRef Optional
    An parent element or parent element id, to be used only if a new iframe is created, the iframe will be append to that parent, if not specified document body is used
    {Function} cb Optional
    An callback function to specify for when the iframe loads.
    {Function} xmsgCB Optional
    An call back for receiving messages from the iframe
    Returns:
    {HTMLElement} a reference to the newly created iframe element if successfully inserted, otherwise NULL.
  • <static> {HTMLWindow} $sf.lib.dom.iframes.view(el)
    Retrieve the window reference inside of an IFRAME. Not to be confused with $sf.lib.dom.view which returns the parent window reference of an element. Note that even in cross-domain scenarios, you are supposed to able to get access to the window reference. In a cross-domain scenario, you would not be able to then acesss most properties / methods / objects of that window, but the reference itself is allowed.
    Parameters:
    {HTMLElement} el
    The iframe element to safely get back the window
    Returns:
    {HTMLWindow} the window reference inside the iframe.