Annotation of html5/spec/the-iframe-element.html, revision 1.13
1.1 mike 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
2: <!DOCTYPE html>
3: <!-- when publishing, change bits marked ZZZ --><html lang="en-US-x-Hixie" class="split chapter"><head><title>4.8.2 The iframe element — HTML5 </title><style type="text/css">
4: pre { margin-left: 2em; white-space: pre-wrap; }
5: h2 { margin: 3em 0 1em 0; }
6: h3 { margin: 2.5em 0 1em 0; }
7: h4 { margin: 2.5em 0 0.75em 0; }
8: h5, h6 { margin: 2.5em 0 1em; }
9: h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
10: h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
11: p { margin: 1em 0; }
12: hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
13: dl, dd { margin-top: 0; margin-bottom: 0; }
14: dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
15: dt + dt { margin-top: 0; }
16: dd dt { margin-top: 0.25em; margin-bottom: 0; }
17: dd p { margin-top: 0; }
18: dd dl + p { margin-top: 1em; }
19: dd table + p { margin-top: 1em; }
20: p + * > li, dd li { margin: 1em 0; }
21: dt, dfn { font-weight: bold; font-style: normal; }
22: dt dfn { font-style: italic; }
23: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
24: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
25: pre em { font-weight: bolder; font-style: normal; }
26: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
27: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
28: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
29: table thead, table tbody { border-bottom: solid; }
30: table tbody th:first-child { border-left: solid; }
31: table tbody th { text-align: left; }
32: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
33: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
34:
35: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
36: .matrix, .matrix td { border: none; text-align: right; }
37: .matrix { margin-left: 2em; }
38: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
39: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
40: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
41:
42: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
43: img.extra { float: right; }
44: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; }
45: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
46: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
47: pre.css:first-line { color: #AAAA50; }
48: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
49: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
50: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
51: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
52: dl.domintro dd p { margin: 0.5em 0; }
53: dl.switch { padding-left: 2em; }
54: dl.switch > dt { text-indent: -1.5em; }
55: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
56: dl.triple { padding: 0 0 0 1em; }
57: dl.triple dt, dl.triple dd { margin: 0; display: inline }
58: dl.triple dt:after { content: ':'; }
59: dl.triple dd:after { content: '\A'; white-space: pre; }
60: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
61: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
62: a .diff-new { border-bottom: 1px blue solid; }
63:
64: h2 { page-break-before: always; }
65: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
66: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
67:
68: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]), li > span:not([title=""]):not([class="XXX"]):not([class="impl"]) { border-bottom: solid #9999CC; }
69:
70: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
71: div.head p { margin: 0; }
72: div.head h1 { margin: 0; }
73: div.head .logo { float: right; margin: 0 1em; }
74: div.head .logo img { border: none } /* remove border from top image */
75: div.head dl { margin: 1em 0; }
76: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
77:
78: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
79: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
80: body > .toc > li > * { margin-bottom: 0.5em; }
81: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
82: .toc, .toc li { list-style: none; }
83:
84: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
85: .brief li { margin: 0; padding: 0; }
86: .brief li p { margin: 0; padding: 0; }
87:
88: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
89: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
90: .category-list li { display: inline; }
91: .category-list li:not(:last-child)::after { content: ', '; }
92: .category-list li > span, .category-list li > a { text-transform: lowercase; }
93: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
94:
95: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
96: .XXX > :first-child { margin-top: 0; }
97: p .XXX { line-height: 3em; }
98: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
99: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
100: .annotation :link, .annotation :visited { color: inherit; }
101: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
102: .annotation span { border: none ! important; }
103: .note { color: green; background: transparent; font-family: sans-serif; }
104: .warning { color: red; background: transparent; }
105: .note, .warning { font-weight: bolder; font-style: italic; }
106: p.note, div.note { padding: 0.5em 2em; }
107: span.note { padding: 0 2em; }
108: .note p:first-child, .warning p:first-child { margin-top: 0; }
109: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
110: .warning:before { font-style: normal; }
111: p.note:before { content: 'Note: '; }
112: p.warning:before { content: '\26A0 Warning! '; }
113:
114: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
115: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
116: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
1.12 mike 117: .bookkeeping dt { margin: 0.5em 2em 0; }
118: .bookkeeping dd { margin: 0 3em 0.5em; }
1.1 mike 119:
120: h4 { position: relative; z-index: 3; }
121: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
122: .element {
123: background: #EEEEFF;
124: color: black;
125: margin: 0 0 1em 0.15em;
126: padding: 0 1em 0.25em 0.75em;
127: border-left: solid #9999FF 0.25em;
128: position: relative;
129: z-index: 1;
130: }
131: .element:before {
132: position: absolute;
133: z-index: 2;
134: top: 0;
135: left: -1.15em;
136: height: 2em;
137: width: 0.9em;
138: background: #EEEEFF;
139: content: ' ';
140: border-style: none none solid solid;
141: border-color: #9999FF;
142: border-width: 0.25em;
143: }
144:
145: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
146: td > .example:only-child { margin: 0 0 0 0.1em; }
147:
148: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
149: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
150: ul.domTree li li { list-style: none; }
151: ul.domTree li:first-child::before { position: absolute; top: 0; height: 0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
152: ul.domTree li:not(:last-child)::after { position: absolute; top: 0; bottom: -0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
153: ul.domTree span { font-style: italic; font-family: serif; }
154: ul.domTree .t1 code { color: purple; font-weight: bold; }
155: ul.domTree .t2 { font-style: normal; font-family: monospace; }
156: ul.domTree .t2 .name { color: black; font-weight: bold; }
157: ul.domTree .t2 .value { color: blue; font-weight: normal; }
158: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
159: ul.domTree .t7 code, .domTree .t8 code { color: green; }
160: ul.domTree .t10 code { color: teal; }
161:
162: body.dfnEnabled dfn { cursor: pointer; }
163: .dfnPanel {
164: display: inline;
165: position: absolute;
166: z-index: 10;
167: height: auto;
168: width: auto;
169: padding: 0.5em 0.75em;
170: font: small sans-serif, Droid Sans Fallback;
171: background: #DDDDDD;
172: color: black;
173: border: outset 0.2em;
174: }
175: .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
176: .dfnPanel :link, .dfnPanel :visited { color: black; }
177: .dfnPanel p { font-weight: bolder; }
178: .dfnPanel * + p { margin-top: 0.25em; }
179: .dfnPanel li { list-style-position: inside; }
180:
181: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
182: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
183: #configUI p label { display: block; }
184: #configUI #updateUI, #configUI .loginUI { text-align: center; }
185: #configUI input[type=button] { display: block; margin: auto; }
1.11 mike 186:
1.1 mike 187: </style><style type="text/css">
188:
189: .applies thead th > * { display: block; }
190: .applies thead code { display: block; }
191: .applies tbody th { whitespace: nowrap; }
192: .applies td { text-align: center; }
193: .applies .yes { background: yellow; }
194:
195: .matrix, .matrix td { border: none; text-align: right; }
196: .matrix { margin-left: 2em; }
197:
198: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
199: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
200: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
201:
202: #table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
203: #table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
204: #table-example-1 caption { padding-bottom: 0.5em; }
205: #table-example-1 thead, #table-example-1 tbody { border: none; }
206: #table-example-1 th, #table-example-1 td { border: solid thin; }
207: #table-example-1 th { font-weight: normal; }
208: #table-example-1 td { border-style: none solid; vertical-align: top; }
209: #table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
210: #table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
211: #table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
212: #table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
213: #table-example-1 tbody td:first-child::after { content: leader(". "); }
214: #table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
215: #table-example-1 tbody td:first-child + td { width: 10em; }
216: #table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
217: #table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
218:
219: .apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
220: .apple-table-examples * { font-family: "Times", serif; }
221: .apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
222: .apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
223: .apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
224: .apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
225: .apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
226: .apple-table-examples td { text-align: right; vertical-align: top; }
227: .apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
228: .apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
229: .apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
230: .apple-table-examples sup { line-height: 0; }
231:
232: .details-example img { vertical-align: top; }
233:
234: #named-character-references-table {
235: font-size: 0.6em;
236: column-width: 28em;
237: column-gap: 1em;
238: -moz-column-width: 28em;
239: -moz-column-gap: 1em;
240: -webkit-column-width: 28em;
241: -webkit-column-gap: 1em;
242: }
243: #named-character-references-table > table > tbody > tr > td:last-child { text-align: center; }
244: #named-character-references-table > table > tbody > tr > td:last-child:hover > span { position: absolute; top: auto; left: auto; margin-left: 0.5em; line-height: 1.2; font-size: 5em; border: outset; padding: 0.25em 0.5em; background: white; width: 1.25em; height: auto; text-align: center; }
245:
1.2 mike 246: .glyph.control { color: red; }
247:
1.4 mike 248: @font-face {
249: font-family: 'Essays1743';
250: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743.ttf');
251: }
252: @font-face {
253: font-family: 'Essays1743';
254: font-weight: bold;
255: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Bold.ttf');
256: }
257: @font-face {
258: font-family: 'Essays1743';
259: font-style: italic;
260: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Italic.ttf');
261: }
262: @font-face {
263: font-family: 'Essays1743';
264: font-style: italic;
265: font-weight: bold;
266: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-BoldItalic.ttf');
267: }
268:
1.1 mike 269: </style><style type="text/css">
270: .domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; }
271: </style><link href="data:text/css," id="complete" rel="stylesheet" title="Complete specification"><link href="data:text/css,.impl%20%7B%20display:%20none;%20%7D%0Ahtml%20%7B%20border:%20solid%20yellow;%20%7D%20.domintro:before%20%7B%20display:%20none;%20%7D" id="author" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D%20.domintro:before%20%7B%20background:%20%23FFEEEE;%20%7D" id="highlight" rel="alternate stylesheet" title="Highlight implementation requirements"><script type="text/javascript">
272: function getCookie(name) {
273: var params = location.search.substr(1).split("&");
274: for (var index = 0; index < params.length; index++) {
275: if (params[index] == name)
276: return "1";
277: var data = params[index].split("=");
278: if (data[0] == name)
279: return unescape(data[1]);
280: }
281: var cookies = document.cookie.split("; ");
282: for (var index = 0; index < cookies.length; index++) {
283: var data = cookies[index].split("=");
284: if (data[0] == name)
285: return unescape(data[1]);
286: }
287: return null;
288: }
289: function load(script) {
290: var e = document.createElement('script');
291: e.setAttribute('src', 'http://www.whatwg.org/specs/web-apps/current-work/' + script + '?' + encodeURIComponent(location) + '&' + encodeURIComponent(document.referrer));
292: document.body.appendChild(e);
293: }
294: function init() {
295: if (location.search == '?slow-browser')
296: return;
297: var configUI = document.createElement('div');
298: configUI.id = 'configUI';
299: document.body.appendChild(configUI);
300: // load('reviewer.js'); // would need cross-site XHR
301: if (document.getElementById('head'))
302: load('toc.js');
303: load('styler.js');
304: // load('updater.js'); // would need cross-site XHR
305: load('dfn.js'); // doesn't support split-out specs, but, oh well.
306: // load('status.js'); // would need cross-site XHR
307: if (getCookie('profile') == '1')
308: document.getElementsByTagName('h2')[0].textContent += '; load: ' + (new Date() - loadTimer) + 'ms';
309: fixBrokenLink();
310: }
1.7 mike 311: </script><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css">
1.1 mike 312: <script src="link-fixup.js"></script>
313: <link href="embedded-content-1.html" title="4.8 Embedded content" rel="prev">
314: <link href="spec.html#contents" title="Table of contents" rel="index">
315: <link href="video.html" title="4.8.6 The video element" rel="next">
316: </head><body onload="fixBrokenLink(); init()"><div class="head" id="head">
317: <p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
1.3 mike 318:
1.1 mike 319: <h1>HTML5</h1>
320: </div><div>
321: <a href="embedded-content-1.html">← 4.8 Embedded content</a> –
322: <a href="spec.html#contents">Table of contents</a> –
323: <a href="video.html">4.8.6 The video element →</a>
324: <ol class="toc"><li><ol><li><ol><li><a href="the-iframe-element.html#the-iframe-element"><span class="secno">4.8.2 </span>The <code>iframe</code> element</a></li><li><a href="the-iframe-element.html#the-embed-element"><span class="secno">4.8.3 </span>The <code>embed</code> element</a></li><li><a href="the-iframe-element.html#the-object-element"><span class="secno">4.8.4 </span>The <code>object</code> element</a></li><li><a href="the-iframe-element.html#the-param-element"><span class="secno">4.8.5 </span>The <code>param</code> element</a></li></ol></li></ol></li></ol></div>
325:
326: <h4 id="the-iframe-element"><span class="secno">4.8.2 </span>The <dfn><code>iframe</code></dfn> element</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments. </i><span><a href="http://www.w3.org/html/wg/tracker/issues/100">ISSUE-100</a> (srcdoc) and <a href="http://www.w3.org/html/wg/tracker/issues/103">ISSUE-103</a> (srcdoc-xml-escaping) block progress to Last Call</span></p><dl class="element"><dt>Categories</dt>
327: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
328: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
329: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
330: <dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
331: <dt>Contexts in which this element may be used:</dt>
332: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
333: <dt>Content model:</dt>
334: <dd>Text that conforms to the requirements given in the prose.</dd>
335: <dt>Content attributes:</dt>
336: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
337: <dd><code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code></dd>
338: <dd><code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code></dd>
339: <dd><code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code></dd>
340: <dd><code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code></dd>
341: <dd><code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code></dd>
342: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
343: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
344: <dt>DOM interface:</dt>
345: <dd>
346: <pre class="idl">interface <dfn id="htmliframeelement">HTMLIFrameElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
347: attribute DOMString <a href="#dom-iframe-src" title="dom-iframe-src">src</a>;
348: attribute DOMString <a href="#dom-iframe-srcdoc" title="dom-iframe-srcdoc">srcdoc</a>;
349: attribute DOMString <a href="#dom-iframe-name" title="dom-iframe-name">name</a>;
350: [PutForwards=<a href="common-dom-interfaces.html#dom-domsettabletokenlist-value" title="dom-DOMSettableTokenList-value">value</a>] readonly attribute <a href="common-dom-interfaces.html#domsettabletokenlist">DOMSettableTokenList</a> <a href="#dom-iframe-sandbox" title="dom-iframe-sandbox">sandbox</a>;
351: attribute boolean <a href="#dom-iframe-seamless" title="dom-iframe-seamless">seamless</a>;
352: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
353: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
354: readonly attribute Document <a href="#dom-iframe-contentdocument" title="dom-iframe-contentDocument">contentDocument</a>;
355: readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a> <a href="#dom-iframe-contentwindow" title="dom-iframe-contentWindow">contentWindow</a>;
356: };</pre>
357: </dd>
358: </dl><p>The <code><a href="#the-iframe-element">iframe</a></code> element <a href="rendering.html#represents">represents</a> a
359: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p><p>The <dfn id="attr-iframe-src" title="attr-iframe-src"><code>src</code></dfn> attribute
360: gives the address of a page that the <a href="browsers.html#nested-browsing-context">nested browsing
361: context</a> is to contain. The attribute, if present, must be a
362: <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
363: spaces</a>.</p><p>The <dfn id="attr-iframe-srcdoc" title="attr-iframe-srcdoc"><code>srcdoc</code></dfn>
364: attribute gives the content of the page that the <a href="browsers.html#nested-browsing-context">nested
365: browsing context</a> is to contain. The value of the attribute
366: in is <dfn id="an-iframe-srcdoc-document">an <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code> document</dfn>.</p><p>For <code><a href="#the-iframe-element">iframe</a></code> elements in <a href="dom.html#html-documents">HTML documents</a>,
367: the attribute, if present, must have a value using <a href="syntax.html#syntax">the HTML
368: syntax</a> that consists of the following syntactic components,
369: in the given order:</p><ol><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
370: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
371:
372: <li>Optionally, a <a href="syntax.html#syntax-doctype" title="syntax-doctype">DOCTYPE</a>.
373:
374: </li><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
375: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
376:
377: <li>The root element, in the form of an <code><a href="semantics.html#the-html-element-0">html</a></code> <a href="syntax.html#syntax-elements" title="syntax-elements">element</a>.</li>
378:
379: <li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
380: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
381:
382: </ol><p>For <code><a href="#the-iframe-element">iframe</a></code> elements in <a href="dom.html#xml-documents">XML documents</a>,
383: the attribute, if present, must have a value that matches the
384: production labeled <code><a href="infrastructure.html#document">document</a></code> in the XML
385: specification. <a href="references.html#refsXML">[XML]</a></p><p>If the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute and the
386: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute are both
387: specified together, the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code>
388: attribute takes priority. This allows authors to provide a fallback
389: <a href="urls.html#url">URL</a> for legacy user agents that do not support the
390: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute.</p><div class="impl">
391:
392: <p>When an <code><a href="#the-iframe-element">iframe</a></code> element is first <a href="infrastructure.html#insert-an-element-into-a-document" title="insert
393: an element into a document">inserted into a document</a>, the
394: user agent must create a <a href="browsers.html#nested-browsing-context">nested browsing context</a>, and
395: then <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> for the
396: first time.</p>
397:
398: <p>Whenever an <code><a href="#the-iframe-element">iframe</a></code> element with a <a href="browsers.html#nested-browsing-context">nested
399: browsing context</a> has its <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute set or changed,
400: the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
401: attributes</a>.</p>
402:
403: <p>Similarly, whenever an <code><a href="#the-iframe-element">iframe</a></code> element with a
404: <a href="browsers.html#nested-browsing-context">nested browsing context</a> but with no <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute specified has its
405: <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute set or changed,
406: the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
407: attributes</a>.</p> <!-- It doesn't happen when the base URL is
408: changed, though. -->
409:
410: <p>When the user agent is to <dfn id="process-the-iframe-attributes">process the <code>iframe</code>
411: attributes</dfn>, it must run the first appropriate steps from the
412: following list:</p>
413:
414: <dl class="switch"><dt>If the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute
415: is specified</dt>
416:
417: <dd><p><a href="history.html#navigate">Navigate</a> the element's <a href="browsers.html#browsing-context">browsing
418: context</a> to a resource whose <a href="fetching-resources.html#content-type">Content-Type</a> is
419: <code><a href="iana.html#text-html">text/html</a></code>, whose <a href="urls.html#url">URL</a> is
420: <code><a href="urls.html#about:srcdoc">about:srcdoc</a></code>, and whose data consists of the value of
421: the attribute.</p></dd>
422:
423: <dt>If the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code>
424: attribute is specified but the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute is not</dt>
425:
426: <dd>
427:
428: <ol><li><p>If the value of the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute is the empty string,
429: jump to the <i title="">empty</i> step below.</p></li>
430:
431: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the value of
432: the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute, relative
433: to the <code><a href="#the-iframe-element">iframe</a></code> element.</p></li>
434:
435: <li><p>If that is not successful, then jump to the <i title="">empty</i> step below.</p></li>
436:
437: <li><p>If the resulting <a href="urls.html#absolute-url">absolute URL</a> is an
438: <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a> match for the string
439: "<code><a href="fetching-resources.html#about:blank">about:blank</a></code>", and the user agent is processing this
440: <code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first time, then jump to
441: the <i title="">empty</i> step below. (In cases other than the
442: first time, <code><a href="fetching-resources.html#about:blank">about:blank</a></code> is loaded
443: normally.)</p></li>
444:
445: <li><p><a href="history.html#navigate">Navigate</a> the element's <a href="browsers.html#browsing-context">browsing
446: context</a> to the resulting <a href="urls.html#absolute-url">absolute
447: URL</a>.</p></li>
448:
449: </ol><p><i>Empty</i>: When the steps above require the user agent to
450: jump to the <i title="">empty</i> step, if the user agent is
451: processing this <code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first
452: time, then the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
453: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-load">load</code> at the <code><a href="#the-iframe-element">iframe</a></code>
454: element. (After jumping to this step, the above steps are not
455: resumed.)</p>
456:
457: </dd>
458:
459: <dt>Otherwise</dt>
460:
461: <dd>
462:
463: <p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
464: named <code title="event-load">load</code> at the
465: <code><a href="#the-iframe-element">iframe</a></code> element.</p>
466:
467: </dd>
468:
469: </dl><p>Any <a href="history.html#navigate" title="navigate">navigation</a> required of the user
470: agent in the <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a>
471: algorithm must be completed with the <code><a href="#the-iframe-element">iframe</a></code> element's
472: document's <a href="browsers.html#browsing-context">browsing context</a> as the <a href="history.html#source-browsing-context">source
473: browsing context</a>.</p>
474:
1.8 mike 475: <p>Furthermore, if the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="history.html#session-history">session
476: history</a> contained only one <code><a href="infrastructure.html#document">Document</a></code> when the
477: <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> algorithm
478: was invoked, and that was the <code><a href="fetching-resources.html#about:blank">about:blank</a></code>
479: <code><a href="infrastructure.html#document">Document</a></code> created when the <a href="browsers.html#browsing-context">browsing context</a>
480: was created, then any <a href="history.html#navigate" title="navigate">navigation</a>
481: required of the user agent in that algorithm must be completed with
482: <a href="history.html#replacement-enabled">replacement enabled</a>.</p> <!-- see also the note near
483: similar text for the location.assign() method -->
1.1 mike 484:
485: </div><p class="note">If, when the element is created, the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute is not set, and
486: the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute is either
487: also not set or set but its value cannot be <a href="urls.html#resolve-a-url" title="resolve a
488: url">resolved</a>, the browsing context will remain at the
489: initial <code><a href="fetching-resources.html#about:blank">about:blank</a></code> page.</p><p class="note">If the user <a href="history.html#navigate" title="navigate">navigates</a>
490: away from this page, the <code><a href="#the-iframe-element">iframe</a></code>'s corresponding
491: <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object will proxy new <code><a href="browsers.html#window">Window</a></code>
1.9 mike 492: objects for new <code><a href="infrastructure.html#document">Document</a></code> objects, but the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute will not change.</p><div class="impl">
493:
494: <div class="note">
495:
496: <p><a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a document">Removing</a>
497: an <code><a href="#the-iframe-element">iframe</a></code> from a <code><a href="infrastructure.html#document">Document</a></code> does not cause
498: its <a href="browsers.html#browsing-context">browsing context</a> to be discarded. Indeed, an
499: <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> can survive its
500: original parent <code><a href="infrastructure.html#document">Document</a></code> if its <code><a href="#the-iframe-element">iframe</a></code> is
501: moved to another <code><a href="infrastructure.html#document">Document</a></code>.</p>
502:
1.10 mike 503: <p>On the other hand, if an <code><a href="#the-iframe-element">iframe</a></code> is <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a document">removed</a> from a
504: <code><a href="infrastructure.html#document">Document</a></code> and is then subsequently garbage collected,
505: this will likely mean (in the absence of other references) that the
506: <a href="browsers.html#child-browsing-context">child browsing context</a>'s <code><a href="browsers.html#windowproxy">WindowProxy</a></code>
507: object will become eligble for garbage collection, which will then
508: lead to that <a href="browsers.html#browsing-context">browsing context</a> being <a href="browsers.html#a-browsing-context-is-discarded" title="a
509: browsing context is discarded">discarded</a>, which will then
510: lead to its <code><a href="infrastructure.html#document">Document</a></code> being <a href="browsers.html#discard-a-document" title="discard a
1.9 mike 511: document">discarded</a> also. This happens without notice to any
512: scripts running in that <code><a href="infrastructure.html#document">Document</a></code>; for example, no
513: <code title="event-unload">unload</code> events are fired (the
1.10 mike 514: "<a href="history.html#unload-a-document">unload a document</a>" steps are not run).</p>
1.9 mike 515:
516: </div>
517:
518: </div><div class="example">
1.1 mike 519:
520: <p>Here a blog uses the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute in conjunction
521: with the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> and <code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code> attributes described
522: below to provide users of user agents that support this feature
523: with an extra layer of protection from script injection in the blog
524: post comments:</p>
525:
526: <pre><article>
527: <h1>I got my own magazine!</h1>
528: <p>After much effort, I've finally found a publisher, and so now I
529: have my own magazine! Isn't that awesome?! The first issue will come
530: out in September, and we have articles about getting food, and about
531: getting in boxes, it's going to be great!</p>
532: <footer>
533: <p>Written by <a href="/users/cap">cap</a>.
534: <time pubdate>2009-08-21T23:32Z</time></p>
535: </footer>
536: <article>
537: <footer> At <time pubdate>2009-08-21T23:35Z</time>, <a href="/users/ch">ch</a> writes: </footer>
538: <iframe seamless sandbox="allow-same-origin" srcdoc="<p>did you get a cover picture yet?"></iframe>
539: </article>
540: <article>
541: <footer> At <time pubdate>2009-08-21T23:44Z</time>, <a href="/users/cap">cap</a> writes: </footer>
542: <iframe seamless sandbox="allow-same-origin" srcdoc="<p>Yeah, you can see it <a href=&quot;/gallery?mode=cover&amp;amp;page=1&quot;>in my gallery</a>."></iframe>
543: </article>
544: <article>
545: <footer> At <time pubdate>2009-08-21T23:58Z</time>, <a href="/users/ch">ch</a> writes: </footer>
546: <iframe seamless sandbox="allow-same-origin" srcdoc="<p>hey that's earl's table.
547: <p>you should get earl&amp;amp;me on the next cover."></iframe>
548: </article></pre>
549:
550: <p>Notice the way that quotes have to be escaped (otherwise the
551: <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute would
552: end prematurely), and the way raw ampersands (e.g. in URLs or in
553: prose) mentioned in the sandboxed content have to be
554: <em>doubly</em> escaped — once so that the ampersand is
555: preserved when originally parsing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and once more
556: to prevent the ampersand from being misinterpreted when parsing the
557: sandboxed content.</p>
558:
559: </div><p class="note">In <a href="syntax.html#syntax">the HTML syntax</a>, authors need only
560: remember to use U+0022 QUOTATION MARK characters (") to wrap the
561: attribute contents and then to escape all U+0022 QUOTATION MARK (")
562: and U+0026 AMPERSAND (&) characters, and to specify the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, to ensure safe
563: embedding of content.</p><p class="note">Due to restrictions of <span>the XML syntax</span>,
564: in XML a number of other characters need to be escaped also to
565: ensure correctness.</p><hr><p>The <dfn id="attr-iframe-name" title="attr-iframe-name"><code>name</code></dfn>
566: attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
567: name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
568: browsing context</a>. <span class="impl">When the browsing
569: context is created, if the attribute is present, the <a href="browsers.html#browsing-context-name">browsing
570: context name</a> must be set to the value of this attribute;
571: otherwise, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set to the
572: empty string.</span></p><div class="impl">
573:
574: <p>Whenever the <code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code> attribute
575: is set, the nested <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#browsing-context-name" title="browsing context name">name</a> must be changed to the new
576: value. If the attribute is removed, the <a href="browsers.html#browsing-context-name">browsing context
577: name</a> must be set to the empty string.</p>
578:
579: <p>When content loads in an <code><a href="#the-iframe-element">iframe</a></code>, after any <code title="event-load">load</code> events are fired within the content
580: itself, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire
581: a simple event</a> named <code title="event-load">load</code> at
582: the <code><a href="#the-iframe-element">iframe</a></code> element. When content whose <a href="urls.html#url">URL</a>
583: has the <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code>
584: element's <code><a href="infrastructure.html#document">Document</a></code> fails to load (e.g. due to a DNS
585: error, network error, or if the server returned a 4xx or 5xx status
586: code <a href="fetching-resources.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or
587: equivalent</a>), then the user agent must <a href="webappapis.html#queue-a-task">queue a
588: task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-error">error</code> at the element instead. (This event
589: does not fire for <a href="parsing.html#parse-error" title="parse error">parse errors</a>,
590: script errors, or any errors for cross-origin resources.)</p>
591:
592: <p>The <a href="webappapis.html#task-source">task source</a> for these <a href="webappapis.html#concept-task" title="concept-task">tasks</a> is the <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation
593: task source</a>.</p>
594:
595: <p class="note">A <code title="event-load">load</code> event is also
596: fired at the <code><a href="#the-iframe-element">iframe</a></code> element when it is created if no
597: other data is loaded in it.</p>
598:
599: <p>When there is an <a href="dom.html#active-parser">active parser</a> in the
600: <code><a href="#the-iframe-element">iframe</a></code>, and when anything in the <code><a href="#the-iframe-element">iframe</a></code> is
601: <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the load event</a> of
602: the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a>'s
603: <a href="browsers.html#active-document">active document</a>, the <code><a href="#the-iframe-element">iframe</a></code> must
604: <a href="the-end.html#delay-the-load-event">delay the load event</a> of its document.</p>
605:
606: <p class="note">If, during the handling of the <code title="event-load">load</code> event, the <a href="browsers.html#browsing-context">browsing
607: context</a> in the <code><a href="#the-iframe-element">iframe</a></code> is again <a href="history.html#navigate" title="navigate">navigated</a>, that will further <a href="the-end.html#delay-the-load-event">delay the
608: load event</a>.</p>
609:
610: </div><hr><p>The <dfn id="attr-iframe-sandbox" title="attr-iframe-sandbox"><code>sandbox</code></dfn>
611: attribute, when specified, enables a set of extra restrictions on
612: any content hosted by the <code><a href="#the-iframe-element">iframe</a></code>. Its value must be an
613: <a href="common-microsyntaxes.html#unordered-set-of-unique-space-separated-tokens">unordered set of unique space-separated tokens</a>. The
614: allowed values are <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>,
615: <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>,
616: <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code>,
617: and <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>. When
618: the attribute is set, the content is treated as being from a unique
619: <a href="origin-0.html#origin">origin</a>, forms and scripts are disabled, links are
620: prevented from targeting other <a href="browsers.html#browsing-context" title="browsing
621: context">browsing contexts</a>, and plugins are disabled. The
622: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
623: keyword allows the content to be treated as being from the same
624: origin instead of forcing it into a unique origin, the <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>
625: keyword allows the content to <a href="history.html#navigate">navigate</a> its
626: <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>, and the <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> and <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
627: keywords re-enable forms and scripts respectively (though scripts
628: are still prevented from creating popups).</p><p class="warning">Setting both the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code> and
629: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
630: keywords together when the embedded page has the <a href="origin-0.html#same-origin">same
631: origin</a> as the page containing the <code><a href="#the-iframe-element">iframe</a></code> allows
632: the embedded page to simply remove the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute.</p><p class="warning">Sandboxing hostile content is of minimal help if
633: an attacker can convince the user to just visit the hostile content
634: directly, rather than in the <code><a href="#the-iframe-element">iframe</a></code>. To limit the
635: damage that can be caused by hostile HTML content, it should be
636: served using the <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> MIME type.</p><div class="impl">
637:
638: <!-- v2: Add a new attribute that enables new restrictions, e.g.:
639: - disallow cross-origin loads of any kind (networking
640: override that only allows same-origin URLs or about:,
641: javascript:, data:)
642: - block access to 'parent.frames' from sandbox
643: -->
644:
645: <p>While the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
646: attribute is specified, the <code><a href="#the-iframe-element">iframe</a></code> element's
647: <a href="browsers.html#nested-browsing-context">nested browsing context</a> must have the flags given in
648: the following list set. In addition, any browsing contexts <a href="browsers.html#nested-browsing-context" title="nested browsing context">nested</a> within an
649: <code><a href="#the-iframe-element">iframe</a></code>, either directly or indirectly, must have all
650: the flags set on them as were set on the <code><a href="#the-iframe-element">iframe</a></code>'s
651: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> when the
652: <code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code> was created.</p>
653:
654: <dl><dt>The <dfn id="sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context flag</dfn></dt>
655:
656: <dd>
657:
658: <p>This flag <a href="history.html#sandboxLinks">prevents content from
659: navigating browsing contexts other than the sandboxed browsing
660: context itself</a> (or browsing contexts further nested inside
661: it), and the <a href="browsers.html#top-level-browsing-context">top-level browsing context</a> (which is
662: protected by the <a href="#sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing
663: context flag</a> defined next).</p>
664:
665: <p>This flag also <a href="browsers.html#sandboxWindowOpen">prevents content
666: from creating new auxiliary browsing contexts</a>, e.g. using the
667: <code title="attr-hyperlink-target"><a href="links.html#attr-hyperlink-target">target</a></code> attribute or the
668: <code title="dom-open"><a href="browsers.html#dom-open">window.open()</a></code> method.</p>
669:
670: </dd>
671:
672:
673: <dt>The <dfn id="sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing context
674: flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
675: <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
676: found to have the <dfn id="attr-iframe-sandbox-allow-top-navigation" title="attr-iframe-sandbox-allow-top-navigation"><code>allow-top-navigation</code></dfn>
677: keyword set</dt>
678:
679: <dd>
680:
681: <p>This flag <a href="history.html#sandboxLinks">prevents content from
682: navigating their <span>top-level browsing context</span></a>.</p>
683:
684: <p>When the <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>
685: is set, content can navigate its <a href="browsers.html#top-level-browsing-context">top-level browsing
686: context</a>, but other <a href="browsers.html#browsing-context" title="browsing context">browsing
687: contexts</a> are still protected by the <a href="#sandboxed-navigation-browsing-context-flag">sandboxed
688: navigation browsing context flag</a> defined above.</p>
689:
690: </dd>
691:
692:
693: <dt>The <dfn id="sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</dfn></dt>
694:
695: <dd>
696:
697: <p>This flag prevents content from instantiating <a href="infrastructure.html#plugin" title="plugin">plugins</a>, whether using <a href="#sandboxPluginEmbed">the <code>embed</code> element</a>, <a href="#sandboxPluginObject">the <code>object</code> element</a>,
698: <a href="obsolete.html#sandboxPluginApplet">the <code>applet</code>
699: element</a>, or through <a href="history.html#sandboxPluginNavigate">navigation</a> of a <a href="browsers.html#nested-browsing-context">nested
700: browsing context</a>.</p>
701:
702: </dd>
703:
704:
705: <dt>The <dfn id="sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</dfn></dt>
706:
707: <dd>
708:
709: <p>This flag prevents content from using the <code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code> attribute on
710: descendant <code><a href="#the-iframe-element">iframe</a></code> elements.</p>
711:
712: <p class="note">This prevents a page inserted using the <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
713: keyword from using a CSS-selector-based method of probing the DOM
714: of other pages on the same site (in particular, pages that contain
715: user-sensitive information).</p>
716:
717: <!-- http://lists.w3.org/Archives/Public/public-web-security/2009Dec/thread.html#msg51 -->
718:
719: </dd>
720:
721:
722: <dt>The <dfn id="sandboxed-origin-browsing-context-flag">sandboxed origin browsing context flag</dfn>, unless
723: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
724: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
725: spaces</a>, is found to have the <dfn id="attr-iframe-sandbox-allow-same-origin" title="attr-iframe-sandbox-allow-same-origin"><code>allow-same-origin</code></dfn>
726: keyword set</dt>
727:
728: <dd>
729:
730: <p>This flag <a href="origin-0.html#sandboxOrigin">forces content into a unique
731: origin</a>, thus preventing it from accessing other content from
732: the same <a href="origin-0.html#origin">origin</a>.</p>
733:
734: <p>This flag also <a href="dom.html#sandboxCookies">prevents script from
735: reading from or writing to the <code title="dom-document-cookie">document.cookie</code> IDL
736: attribute</a>, and blocks access to <code title="dom-localStorage">localStorage</code> and <code title="dom-opendatabase">openDatabase()</code>.
737:
738: <a href="references.html#refsWEBSTORAGE">[WEBSTORAGE]</a>
739:
740: <a href="references.html#refsWEBSQL">[WEBSQL]</a>
741: </p>
742:
743: <div class="note">
744:
745: <p>The <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
746: attribute is intended for two cases.</p>
747:
748: <p>First, it can be used to allow content from the same site to
749: be sandboxed to disable scripting, while still allowing access to
750: the DOM of the sandboxed content.</p>
751:
752: <p>Second, it can be used to embed content from a third-party
753: site, sandboxed to prevent that site from opening popup windows,
754: etc, without preventing the embedded page from communicating back
755: to its originating site, using the database APIs to store data,
756: etc.</p>
757:
758: </div>
759:
760: </dd>
761:
762:
763: <dt>The <dfn id="sandboxed-forms-browsing-context-flag">sandboxed forms browsing context flag</dfn>, unless
764: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
765: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
766: spaces</a>, is found to have the <dfn id="attr-iframe-sandbox-allow-forms" title="attr-iframe-sandbox-allow-forms"><code>allow-forms</code></dfn>
767: keyword set</dt>
768:
769: <dd>
770:
771: <p>This flag <a href="association-of-controls-and-forms.html#sandboxSubmitBlocked">blocks form
772: submission</a>.</p>
773:
774: </dd>
775:
776:
777: <dt>The <dfn id="sandboxed-scripts-browsing-context-flag">sandboxed scripts browsing context flag</dfn>, unless
778: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
779: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
780: spaces</a>, is found to have the <dfn id="attr-iframe-sandbox-allow-scripts" title="attr-iframe-sandbox-allow-scripts"><code>allow-scripts</code></dfn>
781: keyword set</dt>
782:
783: <dd>
784:
785: <p>This flag <a href="webappapis.html#sandboxScriptBlocked">blocks script
786: execution</a>.</p>
787:
788: </dd>
789:
790:
791: <dt>The <dfn id="sandboxed-automatic-features-browsing-context-flag">sandboxed automatic features browsing context
792: flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
793: <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
794: found to have the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
795: keyword (defined above) set</dt>
796:
797: <dd>
798:
799: <p>This flag blocks features that trigger automatically, such as
800: <a href="video.html#attr-media-autoplay" title="attr-media-autoplay">automatically playing a
801: video</a> or <a href="association-of-controls-and-forms.html#attr-fe-autofocus" title="attr-fe-autofocus">automatically
802: focusing a form control</a>. It is relaxed by the same flag as
803: scripts, because when scripts are enabled these features are
804: trivially possible anyway, and it would be unfortunate to force
805: authors to use script to do them when sandboxed rather than
806: allowing them to use the declarative features.</p>
807:
808: </dd>
809:
810: </dl><p>These flags must not be set unless the conditions listed above
811: define them as being set.</p>
812:
813: <p class="warning">These flags only take effect when the
814: <a href="browsers.html#nested-browsing-context">nested browsing context</a> of the <code><a href="#the-iframe-element">iframe</a></code> is
815: <a href="history.html#navigate" title="navigate">navigated</a>. Removing then, or removing
816: the entire <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
817: attribute, has no effect on an already-loaded page.</p>
818:
819: </div><div class="example">
820:
821: <p>In this example, some completely-unknown, potentially hostile,
822: user-provided HTML content is embedded in a page. Because it is
823: sandboxed, it is treated by the user agent as being from a unique
824: origin, despite the content being served from the same site. Thus
825: it is affected by all the normal cross-site restrictions. In
826: addition, the embedded page has scripting disabled, plugins
827: disabled, forms disabled, and it cannot navigate any frames or
828: windows other than itself (or any frames or windows it itself
829: embeds).</p>
830:
831: <pre><p>We're not scared of you! Here is your content, unedited:</p>
832: <iframe sandbox src="getusercontent.cgi?id=12193"></iframe></pre>
833:
834: <p>Note that cookies are still sent to the server in the <code title="">getusercontent.cgi</code> request, though they are not
835: visible in the <code title="dom-document-cookie"><a href="dom.html#dom-document-cookie">document.cookie</a></code> IDL
836: attribute.</p>
837:
838: <p class="warning">It is important that the server serve the
839: user-provided HTML using the <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> MIME
840: type so that if the attacker convinces the user to visit that page
841: directly, the page doesn't run in the context of the site's origin,
842: which would make the user vulnerable to any attack found in the
843: page.</p>
844:
845: </div><div class="example">
846:
847: <p>In this example, a gadget from another site is embedded. The
848: gadget has scripting and forms enabled, and the origin sandbox
849: restrictions are lifted, allowing the gadget to communicate with
850: its originating server. The sandbox is still useful, however, as it
851: disables plugins and popups, thus reducing the risk of the user
852: being exposed to malware and other annoyances.</p>
853:
854: <pre><iframe sandbox="allow-same-origin allow-forms allow-scripts"
855: src="http://maps.example.com/embedded.html"></iframe></pre>
856:
857: </div><div class="example">
858:
859: <p>Suppose a file A contained the following fragment:</p>
860:
861: <pre><iframe sandbox="allow-same-origin allow-forms" src=B></iframe></pre>
862:
863: <p>Suppose that file B contained an iframe also:</p>
864:
865: <pre><iframe sandbox="allow-scripts" src=C></iframe></pre>
866:
867: <p>Further, suppose that file C contained a link:</p>
868:
869: <pre><a href=D>Link</a></pre>
870:
871: <p>For this example, suppose all the files were served as
872: <code><a href="iana.html#text-html">text/html</a></code>.</p>
873:
874: <p>Page C in this scenario has all the sandboxing flags
875: set. Scripts are disabled, because the <code><a href="#the-iframe-element">iframe</a></code> in A has
876: scripts disabled, and this overrides the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
877: keyword set on the <code><a href="#the-iframe-element">iframe</a></code> in B. Forms are also
878: disabled, because the inner <code><a href="#the-iframe-element">iframe</a></code> (in B) does not
879: have the <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keyword
880: set.</p>
881:
882: <p>Suppose now that a script in A removes all the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attributes in A and
883: B. This would change nothing immediately. If the user clicked the
884: link in C, loading page D into the <code><a href="#the-iframe-element">iframe</a></code> in B, page D
885: would now act as if the <code><a href="#the-iframe-element">iframe</a></code> in B had the <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
886: and <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keywords
887: set, because that was the state of the <a href="browsers.html#nested-browsing-context">nested browsing
888: context</a> in the <code><a href="#the-iframe-element">iframe</a></code> in A when page B was
889: loaded.</p>
890:
891: <p>Generally speaking, dynamically removing or changing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute is
892: ill-advised, because it can make it quite hard to reason about what
893: will be allowed and what will not.</p>
894:
895: </div><p class="note">Potentially hostile files can be served from the
896: same server as the file containing the <code><a href="#the-iframe-element">iframe</a></code> element
897: by labeling them as <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> instead of
898: <code><a href="iana.html#text-html">text/html</a></code>. This ensures that scripts in the files are
899: unable to attack the site (as if they were actually served from
900: another server), even if the user is tricked into visiting those
901: pages directly, without the protection of the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute.</p><p class="warning">If the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
902: keyword is set along with <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
903: keyword, and the file is from the <a href="origin-0.html#same-origin">same origin</a> as the
904: <code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code>, then a script in the
905: "sandboxed" iframe could just reach out, remove the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and then
906: reload itself, effectively breaking out of the sandbox
907: altogether.</p><hr><!-- v2: Might be interesting to have a value on seamless that
908: allowed event propagation of some sort, maybe based on the WICD
909: work: http://www.w3.org/TR/WICD/ --><p>The <dfn id="attr-iframe-seamless" title="attr-iframe-seamless"><code>seamless</code></dfn>
910: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When specified, it
911: indicates that the <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#browsing-context">browsing
912: context</a> is to be rendered in a manner that makes it appear to
913: be part of the containing document (seamlessly included in the
914: parent document). <span class="impl">Specifically, when the
915: attribute is set on an <code><a href="#the-iframe-element">iframe</a></code> element whose owner
916: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> did not have
917: the <a href="#sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</a> set when that
918: <code><a href="infrastructure.html#document">Document</a></code> was created, and while either the
919: <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active document</a> has the
920: <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code> element's
921: document, or the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active
922: document</a>'s <em><a href="dom.html#the-document-s-address" title="the document's
923: address">address</a></em> has the <a href="origin-0.html#same-origin">same origin</a> as the
924: <code><a href="#the-iframe-element">iframe</a></code> element's document, the following requirements
925: apply:</span></p><div class="impl">
926:
1.13 ! mike 927: <ul><li><p>The user agent must set the <dfn id="seamless-browsing-context-flag">seamless browsing context
! 928: flag</dfn> to true for that <a href="browsers.html#browsing-context">browsing context</a>. This
! 929: will <a href="history.html#seamlessLinks">cause links to open in the parent
! 930: browsing context</a> unless an <a href="browsers.html#explicit-self-navigation-override">explicit self-navigation
! 931: override</a> is used (<code title="">target="_self"</code>).</p></li>
1.1 mike 932:
933: <li><p>In a CSS-supporting user agent: the user agent must add all
934: the style sheets that apply to the <code><a href="#the-iframe-element">iframe</a></code> element to
935: the cascade of the <a href="browsers.html#active-document">active document</a> of the
936: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
937: at the appropriate cascade levels, before any style sheets
938: specified by the document itself.</p></li>
939:
940: <li><p>In a CSS-supporting user agent: the user agent must, for the
941: purpose of CSS property inheritance only, treat the root element of
942: the <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code>
943: element's <a href="browsers.html#nested-browsing-context">nested browsing context</a> as being a child of
944: the <code><a href="#the-iframe-element">iframe</a></code> element. (Thus inherited properties on the
945: root element of the document in the <code><a href="#the-iframe-element">iframe</a></code> will
946: inherit the computed values of those properties on the
947: <code><a href="#the-iframe-element">iframe</a></code> element instead of taking their initial
948: values.)</p></li>
949:
950: <li><p>In visual media, in a CSS-supporting user agent: the user agent
951: should set the intrinsic width of the <code><a href="#the-iframe-element">iframe</a></code> to the
952: width that the element would have if it was a non-replaced
953: block-level element with 'width: auto'.</p></li>
954:
955: <li><p>In visual media, in a CSS-supporting user agent: the user
956: agent should set the intrinsic height of the <code><a href="#the-iframe-element">iframe</a></code> to
957: the height of the bounding box around the content rendered in the
958: <code><a href="#the-iframe-element">iframe</a></code> at its current width (as given in the previous
959: bullet point), as it would be if the scrolling position was such
960: that the top of the viewport for the content rendered in the
961: <code><a href="#the-iframe-element">iframe</a></code> was aligned with the origin of that content's
962: canvas.</p></li>
963:
964: <li>
965:
966: <p>In visual media, in a CSS-supporting user agent: the user agent
967: must force the height of the initial containing block of the
968: <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#nested-browsing-context">nested browsing
969: context</a> of the <code><a href="#the-iframe-element">iframe</a></code> to zero.</p>
970:
971: <p class="note">This is intended to get around the otherwise
972: circular dependency of percentage dimensions that depend on the
973: height of the containing block, thus affecting the height of the
974: document's bounding box, thus affecting the height of the
975: viewport, thus affecting the size of the initial containing
976: block.</p>
977:
978: </li>
979:
980: <li><p>In speech media, the user agent should render the <a href="browsers.html#nested-browsing-context">nested
981: browsing context</a> without announcing that it is a separate
982: document.</p></li>
983:
984: <li>
985:
986: <p>User agents should, in general, act as if the <a href="browsers.html#active-document">active
987: document</a> of the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#nested-browsing-context">nested browsing
988: context</a> was part of the document that the
989: <code><a href="#the-iframe-element">iframe</a></code> is in.</p>
990:
991: <p class="example">For example if the user agent supports listing
992: all the links in a document, links in "seamlessly" nested
993: documents would be included in that list without being
994: significantly distinguished from links in the document itself.</p>
995:
996: </li>
997:
998: </ul><p>If the attribute is not specified, or if the <a href="origin-0.html#origin">origin</a>
999: conditions listed above are not met, then the user agent should
1000: render the <a href="browsers.html#nested-browsing-context">nested browsing context</a> in a manner that is
1001: clearly distinguishable as a separate <a href="browsers.html#browsing-context">browsing context</a>,
1002: and the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a> must be set to
1003: false for that <a href="browsers.html#browsing-context">browsing context</a>.</p>
1004:
1005: <p class="warning">It is important that user agents recheck the
1006: above conditions whenever the <a href="browsers.html#active-document">active document</a> of the
1007: <a href="browsers.html#nested-browsing-context">nested browsing context</a> of the <code><a href="#the-iframe-element">iframe</a></code>
1008: changes, such that the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a>
1009: gets unset if the <a href="browsers.html#nested-browsing-context">nested browsing context</a> is <a href="history.html#navigate" title="navigate">navigated</a> to another origin.</p>
1010:
1011: </div><p class="note">The attribute can be set or removed dynamically,
1012: with the rendering updating in tandem.</p><div class="example">
1013:
1014: <p>In this example, the site's navigation is embedded using a
1015: client-side include using an <code><a href="#the-iframe-element">iframe</a></code>. Any links in the
1016: <code><a href="#the-iframe-element">iframe</a></code> will, in new user agents, be automatically
1017: opened in the <code><a href="#the-iframe-element">iframe</a></code>'s parent browsing context; for
1018: legacy user agents, the site could also include a <code><a href="semantics.html#the-base-element">base</a></code>
1019: element with a <code title="attr-base-target"><a href="semantics.html#attr-base-target">target</a></code>
1020: attribute with the value <code title="">_parent</code>. Similarly,
1021: in new user agents the styles of the parent page will be
1022: automatically applied to the contents of the frame, but to support
1023: legacy user agents authors might wish to include the styles
1024: explicitly.</p>
1025:
1026: <pre><nav><iframe seamless src="nav.include.html"></iframe></nav></pre>
1027:
1028: </div><hr><p>The <code><a href="#the-iframe-element">iframe</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1029: attributes</a> for cases where the embedded content has specific
1030: dimensions (e.g. ad units have well-defined dimensions).</p><p>An <code><a href="#the-iframe-element">iframe</a></code> element never has <a href="content-models.html#fallback-content">fallback
1031: content</a>, as it will always create a nested <a href="browsers.html#browsing-context">browsing
1032: context</a>, regardless of whether the specified initial contents
1033: are successfully used.</p><p>Descendants of <code><a href="#the-iframe-element">iframe</a></code> elements represent
1034: nothing. (In legacy user agents that do not support
1035: <code><a href="#the-iframe-element">iframe</a></code> elements, the contents would be parsed as markup
1036: that could act as fallback content.)</p><p>When used in <a href="dom.html#html-documents">HTML documents</a>, the allowed content
1037: model of <code><a href="#the-iframe-element">iframe</a></code> elements is text, except that invoking
1038: the <a href="the-end.html#html-fragment-parsing-algorithm">HTML fragment parsing algorithm</a> with the
1039: <code><a href="#the-iframe-element">iframe</a></code> element as the <var title="">context</var>
1040: element and the text contents as the <var title="">input</var> must
1041: result in a list of nodes that are all <a href="content-models.html#phrasing-content">phrasing
1042: content</a>, with no <a href="parsing.html#parse-error" title="parse error">parse
1043: errors</a> having occurred, with no <code><a href="scripting-1.html#script">script</a></code> elements
1044: being anywhere in the list or as descendants of elements in the
1045: list, and with all the elements in the list (including their
1046: descendants) being themselves conforming.</p><p>The <code><a href="#the-iframe-element">iframe</a></code> element must be empty in <a href="dom.html#xml-documents">XML
1047: documents</a>.</p><p class="note">The <a href="parsing.html#html-parser">HTML parser</a> treats markup inside
1048: <code><a href="#the-iframe-element">iframe</a></code> elements as text.</p><div class="impl">
1049:
1050: <p>The IDL attributes <dfn id="dom-iframe-src" title="dom-iframe-src"><code>src</code></dfn>, <dfn id="dom-iframe-srcdoc" title="dom-iframe-srcdoc"><code>srcdoc</code></dfn>, <dfn id="dom-iframe-name" title="dom-iframe-name"><code>name</code></dfn>, <dfn id="dom-iframe-sandbox" title="dom-iframe-sandbox"><code>sandbox</code></dfn>, and <dfn id="dom-iframe-seamless" title="dom-iframe-seamless"><code>seamless</code></dfn> must
1051: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1052: name.</p>
1053:
1054: <p>The <dfn id="dom-iframe-contentdocument" title="dom-iframe-contentDocument"><code>contentDocument</code></dfn>
1055: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1056: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code> element's
1057: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
1058:
1059: <p>The <dfn id="dom-iframe-contentwindow" title="dom-iframe-contentWindow"><code>contentWindow</code></dfn>
1060: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1061: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing
1062: context</a>.</p>
1063:
1064: </div><div class="example">
1065:
1066: <p>Here is an example of a page using an <code><a href="#the-iframe-element">iframe</a></code> to
1067: include advertising from an advertising broker:</p>
1068:
1069: <pre><iframe src="http://ads.example.com/?customerid=923513721&amp;format=banner"
1070: width="468" height="60"></iframe></pre>
1071:
1072: </div><h4 id="the-embed-element"><span class="secno">4.8.3 </span>The <dfn><code>embed</code></dfn> element</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><!-- (v2?)
1073: we have all kinds of quirks we should define if they come up during
1074: testing, as e.g. shown in:
1075: http://mxr.mozilla.org/mozilla-central/source/layout/generic/nsObjectFrame.cpp
1076: http://trac.webkit.org/browser/trunk/WebCore/html/HTMLEmbedElement.cpp
1077: http://trac.webkit.org/browser/trunk/WebCore/rendering/RenderPartObject.cpp (updateWidget)
1078: e.g. - 240x200 default
1079: - the attributes/params are sent in a name/value pair list as follows (for Gecko):
1080: + attributes of the element, in source order
1081: + a synthesised 'src' attribute, if there was no 'src' but
1082: there was a 'data', with the value of the 'data' attribute
1083: + the params, in source order
1084: (WebKit does something different still)
1085: - the HIDDEN attribute (might be moot now)
1086: --><dl class="element"><dt>Categories</dt>
1087: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1088: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1089: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1090: <dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1091: <dt>Contexts in which this element may be used:</dt>
1092: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1093: <dt>Content model:</dt>
1094: <dd>Empty.</dd>
1095: <dt>Content attributes:</dt>
1096: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1097: <dd><code title="attr-embed-src"><a href="#attr-embed-src">src</a></code></dd>
1098: <dd><code title="attr-embed-type"><a href="#attr-embed-type">type</a></code></dd>
1099: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1100: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1101: <dd>Any other attribute that has no namespace (see prose).</dd>
1102: <dt>DOM interface:</dt>
1103: <dd>
1104: <pre class="idl">interface <dfn id="htmlembedelement">HTMLEmbedElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1105: attribute DOMString <a href="#dom-embed-src" title="dom-embed-src">src</a>;
1106: attribute DOMString <a href="#dom-embed-type" title="dom-embed-type">type</a>;
1107: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1108: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1109: };</pre>
1110: <div class="impl">
1111: <p>Depending on the type of content instantiated by the
1112: <code><a href="#the-embed-element">embed</a></code> element, the node may also support other
1113: interfaces.</p>
1114: </div>
1115: </dd>
1116: </dl><p>The <code><a href="#the-embed-element">embed</a></code> element <a href="rendering.html#represents">represents</a> an
1117: integration point for an external (typically non-HTML) application
1118: or interactive content.</p><p>The <dfn id="attr-embed-src" title="attr-embed-src"><code>src</code></dfn> attribute
1119: gives the address of the resource being embedded. The attribute, if
1120: present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially
1121: surrounded by spaces</a>.</p><p>The <dfn id="attr-embed-type" title="attr-embed-type"><code>type</code></dfn>
1122: attribute, if present, gives the <a href="infrastructure.html#mime-type">MIME type</a> by which the
1123: plugin to instantiate is selected. The value must be a <a href="infrastructure.html#valid-mime-type">valid
1124: MIME type</a>. If both the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute and the <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute are present, then the
1125: <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute must specify the
1126: same type as the <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type
1127: metadata</a> of the resource given by the <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute.</p><div class="impl">
1128:
1129: <p>When the element is created with neither a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute nor a <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute, and when attributes
1130: are removed such that neither attribute is present on the element
1131: anymore, and when the element has a <a href="video.html#media-element">media element</a>
1132: ancestor, and when the element has an ancestor <code><a href="#the-object-element">object</a></code>
1133: element that is <em>not</em> showing its <a href="content-models.html#fallback-content">fallback
1134: content</a>, any plugins instantiated for the element must be
1135: removed, and the <code><a href="#the-embed-element">embed</a></code> element represents nothing.</p>
1136:
1137: <p id="sandboxPluginEmbed">If either:
1138:
1139: </p><ul><li>the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> was
1140: set on the <a href="browsers.html#browsing-context">browsing context</a> for which the
1141: <code><a href="#the-embed-element">embed</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> is the
1142: <a href="browsers.html#active-document">active document</a> when that <code><a href="infrastructure.html#document">Document</a></code> was
1143: created, or</li>
1144:
1145: <li>the <code><a href="#the-embed-element">embed</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> was
1146: parsed from a resource whose <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type
1147: sniffing">sniffed type</a> as determined during <a href="history.html#navigate" title="navigate">navigation</a> is
1148: <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code></li>
1149:
1150: </ul><p>...then the user agent must render the <code><a href="#the-embed-element">embed</a></code> element
1151: in a manner that conveys that the <a href="infrastructure.html#plugin">plugin</a> was
1152: disabled. The user agent may offer the user the option to override
1153: the sandbox and instantiate the <a href="infrastructure.html#plugin">plugin</a> anyway; if the
1154: user invokes such an option, the user agent must act as if the
1155: conditions above did not apply for the purposes of this element.</p>
1156:
1157: <p class="warning">Plugins are disabled in sandboxed browsing
1158: contexts because they might not honor the restrictions imposed by
1159: the sandbox (e.g. they might allow scripting even when scripting in
1160: the sandbox is disabled). User agents should convey the danger of
1161: overriding the sandbox to the user if an option to do so is
1162: provided.</p>
1163:
1164: <p>An <code><a href="#the-embed-element">embed</a></code> element is said to be <dfn id="concept-embed-active" title="concept-embed-active">potentially active</dfn> when the
1165: following conditions are all met simultaneously:</p>
1166:
1167: <ul class="brief"><li>The element is <a href="infrastructure.html#in-a-document" title="in a document">in a <code>Document</code></a>.</li>
1168: <li>The element's <code><a href="infrastructure.html#document">Document</a></code> is <a href="browsers.html#fully-active">fully active</a>.</li>
1169: <li>The element has either a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute set or a <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute set (or both).</li>
1170: <li>The element's <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute is either absent or its value is the empty string.</li>
1171: <li>The element is not in a <code><a href="infrastructure.html#document">Document</a></code> whose <a href="browsers.html#browsing-context">browsing context</a> had the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> set when the <code><a href="infrastructure.html#document">Document</a></code> was created (unless this has been overridden as described above).</li>
1172: <li>The element's <code><a href="infrastructure.html#document">Document</a></code> was not parsed from a resource whose <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type sniffing">sniffed type</a> as determined during <a href="history.html#navigate" title="navigate">navigation</a> is <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> (unless this has been overridden as described above).</li>
1173: <li>The element is not a descendant of a <a href="video.html#media-element">media element</a>.</li>
1174: <li>The element is not a descendant of an <code><a href="#the-object-element">object</a></code> element that is not showing its <a href="content-models.html#fallback-content">fallback content</a>.</li>
1175: </ul><p>Whenever an <code><a href="#the-embed-element">embed</a></code> element that was not <a href="#concept-embed-active" title="concept-embed-active">potentially active</a> becomes <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>, and whenever
1176: a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1177: <code><a href="#the-embed-element">embed</a></code> element's <code title="attr-embed-type"><a href="#attr-embed-type">src</a></code> attribute is set, changed, or
1178: removed, and whenever a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1179: <code><a href="#the-embed-element">embed</a></code> element's <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute is set, changed, or
1180: removed, the appropriate set of steps from the following is then
1181: applied:</p>
1182:
1183: <dl class="switch"><dt>If the element has a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1184: attribute set</dt>
1185:
1186: <dd>
1187:
1188: <p>The user agent must <a href="urls.html#resolve-a-url" title="resolve a url">resolve</a>
1189: the value of the element's <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1190: attribute, relative to the element. If that is successful, the
1191: user agent should <a href="fetching-resources.html#fetch">fetch</a> the resulting <a href="urls.html#absolute-url">absolute
1192: URL</a>, from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope
1193: origin</a> if it has one<!-- potentially http-origin privacy
1194: sensitive -->. The <a href="webappapis.html#concept-task" title="concept-task">task</a> that is
1195: <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking
1196: task source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> must find and instantiate an
1197: appropriate <a href="infrastructure.html#plugin">plugin</a> based on the <a href="#concept-embed-type" title="concept-embed-type">content's type</a>, and hand that
1198: <a href="infrastructure.html#plugin">plugin</a> the content of the resource, replacing any
1199: previously instantiated plugin for the element.</p> <!-- Note that
1200: this doesn't happen when the base URL changes. -->
1201:
1202: <p>Fetching the resource must <a href="the-end.html#delay-the-load-event">delay the load event</a> of
1203: the element's document.</p>
1204: <!-- if we add load/error events, then replace the previous
1205: paragraph with the text one: -->
1206: <!-- similar text in various places -->
1207: <!--<p>Fetching the resource must <span>delay the load
1208: event</span> of the element's document until the final <span
1209: title="concept-task">task</span> that is <span title="queue a
1210: task">queued</span> by the <span>networking task source</span>
1211: once the resource has been <span title="fetch">fetched</span> has
1212: been run.</p>-->
1213:
1214: </dd>
1215:
1216: <dt>If the element has no <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1217: attribute set</dt>
1218:
1219: <dd><p>The user agent should find and instantiate an appropriate
1220: <a href="infrastructure.html#plugin">plugin</a> based on the value of the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute.</p>
1221:
1222: </dd></dl><p>Whenever an <code><a href="#the-embed-element">embed</a></code> element that was <a href="#concept-embed-active" title="concept-embed-active">potentially active</a> stops being
1223: <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>, any
1224: <a href="infrastructure.html#plugin">plugin</a> that had been instantiated for that element must
1225: be unloaded.</p>
1226:
1227: <p class="note">The <code><a href="#the-embed-element">embed</a></code> element is unaffected by the
1228: CSS 'display' property. The selected plugin is instantiated even if
1229: the element is hidden with a 'display:none' CSS style.</p>
1230:
1231: <p>The <dfn id="concept-embed-type" title="concept-embed-type">type of the content</dfn>
1232: being embedded is defined as follows:</p>
1233:
1234: <ol><li><p>If the element has a <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute, and that attribute's
1235: value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, then the value
1236: of the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute is the
1237: <a href="#concept-embed-type" title="concept-embed-type">content's type</a>.</p></li>
1238:
1239: <li>
1240:
1241: <!-- if we get to this point we know we can successfully parsed
1242: the URL, since this algorithm is only used after fetching the
1243: resource in the steps above -->
1244:
1245: <p>Otherwise, if the <a href="urls.html#url-path" title="url-path"><path></a>
1246: component of the <a href="urls.html#url">URL</a> of the specified resource (after
1247: any redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1248: supports, then the <a href="#concept-embed-type" title="concept-embed-type">content's
1249: type</a> is the type that that plugin can handle.</p>
1250:
1251: <p class="example">For example, a plugin might say that it can
1252: handle resources with <a href="urls.html#url-path" title="url-path"><path></a>
1253: components that end with the four character string "<code title="">.swf</code>".</p>
1254:
1255: <!-- it's sad that we have to do extension sniffing. sigh. -->
1256: <!-- see also <object> which has a similar step -->
1257:
1258: </li>
1259:
1260: <li><p>Otherwise, if the specified resource has <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type metadata</a>, then
1261: that is the <a href="#concept-embed-type" title="concept-embed-type">content's
1262: type</a>.</p></li>
1263:
1264: <li><p>Otherwise, the content has no type and there can be no
1265: appropriate <a href="infrastructure.html#plugin">plugin</a> for it.</p></li>
1266:
1267: <!-- This algorithm is a monument to bad design. Go legacy! -->
1268:
1269: </ol><p>The <code><a href="#the-embed-element">embed</a></code> element has no <a href="content-models.html#fallback-content">fallback
1270: content</a>. If the user agent can't find a suitable plugin, then
1271: the user agent must use a default plugin. (This default could be as
1272: simple as saying "Unsupported Format".)</p>
1273:
1274: <p>Whether the resource is fetched successfully or not (e.g. whether
1275: the response code was a 2xx code <a href="fetching-resources.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or equivalent</a>) must be
1276: ignored when determining the resource's type and when handing the
1277: resource to the plugin.</p>
1278:
1279: <p class="note">This allows servers to return data for plugins even
1280: with error responses (e.g. HTTP 500 Internal Server Error codes can
1281: still contain plugin data).</p>
1282:
1283: </div><p>Any namespace-less attribute other than <code title="attr-embed-name"><a href="obsolete.html#attr-embed-name">name</a></code>, <code title="attr-embed-align"><a href="obsolete.html#attr-embed-align">align</a></code>, <code title="attr-embed-hspace"><a href="obsolete.html#attr-embed-hspace">hspace</a></code>, and <code title="attr-embed-vspace"><a href="obsolete.html#attr-embed-vspace">vspace</a></code> <!-- when editing, see also
1284: note below --> may be specified on the <code><a href="#the-embed-element">embed</a></code> element,
1285: so long as its name is <a href="infrastructure.html#xml-compatible">XML-compatible</a> and contains no
1286: characters in the range U+0041 to U+005A (LATIN CAPITAL LETTER A to
1287: LATIN CAPITAL LETTER Z). These attributes are then passed as
1288: parameters to the <a href="infrastructure.html#plugin">plugin</a>.</p><p class="note">All attributes in <a href="dom.html#html-documents">HTML documents</a> get
1289: lowercased automatically, so the restriction on uppercase letters
1290: doesn't affect such documents.</p><p class="note">The four exceptions are to exclude legacy attributes
1291: that have side-effects beyond just sending parameters to the
1292: <a href="infrastructure.html#plugin">plugin</a>.</p><div class="impl">
1293:
1294: <p>The user agent should pass the names and values of all the
1295: attributes of the <code><a href="#the-embed-element">embed</a></code> element that have no namespace
1296: to the <a href="infrastructure.html#plugin">plugin</a> used, when it is instantiated.</p>
1297:
1298: <p>If the <a href="infrastructure.html#plugin">plugin</a> instantiated for the
1299: <code><a href="#the-embed-element">embed</a></code> element supports a scriptable interface, the
1300: <code><a href="#htmlembedelement">HTMLEmbedElement</a></code> object representing the element should
1301: expose that interface while the element is instantiated.</p>
1302:
1303: </div><p>The <code><a href="#the-embed-element">embed</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1304: attributes</a>.</p><div class="impl">
1305:
1306: <p>The IDL attributes <dfn id="dom-embed-src" title="dom-embed-src"><code>src</code></dfn> and <dfn id="dom-embed-type" title="dom-embed-type"><code>type</code></dfn> each must
1307: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1308: name.</p>
1309:
1310: </div><div class="example">
1311:
1312: <p>Here's a way to embed a resource that requires a proprietary
1313: plug-in, like Flash:</p>
1314:
1315: <pre><embed src="catgame.swf"></pre>
1316:
1317: <p>If the user does not have the plug-in (for example if the
1318: plug-in vendor doesn't support the user's platform), then the user
1319: will be unable to use the resource.</p>
1320:
1321: <p>To pass the plugin a parameter "quality" with the value "high",
1322: an attribute can be specified:</p>
1323:
1324: <pre><embed src="catgame.swf" quality="high"></pre>
1325:
1326: <p>This would be equivalent to the following, when using an
1327: <code><a href="#the-object-element">object</a></code> element instead:</p>
1328:
1329: <pre><object data="catgame.swf">
1330: <param name="quality" value="high">
1331: </object></pre>
1332:
1333: </div><h4 id="the-object-element"><span class="secno">4.8.4 </span>The <dfn><code>object</code></dfn> element</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="element"><dt>Categories</dt>
1334: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1335: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1336: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1337: <dd>If the element has a <code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code> attribute: <a href="content-models.html#interactive-content">Interactive content</a>.</dd> <!-- also when showing a plugin or a nested browsing context, but checking that statically is hard...) -->
1338: <dd><a href="forms.html#category-listed" title="category-listed">Listed</a>, <a href="forms.html#category-submit" title="category-submit">submittable</a>, <a href="forms.html#form-associated-element">form-associated element</a>.</dd>
1339: <dt>Contexts in which this element may be used:</dt>
1340: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1341: <dt>Content model:</dt>
1342: <dd>Zero or more <code><a href="#the-param-element">param</a></code> elements, then, <a href="content-models.html#transparent">transparent</a>.</dd>
1343: <dt>Content attributes:</dt>
1344: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1345: <dd><code title="attr-object-data"><a href="#attr-object-data">data</a></code></dd>
1346: <dd><code title="attr-object-type"><a href="#attr-object-type">type</a></code></dd>
1347: <dd><code title="attr-object-name"><a href="#attr-object-name">name</a></code></dd>
1348: <dd><code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code></dd>
1349: <dd><code title="attr-fae-form"><a href="association-of-controls-and-forms.html#attr-fae-form">form</a></code></dd>
1350: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1351: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1352: <dt>DOM interface:</dt>
1353: <dd>
1354: <pre class="idl">interface <dfn id="htmlobjectelement">HTMLObjectElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1355: attribute DOMString <a href="#dom-object-data" title="dom-object-data">data</a>;
1356: attribute DOMString <a href="#dom-object-type" title="dom-object-type">type</a>;
1357: attribute DOMString <a href="#dom-object-name" title="dom-object-name">name</a>;
1358: attribute DOMString <a href="#dom-object-usemap" title="dom-object-useMap">useMap</a>;
1359: readonly attribute <a href="forms.html#htmlformelement">HTMLFormElement</a> <a href="association-of-controls-and-forms.html#dom-fae-form" title="dom-fae-form">form</a>;
1360: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1361: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1362: readonly attribute Document <a href="#dom-object-contentdocument" title="dom-object-contentDocument">contentDocument</a>;
1363: readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a> <a href="#dom-object-contentwindow" title="dom-object-contentWindow">contentWindow</a>;
1364:
1365: readonly attribute boolean <a href="association-of-controls-and-forms.html#dom-cva-willvalidate" title="dom-cva-willValidate">willValidate</a>;
1366: readonly attribute <a href="association-of-controls-and-forms.html#validitystate">ValidityState</a> <a href="association-of-controls-and-forms.html#dom-cva-validity" title="dom-cva-validity">validity</a>;
1367: readonly attribute DOMString <a href="association-of-controls-and-forms.html#dom-cva-validationmessage" title="dom-cva-validationMessage">validationMessage</a>;
1368: boolean <a href="association-of-controls-and-forms.html#dom-cva-checkvalidatity" title="dom-cva-checkValidatity">checkValidity</a>();
1369: void <a href="association-of-controls-and-forms.html#dom-cva-setcustomvalidity" title="dom-cva-setCustomValidity">setCustomValidity</a>(in DOMString error);
1370: };</pre>
1371: <div class="impl">
1372: <p>Depending on the type of content instantiated by the
1373: <code><a href="#the-object-element">object</a></code> element, the node also supports other
1374: interfaces.</p>
1375: </div>
1376: </dd>
1377: </dl><p>The <code><a href="#the-object-element">object</a></code> element can represent an external
1378: resource, which, depending on the type of the resource, will either
1379: be treated as an image, as a <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1380: or as an external resource to be processed by a
1381: <a href="infrastructure.html#plugin">plugin</a>.</p><p>The <dfn id="attr-object-data" title="attr-object-data"><code>data</code></dfn>
1382: attribute, if present, specifies the address of the resource. If
1383: present, the attribute must be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
1384: URL potentially surrounded by spaces</a>.</p><p>The <dfn id="attr-object-type" title="attr-object-type"><code>type</code></dfn>
1385: attribute, if present, specifies the type of the resource. If
1386: present, the attribute must be a <a href="infrastructure.html#valid-mime-type">valid MIME type</a>.</p><p>At least one of either the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute or the <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute must be present.</p><p>The <dfn id="attr-object-name" title="attr-object-name"><code>name</code></dfn>
1387: attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
1388: name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
1389: browsing context</a>, if applicable.</p><div class="impl">
1390:
1391: <p>When the element is created, when it is popped off the
1392: <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an <a href="parsing.html#html-parser">HTML parser</a>
1393: or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, and subsequently whenever the element is
1394: <a href="infrastructure.html#insert-an-element-into-a-document" title="insert an element into a document">inserted into a
1395: document</a> or <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a
1396: document">removed from a document</a>; and whenever the element's
1397: <code><a href="infrastructure.html#document">Document</a></code> changes whether it is <a href="browsers.html#fully-active">fully
1398: active</a>; and whenever an ancestor <code><a href="#the-object-element">object</a></code> element
1399: changes to or from showing its <a href="content-models.html#fallback-content">fallback content</a>; and
1400: whenever the element's <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute is set,
1401: changed, or removed; and, when its <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute is not present,
1402: whenever its <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute is
1403: set, changed, or removed; and, when neither its <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute nor its <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute are present, whenever
1404: its <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute is set,
1405: changed, or removed: the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
1406: to run the following steps to (re)determine what the
1407: <code><a href="#the-object-element">object</a></code> element represents. The <a href="webappapis.html#task-source">task source</a>
1408: for this <a href="webappapis.html#concept-task" title="concept-task">task</a> is the <a href="webappapis.html#dom-manipulation-task-source">DOM
1409: manipulation task source</a>.</p> <!-- Changing the base URL
1410: doesn't trigger this. -->
1411:
1412: <ol><li>
1413:
1414: <p>If the user has indicated a preference that this
1415: <code><a href="#the-object-element">object</a></code> element's <a href="content-models.html#fallback-content">fallback content</a> be
1416: shown instead of the element's usual behavior, then jump to the
1417: last step in the overall set of steps (fallback).</p>
1418:
1419: <p class="note">For example, a user could ask for the element's
1420: <a href="content-models.html#fallback-content">fallback content</a> to be shown because that content
1421: uses a format that the user finds more accessible.</p>
1422:
1423: </li>
1424:
1425: <li>
1426:
1427: <p>If the element has an ancestor <a href="video.html#media-element">media element</a>, or
1428: has an ancestor <code><a href="#the-object-element">object</a></code> element that is <em>not</em>
1429: showing its <a href="content-models.html#fallback-content">fallback content</a>, or if the element is
1430: not <a href="infrastructure.html#in-a-document" title="in a document">in a <code>Document</code></a>
1431: with a <a href="browsers.html#browsing-context">browsing context</a>, or if the element's
1432: <code><a href="infrastructure.html#document">Document</a></code> is not <a href="browsers.html#fully-active">fully active</a>, or if the
1433: element is still in the <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an
1434: <a href="parsing.html#html-parser">HTML parser</a> or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, then jump to
1435: the last step in the overall set of steps (fallback).</p>
1436:
1437: </li>
1438:
1439: <li>
1440:
1441: <!-- what if it's not in the document? if that should prevent
1442: plugin instantiation, then here just skip to the last step -->
1443:
1444: <p>If the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code>
1445: attribute is present, and has a value that isn't the empty string,
1446: then: if the user agent can find a <a href="infrastructure.html#plugin">plugin</a> suitable
1447: according to the value of the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute, and <a href="#sandboxPluginObject">plugins aren't being sandboxed</a>,
1448: then that <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be
1449: used</a>, and the value of the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute, if any, should be
1450: passed to the <a href="infrastructure.html#plugin">plugin</a>. If no suitable
1451: <a href="infrastructure.html#plugin">plugin</a> can be found, or if the <a href="infrastructure.html#plugin">plugin</a>
1452: reports an error, jump to the last step in the overall set of
1453: steps (fallback).</p>
1454:
1455: <!--
1456: case insensitive:
1457: is "clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" -> application/x-shockwave-flash
1458: is "clsid:cfcdaa03-8be4-11cf-b84b-0020afbbccfa" -> audio/x-pn-realaudio-plugin
1459: is "clsid:02bf25d5-8c17-4b23-bc80-d3488abddc6b" -> video/quicktime
1460: is "clsid:166b1bca-3f9c-11cf-8075-444553540000" -> application/x-director
1461: is "clsid:6bf52a52-394a-11d3-b153-00c04f79faa6" -> application/x-mplayer2
1462: starts with "java:" -> application/x-java-vm
1463: starts with "clsid:" -> application/x-oleobject
1464: -->
1465:
1466: </li>
1467:
1468: <!-- (v2?)
1469: we may have to define magic fallback to <param> if it turns out to
1470: be needed in testing:
1471: <hyatt> apparently your url can come from <param>
1472: <hyatt> not just the data attribute
1473: <hyatt> our code looks for params with "src", "movie", "code" and "url"
1474: <hyatt> and also tries to find the type on a param
1475: <Hixie> oh that's you trying to have hacky activex support
1476: <Hixie> opera does that too
1477: <hyatt> yeah we support activex versions of plugins that are common
1478: <hyatt> like flash and quicktime and realaudio
1479: <Hixie> that would be a step 1b. if no data attribute, then look for a <param> to get you a URL instead.
1480: <Hixie> and if you find one, carry on as if that was your data="".
1481: -->
1482:
1483: <li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
1484: is present and its value is not the empty string, then:</p>
1485:
1486: <ol><li><p>If the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1487: attribute is present and its value is not a type that the user
1488: agent supports, and is not a type that the user agent can find a
1489: <a href="infrastructure.html#plugin">plugin</a> for, then the user agent may jump to the last
1490: step in the overall set of steps (fallback) without fetching the
1491: content to examine its real type.</p></li>
1492:
1493: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the
1494: <a href="urls.html#url">URL</a> specified by the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute, relative to the
1495: element.</p></li>
1496:
1497: <li><p>If that failed, <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1498: <code title="event-error">error</code> at the element, then jump
1499: to the last step in the overall set of steps (fallback).</p></li>
1500:
1501: <li>
1502:
1503: <p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
1504: from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope origin</a> if
1505: it has one<!-- potentially http-origin privacy sensitive
1506: -->.</p>
1507:
1508: <!-- similar text in various places --> <p>Fetching the resource
1509: must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's document
1510: until the <a href="webappapis.html#concept-task" title="concept-task">task</a> that is <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking task
1511: source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> (defined next) has been run.</p>
1512:
1513: </li>
1514:
1515: <li><p>If the resource is not yet available (e.g. because the
1516: resource was not available in the cache, so that loading the
1517: resource required making a request over the network), then jump
1518: to the last step in the overall set of steps (fallback). The
1519: <a href="webappapis.html#concept-task" title="concept-task">task</a> that is <a href="webappapis.html#queue-a-task" title="queue
1520: a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking task source</a>
1521: once the resource is available must restart this algorithm from
1522: this step. Resources can load incrementally; user agents may opt
1523: to consider a resource "available" whenever enough data has been
1524: obtained to begin processing the resource.</p></li>
1525:
1526: <li><p>If the load failed (e.g. there was an HTTP 404 error,
1527: there was a DNS error), <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1528: <code title="event-error">error</code> at the element, then jump
1529: to the last step in the overall set of steps (fallback).</p></li>
1530:
1531: <li id="object-type-detection">
1532:
1533: <p>Determine the <var title="">resource type</var>, as follows:</p>
1534:
1535: <!-- Hopefully this step is exactly equivalent to the following:
1536:
1537: START
1538: |
1539: V
1540: Is there a Content-Type and is the UA going to obey it blindly?
1541: | |
1542: | YES | NO
1543: | V YES
1544: | Is there a type="" attribute whose value is a plugin type? ============================================-.
1545: | | |
1546: | | NO |
1547: | V NO YES |
1548: | Is there a Content type? ========-> Is there a type="" attribute? ==========> Let TYPE be type="" |
1549: | | | attribute value |
1550: | | YES | NO | |
1551: V NO V | V |
1552: +-<============== Is it text/plain or application/octet-stream? `==> Let TYPE be =====>+ |
1553: | | | Sniffed type | |
1554: | | text/plain | octet-stream V |
1555: | V YES V Is TYPE |
1556: | Does the page sniff as binary? ======> Is there a type="" attribute? application/octet-stream? |
1557: | | | | | | |
1558: | | NO | YES | NO | YES | NO |
1559: | | | YES V V | |
1560: | | application/octet-stream? =====> Extension that is plugin type? | |
1561: | | | | | | |
1562: | | | NO | NO | YES | |
1563: | | V | | | |
1564: | | Type attribute is XML or YES V | | |
1565: | | doesn't start with image/* ======> FALLBACK | | |
1566: | | and is not a plugin type? | | |
1567: | | | | | |
1568: | | | NO | | V
1569: V V V V V Use
1570: Use Use Use it (will be Use Use type=""
1571: Content-Type text/plain bitmap or plugin) extension TYPE attribute
1572: | | | | | |
1573: | V V V V |
1574: `================->-+========================================>-+==============>-+-<============-+-<==============+-<======'
1575: |
1576: V
1577: Continue following rules in the spec, which might
1578: result in a plugin, a browsing context, an image,
1579: or using fallback, depending on the UA and the type.
1580:
1581:
1582: "Extension that is plugin type?" means "Is there an extension that matches one that a plugin supports?".
1583: Plugins are not allowed to register text/plain or application/octet-stream.
1584:
1585: -->
1586:
1587: <ol><li>
1588:
1589: <p>Let the <var title="">resource type</var> be unknown.</p>
1590:
1591: </li>
1592:
1593: <li>
1594:
1595: <!-- by request: http://www.w3.org/Bugs/Public/show_bug.cgi?id=8479 -->
1596:
1597: <p>If the user agent is configured to strictly obey
1598: Content-Type headers for this resource, and the resource has
1599: <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1600: metadata</a>, then let the <var title="">resource
1601: type</var> be the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1602: metadata</a>, and jump to the step below labeled
1603: <i>handler</i>.</p>
1604:
1605: </li>
1606:
1607: <li>
1608:
1609: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1610: attribute present on the <code><a href="#the-object-element">object</a></code> element, and that
1611: attribute's value is not a type that the user agent supports,
1612: but it <em>is</em> a type that a <a href="infrastructure.html#plugin">plugin</a> supports,
1613: then let the <var title="">resource type</var> be the type
1614: specified in that <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1615: attribute, and jump to the step below labeled
1616: <i>handler</i>.</p>
1617:
1618: </li>
1619:
1620: <li>
1621:
1622: <p>Run the approprate set of steps from the following
1623: list:</p>
1624:
1625: <dl class="switch"><dt>The resource has <a href="fetching-resources.html#content-type" title="Content-Type">associated
1626: Content-Type metadata</a></dt>
1627:
1628: <dd>
1629:
1630: <ol><li>
1631:
1632: <p>Let <var title="">binary</var> be false.</p>
1633:
1634: </li>
1635:
1636: <li>
1637:
1638: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1639: resource's Content-Type metadata</a> is
1640: "<code>text/plain</code>", and the result of applying the
1641: <a href="fetching-resources.html#content-type-sniffing:-text-or-binary" title="Content-Type sniffing: text or binary">rules
1642: for distingushing if a resource is text or binary</a>
1643: to the resource is that the resource is not
1644: <code>text/plain</code>, then set <var title="">binary</var> to true.</p>
1645:
1646: </li>
1647:
1648: <li>
1649:
1650: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1651: resource's Content-Type metadata</a> is
1652: "<code>application/octet-stream</code>", then set <var title="">binary</var> to true.</p>
1653:
1654: </li>
1655:
1656: <li>
1657:
1658: <p>If <var title="">binary</var> is false, then let the
1659: <var title="">resource type</var> be the type specified in
1660: <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1661: metadata</a>, and jump to the step below labeled
1662: <i>handler</i>.</p>
1663:
1664: </li>
1665:
1666: <li>
1667:
1668: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1669: the <code><a href="#the-object-element">object</a></code> element, and its value is not
1670: <code>application/octet-stream</code>, then run the
1671: following steps:</p>
1672:
1673: <ol><li>
1674:
1675: <p>If the attribute's value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, or
1676: the attribute's value is a type that starts with "<code>image/</code>" that is not also an <a href="infrastructure.html#xml-mime-type">XML MIME type</a>,
1677: then let the <var title="">resource type</var> be the type specified in that <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute.</p>
1678:
1679: </li>
1680:
1681: <li>
1682:
1683: <p>Jump to the step below labeled <i>handler</i>.</p>
1684:
1685: </li>
1686:
1687: </ol></li>
1688:
1689: </ol></dd>
1690:
1691: <dt>The resource does not have <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1692: metadata</a></dt>
1693:
1694: <dd>
1695:
1696: <ol><li>
1697:
1698: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1699: the <code><a href="#the-object-element">object</a></code> element, then let the <var title="">tentative type</var> be the type specified in that
1700: <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute.</p>
1701:
1702: <p>Otherwise, let <var title="">tentative type</var> be the
1703: <a href="fetching-resources.html#content-type-sniffing-0" title="content-type sniffing">sniffed type of the
1704: resource</a>.</p>
1705:
1706: </li>
1707:
1708: <li>
1709:
1710: <p>If <var title="">tentative type</var> is <em>not</em>
1711: <code>application/octet-stream</code>, then let <var title="">resource type</var> be <var title="">tentative
1712: type</var> and jump to the step below labeled
1713: <i>handler</i>.</p>
1714:
1715: </li>
1716:
1717: </ol></dd>
1718:
1719: </dl></li>
1720:
1721: <li>
1722:
1723: <!-- if we get to this point we know we can successfully
1724: parsed the URL, since this algorithm is only used after
1725: fetching the resource in the steps above -->
1726:
1727: <p>If the <a href="urls.html#url-path" title="url-path"><path></a> component
1728: of the <a href="urls.html#url">URL</a> of the specified resource (after any
1729: redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1730: supports, then let <var title="">resource type</var> be the
1731: type that that plugin can handle.</p>
1732:
1733: <p class="example">For example, a plugin might say that it can
1734: handle resources with <a href="urls.html#url-path" title="url-path"><path></a> components that end with
1735: the four character string "<code title="">.swf</code>".</p>
1736:
1737: <!-- it's sad that we have to do extension sniffing. sigh. -->
1738: <!-- see also <embed> which has a similar step -->
1739:
1740: </li>
1741:
1742: </ol><p class="note">It is possible for this step to finish with <var title="">resource type</var> still being unknown, or for one of
1743: the substeps above to jump straight to the next step. In both
1744: cases, the next step will trigger fallback.</p>
1745:
1746: </li>
1747:
1748: <li><p><i>Handler</i>: Handle the content as given by the first
1749: of the following cases that matches:</p>
1750:
1751: <dl class="switch"><dt>If the <var title="">resource type</var> is not a type that
1752: the user agent supports, but it <em>is</em> a type that a
1753: <a href="infrastructure.html#plugin">plugin</a> supports</dt>
1754:
1755: <dd>
1756:
1757: <p>If <a href="#sandboxPluginObject">plugins are being
1758: sandboxed</a>, jump to the last step in the overall set of
1759: steps (fallback).</p>
1760:
1761: <p>Otherwise, the user agent should <a href="#object-plugin">use the plugin that supports <var title="">resource type</var></a> and pass the content of the
1762: resource to that <a href="infrastructure.html#plugin">plugin</a>. If the
1763: <a href="infrastructure.html#plugin">plugin</a> reports an error, then jump to the last
1764: step in the overall set of steps (fallback).</p>
1765:
1766: </dd>
1767:
1768:
1769: <dt>If the <var title="">resource type</var> is an <a href="infrastructure.html#xml-mime-type">XML MIME
1770: type</a>, or
1771: <!-- (redundant with the next one) if the <var title="">resource type</var> is HTML, or -->
1772: if the <var title="">resource type</var> does not start with
1773: "<code>image/</code>"</dt>
1774:
1775: <dd>
1776:
1777: <p>The <code><a href="#the-object-element">object</a></code> element must be associated with a
1778: newly created <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it does
1779: not already have one.</p>
1780:
1781: <p>If the <a href="urls.html#url">URL</a> of the given resource is not
1782: <code><a href="fetching-resources.html#about:blank">about:blank</a></code>, the element's <a href="browsers.html#nested-browsing-context">nested browsing
1783: context</a> must then be <a href="history.html#navigate" title="navigate">navigated</a> to that resource, with
1784: <a href="history.html#replacement-enabled">replacement enabled</a>, and with the
1785: <code><a href="#the-object-element">object</a></code> element's document's <a href="browsers.html#browsing-context">browsing
1786: context</a> as the <a href="history.html#source-browsing-context">source browsing
1787: context</a>. (The <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute of the
1788: <code><a href="#the-object-element">object</a></code> element doesn't get updated if the
1789: browsing context gets further navigated to other
1790: locations.)</p>
1791:
1792: <p>If the <a href="urls.html#url">URL</a> of the given resource <em>is</em>
1793: <code><a href="fetching-resources.html#about:blank">about:blank</a></code>, then, instead, the user agent must
1794: <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
1795: named <code title="event-load">load</code> at the
1796: <code><a href="#the-object-element">object</a></code> element.</p>
1797:
1798: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
1799: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
1800:
1801: <p>If the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
1802: is present, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
1803: to the value of this attribute; otherwise, the <a href="browsers.html#browsing-context-name">browsing
1804: context name</a> must be set to the empty string.</p>
1805:
1806: <p class="note">It's possible that the <a href="history.html#navigate" title="navigate">navigation</a> of the <a href="browsers.html#browsing-context">browsing
1807: context</a> will actually obtain the resource from a
1808: different <a href="offline.html#application-cache">application cache</a>. Even if the resource
1809: is then found to have a different type, it is still used as
1810: part of a <a href="browsers.html#nested-browsing-context">nested browsing context</a>; this algorithm
1811: doesn't restart with the new resource.</p>
1812:
1813: <!-- note that malformed XML files don't cause fallback -->
1814:
1815: </dd>
1816:
1817:
1818: <dt>If the <var title="">resource type</var> starts with
1819: "<code>image/</code>", and support for images has not been
1820: disabled</dt>
1821:
1822: <dd>
1823:
1824: <p>Apply the <a href="fetching-resources.html#content-type-sniffing:-image" title="content-type sniffing: image">image
1825: sniffing</a> rules to determine the type of the image.</p>
1826:
1827: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
1828: specified image. The image is not a <a href="browsers.html#nested-browsing-context">nested browsing
1829: context</a>.</p>
1830:
1831: <p>If the image cannot be rendered, e.g. because it is
1832: malformed or in an unsupported format, jump to the last step
1833: in the overall set of steps (fallback).</p>
1834:
1835: </dd>
1836:
1837:
1838: <dt>Otherwise</dt>
1839:
1840: <dd>
1841:
1842: <p>The given <var title="">resource type</var> is not
1843: supported. Jump to the last step in the overall set of steps
1844: (fallback).</p>
1845:
1846: <p class="note">If the previous step ended with the <var title="">resource type</var> being unknown, this is the case
1847: that is triggered.</p>
1848:
1849: </dd>
1850:
1851: </dl></li>
1852:
1853: <li><p>The element's contents are not part of what the
1854: <code><a href="#the-object-element">object</a></code> element represents.</p>
1855:
1856: </li><li>
1857:
1858: <p>Once the resource is completely loaded, <a href="webappapis.html#queue-a-task">queue a
1859: task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-load">load</code> at the element.</p>
1860:
1861: <p>The <a href="webappapis.html#task-source">task source</a> for this task<!--tasks mentioned
1862: in this section--> is the <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task
1863: source</a>.</p>
1864:
1865: </li>
1866:
1867: </ol></li>
1868:
1869: <li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
1870: is absent but the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1871: attribute is present, <a href="#sandboxPluginObject">plugins aren't
1872: being sandboxed</a>, and the user agent can find a
1873: <a href="infrastructure.html#plugin">plugin</a> suitable according to the value of the <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute, then that
1874: <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be used</a>. If
1875: no suitable <a href="infrastructure.html#plugin">plugin</a> can be found, or if the
1876: <a href="infrastructure.html#plugin">plugin</a> reports an error, jump to the next step
1877: (fallback).</p></li>
1878:
1879: <li><p>(Fallback.) The <code><a href="#the-object-element">object</a></code> element
1880: <a href="rendering.html#represents">represents</a> the element's children, ignoring any
1881: leading <code><a href="#the-param-element">param</a></code> element children. This is the element's
1882: <a href="content-models.html#fallback-content">fallback content</a>. If the element has an instantiated
1883: <a href="infrastructure.html#plugin">plugin</a>, then unload it.</p></li>
1884:
1885: </ol><p id="object-plugin">When the algorithm above instantiates a
1886: <a href="infrastructure.html#plugin">plugin</a>, the user agent should pass to the
1887: <a href="infrastructure.html#plugin">plugin</a> used the names and values of all the attributes
1888: on the element, in the order they were added to the element, with
1889: the attributes added by the parser being ordered in source order,
1890: followed by a parameter named "PARAM" whose value is null,
1891: followed by all the names and values of <a href="#concept-param-parameter" title="concept-param-parameter">parameters</a> given by
1892: <code><a href="#the-param-element">param</a></code> elements that are children of the
1893: <code><a href="#the-object-element">object</a></code> element, in <a href="infrastructure.html#tree-order">tree order</a>. If the
1894: <a href="infrastructure.html#plugin">plugin</a> supports a scriptable interface, the
1895: <code><a href="#htmlobjectelement">HTMLObjectElement</a></code> object representing the element
1896: should expose that interface. The <code><a href="#the-object-element">object</a></code> element
1897: <a href="rendering.html#represents">represents</a> the <a href="infrastructure.html#plugin">plugin</a>. The
1898: <a href="infrastructure.html#plugin">plugin</a> is not a nested <a href="browsers.html#browsing-context">browsing
1899: context</a>.</p>
1900:
1901: <p id="sandboxPluginObject">If either:</p>
1902:
1903: <ul><li>the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> was
1904: set on the <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code>'s
1905: <a href="browsers.html#browsing-context">browsing context</a> when the <code><a href="infrastructure.html#document">Document</a></code> was
1906: created, or</li>
1907:
1908: <li>the <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> was
1909: parsed from a resource whose <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type
1910: sniffing">sniffed type</a> as determined during <a href="history.html#navigate" title="navigate">navigation</a> is
1911: <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code></li>
1912:
1913: </ul><p>...then the steps above must always act as if they had failed to
1914: find a <a href="infrastructure.html#plugin">plugin</a>, even if one would otherwise have been
1915: used.</p>
1916:
1917: <p class="note">The above algorithm is independent of CSS properties
1918: (including 'display', 'overflow', and 'visibility'). For example, it
1919: runs even if the element is hidden with a 'display:none' CSS style,
1920: and does not run <em>again</em> if the element's visibility
1921: changes.</p>
1922:
1923: <p>Due to the algorithm above, the contents of <code><a href="#the-object-element">object</a></code>
1924: elements act as <a href="content-models.html#fallback-content">fallback content</a>, used only when
1925: referenced resources can't be shown (e.g. because it returned a 404
1926: error). This allows multiple <code><a href="#the-object-element">object</a></code> elements to be
1927: nested inside each other, targeting multiple user agents with
1928: different capabilities, with the user agent picking the first one it
1929: supports.</p>
1930:
1931: <p>Whenever the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
1932: is set, if the <code><a href="#the-object-element">object</a></code> element has a nested
1933: <a href="browsers.html#browsing-context">browsing context</a>, its <a href="browsers.html#browsing-context-name" title="browsing context
1934: name">name</a> must be changed to the new value. If the attribute
1935: is removed, if the <code><a href="#the-object-element">object</a></code> element has a <a href="browsers.html#browsing-context">browsing
1936: context</a>, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
1937: to the empty string.</p>
1938:
1939: </div><p>The <code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code> attribute,
1940: if present while the <code><a href="#the-object-element">object</a></code> element represents an
1941: image, can indicate that the object has an associated <a href="the-map-element.html#image-map">image
1942: map</a>. <span class="impl">The attribute must be ignored if the
1943: <code><a href="#the-object-element">object</a></code> element doesn't represent an image.</span></p><p>The <code title="attr-fae-form"><a href="association-of-controls-and-forms.html#attr-fae-form">form</a></code> attribute is used to
1944: explicitly associate the <code><a href="#the-object-element">object</a></code> element with its
1945: <a href="association-of-controls-and-forms.html#form-owner">form owner</a>.</p><div class="impl">
1946:
1947: <p><strong>Constraint validation</strong>: <code><a href="#the-object-element">object</a></code>
1948: elements are always <a href="association-of-controls-and-forms.html#barred-from-constraint-validation">barred from constraint
1949: validation</a>.</p>
1950:
1951: </div><p>The <code><a href="#the-object-element">object</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1952: attributes</a>.</p><div class="impl">
1953:
1954: <p>The IDL attributes <dfn id="dom-object-data" title="dom-object-data"><code>data</code></dfn>, <dfn id="dom-object-type" title="dom-object-type"><code>type</code></dfn>, <dfn id="dom-object-name" title="dom-object-name"><code>name</code></dfn>, and <dfn id="dom-object-usemap" title="dom-object-useMap"><code>useMap</code></dfn> each must
1955: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1956: name.</p>
1957:
1958: <p>The <dfn id="dom-object-contentdocument" title="dom-object-contentDocument"><code>contentDocument</code></dfn>
1959: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1960: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-object-element">object</a></code> element's
1961: <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it has one; otherwise, it
1962: must return null.</p>
1963:
1964: <p>The <dfn id="dom-object-contentwindow" title="dom-object-contentWindow"><code>contentWindow</code></dfn>
1965: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1966: <code><a href="#the-object-element">object</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1967: if it has one; otherwise, it must return null.</p>
1968:
1969: <p>The <code title="dom-cva-willValidate"><a href="association-of-controls-and-forms.html#dom-cva-willvalidate">willValidate</a></code>, <code title="dom-cva-validity"><a href="association-of-controls-and-forms.html#dom-cva-validity">validity</a></code>, and <code title="dom-cva-validationMessage"><a href="association-of-controls-and-forms.html#dom-cva-validationmessage">validationMessage</a></code>
1970: attributes, and the <code title="dom-cva-checkValidatity"><a href="association-of-controls-and-forms.html#dom-cva-checkvalidatity">checkValidity()</a></code> and <code title="dom-cva-setCustomValidity"><a href="association-of-controls-and-forms.html#dom-cva-setcustomvalidity">setCustomValidity()</a></code>
1971: methods, are part of the <a href="association-of-controls-and-forms.html#the-constraint-validation-api">constraint validation API</a>. The
1972: <code title="dom-fae-form"><a href="association-of-controls-and-forms.html#dom-fae-form">form</a></code> IDL attribute is part of the
1973: element's forms API.</p>
1974:
1975: </div><div class="example">
1976:
1977: <p>In the following example, a Java applet is embedded in a page
1978: using the <code><a href="#the-object-element">object</a></code> element. (Generally speaking, it is
1979: better to avoid using applets like these and instead use native
1980: JavaScript and HTML to provide the functionality, since that way
1981: the application will work on all Web browsers without requiring a
1982: third-party plugin. Many devices, especially embedded devices, do
1983: not support third-party technologies like Java.)</p>
1984:
1985: <pre><figure>
1986: <object type="application/x-java-applet">
1987: <param name="code" value="MyJavaClass">
1988: <p>You do not have Java available, or it is disabled.</p>
1989: </object>
1990: <figcaption>My Java Clock</figcaption>
1991: </figure></pre>
1992:
1993: </div><div class="example">
1994:
1995: <p>In this example, an HTML page is embedded in another using the
1996: <code><a href="#the-object-element">object</a></code> element.</p>
1997:
1998: <pre><figure>
1999: <object data="clock.html"></object>
2000: <figcaption>My HTML Clock</figcaption>
2001: </figure></pre>
2002:
2003: </div><div class="example">
2004:
2005: <p>The following example shows how a plugin can be used in HTML (in
2006: this case the Flash plugin, to show a video file). Fallback is
2007: provided for users who do not have Flash enabled, in this case
2008: using the <code><a href="video.html#video">video</a></code> element to show the video for those
2009: using user agents that support <code><a href="video.html#video">video</a></code>, and finally
2010: providing a link to the video for those who have neither Flash nor
2011: a <code><a href="video.html#video">video</a></code>-capable browser.</p>
2012:
2013: <pre><p>Look at my video:
2014: <object type="application/x-shockwave-flash">
2015: <param name=movie value="http://video.example.com/library/watch.swf">
2016: <param name=allowfullscreen value=true>
2017: <param name=flashvars value="http://video.example.com/vids/315981">
2018: <video controls src="http://video.example.com/vids/315981">
2019: <a href="http://video.example.com/vids/315981">View video</a>.
2020: </video>
2021: </object>
2022: </p></pre>
2023:
2024: </div><h4 id="the-param-element"><span class="secno">4.8.5 </span>The <dfn><code>param</code></dfn> element</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="element"><dt>Categories</dt>
2025: <dd>None.</dd>
2026: <dt>Contexts in which this element may be used:</dt>
2027: <dd>As a child of an <code><a href="#the-object-element">object</a></code> element, before any <a href="content-models.html#flow-content">flow content</a>.</dd>
2028: <dt>Content model:</dt>
2029: <dd>Empty.</dd>
2030: <dt>Content attributes:</dt>
2031: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2032: <dd><code title="attr-param-name"><a href="#attr-param-name">name</a></code></dd>
2033: <dd><code title="attr-param-value"><a href="#attr-param-value">value</a></code></dd>
2034: <dt>DOM interface:</dt>
2035: <dd>
2036: <pre class="idl">interface <dfn id="htmlparamelement">HTMLParamElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2037: attribute DOMString <a href="#dom-param-name" title="dom-param-name">name</a>;
2038: attribute DOMString <a href="#dom-param-value" title="dom-param-value">value</a>;
2039: };</pre>
2040: </dd>
2041: </dl><p>The <code><a href="#the-param-element">param</a></code> element defines parameters for plugins
2042: invoked by <code><a href="#the-object-element">object</a></code> elements. It does not <a href="rendering.html#represents" title="represents">represent</a> anything on its own.</p><p>The <dfn id="attr-param-name" title="attr-param-name"><code>name</code></dfn>
2043: attribute gives the name of the parameter.</p><p>The <dfn id="attr-param-value" title="attr-param-value"><code>value</code></dfn>
2044: attribute gives the value of the parameter.</p><p>Both attributes must be present. They may have any value.</p><div class="impl">
2045:
2046: <p>If both attributes are present, and if the parent element of the
2047: <code><a href="#the-param-element">param</a></code> is an <code><a href="#the-object-element">object</a></code> element, then the
2048: element defines a <dfn id="concept-param-parameter" title="concept-param-parameter">parameter</dfn> with the given
2049: name/value pair.</p>
2050:
2051: <p>The IDL attributes <dfn id="dom-param-name" title="dom-param-name"><code>name</code></dfn> and <dfn id="dom-param-value" title="dom-param-value"><code>value</code></dfn> must both
2052: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
2053: name.</p>
2054:
2055: </div><div class="example">
2056:
2057: <p>The following example shows how the <code><a href="#the-param-element">param</a></code> element
2058: can be used to pass a parameter to a plugin, in this case the O3D
2059: plugin.</p>
2060:
2061: <pre><!DOCTYPE HTML>
2062: <html lang="en">
1.6 mike 2063: <head>
2064: <title>O3D Utah Teapot</title>
2065: </head>
2066: <body>
2067: <p>
2068: <object type="application/vnd.o3d.auto">
2069: <strong><param name="o3d_features" value="FloatingPointTextures"></strong>
2070: <img src="o3d-teapot.png"
2071: title="3D Utah Teapot illustration rendered using O3D."
2072: alt="When O3D renders the Utah Teapot, it appears as a squat
2073: teapot with a shiny metallic finish on which the
2074: surroundings are reflected, with a faint shadow caused by
2075: the lighting.">
2076: <p>To see the teapot actually rendered by O3D on your
2077: computer, please download and install the <a
2078: href="http://code.google.com/apis/o3d/docs/gettingstarted.html#install">O3D plugin</a>.</p>
2079: </object>
2080: <script src="o3d-teapot.js"></script>
2081: </p>
2082: </body>
1.1 mike 2083: </html></pre>
2084:
2085: </div></body></html>
Webmaster
![[BACK]](/https/dev.w3.org/cvsweb/icons/back.gif){kind=icon}
Return to the-iframe-element.html CVS log ![[TXT]](/https/dev.w3.org/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/https/dev.w3.org/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / html5 / spec