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.
- Creates a fallback for child pages that block cross-origin cookies. (Safari)
- Allow the child page to pop out of the parent page.
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.
First, you will need to include this library in both the Parent and Child pages.
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>
You will now need to include the child version in all the child pages.
<script src="seamless/build/seamless.child.min.js"></script>
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 - The text to show when the child page is loading.
- type: string
- required: false
- default: 'Loading ...'
- spinner - The url of the spinner GIF that is shown when the child page is loading.
- type: string
- required: false
- default: 'http://www.travistidwell.com/seamless.js/src/loader.gif'
- onConnect - Called when a child iframe has finished connecting.
- type: function
- required: false
- default: null
- styles - The styles to inject into the child page.
- type: array of strings
- required: false
- default: []
- fallback - If the fallback functionality is enabled.
- type: bool
- required: false
- default: true
- fallbackParams - Additional query params to attach to the fallback window when it is opened.
- type: string
- required: false
- default: ''
- fallbackText - A message to show below the child iframe to offer assistance if they are having problems.
- type: string
- required: false
- default: ''
- fallbackLinkText - The string to show within the 'Click here' link to open the fallback window.
- type: string
- required: false
- default: 'Click Here'
- fallbackLinkAfter - Text to add after the fallbackLinkText link.
- type: string
- required: false
- default: ' to open in a separate window.'
- fallbackStyles - An array of string styles to add to the fallback text when something bad happens.
- type: array of strings
- required: false
- default:
[ 'padding: 15px', 'border: 1px solid transparent', 'border-radius: 4px', 'color: #3a87ad', 'background-color: #d9edf7', 'border-color: #bce8f1' ]
- fallbackLinkStyles - An array of string styles to add to the fallback link.
- type: array of strings
- required: false
- default:
[ 'display: inline-block', 'color: #333', 'border: 1px solid #ccc', 'background-color: #fff', 'padding: 5px 10px', 'text-decoration: none', 'font-size: 12px', 'line-height: 1.5', 'border-radius: 6px', 'font-weight: 400', 'cursor: pointer', '-webkit-user-select: none', '-moz-user-select: none', '-ms-user-select: none', 'user-select: none' ]
- fallbackLinkHoverStyles - An array of string styles to add to the fallback link on hover.
- type: array of strings
- required: false
- default:
[ 'background-color:#ebebeb', 'border-color:#adadad' ]
- fallbackWindowWidth - The width of the window that is opened up for the fallback.
- type: int
- required: false
- default: 960
- fallbackWindowHeight - The height of the window that is opened up for the fallback.
- type: int
- required: false
- default: 800
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 - The url of the parent page to connect to.
- type: string
- required: true
- default: ''
- container - The container for the main content on the page which determines the height of the page.
- type: string
- required: false
- default: 'body'
- update - The milliseconds that an update is created from the child to the parent.
- type: int
- required: false
- default: 200
- allowStyleInjection - If this page should allow injected styles.
- type: bool
- required: false
- default: false
- requireCookies - If the child page requires cookies (See Child iFrame Cookie Problem section)
- type: bool
- required: false
- default: false
- cookieFallbackMsg - The message to show if the cookie test fails.
- type: string
- required: false
- default: 'Your browser requires this page to be opened in a separate window.'
- cookieFallbackLinkMsg - The text to place inside the link to have them open a new window if the cookie test fails.
- type: string
- required: false
- default: 'Click Here'
- cookieFallbackAfterMsg - The text to place after the link when the cookie test fails.
- type: string
- required: false
- default: ' to open in a separate window.'
- onUpdate - Callback that is called when an update is triggered to the parent.
- type: function
- required: false
- default: null
- onConnect - Called when the parent connects to this iframe.
- type: function
- required: false
- default: null
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.
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);
});
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);
});
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 success 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...
var child = $('#myiframe').seamless();
child.send({
data: {
mydata: 'This is a message'
},
success: function(data) {
// 'data' is what was returned from the child 'receive' function.
console.log(data);
}
});
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..."
};
});
Some browsers (Safari) have an issue where by default they do not allow cookies within the child iframe if it is a cross-origin domain within the child iframe. This library solves this problem by creating a fallback text to prompt the user to open up the child iframe in a separate window. Although this is not ideal, it is also not malicious where it is performing actions without the user knowing and prompts them to actually open up the separate window.
This is only necessary if the child iframe requires cookies, so for that reason, this is not a default option. To turn this on, add the following parameter to the child iframe.
$.seamless({
requireCookies: true
});