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