A shim for the iFrame "srcdoc" attribute
MIT License
srcdoc
polyfill
HTML5 defines a new attribute for iFrames named srcdoc
. This attribute allows
developers to specify an iFrame's content in-line with the iFrame itself. For
instance:
<iframe srcdoc="<html><body>Hello, <b>world</b>.</body></html>"></iframe>
This feature only began to see adoption in major browsers in early 2013. Fortunately, most older browsers support similar functionality through script-targeted URLs, i.e.
<iframe src="javascript: '<html><body>Hello, <b>world</b>.</body></html>'"></iframe>
(Because of limitations on URL length, the actual mechanism that the polyfill implements not quite this direct.)
For more on srcdoc
, see the WhatWG specification and this post on
Bocoup.com.
By including the script at the bottom of the document <body>
, any available
iFrames which declare a srcdoc
attribute attribute) will receive this
"shimmed" behavior. (In browsers that already implement this functionality, no
change will take place.)
Note on the HTML5 sandbox
attribute:
Because the shim operates using a script-targeted URL in legacy environments,
some configurations of the sandbox
attribute may interfere with its behavior.
This issue will only surface in environments that implement sandbox
but that
do not implement srcdoc
. Because of this, this polyfill's default behavior
is to issue a warning for potentially-hazardous configurations but to proceed
optimistically. The API supports an force
option that enables modification of
this behavior.
This script may be consumed as a AMD module, a CommonJS module, or standalone
via direct inclusion with a <script>
element.
The shim also defines a minimal JavaScript API:
srcDoc.set( iframe [, content [, options ] ] )
- sets the content of thesrcdoc
attribute where available (fallingcontent
(optional) - The desired content of the iFrame. If blank, thesrcdoc
attribute will be referenced foroptions
(optional) - An object used to specify low-level behavior.force
, for controlling behavior in thesandbox
attribute (see the note in "Usage" section ofsrcdoc
behavior optimistically.true
, then the target iFrame's sandbox
attribute will be removedfalse
, no warning will be issued and the library will attempt tosrcdoc
behavior optimistically.srcDoc.noConflict()
- Sets the value of the global srcDoc
variable to itssrcDoc
object defined by this project forTested in the following browsers:
The following browsers are not supported:
The build process for this project is written with Grunt.js. Please refer to the grunt documentation for details on installing grunt.
The shim's tests are written in QUnit, and can be run by visiting the
test/index.html
file in the browser, or by running grunt test
from the
command line.
1.0.0
(2017-01-29)
sandbox
attribute if its value may cause0.2.0
(2015-10-02)
0.1.1
(2013-03-01)
0.1.0
(2012-06-13)
Copyright (c) 2012 Mike Pennisi Licensed under the MIT license.