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

Quick demo

Run demo.html, in the repository.
Any problems? Consult the wiki or contact Prem .

Overview

iframes are commonly used to embed external documents into a web page (via the element’s src attribute). However, they can also be used to create an entirely new document on-the-fly, via JavaScript in the host document. This can be useful, for example, to shield the iframe’s contents from the CSS and JavaScript contained within the host document, such as when creating widgets and other kinds of modules.

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

As an example of this quirky behaviour: when an iframe element is created, and some content is put into the iframe’s document, if the iframe element is moved to a different part of the host DOM (e.g. if it is drag-and-dropped, like an iGoogle widget, or shifted to a new position via JavaScript), then the iframe’s document is completely destroyed, and its contents is lost. (Except when using Internet Explorer, but then, that has its own quirks).

AppleOfMyIframe provides a clean and simple API for manipulating iframe documents, and smooths over these cross-browser differences. The API brings iframe contents closer to the experience of manipulating <div&gt elements and other first-class citizens of the host DOM, with the 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 project wiki for details on other methods and events.