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