Beautiful, seamless iframes with seamless.js

A seamless iframe makes it so that visitors are unable to distinguish between content within the iframe and content beside the iframe. Seamless.js is a jQuery library that makes working with iframes easy by doing all the seamless stuff for you automatically. Stuff like...

Automatically adds 'seamless' attributes to an iframe.
Easy communication between parent page and iframe page.
Auto-resizing the iframe to fit the contents of the child page.
Loading indicator when the child page is loading.
Auto failsafe to open iframe in separate window in case of error.
Inject CSS styles into the child pages.
Easily manage multiple iframes on the same page.
Allow the child page to pop out of the parent page.

Definitions

Throughout this document you will see the following definitions. It is important that you know what they mean.

Parent Page - The page that contains the iframe(s).
Child Page - The page that the iframe is referencing, hence it is a child page of the parent page.

How to use:

First, you will need to include this library in both the Parent and Child pages.

Setup

Parent Page Header

Assuming you have this library in a seamless directory, you will need to include the following in the Parent page.

<script src="seamless/build/seamless.parent.min.js"></script>

Child Page Header

You will now need to include the child version in all the child pages.

<script src="seamless/build/seamless.child.min.js"></script>

Connect

Create Parent Seamless IFrame

You can now use the following code within the Parent Page to turn your iframes into seamless iframes.

<script type="text/javascript">
  $(function() {

    // Turns the iframe into a seamless iframe.
    $('#myiframe').seamless();
  });
</script>

<iframe id="myiframe" src="childpage.html"></iframe>

You can also pass in options to this jQuery library like so...

$('#myiframe').seamless({
  loading: 'I am loading!!!!'
});

The following parameters are accepted.

loading - (string) The text to show when the child page is loading.
spinner - (string) The url of the spinner GIF that is shown when the child page is loading.
styles - (array of strings) The styles to inject into the child page.
fallback - (boolean) If the fallback functionality is enabled. Default true.
fallbackParams - (string) Additional query params to attach to the fallback window when it is opened.
fallbackText - (string) A message to show below the child iframe to offer assistance if they are having problems.
fallbackLinkText - (string) The string to show within the 'Click here' link to open the fallback window.
fallbackLinkAfter - (string) Text to add after the fallbackLinkText link.
fallbackStyles - (array) An array of string styles to add to the fallback text when something bad happens.

Connect Child Page to Parent Page

Within the Child Page, you will need to now add the following code to connect the Child Page to the parent page.

<script type="text/javascript">

  // Connect to the parent page.
  $.seamless.connect({
    url: 'index.html'
  });
</script>

You can also pass in parameters to this like so...

$.seamless.connect({
  url: 'index.html',
  container: 'div.content'
});

The following parameters are accepted.

url - REQUIRED (string) The url of the parent page to connect to.
container - (string) The container for the main content on the page which determines the height of the page.
update - (int) The milliseconds that an update is created from the child to the parent.
allowStyleInjection - (bool) If this page should allow injected styles.

Communicate

Another big part of this library is that it enables communication to both the Child and Parent pages. This is done through the send and receive commands.

Communicate to the Child page from the Parent page.

To communicate to the child page from the parent page, you simply need to store the jQuery object that you create. You can then use it to send and receive events to the child, like so.

var child = $('#myiframe').seamless();

// Send a message
child.send({
  myparam: 'This is anything you want it to be...'
});

// Receive a message
child.receive(function(data, event) {

  // Print out the data that was received.
  console.log(data);
});

Communicate to the Parent page from the Child page.

Inversely, you can easily communicate to the parent page from the child page like so...

var parent = $.seamless.connect({
  url: 'index.html'
});

// Send a message
parent.send({
  myparam: 'This is anything you want it to be...'
});

// Receive a message
parent.receive(function(data, event) {

  // Print out the data that was received.
  console.log(data);
});

Send Responses

The last way to communicate is through a 'send' response, where you can receive a response from a send command. To do this, you simply need to pass along an object to the send method with two parameters, data to contain the data, and complete to be called when the resonse has been made. Then, within a receive command, you simply return the data you wish to send as the response. The code below shows this best...

Parent Page

var child = $('#myiframe').seamless();

child.send({
  data: {
    mydata: 'This is a message'
  },
  complete: function(data) {

    // 'data' is what was returned from the child 'receive' function.
    console.log(data);
  }
});

Child Page

var parent = $.seamless.connect({
  url: 'index.html'
});

// Receive a message
parent.receive(function(data, event) {

  // Print out the data that was received.
  console.log(data);

  // Now return something for the response.
  return {
    myresponse: "I'm listening..."
  };
});

YusufBesim / seamless.js