Home

AppleOfMyIframe is a jQuery Plugin. It aims to provide a simple JavaScript API for the manipulation of iframe elements and their contents.

• by Premasagar Rose
  • premasagar.com / dharmafly.com
• contributors:
  • Alastair James, Jonathan Lister
• MIT license
• 3KB minified & gzipped

Overview

iframes are commonly used to embed external documents in a web page (via the element’s src attribute). However, they are rarely used for another purpose: to create a brand new document on-the-fly, via JavaScript within a host document. This can be useful, for example, to protect the iframe document’s contents from the CSS and JavaScript contained within the host document – for example, when creating widgets and other kinds of modular user interfaces.

The standard JavaScript API for achieving this is pretty convoluted and fragile, and the behaviour of iframe documents can vary wildly between different browsers. As a result, it has been tricky to take advantage of the potential for this technique.

As an example of this quirky behaviour: when an iframe element is created, and a document created within it, and some content put into the document’s body, if the iframe element is moved to a different part of the host document’s DOM (e.g. if it is drag-and-dropped, or shifted to a new position), then the iframe’s document is completely destroyed, and its contents is lost. That is, except in Interet Explorer, which has its own quirks.

AppleOfMyIframe aims to smooth over all these differences between browsers, and bring iframe documents closer to being a first-class citizen in the host document’s DOM. All with a jQuery style of simple, intuitive, chainable methods.

jQuery Methods

The plugin creates two core methods:

jQuery.iframe()

This is used to create a new iframe element, wrapped inside a standard jQuery collection – i.e. $('<iframe></iframe>') – that has been extended with some additional methods.

jQuery(elem).intoIframe()

This is used to replace elements in the host document with an iframe, and inject those replaced elements into the iframe’s body.

Example usage

All arguments to $.iframe() are optional.

1. Create an iframe with some body contents, and add it to the document:

$.iframe('<p>hello world</p>') // Add contents to the iframe's body
        .appendTo('body'); // Use any jQuery method here

2. Insert HTML into the iframe’s head and body:

$.iframe(
    '<style>background-color:green;</style>',
    '<p>hello world</p>'
)
    .appendTo('body');

3. Supply various options:

$.iframe(
    '<p>hello world</p>',
    { // Options object - more options than shown here are available
        title:"Jimbob", // document title
        doctype:5, // HTML5 doctype
        autoheight:true, // Automatically resize iframe height, when content is added or removed from the iframe's body
        autowidth:false // As above, for the iframe width
    }
)
    .appendTo('body');

4. Supply a callback function, for when the iframe first loads:

$.iframe(
    '<p>hello world</p>', // This argument could be omitted, and instead added to the callback function
    function(){ // Callback function
        alert('iframe has loaded');
        this.body('<p>hello again</p>'); // Append contents to the body
    }
)
    .appendTo('body');

5. Inject elements that are already in the host document into an iframe:

$('<p>Hello world</p>') // A standard jQuery collection
    .appendTo('body')
    .intoIframe(); // Move the collection into the body of an iframe, and insert the iframe into the host document

See the API pages in the wiki for details on other methods and events.