Annotation of html5/spec/browsers.html, revision 1.1277
1.1175 mike 1: <!DOCTYPE html>
1.1246 sruby 2: <html lang="en-US-x-Hixie"><head><title>5 Loading Web pages — HTML5</title><style type="text/css">
1.1 mike 3: pre { margin-left: 2em; white-space: pre-wrap; }
4: h2 { margin: 3em 0 1em 0; }
5: h3 { margin: 2.5em 0 1em 0; }
6: h4 { margin: 2.5em 0 0.75em 0; }
7: h5, h6 { margin: 2.5em 0 1em; }
8: h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
9: h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
10: p { margin: 1em 0; }
11: hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
12: dl, dd { margin-top: 0; margin-bottom: 0; }
13: dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
14: dt + dt { margin-top: 0; }
15: dd dt { margin-top: 0.25em; margin-bottom: 0; }
16: dd p { margin-top: 0; }
17: dd dl + p { margin-top: 1em; }
18: dd table + p { margin-top: 1em; }
19: p + * > li, dd li { margin: 1em 0; }
20: dt, dfn { font-weight: bold; font-style: normal; }
1.1060 mike 21: i, em { font-style: italic; }
1.1 mike 22: dt dfn { font-style: italic; }
23: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
24: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
25: pre em { font-weight: bolder; font-style: normal; }
26: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
27: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
28: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
1.976 mike 29: table thead, table tbody { border-bottom: solid; }
1.1 mike 30: table tbody th:first-child { border-left: solid; }
1.475 mike 31: table tbody th { text-align: left; }
1.1 mike 32: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
33: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
34:
35: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
36: .matrix, .matrix td { border: none; text-align: right; }
37: .matrix { margin-left: 2em; }
38: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
39: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
40: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
41:
42: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
1.1065 mike 43: img.extra, p.overview { float: right; }
1.1064 mike 44: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
1.1 mike 45: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
1.1064 mike 46: pre.idl::before { content: "IDL"; font: bold small sans-serif; padding: 0.5em; background: white; position: absolute; top: 0; margin: -1px 0 0 -4em; width: 1.5em; border: thin solid; border-radius: 0 0 0 0.5em }
1.1 mike 47: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
48: pre.css:first-line { color: #AAAA50; }
1.840 mike 49: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
1.1 mike 50: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
51: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
52: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
53: dl.domintro dd p { margin: 0.5em 0; }
1.1077 mike 54: dl.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.1 mike 55: dl.switch { padding-left: 2em; }
56: dl.switch > dt { text-indent: -1.5em; }
57: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
58: dl.triple { padding: 0 0 0 1em; }
59: dl.triple dt, dl.triple dd { margin: 0; display: inline }
60: dl.triple dt:after { content: ':'; }
61: dl.triple dd:after { content: '\A'; white-space: pre; }
62: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
63: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
64: a .diff-new { border-bottom: 1px blue solid; }
65:
1.1270 sruby 66: figure.diagrams { border: double black; background: white; padding: 1em; }
67: figure.diagrams img { display: block; margin: 1em auto; }
68:
1.1 mike 69: h2 { page-break-before: always; }
70: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
71: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
72:
1.1016 mike 73: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
74: li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
1.1 mike 75:
76: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
77: div.head p { margin: 0; }
78: div.head h1 { margin: 0; }
79: div.head .logo { float: right; margin: 0 1em; }
80: div.head .logo img { border: none } /* remove border from top image */
81: div.head dl { margin: 1em 0; }
1.671 mike 82: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
1.1 mike 83:
84: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
85: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
86: body > .toc > li > * { margin-bottom: 0.5em; }
87: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
88: .toc, .toc li { list-style: none; }
89:
90: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
91: .brief li { margin: 0; padding: 0; }
92: .brief li p { margin: 0; padding: 0; }
93:
94: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
95: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
96: .category-list li { display: inline; }
97: .category-list li:not(:last-child)::after { content: ', '; }
98: .category-list li > span, .category-list li > a { text-transform: lowercase; }
99: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
100:
101: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
102: .XXX > :first-child { margin-top: 0; }
103: p .XXX { line-height: 3em; }
1.159 mike 104: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
105: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
106: .annotation :link, .annotation :visited { color: inherit; }
107: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
108: .annotation span { border: none ! important; }
1.1 mike 109: .note { color: green; background: transparent; font-family: sans-serif; }
110: .warning { color: red; background: transparent; }
111: .note, .warning { font-weight: bolder; font-style: italic; }
1.1060 mike 112: .note em, .warning em, .note i, .warning i { font-style: normal; }
1.1 mike 113: p.note, div.note { padding: 0.5em 2em; }
114: span.note { padding: 0 2em; }
115: .note p:first-child, .warning p:first-child { margin-top: 0; }
116: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
117: .warning:before { font-style: normal; }
118: p.note:before { content: 'Note: '; }
119: p.warning:before { content: '\26A0 Warning! '; }
120:
121: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
122: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
123: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
1.999 mike 124: .bookkeeping dt { margin: 0.5em 2em 0; }
125: .bookkeeping dd { margin: 0 3em 0.5em; }
1.1 mike 126:
127: h4 { position: relative; z-index: 3; }
128: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
129: .element {
130: background: #EEEEFF;
131: color: black;
132: margin: 0 0 1em 0.15em;
133: padding: 0 1em 0.25em 0.75em;
134: border-left: solid #9999FF 0.25em;
135: position: relative;
136: z-index: 1;
137: }
138: .element:before {
139: position: absolute;
140: z-index: 2;
141: top: 0;
142: left: -1.15em;
143: height: 2em;
144: width: 0.9em;
145: background: #EEEEFF;
146: content: ' ';
147: border-style: none none solid solid;
148: border-color: #9999FF;
149: border-width: 0.25em;
150: }
151:
1.149 mike 152: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
153: td > .example:only-child { margin: 0 0 0 0.1em; }
1.1 mike 154:
155: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
156: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
157: ul.domTree li li { list-style: none; }
158: 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; }
159: 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; }
160: ul.domTree span { font-style: italic; font-family: serif; }
161: ul.domTree .t1 code { color: purple; font-weight: bold; }
162: ul.domTree .t2 { font-style: normal; font-family: monospace; }
163: ul.domTree .t2 .name { color: black; font-weight: bold; }
164: ul.domTree .t2 .value { color: blue; font-weight: normal; }
165: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
166: ul.domTree .t7 code, .domTree .t8 code { color: green; }
167: ul.domTree .t10 code { color: teal; }
168:
1.736 mike 169: body.dfnEnabled dfn { cursor: pointer; }
170: .dfnPanel {
171: display: inline;
172: position: absolute;
173: z-index: 10;
174: height: auto;
175: width: auto;
176: padding: 0.5em 0.75em;
177: font: small sans-serif, Droid Sans Fallback;
178: background: #DDDDDD;
179: color: black;
180: border: outset 0.2em;
181: }
182: .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
183: .dfnPanel :link, .dfnPanel :visited { color: black; }
184: .dfnPanel p { font-weight: bolder; }
185: .dfnPanel * + p { margin-top: 0.25em; }
186: .dfnPanel li { list-style-position: inside; }
187:
1.671 mike 188: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
189: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
190: #configUI p label { display: block; }
191: #configUI #updateUI, #configUI .loginUI { text-align: center; }
192: #configUI input[type=button] { display: block; margin: auto; }
1.998 mike 193:
1.1020 mike 194: fieldset { margin: 1em; padding: 0.5em 1em; }
195: fieldset > legend + * { margin-top: 0; }
1.1012 mike 196: fieldset > :last-child { margin-bottom: 0; }
1.1020 mike 197: fieldset p { margin: 0.5em 0; }
198:
1.1246 sruby 199: </style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css"><style type="text/css">
1.267 mike 200:
1.292 mike 201: .applies thead th > * { display: block; }
202: .applies thead code { display: block; }
203: .applies tbody th { whitespace: nowrap; }
204: .applies td { text-align: center; }
205: .applies .yes { background: yellow; }
206:
1.1001 mike 207: .matrix, .matrix td { border: hidden; text-align: right; }
1.267 mike 208: .matrix { margin-left: 2em; }
209:
210: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
211: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
212: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
213:
1.1006 mike 214: td.eg { border-width: thin; text-align: center; }
215:
1.267 mike 216: #table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
217: #table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
218: #table-example-1 caption { padding-bottom: 0.5em; }
219: #table-example-1 thead, #table-example-1 tbody { border: none; }
220: #table-example-1 th, #table-example-1 td { border: solid thin; }
221: #table-example-1 th { font-weight: normal; }
222: #table-example-1 td { border-style: none solid; vertical-align: top; }
223: #table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
224: #table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
225: #table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
226: #table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
227: #table-example-1 tbody td:first-child::after { content: leader(". "); }
228: #table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
229: #table-example-1 tbody td:first-child + td { width: 10em; }
230: #table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
231: #table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
232:
233: .apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
234: .apple-table-examples * { font-family: "Times", serif; }
235: .apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
236: .apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
237: .apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
238: .apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
239: .apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
240: .apple-table-examples td { text-align: right; vertical-align: top; }
241: .apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
242: .apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
243: .apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
244: .apple-table-examples sup { line-height: 0; }
245:
1.724 mike 246: .details-example img { vertical-align: top; }
247:
1.1031 mike 248: #base64-table {
249: white-space: nowrap;
250: font-size: 0.6em;
251: column-width: 6em;
252: column-count: 5;
253: column-gap: 1em;
254: -moz-column-width: 6em;
255: -moz-column-count: 5;
256: -moz-column-gap: 1em;
257: -webkit-column-width: 6em;
258: -webkit-column-count: 5;
259: -webkit-column-gap: 1em;
260: }
261: #base64-table thead { display: none; }
262: #base64-table * { border: none; }
263: #base64-table tbody td:first-child:after { content: ':'; }
264: #base64-table tbody td:last-child { text-align: right; }
265:
1.877 mike 266: #named-character-references-table {
1.1009 mike 267: white-space: nowrap;
1.877 mike 268: font-size: 0.6em;
1.1009 mike 269: column-width: 30em;
1.877 mike 270: column-gap: 1em;
1.1009 mike 271: -moz-column-width: 30em;
1.877 mike 272: -moz-column-gap: 1em;
1.1009 mike 273: -webkit-column-width: 30em;
1.877 mike 274: -webkit-column-gap: 1em;
275: }
1.1009 mike 276: #named-character-references-table > table > tbody > tr > td:first-child + td,
1.877 mike 277: #named-character-references-table > table > tbody > tr > td:last-child { text-align: center; }
278: #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.1009 mike 279: #named-character-references-table > table > tbody > tr#entity-CounterClockwiseContourIntegral > td:first-child { font-size: 0.5em; }
1.877 mike 280:
1.990 mike 281: .glyph.control { color: red; }
282:
1.993 mike 283: @font-face {
284: font-family: 'Essays1743';
1.1268 sruby 285: src: url('../fonts/Essays1743.ttf');
1.993 mike 286: }
287: @font-face {
288: font-family: 'Essays1743';
289: font-weight: bold;
1.1268 sruby 290: src: url('../fonts/Essays1743-Bold.ttf');
1.993 mike 291: }
292: @font-face {
293: font-family: 'Essays1743';
294: font-style: italic;
1.1268 sruby 295: src: url('../fonts/Essays1743-Italic.ttf');
1.993 mike 296: }
297: @font-face {
298: font-family: 'Essays1743';
299: font-style: italic;
300: font-weight: bold;
1.1268 sruby 301: src: url('../fonts/Essays1743-BoldItalic.ttf');
1.993 mike 302: }
303:
1.1246 sruby 304: </style><link href="data:text/css," id="complete" rel="stylesheet" title="Complete specification"><link href="data:text/css,.impl%20%7B%20display:%20none;%20%7D%0Ahtml%20%7B%20border:%20solid%20yellow;%20%7D%20.domintro:before%20%7B%20display:%20none;%20%7D" id="author" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D%20.domintro:before%20%7B%20background:%20%23FFEEEE;%20%7D" id="highlight" rel="alternate stylesheet" title="Highlight implementation requirements"><script>
1.1038 mike 305: function getCookie(name) {
306: var params = location.search.substr(1).split("&");
307: for (var index = 0; index < params.length; index++) {
308: if (params[index] == name)
309: return "1";
310: var data = params[index].split("=");
311: if (data[0] == name)
312: return unescape(data[1]);
313: }
314: var cookies = document.cookie.split("; ");
315: for (var index = 0; index < cookies.length; index++) {
316: var data = cookies[index].split("=");
317: if (data[0] == name)
318: return unescape(data[1]);
319: }
320: return null;
321: }
1.1257 sruby 322: </script><link href="links.html" title="4.12 Links" rel="prev">
1.1248 sruby 323: <link href="spec.html#contents" title="Table of contents" rel="contents">
1.1246 sruby 324: <link href="history.html" title="5.5 Session history and navigation" rel="next">
1.1109 mike 325: </head><body onload="fixBrokenLink();" class="split chapter"><div class="head" id="head">
1.1 mike 326: <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.991 mike 327:
1.183 mike 328: <h1>HTML5</h1>
1.1246 sruby 329: <h2 class="no-num no-toc" id="a-vocabulary-and-associated-apis-for-html-and-xhtml">A vocabulary and associated APIs for HTML and XHTML</h2>
1.1277 ! sruby 330: <h2 class="no-num no-toc" id="editor's-draft-date-1-january-1970">Editor's Draft 28 September 2012</h2>
1.1172 mike 331: </div>
1.1263 sruby 332: <div class="prev_next">
1.1257 sruby 333: <a href="links.html">← 4.12 Links</a> –
1.1248 sruby 334: <a href="spec.html#contents">Table of contents</a> –
1.1246 sruby 335: <a href="history.html">5.5 Session history and navigation →</a>
1.989 mike 336: <ol class="toc"><li><a href="browsers.html#browsers"><span class="secno">5 </span>Loading Web pages</a>
337: <ol><li><a href="browsers.html#windows"><span class="secno">5.1 </span>Browsing contexts</a>
338: <ol><li><a href="browsers.html#nested-browsing-contexts"><span class="secno">5.1.1 </span>Nested browsing contexts</a>
339: <ol><li><a href="browsers.html#navigating-nested-browsing-contexts-in-the-dom"><span class="secno">5.1.1.1 </span>Navigating nested browsing contexts in the DOM</a></li></ol></li><li><a href="browsers.html#auxiliary-browsing-contexts"><span class="secno">5.1.2 </span>Auxiliary browsing contexts</a>
340: <ol><li><a href="browsers.html#navigating-auxiliary-browsing-contexts-in-the-dom"><span class="secno">5.1.2.1 </span>Navigating auxiliary browsing contexts in the DOM</a></li></ol></li><li><a href="browsers.html#secondary-browsing-contexts"><span class="secno">5.1.3 </span>Secondary browsing contexts</a></li><li><a href="browsers.html#security-nav"><span class="secno">5.1.4 </span>Security</a></li><li><a href="browsers.html#groupings-of-browsing-contexts"><span class="secno">5.1.5 </span>Groupings of browsing contexts</a></li><li><a href="browsers.html#browsing-context-names"><span class="secno">5.1.6 </span>Browsing context names</a></li></ol></li><li><a href="browsers.html#the-window-object"><span class="secno">5.2 </span>The <code>Window</code> object</a>
1.1246 sruby 341: <ol><li><a href="browsers.html#security-window"><span class="secno">5.2.1 </span>Security</a></li><li><a href="browsers.html#apis-for-creating-and-navigating-browsing-contexts-by-name"><span class="secno">5.2.2 </span>APIs for creating and navigating browsing contexts by name</a></li><li><a href="browsers.html#accessing-other-browsing-contexts"><span class="secno">5.2.3 </span>Accessing other browsing contexts</a></li><li><a href="browsers.html#named-access-on-the-window-object"><span class="secno">5.2.4 </span>Named access on the <code>Window</code> object</a></li><li><a href="browsers.html#garbage-collection-and-browsing-contexts"><span class="secno">5.2.5 </span>Garbage collection and browsing contexts</a></li><li><a href="browsers.html#browser-interface-elements"><span class="secno">5.2.6 </span>Browser interface elements</a></li><li><a href="browsers.html#the-windowproxy-object"><span class="secno">5.2.7 </span>The <code>WindowProxy</code> object</a></li></ol></li><li><a href="browsers.html#origin"><span class="secno">5.3 </span>Origin</a>
342: <ol><li><a href="browsers.html#relaxing-the-same-origin-restriction"><span class="secno">5.3.1 </span>Relaxing the same-origin restriction</a></li></ol></li><li><a href="browsers.html#sandboxing"><span class="secno">5.4 </span>Sandboxing</a></li></ol></li></ol></div>
1.1 mike 343:
1.1172 mike 344: <h2 id="browsers"><span class="secno">5 </span>Loading Web pages</h2>
345:
346: <div class="impl">
1.1 mike 347:
348: <p>This section describes features that apply most directly to Web
1.409 mike 349: browsers. Having said that, except where specified otherwise, the
1.1 mike 350: requirements defined in this section <em>do</em> apply to all user
351: agents, whether they are Web browsers or not.</p>
352:
1.1172 mike 353: </div>
354:
355:
356:
357: <h3 id="windows"><span class="secno">5.1 </span>Browsing contexts</h3>
358:
359: <p>A <dfn id="browsing-context">browsing context</dfn> is an environment in which
360: <code><a href="dom.html#document">Document</a></code> objects are presented to the user.</p>
361:
362: <p class="note">A tab or window in a Web browser typically contains
1.1067 mike 363: a <a href="#browsing-context">browsing context</a>, as does an <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code><span class="impl"> or <code><a href="obsolete.html#frame">frame</a></code>s in a
1.1172 mike 364: <code><a href="obsolete.html#frameset">frameset</a></code></span>.</p>
365:
366: <p>Each <a href="#browsing-context">browsing context</a> has a corresponding
367: <code><a href="#windowproxy">WindowProxy</a></code> object.</p>
368:
369: <p>A <a href="#browsing-context">browsing context</a> has a <a href="history.html#session-history">session
1.1087 mike 370: history</a>, which lists the <code><a href="dom.html#document">Document</a></code> objects that
1.364 mike 371: that <a href="#browsing-context">browsing context</a> has presented, is presenting, or
1.1087 mike 372: will present. At any time, one <code><a href="dom.html#document">Document</a></code> in each
1.364 mike 373: <a href="#browsing-context">browsing context</a> is designated the <dfn id="active-document">active
1.1144 mike 374: document</dfn>. A <code><a href="dom.html#document">Document</a></code>'s <a href="#browsing-context">browsing
375: context</a> is that <a href="#browsing-context">browsing context</a> whose
376: <a href="history.html#session-history">session history</a> contains the <code><a href="dom.html#document">Document</a></code>, if
377: any. (A <code><a href="dom.html#document">Document</a></code> created using an API such as <code title="dom-DOMImplementation-createDocument"><a href="infrastructure.html#dom-domimplementation-createdocument">createDocument()</a></code>
1.1172 mike 378: has no <a href="#browsing-context">browsing context</a>.)</p>
379:
380: <p>Each <code><a href="dom.html#document">Document</a></code> is associated with a
1.881 mike 381: <code><a href="#window">Window</a></code> object. A <a href="#browsing-context">browsing context</a>'s
382: <code><a href="#windowproxy">WindowProxy</a></code> object forwards everything to the
383: <a href="#browsing-context">browsing context</a>'s <a href="#active-document">active document</a>'s
1.1172 mike 384: <code><a href="#window">Window</a></code> object.</p>
385:
386: <p class="note">In general, there is a 1-to-1 mapping from the
1.1087 mike 387: <code><a href="#window">Window</a></code> object to the <code><a href="dom.html#document">Document</a></code> object.
1.1048 mike 388: There are two exceptions. First, a <code><a href="#window">Window</a></code> can be reused
1.1087 mike 389: for the presentation of a second <code><a href="dom.html#document">Document</a></code> in the same
1.1273 sruby 390: <a href="#browsing-context">browsing context</a>, such that the mapping is then 1-to-2.
1.1048 mike 391: This occurs when a <a href="#browsing-context">browsing context</a> is <a href="history.html#navigate" title="navigate">navigated</a> from the initial
1.1088 mike 392: <code><a href="urls.html#about:blank">about:blank</a></code> <code><a href="dom.html#document">Document</a></code> to another, with
1.1087 mike 393: <a href="history.html#replacement-enabled">replacement enabled</a>. Second, a <code><a href="dom.html#document">Document</a></code>
1.1048 mike 394: can end up being reused for several <code><a href="#window">Window</a></code> objects when
1.1088 mike 395: the <code title="dom-document-open"><a href="dynamic-markup-insertion.html#dom-document-open">document.open()</a></code> method is
1.1273 sruby 396: used, such that the mapping is then many-to-1.</p>
1.1172 mike 397:
398: <p class="note">A <code><a href="dom.html#document">Document</a></code> does not necessarily have a
1.1 mike 399: <a href="#browsing-context">browsing context</a> associated with it. In particular,
400: data mining tools are likely to never instantiate browsing
1.1172 mike 401: contexts.</p>
402:
403: <hr><p>A <a href="#browsing-context">browsing context</a> can have a <dfn id="creator-browsing-context">creator browsing
1.1 mike 404: context</dfn>, the <a href="#browsing-context">browsing context</a> that was
1.742 mike 405: responsible for its creation. If a <a href="#browsing-context">browsing context</a> has
406: a <a href="#parent-browsing-context">parent browsing context</a>, then that is its
407: <a href="#creator-browsing-context">creator browsing context</a>. Otherwise, if the
408: <a href="#browsing-context">browsing context</a> has an <a href="#opener-browsing-context">opener browsing
409: context</a>, then <em>that</em> is its <a href="#creator-browsing-context">creator browsing
410: context</a>. Otherwise, the <a href="#browsing-context">browsing context</a> has no
1.1172 mike 411: <a href="#creator-browsing-context">creator browsing context</a>.</p>
412:
413: <p>If a <a href="#browsing-context">browsing context</a> <var title="">A</var> has a
1.1 mike 414: <a href="#creator-browsing-context">creator browsing context</a>, then the
1.1087 mike 415: <code><a href="dom.html#document">Document</a></code> that was the <a href="#active-document">active document</a> of
1.1 mike 416: that <a href="#creator-browsing-context">creator browsing context</a> at the time <var title="">A</var> was created is the <dfn id="creator-document">creator
1.1172 mike 417: <code>Document</code></dfn>.</p>
418:
419: <div class="impl">
1.1 mike 420:
421: <p>When a <a href="#browsing-context">browsing context</a> is first created, it must be
1.1087 mike 422: created with a single <code><a href="dom.html#document">Document</a></code> in its session history,
1.1246 sruby 423: whose <a href="dom.html#the-document's-address" title="the document's address">address</a> is
424: <code><a href="urls.html#about:blank">about:blank</a></code>, which is marked as being an <a href="infrastructure.html#html-documents" title="HTML documents">HTML document</a>, and whose <a href="infrastructure.html#document's-character-encoding" title="document's character encoding">character encoding</a> is
1.1087 mike 425: UTF-8. The <code><a href="dom.html#document">Document</a></code> must have a single child
1.1088 mike 426: <code><a href="the-html-element.html#the-html-element">html</a></code> node, which itself has a single child
427: <code><a href="the-body-element.html#the-body-element">body</a></code> node.</p>
1.1 mike 428:
429: <p class="note">If the <a href="#browsing-context">browsing context</a> is created
430: specifically to be immediately navigated, then that initial
431: navigation will have <a href="history.html#replacement-enabled">replacement enabled</a>.</p>
432:
1.1246 sruby 433: <p id="about-blank-origin">The <a href="#origin-0">origin</a> and
434: <a href="#effective-script-origin">effective script origin</a> of the <code><a href="urls.html#about:blank">about:blank</a></code>
1.1242 mike 435: <code><a href="dom.html#document">Document</a></code> are set when the <code><a href="dom.html#document">Document</a></code> is
436: created. If the new <a href="#browsing-context">browsing context</a> has a
1.1246 sruby 437: <a href="#creator-browsing-context">creator browsing context</a>, then the <a href="#origin-0">origin</a>
438: of the <code><a href="urls.html#about:blank">about:blank</a></code> <code><a href="dom.html#document">Document</a></code> is an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the <a href="#origin-0">origin</a>
1.1242 mike 439: of the <a href="#creator-document">creator <code>Document</code></a> and the
1.1246 sruby 440: <a href="#effective-script-origin">effective script origin</a> of the <code><a href="urls.html#about:blank">about:blank</a></code>
441: <code><a href="dom.html#document">Document</a></code> is initially an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the <a href="#effective-script-origin">effective
1.1242 mike 442: script origin</a> of the <a href="#creator-document">creator
1.1246 sruby 443: <code>Document</code></a>. Otherwise, the <a href="#origin-0">origin</a> of
1.1242 mike 444: the <code><a href="urls.html#about:blank">about:blank</a></code> <code><a href="dom.html#document">Document</a></code> is a globally
445: unique identifier assigned when the new <a href="#browsing-context">browsing
1.1246 sruby 446: context</a> is created and the <a href="#effective-script-origin">effective script
1.1242 mike 447: origin</a> of the <code><a href="urls.html#about:blank">about:blank</a></code> <code><a href="dom.html#document">Document</a></code>
1.1246 sruby 448: is initially an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to
449: its <a href="#origin-0">origin</a>.</p>
1.1 mike 450:
1.1172 mike 451: </div>
452:
453:
454: <h4 id="nested-browsing-contexts"><span class="secno">5.1.1 </span>Nested browsing contexts</h4>
455:
456: <p>Certain elements (for example, <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code> elements) can
1.1 mike 457: instantiate further <a href="#browsing-context" title="browsing context">browsing
458: contexts</a>. These are called <dfn id="nested-browsing-context" title="nested browsing
1.1087 mike 459: context">nested browsing contexts</dfn>. If a browsing context <var title="">P</var> has a <code><a href="dom.html#document">Document</a></code> <var title="">D</var>
1.1023 mike 460: with an element <var title="">E</var> that nests another browsing
461: context <var title="">C</var> inside it, then <var title="">C</var>
462: is said to be <dfn id="browsing-context-nested-through" title="browsing context nested through">nested
463: through</dfn> <var title="">D</var>, and <var title="">E</var> is
464: said to be the <dfn id="browsing-context-container">browsing context container</dfn> of <var title="">C</var>. If the <a href="#browsing-context-container">browsing context container</a>
465: element <var title="">E</var> is <a href="infrastructure.html#in-a-document" title="in a
1.1087 mike 466: Document">in</a> the <code><a href="dom.html#document">Document</a></code> <var title="">D</var>,
1.1023 mike 467: then <var title="">P</var> is said to be the <dfn id="parent-browsing-context">parent browsing
468: context</dfn> of <var title="">C</var> and <var title="">C</var> is
469: said to be a <dfn id="child-browsing-context">child browsing context</dfn> of <var title="">P</var>. Otherwise, the <a href="#nested-browsing-context">nested browsing
470: context</a> <var title="">C</var> has no <a href="#parent-browsing-context">parent browsing
1.1172 mike 471: context</a>.</p>
472:
473: <p>A browsing context <var title="">A</var> is said to be an <dfn id="ancestor-browsing-context" title="ancestor browsing context">ancestor</dfn> of a browsing
1.1023 mike 474: context <var title="">B</var> if there exists a browsing context
475: <var title="">A'</var> that is a <a href="#child-browsing-context">child browsing context</a>
476: of <var title="">A</var> and that is itself an <a href="#ancestor-browsing-context" title="ancestor
477: browsing context">ancestor</a> of <var title="">B</var>, or if
478: there is a browsing context <var title="">P</var> that is a
479: <a href="#child-browsing-context">child browsing context</a> of <var title="">A</var> and
1.1172 mike 480: that is the <a href="#parent-browsing-context">parent browsing context</a> of <var title="">B</var>.</p>
481:
482: <p>A browsing context that is not a <a href="#nested-browsing-context">nested browsing
1.1023 mike 483: context</a> has no <a href="#parent-browsing-context">parent browsing context</a>, and is
484: the <dfn id="top-level-browsing-context">top-level browsing context</dfn> of all the browsing
485: contexts for which it is an <a href="#ancestor-browsing-context">ancestor browsing
1.1172 mike 486: context</a>.</p>
487:
488: <p>The transitive closure of <a href="#parent-browsing-context" title="parent browsing
1.1 mike 489: context">parent browsing contexts</a> for a <a href="#nested-browsing-context">nested browsing
1.1023 mike 490: context</a> gives the list of <a href="#ancestor-browsing-context" title="ancestor browsing
1.1172 mike 491: context">ancestor browsing contexts</a>.</p>
492:
493: <p>The <dfn id="list-of-the-descendant-browsing-contexts">list of the descendant browsing contexts</dfn> of a
1.1087 mike 494: <code><a href="dom.html#document">Document</a></code> <var title="">d</var> is the (ordered) list
1.1172 mike 495: returned by the following algorithm:</p>
496:
497: <ol><li><p>Let <var title="">list</var> be an empty list.</p></li>
1.698 mike 498:
1.1029 mike 499: <li>
500:
501: <p>For each <a href="#child-browsing-context">child browsing context</a> of <var title="">d</var> that is <a href="#browsing-context-nested-through" title="browsing context nested
502: through">nested through</a> an element that is <a href="infrastructure.html#in-a-document" title="in
503: a document">in the <code>Document</code></a> <var title="">d</var>, in the <a href="infrastructure.html#tree-order">tree order</a> of the elements
504: nesting those <a href="#browsing-context" title="browsing context">browsing
505: contexts</a>, run these substeps:</p>
506:
507: <ol><li><p>Append that <a href="#child-browsing-context">child browsing context</a> to the
508: list <var title="">list</var>.</p>
509:
510: </li><li><p>Append the <a href="#list-of-the-descendant-browsing-contexts">list of the descendant browsing
511: contexts</a> of the <a href="#active-document">active document</a> of that
512: <a href="#child-browsing-context">child browsing context</a> to the list <var title="">list</var>.</p></li>
513:
514: </ol></li>
1.698 mike 515:
516: <li><p>Return the constructed <var title="">list</var>.</p></li>
517:
1.1087 mike 518: </ol><p>A <code><a href="dom.html#document">Document</a></code> is said to be <dfn id="fully-active">fully active</dfn>
1.1 mike 519: when it is the <a href="#active-document">active document</a> of its <a href="#browsing-context">browsing
520: context</a>, and either its browsing context is a <a href="#top-level-browsing-context">top-level
1.1023 mike 521: browsing context</a>, or it has a <a href="#parent-browsing-context">parent browsing
1.1087 mike 522: context</a> and the <code><a href="dom.html#document">Document</a></code> <a href="#browsing-context-nested-through" title="browsing
1.1023 mike 523: context nested through">through which</a> it is <a href="#nested-browsing-context" title="nested browsing context">nested</a> is itself <a href="#fully-active">fully
1.1172 mike 524: active</a>.</p>
525:
526: <p>Because they are nested through an element, <a href="#child-browsing-context" title="child
1.1 mike 527: browsing context">child browsing contexts</a> are always tied to
1.1087 mike 528: a specific <code><a href="dom.html#document">Document</a></code> in their <a href="#parent-browsing-context">parent browsing
1.1 mike 529: context</a>. User agents must not allow the user to interact with
530: <a href="#child-browsing-context" title="child browsing context">child browsing contexts</a>
1.1087 mike 531: of elements that are in <code><a href="dom.html#document">Document</a></code>s that are not
1.1172 mike 532: themselves <a href="#fully-active">fully active</a>.</p>
533:
534: <p>A <a href="#nested-browsing-context">nested browsing context</a> can have a <a href="the-iframe-element.html#seamless-browsing-context-flag">seamless
1.1 mike 535: browsing context flag</a> set, if it is embedded through an
1.1172 mike 536: <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code> element with a <code title="attr-iframe-seamless"><a href="the-iframe-element.html#attr-iframe-seamless">seamless</a></code> attribute.</p>
537:
538: <p class="note">A <a href="#nested-browsing-context">nested browsing context</a> can in some
1.1023 mike 539: cases be taken out of its <a href="#parent-browsing-context">parent browsing context</a> (e.g.
1.1064 mike 540: if an <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code> element is removed from its
1.1087 mike 541: <code><a href="dom.html#document">Document</a></code>). In such a situation, the <a href="#nested-browsing-context">nested
1.1023 mike 542: browsing context</a> has no <a href="#parent-browsing-context">parent browsing context</a>,
543: but it still has the same <a href="#browsing-context-container">browsing context container</a>
544: and is still <a href="#browsing-context-nested-through" title="browsing context nested through">nested
1.1087 mike 545: through</a> that element's <code><a href="dom.html#document">Document</a></code>. Such a
1.1023 mike 546: <a href="#nested-browsing-context">nested browsing context</a> is <em>not</em> a
547: <a href="#top-level-browsing-context">top-level browsing context</a>, and cannot contain
1.1087 mike 548: <code><a href="dom.html#document">Document</a></code>s that are <a href="#fully-active">fully active</a>.
1.1023 mike 549: Furthermore, if a <a href="#browsing-context-container">browsing context container</a> (such as
1.1087 mike 550: an <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code>) is moved to another <code><a href="dom.html#document">Document</a></code>,
1.1023 mike 551: then the <a href="#parent-browsing-context">parent browsing context</a> of its <a href="#nested-browsing-context">nested
1.1172 mike 552: browsing context</a> will change.</p>
553:
1.1220 mike 554: <p>The <dfn id="document-family">document family</dfn> of a <a href="#browsing-context">browsing context</a>
555: consists of the union of all the <code><a href="dom.html#document">Document</a></code> objects in
556: that <a href="#browsing-context">browsing context</a>'s <a href="history.html#session-history">session history</a>
557: and the <a href="#document-family" title="document family">document families</a> of
558: all those <code><a href="dom.html#document">Document</a></code> objects. The <a href="#document-family">document
559: family</a> of a <code><a href="dom.html#document">Document</a></code> object consists of the
560: union of all the <a href="#document-family" title="document family">document
561: families</a> of the <a href="#browsing-context" title="browsing context">browsing
562: contexts</a> that are <a href="#browsing-context-nested-through" title="browsing context nested
563: through">nested through</a> the <code><a href="dom.html#document">Document</a></code> object.</p>
564:
1.1172 mike 565:
566: <h5 id="navigating-nested-browsing-contexts-in-the-dom"><span class="secno">5.1.1.1 </span>Navigating nested browsing contexts in the DOM</h5>
567:
568: <dl class="domintro"><dt><var title="">window</var> . <code title="dom-top"><a href="#dom-top">top</a></code></dt>
1.1 mike 569:
570: <dd>
571:
572: <p>Returns the <code><a href="#windowproxy">WindowProxy</a></code> for the <a href="#top-level-browsing-context">top-level browsing context</a>.</p>
573:
574: </dd>
575:
576: <dt><var title="">window</var> . <code title="dom-parent"><a href="#dom-parent">parent</a></code></dt>
577:
578: <dd>
579:
580: <p>Returns the <code><a href="#windowproxy">WindowProxy</a></code> for the <a href="#parent-browsing-context">parent browsing context</a>.</p>
581:
582: </dd>
583:
584: <dt><var title="">window</var> . <code title="dom-frameElement"><a href="#dom-frameelement">frameElement</a></code></dt>
585:
586: <dd>
587:
1.810 mike 588: <p>Returns the <code><a href="infrastructure.html#element">Element</a></code> for the <a href="#browsing-context-container">browsing context container</a>.</p>
1.1 mike 589:
590: <p>Returns null if there isn't one.</p>
591:
1.1076 mike 592: <p>Throws a <code><a href="infrastructure.html#securityerror">SecurityError</a></code> exception in cross-origin situations.</p>
1.1 mike 593:
594: </dd>
595:
596: </dl><div class="impl">
597:
1.192 mike 598: <p>The <dfn id="dom-top" title="dom-top"><code>top</code></dfn> IDL attribute on
1.1087 mike 599: the <code><a href="#window">Window</a></code> object of a <code><a href="dom.html#document">Document</a></code> in a
1.1 mike 600: <a href="#browsing-context">browsing context</a> <var title="">b</var> must return the
601: <code><a href="#windowproxy">WindowProxy</a></code> object of its <a href="#top-level-browsing-context">top-level browsing
602: context</a> (which would be its own <code><a href="#windowproxy">WindowProxy</a></code>
1.1025 mike 603: object if it was a <a href="#top-level-browsing-context">top-level browsing context</a> itself),
604: if it has one, or its own <code><a href="#windowproxy">WindowProxy</a></code> object otherwise
605: (e.g. if it was a detached <a href="#nested-browsing-context">nested browsing
606: context</a>).</p>
1.1 mike 607:
1.192 mike 608: <p>The <dfn id="dom-parent" title="dom-parent"><code>parent</code></dfn> IDL
1.1 mike 609: attribute on the <code><a href="#window">Window</a></code> object of a
1.1087 mike 610: <code><a href="dom.html#document">Document</a></code> in a <a href="#browsing-context">browsing context</a> <var title="">b</var> must return the <code><a href="#windowproxy">WindowProxy</a></code> object of
1.1 mike 611: the <a href="#parent-browsing-context">parent browsing context</a>, if there is one (i.e. if
612: <var title="">b</var> is a <a href="#child-browsing-context">child browsing context</a>), or
613: the <code><a href="#windowproxy">WindowProxy</a></code> object of the <a href="#browsing-context">browsing
614: context</a> <var title="">b</var> itself, otherwise (i.e. if it
1.1025 mike 615: is a <a href="#top-level-browsing-context">top-level browsing context</a> or a detached
616: <a href="#nested-browsing-context">nested browsing context</a>).</p>
1.1 mike 617:
618: <p>The <dfn id="dom-frameelement" title="dom-frameElement"><code>frameElement</code></dfn>
1.192 mike 619: IDL attribute on the <code><a href="#window">Window</a></code> object of a
1.1087 mike 620: <code><a href="dom.html#document">Document</a></code> <var title="">d</var>, on getting, must run
1.1 mike 621: the following algorithm:</p>
622:
1.1087 mike 623: <ol><li><p>If <var title="">d</var> is not a <code><a href="dom.html#document">Document</a></code> in a
1.1025 mike 624: <a href="#nested-browsing-context">nested browsing context</a>, return null and abort these
1.1 mike 625: steps.</p></li>
626:
1.1025 mike 627: <li><p>If the <a href="#browsing-context-container">browsing context container</a>'s
1.1246 sruby 628: <code><a href="dom.html#document">Document</a></code> does not have the <a href="#same-origin" title="same
629: origin">same</a> <a href="#effective-script-origin">effective script origin</a> as the
1.1076 mike 630: <a href="#entry-script">entry script</a>, then throw a <code><a href="infrastructure.html#securityerror">SecurityError</a></code>
1.582 mike 631: exception.</p></li>
1.1 mike 632:
633: <li><p>Otherwise, return the <a href="#browsing-context-container">browsing context
634: container</a> for <var title="">b</var>.</p></li>
635:
1.1172 mike 636: </ol></div>
637:
638:
639:
640: <h4 id="auxiliary-browsing-contexts"><span class="secno">5.1.2 </span>Auxiliary browsing contexts</h4>
641:
642: <p>It is possible to create new browsing contexts that are related
1.174 mike 643: to a <a href="#top-level-browsing-context">top-level browsing context</a> without being nested
1.1 mike 644: through an element. Such browsing contexts are called <dfn id="auxiliary-browsing-context" title="auxiliary browsing context">auxiliary browsing
645: contexts</dfn>. Auxiliary browsing contexts are always <a href="#top-level-browsing-context" title="top-level browsing context">top-level browsing
1.1172 mike 646: contexts</a>.</p>
647:
648: <p>An <a href="#auxiliary-browsing-context">auxiliary browsing context</a> has an <dfn id="opener-browsing-context">opener
1.1 mike 649: browsing context</dfn>, which is the <a href="#browsing-context">browsing context</a>
1.1026 mike 650: from which the <a href="#auxiliary-browsing-context">auxiliary browsing context</a> was
1.1172 mike 651: created.</p>
652:
653:
654: <h5 id="navigating-auxiliary-browsing-contexts-in-the-dom"><span class="secno">5.1.2.1 </span>Navigating auxiliary browsing contexts in the DOM</h5>
655:
656: <p>The <dfn id="dom-opener" title="dom-opener"><code>opener</code></dfn> IDL
1.1032 mike 657: attribute on the <code><a href="#window">Window</a></code> object, on getting, must return
658: the <code><a href="#windowproxy">WindowProxy</a></code> object of the <a href="#browsing-context">browsing
659: context</a> from which the current <a href="#browsing-context">browsing context</a>
660: was created (its <a href="#opener-browsing-context">opener browsing context</a>), if there is
661: one, if it is still available, and if the current <a href="#browsing-context">browsing
1.1135 mike 662: context</a> has not <i><a href="#disowned-its-opener">disowned its opener</a></i>; otherwise, it
663: must return null. On setting, if the new value is null then the
664: current <a href="#browsing-context">browsing context</a> must <dfn id="disowned-its-opener" title="disowned its
665: opener">disown its opener</dfn>; if the new value is anything else
1.1172 mike 666: then the user agent must ignore the new value.</p>
667:
668:
669:
670: <h4 id="secondary-browsing-contexts"><span class="secno">5.1.3 </span>Secondary browsing contexts</h4>
671:
1.1246 sruby 672: <!-- This section only exists for the purpose of defining
673: rel=sidebar, which was dropped due to wg decision in
674: http://www.w3.org/Bugs/Public/show_bug.cgi?id=11183
675: and then moved to the wiki -->
1.1172 mike 676:
677: <p>User agents may support <dfn id="secondary-browsing-context" title="secondary browsing
1.1 mike 678: context">secondary browsing contexts</dfn>, which are <a href="#browsing-context" title="browsing context">browsing contexts</a> that form part of
1.1172 mike 679: the user agent's interface, apart from the main content area.</p>
680:
681:
1.1246 sruby 682: <!--ADD-TOPIC:Security-->
1.1172 mike 683: <div class="impl">
1.1 mike 684:
1.877 mike 685: <h4 id="security-nav"><span class="secno">5.1.4 </span>Security</h4>
1.1 mike 686:
1.877 mike 687: <p id="security-1">A <a href="#browsing-context">browsing context</a> <var title="">A</var> is <dfn id="allowed-to-navigate">allowed to navigate</dfn> a second
688: <a href="#browsing-context">browsing context</a> <var title="">B</var> if one of the
689: following conditions is true:</p>
1.1 mike 690:
1.1246 sruby 691: <ul><li>Either the <a href="#origin-0">origin</a> of the <a href="#active-document">active
692: document</a> of <var title="">A</var> is the <a href="#same-origin" title="same
693: origin">same</a> as the <a href="#origin-0">origin</a> of the <a href="#active-document">active
1.1 mike 694: document</a> of <var title="">B</var>, or</li>
695:
696: <li>The browsing context <var title="">A</var> is a <a href="#nested-browsing-context">nested
1.1026 mike 697: browsing context</a> with a <a href="#top-level-browsing-context">top-level browsing
698: context</a>, and its <a href="#top-level-browsing-context">top-level browsing context</a> is
699: <var title="">B</var>, or</li>
1.1 mike 700:
701: <li>The browsing context <var title="">B</var> is an
702: <a href="#auxiliary-browsing-context">auxiliary browsing context</a> and <var title="">A</var>
703: is <a href="#allowed-to-navigate">allowed to navigate</a> <var title="">B</var>'s
704: <a href="#opener-browsing-context">opener browsing context</a>, or</li>
705:
706: <li>The browsing context <var title="">B</var> is not a
707: <a href="#top-level-browsing-context">top-level browsing context</a>, but there exists an
708: <a href="#ancestor-browsing-context">ancestor browsing context</a> of <var title="">B</var>
1.1246 sruby 709: whose <a href="#active-document">active document</a> has the <a href="#same-origin" title="same
710: origin">same</a> <a href="#origin-0">origin</a> as the <a href="#active-document">active
1.1 mike 711: document</a> of <var title="">A</var> (possibly in fact being
712: <var title="">A</var> itself).</li>
713:
1.414 mike 714: </ul><hr><p>An element has a <dfn id="browsing-context-scope-origin">browsing context scope origin</dfn> if its
1.1087 mike 715: <code><a href="dom.html#document">Document</a></code>'s <a href="#browsing-context">browsing context</a> is a
1.414 mike 716: <a href="#top-level-browsing-context">top-level browsing context</a> or if all of its
1.1087 mike 717: <code><a href="dom.html#document">Document</a></code>'s <a href="#ancestor-browsing-context" title="ancestor browsing
1.414 mike 718: context">ancestor browsing contexts</a> all have <a href="#active-document" title="active document">active documents</a> whose
1.1246 sruby 719: <a href="#origin-0">origin</a> are the <a href="#same-origin">same origin</a> as the
720: element's <code><a href="dom.html#document">Document</a></code>'s <a href="#origin-0">origin</a>. If an element
1.414 mike 721: has a <a href="#browsing-context-scope-origin">browsing context scope origin</a>, then its value is
1.1246 sruby 722: the <a href="#origin-0">origin</a> of the element's <code><a href="dom.html#document">Document</a></code>.</p>
1.414 mike 723:
1.1172 mike 724: </div>
1.1246 sruby 725: <!--REMOVE-TOPIC:Security-->
1.1172 mike 726:
727:
728: <div class="impl">
1.1 mike 729:
1.1004 mike 730: <h4 id="groupings-of-browsing-contexts"><span class="secno">5.1.5 </span>Groupings of browsing contexts</h4>
1.1 mike 731:
732: <p>Each <a href="#browsing-context">browsing context</a> is defined as having a list of
1.1004 mike 733: one or more <dfn id="directly-reachable-browsing-contexts">directly reachable browsing contexts</dfn>. These
1.1 mike 734: are:</p>
735:
1.1004 mike 736: <ul><li>The <a href="#browsing-context">browsing context</a> itself.</li>
737:
738: <li>All the <a href="#browsing-context">browsing context</a>'s <a href="#child-browsing-context" title="child
1.1 mike 739: browsing context">child browsing contexts</a>.</li>
740:
741: <li>The <a href="#browsing-context">browsing context</a>'s <a href="#parent-browsing-context">parent browsing
742: context</a>.</li>
743:
744: <li>All the <a href="#browsing-context" title="browsing context">browsing contexts</a>
745: that have the <a href="#browsing-context">browsing context</a> as their <a href="#opener-browsing-context">opener
746: browsing context</a>.</li>
747:
748: <li>The <a href="#browsing-context">browsing context</a>'s <a href="#opener-browsing-context">opener browsing
749: context</a>.</li>
750:
751: </ul><p>The transitive closure of all the <a href="#browsing-context" title="browsing
752: context">browsing contexts</a> that are <a href="#directly-reachable-browsing-contexts">directly reachable
753: browsing contexts</a> forms a <dfn id="unit-of-related-browsing-contexts">unit of related browsing
754: contexts</dfn>.</p>
755:
756: <p>Each <a href="#unit-of-related-browsing-contexts">unit of related browsing contexts</a> is then
757: further divided into the smallest number of groups such that every
1.1026 mike 758: member of each group has an <a href="#active-document">active document</a> with an
1.1246 sruby 759: <a href="#effective-script-origin">effective script origin</a> that, through appropriate
760: manipulation of the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute, could
1.1 mike 761: be made to be the same as other members of the group, but could not
762: be made the same as members of any other group. Each such group is a
763: <dfn id="unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing contexts</dfn>.</p>
764:
765: <p>Each <a href="#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing
1.1086 mike 766: contexts</a> can have an <dfn id="entry-script">entry script</dfn> which is used to
1.1246 sruby 767: obtain, amongst other things, the <a href="webappapis.html#script's-base-url">script's base URL</a> to
1.1064 mike 768: <a href="urls.html#resolve-a-url" title="resolve a url">resolve</a> relative <a href="urls.html#url" title="URL">URLs</a> used in scripts running in that <a href="#unit-of-related-similar-origin-browsing-contexts">unit
1.1 mike 769: of related similar-origin browsing contexts</a>. Initially, there
1.997 mike 770: is no <a href="#entry-script">entry script</a>. It is changed by the <a href="webappapis.html#jump-to-a-code-entry-point">jump to
771: a code entry-point</a> algorithm.</p>
1.1 mike 772:
1.1165 mike 773: <p>Each <a href="#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing
774: contexts</a> also has a <dfn id="running-mutation-observers">running mutation observers</dfn>
775: flag, which must initially be false. It is used to prevent reentrant
776: invocation of the algorithm to <a href="infrastructure.html#concept-mo-invoke" title="concept-mo-invoke">invoke <code>MutationObserver</code>
777: objects</a>. For the purposes of <code><a href="infrastructure.html#mutationobserver">MutationObserver</a></code>
778: objects, each <a href="#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing
779: contexts</a> is a distinct <var title="MutationObserver scripting
780: environment"><a href="infrastructure.html#mutationobserver-scripting-environment">scripting environment</a></var>.</p>
781:
782: <p class="note">There is also at most one <a href="webappapis.html#event-loop">event loop</a>
783: per <a href="#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing contexts</a>
784: (though several <a href="#unit-of-related-similar-origin-browsing-contexts" title="unit of related similar-origin browsing
785: contexts">units of related similar-origin browsing contexts</a>
786: can have a shared <a href="webappapis.html#event-loop">event loop</a>).</p>
1.213 mike 787:
1.1172 mike 788: </div>
789:
790:
791:
792: <h4 id="browsing-context-names"><span class="secno">5.1.6 </span>Browsing context names</h4>
793:
794: <p>Browsing contexts can have a <dfn id="browsing-context-name">browsing context name</dfn>. By
795: default, a browsing context has no name (its name is not set).</p>
796:
797: <p>A <dfn id="valid-browsing-context-name">valid browsing context name</dfn> is any string with at
1.1 mike 798: least one character that does not start with a U+005F LOW LINE
799: character. (Names starting with an underscore are reserved for
1.1172 mike 800: special keywords.)</p>
801:
802: <p>A <dfn id="valid-browsing-context-name-or-keyword">valid browsing context name or keyword</dfn> is any string
1.1 mike 803: that is either a <a href="#valid-browsing-context-name">valid browsing context name</a> or that is
1.1172 mike 804: an <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a> match for one of: <code title="">_blank</code>, <code title="">_self</code>, <code title="">_parent</code>, or <code title="">_top</code>.</p>
805:
806: <p>These values have different meanings based on whether the page is
1.1051 mike 807: sandboxed or not, as summarized in the following (non-normative)
808: table. In this table, "current" means the <a href="#browsing-context">browsing
809: context</a> that the link or script is in, "parent" means the
810: <a href="#parent-browsing-context">parent browsing context</a> of the one the link or script
811: is in, "master" means the nearest <a href="#ancestor-browsing-context">ancestor browsing
812: context</a> of the one the link or script is in that is not
1.1064 mike 813: itself in a <a href="the-iframe-element.html#attr-iframe-seamless" title="attr-iframe-seamless">seamless
1.1051 mike 814: iframe</a>, "top" means the <a href="#top-level-browsing-context">top-level browsing
815: context</a> of the one the link or script is in, "new" means a
816: new <a href="#top-level-browsing-context">top-level browsing context</a> or <a href="#auxiliary-browsing-context">auxiliary
817: browsing context</a> is to be created, subject to various user
1.1196 mike 818: preferences and user agent policies, "none" means that nothing will
1.1246 sruby 819: happen, and "maybe new" means the same as "new" if the "<code title="attr-iframe-sandbox-allow-popups"><a href="#attr-iframe-sandbox-allow-popups">allow-popups</a></code>"
1.1196 mike 820: keyword is also specified on the <code title="attr-iframe-sandbox"><a href="the-iframe-element.html#attr-iframe-sandbox">sandbox</a></code> attribute (or if the user
821: overrode the sandboxing), and the same as "none" otherwise.</p>
1.1172 mike 822:
823: <table><thead><tr><th rowspan="2">Keyword
1.1051 mike 824: </th><th rowspan="2">Ordinary effect
1.1064 mike 825: </th><th colspan="5">Effect in an <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code> with...
1.1246 sruby 826: </th></tr><tr><!-- nothing --><th><code title="">seamless=""</code>
1.1051 mike 827: </th><th><code title="">sandbox=""</code>
828: </th><th><code title="">sandbox="" seamless=""</code>
829: </th><th><code title="">sandbox="allow-top-navigation"</code>
830: </th><th><code title="">sandbox="allow-top-navigation" seamless=""</code>
831:
1.1246 sruby 832: </th></tr></thead><tbody><tr><td>none specified, for links and form submissions <!-- same as empty string -->
1.1051 mike 833: </td><td>current
834: </td><td>master
835: </td><td>current
836: </td><td>master
837: </td><td>current
838: </td><td>master
839:
1.1246 sruby 840: </td></tr><tr><td>none specified, for <code title="dom-open"><a href="#dom-open">window.open()</a></code> <!-- same as _blank -->
1.1051 mike 841: </td><td>new
842: </td><td>new
843: </td><td>maybe new†
844: </td><td>maybe new†
845: </td><td>maybe new†
846: </td><td>maybe new†
847:
848: </td></tr><tr><td>empty string
849: </td><td>current
850: </td><td>master
851: </td><td>current
852: </td><td>master
853: </td><td>current
854: </td><td>master
855:
856: </td></tr><tr><td><code title="">_blank</code>
857: </td><td>new
858: </td><td>new
859: </td><td>maybe new
860: </td><td>maybe new
861: </td><td>maybe new
862: </td><td>maybe new
863:
864: </td></tr><tr><td><code title="">_self</code>
865: </td><td>current
866: </td><td>current
867: </td><td>current
868: </td><td>current
869: </td><td>current
870: </td><td>current
871:
872: </td></tr><tr><td><code title="">_parent</code> if there isn't a parent
873: </td><td>current
874: </td><td>current
875: </td><td>current
876: </td><td>current
877: </td><td>current
878: </td><td>current
879:
880: </td></tr><tr><td><code title="">_parent</code> if parent is also top
881: </td><td>parent/top
882: </td><td>parent/top
883: </td><td>none
884: </td><td>none
885: </td><td>parent/top
886: </td><td>parent/top
887:
888: </td></tr><tr><td><code title="">_parent</code> if there is one and it's not top
889: </td><td>parent
890: </td><td>parent
891: </td><td>none
892: </td><td>none
893: </td><td>none
894: </td><td>none
895:
896: </td></tr><tr><td><code title="">_top</code> if top is current
897: </td><td>current
898: </td><td>current
899: </td><td>current
900: </td><td>current
901: </td><td>current
902: </td><td>current
903:
904: </td></tr><tr><td><code title="">_top</code> if top is not current
905: </td><td>top
906: </td><td>top
907: </td><td>none
908: </td><td>none
909: </td><td>top
910: </td><td>top
911:
912: </td></tr><tr><td>name that doesn't exist
913: </td><td>new
914: </td><td>new
915: </td><td>maybe new
916: </td><td>maybe new
917: </td><td>maybe new
918: </td><td>maybe new
919:
920: </td></tr><tr><td>name that exists and is a descendant
921: </td><td>specified descendant
922: </td><td>specified descendant
923: </td><td>specified descendant
924: </td><td>specified descendant
925: </td><td>specified descendant
926: </td><td>specified descendant
927:
928: </td></tr><tr><td>name that exists and is current
929: </td><td>current
930: </td><td>current
931: </td><td>current
932: </td><td>current
933: </td><td>current
934: </td><td>current
935:
1.1086 mike 936: </td></tr><tr><td>name that exists and is an ancestor that is top
1.1051 mike 937: </td><td>specified ancestor
938: </td><td>specified ancestor
939: </td><td>none
940: </td><td>none
941: </td><td>specified ancestor/top
942: </td><td>specified ancestor/top
943:
1.1086 mike 944: </td></tr><tr><td>name that exists and is an ancestor that is not top
1.1051 mike 945: </td><td>specified ancestor
946: </td><td>specified ancestor
947: </td><td>none
948: </td><td>none
949: </td><td>none
950: </td><td>none
951:
1.1064 mike 952: </td></tr></tbody></table><p><small>† This case is only possible if the <code title="attr-iframe-sandbox"><a href="the-iframe-element.html#attr-iframe-sandbox">sandbox</a></code> attribute also allows
1.1172 mike 953: scripts.</small></p>
954:
955: <div class="impl">
1.1 mike 956:
1.1084 mike 957: <hr><p>An algorithm is <dfn id="allowed-to-show-a-pop-up">allowed to show a pop-up</dfn> if, in the
958: <a href="webappapis.html#concept-task" title="concept-task">task</a> in which the algorithm is
959: running, either:</p>
960:
961: <ul class="brief"><li>an <a href="content-models.html#activation-behavior">activation behavior</a> is currently being
962: processed whose <code title="event-click"><a href="infrastructure.html#event-click">click</a></code> event was
963: <a href="infrastructure.html#concept-events-trusted" title="concept-events-trusted">trusted</a>, or</li>
1.1079 mike 964:
1.1084 mike 965: <li>the event listener for a <a href="infrastructure.html#concept-events-trusted" title="concept-events-trusted">trusted</a> <code title="event-click"><a href="infrastructure.html#event-click">click</a></code> event is being handled.</li>
1.1079 mike 966:
967: </ul><hr><p><dfn id="the-rules-for-choosing-a-browsing-context-given-a-browsing-context-name">The rules for choosing a browsing context given a browsing
1.1 mike 968: context name</dfn> are as follows. The rules assume that they are
969: being applied in the context of a <a href="#browsing-context">browsing context</a>.</p>
970:
1.1029 mike 971: <ol><li>
972:
973: <p>If the given browsing context name is the empty string or <code title="">_self</code>, then the chosen browsing context must be
974: the current one.</p>
975:
1.1259 sruby 976: <p>If the given browsing context name is <code title="">_self</code>, then this is an <a href="history.html#explicit-self-navigation-override">explicit
977: self-navigation override</a>, which overrides the behavior of
1.1064 mike 978: the <a href="the-iframe-element.html#seamless-browsing-context-flag">seamless browsing context flag</a> set by the <code title="attr-iframe-seamless"><a href="the-iframe-element.html#attr-iframe-seamless">seamless</a></code> attribute on
979: <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code> elements.</p>
1.1029 mike 980:
981: </li>
1.1 mike 982:
983: <li><p>If the given browsing context name is <code title="">_parent</code>, then the chosen browsing context must be
984: the <a href="#parent-browsing-context"><em>parent</em> browsing context</a> of the current
985: one, unless there isn't one, in which case the chosen browsing
986: context must be the current browsing context.</p></li>
987:
988: <li><p>If the given browsing context name is <code title="">_top</code>, then the chosen browsing context must be the
1.1026 mike 989: <a href="#top-level-browsing-context">top-level browsing context</a> of the current one, if
990: there is one, or else the current browsing context.</p></li>
1.1 mike 991:
992: <li>
993:
994: <p>If the given browsing context name is not <code title="">_blank</code> and there exists a browsing context whose
995: <a href="#browsing-context-name" title="browsing context name">name</a> is the same as the
996: given browsing context name, and the current browsing context is
997: <a href="#allowed-to-navigate">allowed to navigate</a> that browsing context, and the
998: user agent determines that the two browsing contexts are related
999: enough that it is ok if they reach each other, then that browsing
1000: context must be the chosen one. If there are multiple matching
1001: browsing contexts, the user agent should select one in some
1002: arbitrary consistent manner, such as the most recently opened,
1003: most recently focused, or more closely related.</p>
1004:
1.1000 mike 1005: <p>If the browsing context is chosen by this step to be the
1.1259 sruby 1006: current browsing context, then this is also an <a href="history.html#explicit-self-navigation-override">explicit
1.1000 mike 1007: self-navigation override</a>.</p>
1008:
1.1 mike 1009: </li>
1010:
1011: <li>
1012:
1013: <p>Otherwise, a new browsing context is being requested, and what
1.1053 mike 1014: happens depends on the user agent's configuration and/or abilities
1015: — it is determined by the rules given for the first
1016: applicable option from the following list:</p>
1.1 mike 1017:
1.1195 mike 1018: <dl class="switch"><dt id="sandboxWindowOpen">If the current browsing context's
1.1246 sruby 1019: <a href="#active-document">active document</a>'s <a href="#active-sandboxing-flag-set">active sandboxing flag
1020: set</a> has the <a href="#sandboxed-auxiliary-navigation-browsing-context-flag">sandboxed auxiliary navigation browsing
1.1196 mike 1021: context flag</a> set.</dt>
1.1 mike 1022:
1.1196 mike 1023: <dd>
1024:
1025: <p>Typically, there is no chosen browsing context.</p>
1026:
1027: <p>The user agent may offer to create a new <a href="#top-level-browsing-context">top-level
1028: browsing context</a> or reuse an existing <a href="#top-level-browsing-context">top-level
1029: browsing context</a>. If the user picks one of those options,
1030: then the designated browsing context must be the chosen one (the
1031: browsing context's name isn't set to the given browsing context
1032: name). The default behaviour (if the user agent doesn't offer
1033: the option to the user, or if the user declines to allow a
1034: browsing context to be used) must be that there must not be a
1035: chosen browsing context.</p>
1036:
1037: <p class="warning">If this case occurs, it means that an author
1038: has explicitly sandboxed the document that is trying to open a
1039: link.</p>
1040:
1041: </dd>
1.1 mike 1042:
1.730 mike 1043:
1.1 mike 1044: <dt id="noopener">If the user agent has been configured such that
1045: in this instance it will create a new browsing context, and the
1.1246 sruby 1046: browsing context is being requested as part of <a href="links.html#following-hyperlinks-0" title="following hyperlinks">following a hyperlink</a> whose
1.1064 mike 1047: <a href="links.html#linkTypes">link types</a> include the <code title="rel-noreferrer"><a href="links.html#link-type-noreferrer">noreferrer</a></code> keyword</dt>
1.1 mike 1048:
1049: <dd><p>A new <a href="#top-level-browsing-context">top-level browsing context</a> must be
1050: created. If the given browsing context name is not <code title="">_blank</code>, then the new top-level browsing context's
1051: name must be the given browsing context name (otherwise, it has
1052: no name). The chosen browsing context must be this new browsing
1053: context.</p>
1054:
1055: <p class="note">If it is immediately <a href="history.html#navigate" title="navigate">navigated</a>, then the navigation will be
1056: done with <a href="history.html#replacement-enabled">replacement enabled</a>.</p></dd>
1057:
1.730 mike 1058:
1.1 mike 1059: <dt>If the user agent has been configured such that in this
1.1064 mike 1060: instance it will create a new browsing context, and the <code title="rel-noreferrer"><a href="links.html#link-type-noreferrer">noreferrer</a></code> keyword doesn't
1.1 mike 1061: apply</dt>
1062:
1063: <dd><p>A new <a href="#auxiliary-browsing-context">auxiliary browsing context</a> must be
1064: created, with the <a href="#opener-browsing-context">opener browsing context</a> being the
1065: current one. If the given browsing context name is not <code title="">_blank</code>, then the new auxiliary browsing context's
1066: name must be the given browsing context name (otherwise, it has
1067: no name). The chosen browsing context must be this new browsing
1068: context.</p>
1069:
1.1022 mike 1070: <p class="note">If it is immediately <a href="history.html#navigate" title="navigate">navigated</a>, then the navigation will be
1071: done with <a href="history.html#replacement-enabled">replacement enabled</a>.</p></dd>
1.1 mike 1072:
1.730 mike 1073:
1.1 mike 1074: <dt>If the user agent has been configured such that in this
1075: instance it will reuse the current browsing context</dt>
1076:
1077: <dd><p>The chosen browsing context is the current browsing
1078: context.</p></dd>
1079:
1.730 mike 1080:
1.1 mike 1081: <dt>If the user agent has been configured such that in this
1082: instance it will not find a browsing context</dt>
1083:
1084: <dd><p>There must not be a chosen browsing context.</p></dd>
1085:
1086: </dl><p>User agent implementors are encouraged to provide a way for
1087: users to configure the user agent to always reuse the current
1088: browsing context.</p>
1089:
1.1196 mike 1090: <p>If the current browsing context's <a href="#active-document">active
1.1246 sruby 1091: document</a>'s <a href="#active-sandboxing-flag-set">active sandboxing flag set</a> has the
1092: <a href="#sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context flag</a> set and
1.1196 mike 1093: chosen browsing context picked above, if any, is a new browsing
1094: context (whether top-level or auxiliary), then all the flags that
1095: are set in the current browsing context's <a href="#active-document">active
1.1246 sruby 1096: document</a>'s <a href="#active-sandboxing-flag-set">active sandboxing flag set</a> when the
1.1196 mike 1097: new browsing context is created must be set in the new browsing
1.1246 sruby 1098: context's <a href="#popup-sandboxing-flag-set">popup sandboxing flag set</a>, and the current
1.1196 mike 1099: browsing context must be set as the new browsing context's
1.1246 sruby 1100: <a href="#one-permitted-sandboxed-navigator">one permitted sandboxed navigator</a>.</p>
1.1196 mike 1101:
1.1 mike 1102: </li>
1103:
1.1172 mike 1104: </ol></div>
1105:
1106:
1107:
1.1246 sruby 1108: <!--TOPIC:DOM APIs-->
1.1172 mike 1109: <h3 id="the-window-object"><span class="secno">5.2 </span>The <code><a href="#window">Window</a></code> object</h3>
1110:
1.1228 mike 1111: <pre class="idl">[NamedPropertiesObject]
1.1061 mike 1112: interface <dfn id="window">Window</dfn> : <a href="infrastructure.html#eventtarget">EventTarget</a> {
1.1 mike 1113: // the current browsing context
1.1071 mike 1114: [Unforgeable] readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-window" title="dom-window">window</a>;
1.1072 mike 1115: [Replaceable] readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-self" title="dom-self">self</a>;
1.1087 mike 1116: [Unforgeable] readonly attribute <a href="dom.html#document">Document</a> <a href="#dom-document-0" title="dom-document">document</a>;
1.1246 sruby 1117: attribute DOMString <a href="#dom-name" title="dom-name">name</a>; <!-- not [Replaceable] per WebKit and IE8 -->
1.1071 mike 1118: [PutForwards=<a href="history.html#dom-location-href" title="dom-location-href">href</a>, Unforgeable] readonly attribute <a href="history.html#location">Location</a> <a href="history.html#dom-location" title="dom-location">location</a>;
1.1246 sruby 1119: readonly attribute <a href="history.html#history-1">History</a> <a href="history.html#dom-history" title="dom-history">history</a>;
1120: <!--FIND-->
1.1 mike 1121: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-locationbar" title="dom-window-locationbar">locationbar</a>;
1122: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-menubar" title="dom-window-menubar">menubar</a>;
1123: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-personalbar" title="dom-window-personalbar">personalbar</a>;
1124: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-scrollbars" title="dom-window-scrollbars">scrollbars</a>;
1125: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-statusbar" title="dom-window-statusbar">statusbar</a>;
1.1246 sruby 1126: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-toolbar" title="dom-window-toolbar">toolbar</a>;<!--
1127: [Replaceable] readonly attribute <span>BarProp</span> <span title="dom-window-directories">directories</span>; // legacy (Gecko-only) -->
1.1091 mike 1128: attribute DOMString <a href="#dom-window-status" title="dom-window-status">status</a>;
1.1049 mike 1129: void <a href="#dom-window-close" title="dom-window-close">close</a>();
1.947 mike 1130: void <a href="#dom-window-stop" title="dom-window-stop">stop</a>();
1.1067 mike 1131: void <a href="editing.html#dom-window-focus" title="dom-window-focus">focus</a>();
1132: void <a href="editing.html#dom-window-blur" title="dom-window-blur">blur</a>();
1.1 mike 1133:
1134: // other browsing contexts
1.190 mike 1135: [Replaceable] readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-frames" title="dom-frames">frames</a>;
1136: [Replaceable] readonly attribute unsigned long <a href="#dom-length" title="dom-length">length</a>;
1.1071 mike 1137: [Unforgeable] readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-top" title="dom-top">top</a>;
1.1135 mike 1138: attribute <a href="#windowproxy">WindowProxy</a>? <a href="#dom-opener" title="dom-opener">opener</a>;
1.1 mike 1139: readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-parent" title="dom-parent">parent</a>;
1.1052 mike 1140: readonly attribute <a href="infrastructure.html#element">Element</a>? <a href="#dom-frameelement" title="dom-frameElement">frameElement</a>;
1.1074 mike 1141: <a href="#windowproxy">WindowProxy</a> <a href="#dom-open" title="dom-open">open</a>(optional DOMString url, optional DOMString target, optional DOMString features, optional boolean replace);
1.1067 mike 1142: <a href="#dom-window-item" title="dom-window-item">getter</a> <a href="#windowproxy">WindowProxy</a> (unsigned long index);
1143: <a href="#dom-window-nameditem" title="dom-window-namedItem">getter</a> object (DOMString name);
1.1 mike 1144:
1145: // the user agent
1.1246 sruby 1146: readonly attribute <a href="system-state-and-capabilities.html#navigator">Navigator</a> <a href="system-state-and-capabilities.html#dom-navigator" title="dom-navigator">navigator</a>; <!-- IE also has window.clientInformation === window.navigator -->
1.1088 mike 1147: readonly attribute <a href="system-state-and-capabilities.html#external">External</a> <a href="system-state-and-capabilities.html#dom-external" title="dom-external">external</a>;
1.1 mike 1148: readonly attribute <a href="offline.html#applicationcache">ApplicationCache</a> <a href="offline.html#dom-applicationcache" title="dom-applicationCache">applicationCache</a>;
1149:
1150: // user prompts
1.1088 mike 1151: void <a href="user-prompts.html#dom-alert" title="dom-alert">alert</a>(DOMString message);
1152: boolean <a href="user-prompts.html#dom-confirm" title="dom-confirm">confirm</a>(DOMString message);
1153: DOMString? <a href="user-prompts.html#dom-prompt" title="dom-prompt">prompt</a>(DOMString message, optional DOMString default);
1154: void <a href="user-prompts.html#dom-print" title="dom-print">print</a>();
1.1246 sruby 1155: any <a href="user-prompts.html#dom-showmodaldialog" title="dom-showModalDialog">showModalDialog</a>(DOMString url, optional any argument<!--, optional DOMString features-->);
1.794 mike 1156:
1.1246 sruby 1157: <!--POSTMSG-->
1.794 mike 1158: // <a href="webappapis.html#event-handler-idl-attributes">event handler IDL attributes</a>
1.1245 mike 1159: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onabort" title="handler-onabort">onabort</a>;
1160: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onafterprint" title="handler-window-onafterprint">onafterprint</a>;
1161: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onbeforeprint" title="handler-window-onbeforeprint">onbeforeprint</a>;
1162: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onbeforeunload" title="handler-window-onbeforeunload">onbeforeunload</a>;
1163: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onblur" title="handler-window-onblur">onblur</a>;
1164: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-oncancel" title="handler-oncancel">oncancel</a>;
1165: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-oncanplay" title="handler-oncanplay">oncanplay</a>;
1166: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-oncanplaythrough" title="handler-oncanplaythrough">oncanplaythrough</a>;
1167: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onchange" title="handler-onchange">onchange</a>;
1168: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onclick" title="handler-onclick">onclick</a>;
1169: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onclose" title="handler-onclose">onclose</a>;
1170: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-oncontextmenu" title="handler-oncontextmenu">oncontextmenu</a>;
1171: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-oncuechange" title="handler-oncuechange">oncuechange</a>;
1172: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-ondblclick" title="handler-ondblclick">ondblclick</a>;
1173: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-ondrag" title="handler-ondrag">ondrag</a>;
1174: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-ondragend" title="handler-ondragend">ondragend</a>;
1175: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-ondragenter" title="handler-ondragenter">ondragenter</a>;
1176: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-ondragleave" title="handler-ondragleave">ondragleave</a>;
1177: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-ondragover" title="handler-ondragover">ondragover</a>;
1178: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-ondragstart" title="handler-ondragstart">ondragstart</a>;
1179: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-ondrop" title="handler-ondrop">ondrop</a>;
1180: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-ondurationchange" title="handler-ondurationchange">ondurationchange</a>;
1181: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onemptied" title="handler-onemptied">onemptied</a>;
1182: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onended" title="handler-onended">onended</a>;
1183: attribute <a href="webappapis.html#onerroreventhandler">OnErrorEventHandler</a> <a href="webappapis.html#handler-window-onerror" title="handler-window-onerror">onerror</a>;
1184: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onfocus" title="handler-window-onfocus">onfocus</a>;
1185: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onhashchange" title="handler-window-onhashchange">onhashchange</a>;
1186: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-oninput" title="handler-oninput">oninput</a>;
1187: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-oninvalid" title="handler-oninvalid">oninvalid</a>;
1188: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onkeydown" title="handler-onkeydown">onkeydown</a>;
1189: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onkeypress" title="handler-onkeypress">onkeypress</a>;
1190: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onkeyup" title="handler-onkeyup">onkeyup</a>;
1191: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onload" title="handler-window-onload">onload</a>;
1192: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onloadeddata" title="handler-onloadeddata">onloadeddata</a>;
1193: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onloadedmetadata" title="handler-onloadedmetadata">onloadedmetadata</a>;
1194: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onloadstart" title="handler-onloadstart">onloadstart</a>;
1195: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onmessage" title="handler-window-onmessage">onmessage</a>;
1196: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onmousedown" title="handler-onmousedown">onmousedown</a>;
1197: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onmousemove" title="handler-onmousemove">onmousemove</a>;
1198: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onmouseout" title="handler-onmouseout">onmouseout</a>;
1199: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onmouseover" title="handler-onmouseover">onmouseover</a>;
1200: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onmouseup" title="handler-onmouseup">onmouseup</a>;
1201: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onmousewheel" title="handler-onmousewheel">onmousewheel</a>;
1202: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onoffline" title="handler-window-onoffline">onoffline</a>;
1203: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-ononline" title="handler-window-ononline">ononline</a>;
1204: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onpause" title="handler-onpause">onpause</a>;
1205: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onplay" title="handler-onplay">onplay</a>;
1206: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onplaying" title="handler-onplaying">onplaying</a>;
1207: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onpagehide" title="handler-window-onpagehide">onpagehide</a>;
1208: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onpageshow" title="handler-window-onpageshow">onpageshow</a>;
1209: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onpopstate" title="handler-window-onpopstate">onpopstate</a>;
1210: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onprogress" title="handler-onprogress">onprogress</a>;
1211: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onratechange" title="handler-onratechange">onratechange</a>;
1212: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onreset" title="handler-onreset">onreset</a>;
1213: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onresize" title="handler-window-onresize">onresize</a>;
1214: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onscroll" title="handler-onscroll">onscroll</a>;
1215: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onseeked" title="handler-onseeked">onseeked</a>;
1216: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onseeking" title="handler-onseeking">onseeking</a>;
1217: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onselect" title="handler-onselect">onselect</a>;
1218: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onshow" title="handler-onshow">onshow</a>;
1219: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onstalled" title="handler-onstalled">onstalled</a>;
1220: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onstorage" title="handler-window-onstorage">onstorage</a>;
1221: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onsubmit" title="handler-onsubmit">onsubmit</a>;
1222: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onsuspend" title="handler-onsuspend">onsuspend</a>;
1223: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-ontimeupdate" title="handler-ontimeupdate">ontimeupdate</a>;
1224: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-window-onunload" title="handler-window-onunload">onunload</a>;
1225: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onvolumechange" title="handler-onvolumechange">onvolumechange</a>;
1226: attribute <a href="webappapis.html#eventhandler">EventHandler</a> <a href="webappapis.html#handler-onwaiting" title="handler-onwaiting">onwaiting</a>;
1.1172 mike 1227: };</pre>
1228:
1.1246 sruby 1229: <!-- for more features to add here, look here:
1230: http://msdn.microsoft.com/workshop/author/dhtml/reference/objects/obj_window.asp
1231: http://www.mozilla.org/docs/dom/domref/dom_window_ref.html
1232: http://lxr.mozilla.org/mozilla/source/dom/public/idl/base/nsIDOMWindow.idl - scrollBy, etc
1233: http://lxr.mozilla.org/mozilla/source/dom/public/idl/base/nsIDOMWindowInternal.idl - DOM level 0
1234: -->
1.1172 mike 1235:
1236: <dl class="domintro"><dt><var title="">window</var> . <code title="dom-window"><a href="#dom-window">window</a></code></dt>
1.1 mike 1237: <dt><var title="">window</var> . <code title="dom-frames"><a href="#dom-frames">frames</a></code></dt>
1238: <dt><var title="">window</var> . <code title="dom-self"><a href="#dom-self">self</a></code></dt>
1239:
1240: <dd>
1241:
1242: <p>These attributes all return <var title="">window</var>.</p>
1243:
1244: </dd>
1245:
1.881 mike 1246:
1.1087 mike 1247: <dt><var title="">window</var> . <code title="dom-document"><a href="#dom-document-0">document</a></code></dt>
1.881 mike 1248:
1249: <dd>
1250:
1251: <p>Returns the <a href="#active-document">active document</a>.</p>
1252:
1253: </dd>
1254:
1255:
1256: <dt><var title="">document</var> . <code title="dom-document-defaultView"><a href="#dom-document-defaultview">defaultView</a></code></dt>
1257:
1258: <dd>
1259:
1260: <p>Returns the <code><a href="#window">Window</a></code> object of the <a href="#active-document">active document</a>.</p>
1261:
1262: </dd>
1263:
1.1 mike 1264: </dl><div class="impl">
1265:
1.1267 sruby 1266: <p>The <code><a href="#window">Window</a></code> interface must only be <a href="infrastructure.html#expose" title="expose">exposed</a> if the <a href="infrastructure.html#javascript-global-environment">JavaScript global
1267: environment</a> is a <a href="webappapis.html#document-environment">document environment</a>.</p>
1.1087 mike 1268:
1.192 mike 1269: <p>The <dfn id="dom-window" title="dom-window"><code>window</code></dfn>, <dfn id="dom-frames" title="dom-frames"><code>frames</code></dfn>, and <dfn id="dom-self" title="dom-self"><code>self</code></dfn> IDL attributes must all
1.1 mike 1270: return the <code><a href="#window">Window</a></code> object's <a href="#browsing-context">browsing
1271: context</a>'s <code><a href="#windowproxy">WindowProxy</a></code> object.</p>
1272:
1.1087 mike 1273: <p>The <dfn id="dom-document-0" title="dom-document"><code>document</code></dfn> IDL
1274: attribute must return the <code><a href="dom.html#document">Document</a></code> object of the
1275: <code><a href="#window">Window</a></code> object's <code><a href="dom.html#document">Document</a></code>'s <a href="#browsing-context">browsing
1.881 mike 1276: context</a>'s <a href="#active-document">active document</a>.</p>
1277:
1278: <p>The <dfn id="dom-document-defaultview" title="dom-document-defaultView"><code>defaultView</code></dfn> IDL
1.1087 mike 1279: attribute of the <code><a href="dom.html#document">Document</a></code> interface must return the
1280: <code><a href="dom.html#document">Document</a></code>'s <a href="#browsing-context">browsing context</a>'s
1.1004 mike 1281: <code><a href="#windowproxy">WindowProxy</a></code> object, if there is one, or null
1282: otherwise.</p>
1.881 mike 1283:
1.1085 mike 1284: <hr><p>For historical reasons, <code><a href="#window">Window</a></code> objects must also
1285: have a writable, configurable, non-enumerable property named
1286: <dfn id="htmldocument"><code>HTMLDocument</code></dfn> whose value is the
1.1087 mike 1287: <code><a href="dom.html#document">Document</a></code> interface object.</p>
1.1082 mike 1288:
1.1172 mike 1289: </div>
1290:
1291:
1.1246 sruby 1292: <!--ADD-TOPIC:Security-->
1.1172 mike 1293: <div class="impl">
1.1 mike 1294:
1.877 mike 1295: <h4 id="security-window"><span class="secno">5.2.1 </span>Security</h4>
1.1 mike 1296:
1.1076 mike 1297: <p id="security-2">User agents must throw a
1298: <code><a href="infrastructure.html#securityerror">SecurityError</a></code> exception whenever any properties of a
1.877 mike 1299: <code><a href="#window">Window</a></code> object are accessed by scripts whose
1.1246 sruby 1300: <a href="#effective-script-origin">effective script origin</a> is not the same as the
1301: <code><a href="#window">Window</a></code> object's <code><a href="dom.html#document">Document</a></code>'s <a href="#effective-script-origin">effective
1.877 mike 1302: script origin</a>, with the following exceptions:</p>
1.1 mike 1303:
1.1054 mike 1304: <ul><li>The <code title="dom-location"><a href="history.html#dom-location">location</a></code> attribute
1.1 mike 1305:
1.923 mike 1306: </li><li>The <code title="dom-window-postMessage">postMessage()</code> method
1.1 mike 1307:
1308: </li><li>The <code title="dom-frames"><a href="#dom-frames">frames</a></code> attribute
1309:
1310: </li><li>The <a href="#dynamic-nested-browsing-context-properties">dynamic nested browsing context properties</a>
1311:
1.1246 sruby 1312: </li></ul><p>When a script whose <a href="#effective-script-origin">effective script origin</a> is not
1.1087 mike 1313: the same as the <code><a href="#window">Window</a></code> object's <code><a href="dom.html#document">Document</a></code>'s
1.1246 sruby 1314: <a href="#effective-script-origin">effective script origin</a> attempts to access that
1.138 mike 1315: <code><a href="#window">Window</a></code> object's methods or attributes, the user agent
1316: must act as if any changes to the <code><a href="#window">Window</a></code> object's
1317: properties, getters, setters, etc, were not present.</p>
1318:
1319: <p>For members that return objects (including function objects),
1.1246 sruby 1320: each distinct <a href="#effective-script-origin">effective script origin</a> that is not the
1.1087 mike 1321: same as the <code><a href="#window">Window</a></code> object's <code><a href="dom.html#document">Document</a></code>'s
1.1246 sruby 1322: <a href="#effective-script-origin">effective script origin</a> must be provided with a
1.138 mike 1323: separate set of objects. These objects must have the prototype chain
1324: appropriate for the script for which the objects are created (not
1.1246 sruby 1325: those that would be appropriate for scripts whose <a href="webappapis.html#script's-global-object">script's
1.138 mike 1326: global object</a> is the <code><a href="#window">Window</a></code> object in
1327: question).</p>
1328:
1329: <div class="example">
1330:
1.1087 mike 1331: <p>For instance, if two frames containing <code><a href="dom.html#document">Document</a></code>s
1.1246 sruby 1332: from different <a href="#origin-0" title="origin">origins</a> access the same
1.923 mike 1333: <code><a href="#window">Window</a></code> object's <code title="dom-window-postMessage">postMessage()</code> method, they
1.138 mike 1334: will get distinct objects that are not equal.</p>
1335:
1336: </div>
1.1 mike 1337:
1.1172 mike 1338: </div>
1.1246 sruby 1339: <!--REMOVE-TOPIC:Security-->
1.1172 mike 1340:
1341:
1342:
1343: <h4 id="apis-for-creating-and-navigating-browsing-contexts-by-name"><span class="secno">5.2.2 </span>APIs for creating and navigating browsing contexts by name</h4>
1344:
1345: <dl class="domintro"><dt><var title="">window</var> = <var title="">window</var> . <code title="dom-open"><a href="#dom-open">open</a></code>( [ <var title="">url</var> [, <var title="">target</var> [, <var title="">features</var> [, <var title="">replace</var> ] ] ] ] )</dt>
1.1 mike 1346:
1347: <dd>
1348:
1349: <p>Opens a window to show <var title="">url</var> (defaults to
1.1088 mike 1350: <code><a href="urls.html#about:blank">about:blank</a></code>), and returns it. The <var title="">target</var> argument gives the name of the new
1.1 mike 1351: window. If a window exists with that name already, it is
1352: reused. The <var title="">replace</var> attribute, if true, means
1353: that whatever page is currently open in that window will be
1354: removed from the window's session history. The <var title="">features</var> argument is ignored.</p>
1355:
1356: </dd>
1357:
1358: <dt><var title="">window</var> . <code title="dom-name"><a href="#dom-name">name</a></code> [ = <var title="">value</var> ]</dt>
1359:
1360: <dd>
1361:
1362: <p>Returns the name of the window.</p>
1363:
1364: <p>Can be set, to change the name.</p>
1365:
1366: </dd>
1367:
1.947 mike 1368: <dt><var title="">window</var> . <code title="dom-window-close"><a href="#dom-window-close">close</a></code>()</dt>
1.1 mike 1369:
1370: <dd>
1371:
1372: <p>Closes the window.</p>
1373:
1374: </dd>
1375:
1.947 mike 1376: <dt><var title="">window</var> . <code title="dom-window-stop"><a href="#dom-window-stop">stop</a></code>()</dt>
1377:
1378: <dd>
1379:
1380: <p>Cancels the document load.</p>
1381:
1382: </dd>
1383:
1.1 mike 1384: </dl><div class="impl">
1385:
1.1246 sruby 1386: <!-- This whole section should be rewritten to use algorithmic style -->
1.1079 mike 1387:
1.1 mike 1388: <p>The <dfn id="dom-open" title="dom-open"><code>open()</code></dfn> method on
1389: <code><a href="#window">Window</a></code> objects provides a mechanism for <a href="history.html#navigate" title="navigate">navigating</a> an existing <a href="#browsing-context">browsing
1390: context</a> or opening and navigating an <a href="#auxiliary-browsing-context">auxiliary browsing
1391: context</a>.</p>
1392:
1393: <p>The method has four arguments, though they are all optional.</p>
1394:
1395: <p>The first argument, <var title="">url</var>, must be a
1.1064 mike 1396: <a href="urls.html#valid-non-empty-url">valid non-empty URL</a> for a page to load in the browsing
1.1 mike 1397: context. If no arguments are provided, or if the first argument is
1398: the empty string, then the <var title="">url</var> argument defaults
1.1088 mike 1399: to "<code><a href="urls.html#about:blank">about:blank</a></code>". The argument must be <a href="urls.html#resolve-a-url" title="resolve a url">resolved</a> to an <a href="urls.html#absolute-url">absolute
1.700 mike 1400: URL</a> (or an error), relative to the <a href="#entry-script">entry
1.1246 sruby 1401: script</a>'s <a href="webappapis.html#script's-base-url" title="script's base URL">base URL</a>,
1.1 mike 1402: when the method is invoked.</p>
1403:
1404: <p>The second argument, <var title="">target</var>, specifies the
1405: <a href="#browsing-context-name" title="browsing context name">name</a> of the browsing
1406: context that is to be navigated. It must be a <a href="#valid-browsing-context-name-or-keyword">valid browsing
1407: context name or keyword</a>. If fewer than two arguments are
1.1003 mike 1408: provided, then the <var title="">target</var> argument defaults to the
1.1 mike 1409: value "<code>_blank</code>".</p>
1410:
1.1008 mike 1411: <p>The third argument, <var title="">features</var>, has no defined
1412: effect and is mentioned for historical reasons only. User agents may
1413: interpret this argument as instructions to set the size and position
1414: of the browsing context, but are encouraged to instead ignore the
1415: argument entirely.</p>
1.1 mike 1416:
1417: <p>The fourth argument, <var title="">replace</var>, specifies
1418: whether or not the new page will <a href="history.html#replacement-enabled" title="replacement
1419: enabled">replace</a> the page currently loaded in the browsing
1420: context, when <var title="">target</var> identifies an existing
1421: browsing context (as opposed to leaving the current page in the
1422: browsing context's <a href="history.html#session-history">session history</a>). When three or
1423: fewer arguments are provided, <var title="">replace</var> defaults
1424: to false.</p>
1425:
1426: <p>When the method is invoked, the user agent must first select a
1427: <a href="#browsing-context">browsing context</a> to navigate by applying <a href="#the-rules-for-choosing-a-browsing-context-given-a-browsing-context-name">the
1428: rules for choosing a browsing context given a browsing context
1429: name</a> using the <var title="">target</var> argument as the
1430: name and the <a href="#browsing-context">browsing context</a> of the script as the
1431: context in which the algorithm is executed, unless the user has
1432: indicated a preference, in which case the browsing context to
1433: navigate may instead be the one indicated by the user.</p>
1434:
1435: <p class="example">For example, suppose there is a user agent that
1436: supports control-clicking a link to open it in a new tab. If a user
1.794 mike 1437: clicks in that user agent on an element whose <code title="handler-onclick"><a href="webappapis.html#handler-onclick">onclick</a></code> handler uses the <code title="dom-open"><a href="#dom-open">window.open()</a></code> API to open a page in an
1.1 mike 1438: iframe, but, while doing so, holds the control key down, the user
1439: agent could override the selection of the target browsing context to
1440: instead target a new tab.</p>
1441:
1.1079 mike 1442: <p>If the method is not <a href="#allowed-to-show-a-pop-up">allowed to show a pop-up</a> and
1443: applying <a href="#the-rules-for-choosing-a-browsing-context-given-a-browsing-context-name">the rules for choosing a browsing context given a
1444: browsing context name</a> using the <var title="">target</var>
1445: argument, would result in there not being a chosen browsing context,
1446: then throw an <code><a href="infrastructure.html#invalidaccesserror">InvalidAccessError</a></code> exception and abort
1447: these steps.</p>
1448:
1449: <p>Otherwise, if <var title="">url</var> is not
1.1088 mike 1450: "<code><a href="urls.html#about:blank">about:blank</a></code>", the user agent must
1.1246 sruby 1451: <a href="history.html#navigate">navigate</a><!--DONAV window.open()--> the selected
1.1216 mike 1452: <a href="#browsing-context">browsing context</a> to the <a href="urls.html#absolute-url">absolute URL</a>
1453: obtained from <a href="urls.html#resolve-a-url" title="resolve a url">resolving</a> <var title="">url</var> earlier. If the <var title="">replace</var> is
1454: true or if the <a href="#browsing-context">browsing context</a> was just created as
1.1050 mike 1455: part of <a href="#the-rules-for-choosing-a-browsing-context-given-a-browsing-context-name">the rules for choosing a browsing context given a
1456: browsing context name</a>, then <a href="history.html#replacement-enabled" title="replacement
1457: enabled">replacement must be enabled</a>. The navigation must be
1.1246 sruby 1458: done with the <a href="webappapis.html#script's-browsing-context" title="script's browsing context">browsing
1.1050 mike 1459: context</a> of the <a href="#entry-script">entry script</a> as the <a href="history.html#source-browsing-context">source
1.1216 mike 1460: browsing context</a>. If the <a href="urls.html#resolve-a-url">resolve a URL</a> algorithm
1461: failed, then the user agent may either instead <a href="history.html#navigate">navigate</a>
1462: to an inline error page, using the same replacement behavior and
1463: source browsing context behavior as described earlier in this
1464: paragraph; or treat the <var title="">url</var> as
1465: "<code><a href="urls.html#about:blank">about:blank</a></code>", acting as described in the next
1466: paragraph.</p>
1.1050 mike 1467:
1468: <p>If <var title="">url</var> <em>is</em>
1.1088 mike 1469: "<code><a href="urls.html#about:blank">about:blank</a></code>", the user agent must instead <a href="webappapis.html#queue-a-task">queue
1.1069 mike 1470: a 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 selected <a href="#browsing-context">browsing
1471: context</a>'s <code><a href="#window">Window</a></code> object, but with its <code title="dom-event-target"><a href="infrastructure.html#dom-event-target">target</a></code> set to the selected
1.1050 mike 1472: <a href="#browsing-context">browsing context</a>'s <code><a href="#window">Window</a></code> object's
1.1087 mike 1473: <code><a href="dom.html#document">Document</a></code> object (and the <code title="dom-event-currentTarget">currentTarget</code> set to the
1.1050 mike 1474: <code><a href="#window">Window</a></code> object).</p>
1.1 mike 1475:
1476: <p>The method must return the <code><a href="#windowproxy">WindowProxy</a></code> object of the
1477: <a href="#browsing-context">browsing context</a> that was navigated, or null if no
1478: browsing context was navigated.</p>
1479:
1480: <hr><p>The <dfn id="dom-name" title="dom-name"><code>name</code></dfn> attribute of
1481: the <code><a href="#window">Window</a></code> object must, on getting, return the current
1.1273 sruby 1482: <a href="#browsing-context-name" title="browsing context name">name</a> of the
1483: <a href="#browsing-context">browsing context</a>, and, on setting, set the <a href="#browsing-context-name" title="browsing context name">name</a> of the <a href="#browsing-context">browsing
1484: context</a> to the new value.</p>
1.1 mike 1485:
1486: <p class="note">The name <a href="history.html#resetBCName">gets reset</a> when
1487: the browsing context is navigated to another domain.</p>
1488:
1489: <hr><p>The <dfn id="dom-window-close" title="dom-window-close"><code>close()</code></dfn>
1490: method on <code><a href="#window">Window</a></code> objects should, if the corresponding
1.1231 mike 1491: <a href="#browsing-context">browsing context</a> <var title="">A</var> is
1.1246 sruby 1492: <a href="#script-closable">script-closable</a> and the <a href="webappapis.html#script's-browsing-context" title="script's
1.1231 mike 1493: browsing context">browsing context</a> of the <a href="webappapis.html#concept-script" title="concept-script">script</a> that invokes the method is
1494: <a href="#allowed-to-navigate">allowed to navigate</a> the <a href="#browsing-context">browsing context</a>
1495: <var title="">A</var>, close the <a href="#browsing-context">browsing context</a> <var title="">A</var> (and may <a href="#a-browsing-context-is-discarded" title="a browsing context is
1496: discarded">discard</a> it too).</p>
1497:
1498: <p>A <a href="#browsing-context">browsing context</a> is <dfn id="script-closable">script-closable</dfn> if
1499: it is an <a href="#auxiliary-browsing-context">auxiliary browsing context</a> that was created by
1500: a script (as opposed to by an action of the user), or if it is a
1501: <a href="#browsing-context">browsing context</a> whose <a href="history.html#session-history">session history</a>
1502: contains only one <code><a href="dom.html#document">Document</a></code>.</p>
1.1 mike 1503:
1.947 mike 1504: <p>The <dfn id="dom-window-stop" title="dom-window-stop"><code>stop()</code></dfn> method
1505: on <code><a href="#window">Window</a></code> objects should, if there is an existing
1506: attempt to <a href="history.html#navigate">navigate</a> the <a href="#browsing-context">browsing context</a>
1507: and that attempt is not currently running the <a href="history.html#unload-a-document">unload a
1.1258 sruby 1508: document</a> algorithm, cancel that <a href="history.html#navigate" title="navigate">navigation</a>; then, it must <a href="history.html#abort-a-document" title="abort
1509: a document">abort</a> the <a href="#active-document">active document</a> of the
1510: <a href="#browsing-context">browsing context</a> of the <code><a href="#window">Window</a></code> object on
1511: which it was invoked.</p>
1.947 mike 1512:
1.1172 mike 1513: </div>
1514:
1515:
1516: <h4 id="accessing-other-browsing-contexts"><span class="secno">5.2.3 </span>Accessing other browsing contexts</h4>
1517:
1518: <dl class="domintro"><dt><var title="">window</var> . <code title="dom-length"><a href="#dom-length">length</a></code></dt>
1.1 mike 1519:
1520: <dd>
1521:
1522: <p>Returns the number of <a href="#child-browsing-context" title="child browsing
1523: context">child browsing contexts</a>.</p>
1524:
1525: </dd>
1526:
1527: <dt><var title="">window</var>[<var title="">index</var>]</dt>
1528:
1529: <dd>
1530:
1531: <p>Returns the indicated <a href="#child-browsing-context">child browsing context</a>.</p>
1532:
1533: </dd>
1534:
1535: </dl><div class="impl">
1536:
1.192 mike 1537: <p>The <dfn id="dom-length" title="dom-length"><code>length</code></dfn> IDL
1.1 mike 1538: attribute on the <code><a href="#window">Window</a></code> interface must return the
1539: number of <a href="#child-browsing-context" title="child browsing context">child browsing
1.698 mike 1540: contexts</a> that are <a href="#browsing-context-nested-through" title="browsing context nested
1541: through">nested through</a> elements that are <a href="infrastructure.html#in-a-document" title="in a
1542: document">in the <code>Document</code></a> that is the
1543: <a href="#active-document">active document</a> of that <code><a href="#window">Window</a></code> object, if
1544: that <code><a href="#window">Window</a></code>'s <a href="#browsing-context">browsing context</a> shares the
1.1246 sruby 1545: same <a href="webappapis.html#event-loop">event loop</a> as the <a href="webappapis.html#script's-browsing-context">script's browsing
1.700 mike 1546: context</a> of the <a href="#entry-script">entry script</a> accessing the IDL
1.698 mike 1547: attribute; otherwise, it must return zero.</p>
1.177 mike 1548:
1.1246 sruby 1549: <!-- in other words, frames are only accessible to same-thread processes -->
1.1 mike 1550:
1.1013 mike 1551: <p>The <a href="infrastructure.html#supported-property-indices">supported property indices</a> on the
1552: <code><a href="#window">Window</a></code> object at any instant are the numbers in the
1553: range 0 .. <span title=""><var title="">n</var>-1</span>, where <var title="">n</var> is the number returned by the <code title="dom-length"><a href="#dom-length">length</a></code> IDL attribute. If <var title="">n</var> is zero then there are no <a href="infrastructure.html#supported-property-indices">supported property
1554: indices</a>.</p>
1.1 mike 1555:
1.1020 mike 1556: <p>To <dfn id="dom-window-item" title="dom-window-item">determine the value of an indexed
1557: property</dfn> <var title="">index</var> of a <code><a href="#window">Window</a></code>
1558: object, the user agent must return the <code><a href="#windowproxy">WindowProxy</a></code>
1559: object of the <var title="">index</var>th <a href="#child-browsing-context">child browsing
1.1087 mike 1560: context</a> of the <code><a href="dom.html#document">Document</a></code> that is nested through
1.1020 mike 1561: an element that is <a href="infrastructure.html#in-a-document" title="in a document">in the
1562: <code>Document</code></a>, sorted in the <a href="infrastructure.html#tree-order">tree order</a>
1563: of the elements nesting those <a href="#browsing-context" title="browsing
1564: context">browsing contexts</a>.</p>
1.1 mike 1565:
1566: <p>These properties are the <dfn id="dynamic-nested-browsing-context-properties">dynamic nested browsing context
1567: properties</dfn>.</p>
1568:
1.1172 mike 1569: </div>
1570:
1571:
1572:
1573: <h4 id="named-access-on-the-window-object"><span class="secno">5.2.4 </span>Named access on the <code><a href="#window">Window</a></code> object</h4>
1574:
1575: <dl class="domintro"><dt><var title="">window</var>[<var title="">name</var>]</dt>
1.1 mike 1576:
1577: <dd>
1578:
1.943 mike 1579: <p>Returns the indicated element or collection of elements.</p>
1.1 mike 1580:
1581: </dd>
1582:
1583: </dl><div class="impl">
1584:
1.1145 mike 1585: <p>The <code><a href="#window">Window</a></code> interface <a href="infrastructure.html#support-named-properties" title="support named
1586: properties">supports named properties</a>. The <a href="infrastructure.html#supported-property-names">supported
1.1013 mike 1587: property names</a> at any moment consist of:</p>
1.1 mike 1588:
1.1273 sruby 1589: <ul><li>the <a href="#browsing-context-name">browsing context name</a> of any <a href="#child-browsing-context">child
1590: browsing context</a> of the <a href="#active-document">active document</a> whose
1591: name is not the empty string,</li>
1592:
1593: <li>the value of the <code title="">name</code> content attribute
1.1088 mike 1594: for all <code><a href="the-a-element.html#the-a-element">a</a></code>, <code><a href="obsolete.html#the-applet-element">applet</a></code>, <code><a href="the-area-element.html#the-area-element">area</a></code>,
1.1273 sruby 1595: <code><a href="the-embed-element.html#the-embed-element">embed</a></code>, <code><a href="the-form-element.html#the-form-element">form</a></code>, <code><a href="obsolete.html#frameset">frameset</a></code>,
1596: <code><a href="the-img-element.html#the-img-element">img</a></code>, and <code><a href="the-object-element.html#the-object-element">object</a></code> elements in the
1597: <a href="#active-document">active document</a> that have a <code title="">name</code>
1598: content attribute, and</li>
1.1 mike 1599:
1.1088 mike 1600: <li>the value of the <code title="attr-id"><a href="global-attributes.html#the-id-attribute">id</a></code> content
1.1 mike 1601: attribute of any <a href="infrastructure.html#html-elements" title="HTML elements">HTML element</a> in
1.1088 mike 1602: the <a href="#active-document">active document</a> with an <code title="attr-id"><a href="global-attributes.html#the-id-attribute">id</a></code> content attribute.</li>
1.1 mike 1603:
1.1273 sruby 1604: </ul><p>To <a href="infrastructure.html#determine-the-value-of-a-named-property">determine the value of a named property</a> <var title="">name</var> when <dfn id="dom-window-nameditem" title="dom-window-namedItem">the
1.1055 mike 1605: <code>Window</code> object is indexed for property retrieval</dfn>,
1606: the user agent must return the value obtained using the following
1607: steps:</p>
1.1 mike 1608:
1.1273 sruby 1609: <ol><!-- http://software.hixie.ch/utilities/js/live-dom-viewer/saved/1716 --><li>
1.1 mike 1610:
1.1273 sruby 1611: <p>Let <var title="">objects</var> be the list of <a href="#dom-window-nameditem-filter" title="dom-window-namedItem-filter">named objects</a> with the
1.1 mike 1612: name <var title="">name</var> in the <a href="#active-document">active document</a>.
1613:
1.1273 sruby 1614: </p><p class="note">There will be at least one such object, by
1.1246 sruby 1615: definition.<!-- (If there wasn't, then this algorithm wouldn't
1616: have been invoked by Web IDL.) --></p>
1.1 mike 1617:
1618: </li>
1619:
1620: <li>
1621:
1.1273 sruby 1622: <p>If <var title="">objects</var> contains a <a href="#nested-browsing-context">nested browsing
1623: context</a>, then return the <code><a href="#windowproxy">WindowProxy</a></code> object of
1624: the <a href="#nested-browsing-context">nested browsing context</a> corresponding to the
1625: first <a href="#browsing-context-container">browsing context container</a> in <a href="infrastructure.html#tree-order">tree
1626: order</a> whose <a href="#browsing-context">browsing context</a> is in <var title="">objects</var>, and abort these steps.</p>
1.1 mike 1627:
1628: </li>
1629:
1630: <li>
1631:
1632: <p>Otherwise, if <var title="">elements</var> has only one
1633: element, return that element and abort these steps.</p>
1634:
1635: </li>
1636:
1637: <li>
1638:
1.1057 mike 1639: <p>Otherwise return an <code><a href="infrastructure.html#htmlcollection">HTMLCollection</a></code> rooted at the
1.1273 sruby 1640: <code><a href="dom.html#document">Document</a></code> node, whose filter matches only <a href="#dom-window-nameditem-filter" title="dom-window-namedItem-filter">named objects</a> with the
1641: name <var title="">name</var>. (By definition, these will all be
1642: elements.)</p> <!-- the same one each time is returned, because of
1643: the rule under collections -->
1.1091 mike 1644:
1.1 mike 1645: </li>
1646:
1.1273 sruby 1647: </ol><p><dfn id="dom-window-nameditem-filter" title="dom-window-nameditem-filter">Named objects</dfn>
1.1 mike 1648: with the name <var title="">name</var>, for the purposes of the
1649: above algorithm, are those that are either:</p>
1650:
1.1273 sruby 1651: <ul><li><a href="#child-browsing-context" title="child browsing context">child browsing
1652: contexts</a> of the <a href="#active-document">active document</a> whose name is
1653: <var title="">name</var>,</li>
1654:
1655: <li><code><a href="the-a-element.html#the-a-element">a</a></code>, <code><a href="obsolete.html#the-applet-element">applet</a></code>, <code><a href="the-area-element.html#the-area-element">area</a></code>,
1656: <code><a href="the-embed-element.html#the-embed-element">embed</a></code>, <code><a href="the-form-element.html#the-form-element">form</a></code>, <code><a href="obsolete.html#frameset">frameset</a></code>,
1657: <code><a href="the-img-element.html#the-img-element">img</a></code>, or <code><a href="the-object-element.html#the-object-element">object</a></code> elements that have a <code title="attr-name">name</code> content attribute whose value is <var title="">name</var>, or</li>
1.1 mike 1658:
1.1088 mike 1659: <li><a href="infrastructure.html#html-elements">HTML elements</a> that have an <code title="attr-id"><a href="global-attributes.html#the-id-attribute">id</a></code> content attribute whose value is <var title="">name</var>.</li>
1.1 mike 1660:
1.1172 mike 1661: </ul></div>
1662:
1663:
1664: <div class="impl">
1.1 mike 1665:
1.1004 mike 1666: <h4 id="garbage-collection-and-browsing-contexts"><span class="secno">5.2.5 </span>Garbage collection and browsing contexts</h4>
1.1 mike 1667:
1668: <p>A <a href="#browsing-context">browsing context</a> has a strong reference to each of
1.1087 mike 1669: its <code><a href="dom.html#document">Document</a></code>s and its <code><a href="#windowproxy">WindowProxy</a></code> object,
1.1 mike 1670: and the user agent itself has a strong reference to its <a href="#top-level-browsing-context" title="top-level browsing context">top-level browsing
1671: contexts</a>.</p>
1672:
1.1087 mike 1673: <p>A <code><a href="dom.html#document">Document</a></code> has a strong reference to its
1.881 mike 1674: <code><a href="#window">Window</a></code> object.</p>
1675:
1.1064 mike 1676: <p class="note">A <code><a href="#window">Window</a></code> object <a href="common-dom-interfaces.html#implied-strong-reference" title="implied
1.881 mike 1677: strong reference">has a strong reference</a> to its
1.1087 mike 1678: <code><a href="dom.html#document">Document</a></code> object through its <code title="dom-document"><a href="#dom-document-0">document</a></code> attribute. Thus, references
1.881 mike 1679: from other scripts to either of those objects will keep both
1.1087 mike 1680: alive. Similarly, both <code><a href="dom.html#document">Document</a></code> and <code><a href="#window">Window</a></code>
1.1064 mike 1681: objects have <a href="common-dom-interfaces.html#implied-strong-reference" title="implied strong reference">implied strong
1.881 mike 1682: references</a> to the <code><a href="#windowproxy">WindowProxy</a></code> object.</p>
1.1 mike 1683:
1.842 mike 1684: <p>Each <a href="webappapis.html#concept-script" title="concept-script">script</a> has a strong
1.1246 sruby 1685: reference to its <a href="webappapis.html#script's-browsing-context" title="script's browsing context">browsing
1686: context</a> and its <a href="webappapis.html#script's-document" title="script's
1.842 mike 1687: document">document</a>.</p>
1688:
1.1246 sruby 1689: <!-- discard a document -->
1.1 mike 1690: <p>When a <a href="#browsing-context">browsing context</a> is to <dfn id="discard-a-document">discard a
1.782 mike 1691: <code>Document</code></dfn>, the user agent must run the following
1692: steps:</p>
1.1 mike 1693:
1.1087 mike 1694: <ol><li><p>Set the <code><a href="dom.html#document">Document</a></code>'s <var title="concept-document-salvageable"><a href="history.html#concept-document-salvageable">salvageable</a></var> state to
1.827 mike 1695: false.</p></li>
1696:
1697: <li><p>Run any <a href="history.html#unloading-document-cleanup-steps">unloading document cleanup steps</a> for
1.1087 mike 1698: the <code><a href="dom.html#document">Document</a></code> that are defined by this specification
1.1002 mike 1699: and <a href="infrastructure.html#other-applicable-specifications">other applicable specifications</a>.</p></li>
1.782 mike 1700:
1.1074 mike 1701: <li><p><a href="history.html#abort-a-document" title="abort a document">Abort the
1702: <code>Document</code></a>.</p></li>
1703:
1.794 mike 1704: <li><p>Remove any <a href="webappapis.html#concept-task" title="concept-task">tasks</a>
1.1087 mike 1705: associated with the <code><a href="dom.html#document">Document</a></code> in any <a href="webappapis.html#task-source">task
1.782 mike 1706: source</a>, without running those tasks.</p></li>
1707:
1708: <li><p><a href="#a-browsing-context-is-discarded" title="a browsing context is discarded">Discard</a>
1709: all the <a href="#child-browsing-context" title="child browsing context">child browsing
1.1087 mike 1710: contexts</a> of the <code><a href="dom.html#document">Document</a></code>.</p></li>
1.782 mike 1711:
1.1087 mike 1712: <li><p>Lose the strong reference from the <code><a href="dom.html#document">Document</a></code>'s
1.782 mike 1713: <a href="#browsing-context">browsing context</a> to the
1.1087 mike 1714: <code><a href="dom.html#document">Document</a></code>.</p></li>
1.782 mike 1715:
1.1087 mike 1716: </ol><p class="note">Whenever a <code><a href="dom.html#document">Document</a></code> object is <a href="#discard-a-document" title="discard a Document">discarded</a>, it is also removed from
1717: the list of <span>the worker's <code><a href="dom.html#document">Document</a></code>s</span> of each
1718: worker whose list contains that <code><a href="dom.html#document">Document</a></code>.</p>
1.1 mike 1719:
1720: <p>When <dfn id="a-browsing-context-is-discarded">a <em><span>browsing context</span></em> is
1721: discarded</dfn>, the strong reference from the user agent itself to
1722: the <a href="#browsing-context">browsing context</a> must be severed, and all the
1.1087 mike 1723: <code><a href="dom.html#document">Document</a></code> objects for all the entries in the
1.1 mike 1724: <a href="#browsing-context">browsing context</a>'s session history must be <a href="#discard-a-document" title="discard a document">discarded</a> as well.</p>
1725:
1726: <p>User agents may <a href="#a-browsing-context-is-discarded" title="a browsing context is
1727: discarded">discard</a> <a href="#top-level-browsing-context" title="top-level browsing
1728: context">top-level browsing contexts</a> at any time (typically,
1729: in response to user requests, e.g. when a user closes a window
1730: containing one or more <a href="#top-level-browsing-context" title="top-level browsing
1731: context">top-level browsing contexts</a>). Other <a href="#browsing-context" title="browsing context">browsing contexts</a> must be discarded
1732: once their <code><a href="#windowproxy">WindowProxy</a></code> object is eligible for garbage
1733: collection.</p>
1734:
1.1172 mike 1735: </div>
1736:
1737:
1738:
1739: <h4 id="browser-interface-elements"><span class="secno">5.2.6 </span>Browser interface elements</h4>
1740:
1741: <p>To allow Web pages to integrate with Web browsers, certain Web
1.1 mike 1742: browser interface elements are exposed in a limited way to scripts
1.1172 mike 1743: in Web pages.</p>
1744:
1745: <p>Each interface element is represented by a <code><a href="#barprop">BarProp</a></code>
1746: object:</p>
1747:
1748: <pre class="idl">interface <dfn id="barprop">BarProp</dfn> {
1.1 mike 1749: attribute boolean <a href="#dom-barprop-visible" title="dom-BarProp-visible">visible</a>;
1.1172 mike 1750: };</pre>
1751:
1752: <dl class="domintro"><dt><var title="">window</var> . <code title="dom-window-locationbar"><a href="#dom-window-locationbar">locationbar</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1.1 mike 1753: <dd>
1754: <p>Returns true if the location bar is visible; otherwise, returns false.</p>
1755: </dd>
1756:
1757: <dt><var title="">window</var> . <code title="dom-window-menubar"><a href="#dom-window-menubar">menubar</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1758: <dd>
1759: <p>Returns true if the menu bar is visible; otherwise, returns false.</p>
1760: </dd>
1761:
1762: <dt><var title="">window</var> . <code title="dom-window-personalbar"><a href="#dom-window-personalbar">personalbar</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1.1246 sruby 1763: <!--<dt><var title="">window</var> . <code title="dom-window-directories">directories</code> . <code title="dom-BarProp-visible">visible</code></dt>-->
1.1 mike 1764: <dd>
1765: <p>Returns true if the personal bar is visible; otherwise, returns false.</p>
1766: </dd>
1767:
1768: <dt><var title="">window</var> . <code title="dom-window-scrollbars"><a href="#dom-window-scrollbars">scrollbars</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1769: <dd>
1770: <p>Returns true if the scroll bars are visible; otherwise, returns false.</p>
1771: </dd>
1772:
1773: <dt><var title="">window</var> . <code title="dom-window-statusbar"><a href="#dom-window-statusbar">statusbar</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1774: <dd>
1775: <p>Returns true if the status bar is visible; otherwise, returns false.</p>
1776: </dd>
1777:
1778: <dt><var title="">window</var> . <code title="dom-window-toolbar"><a href="#dom-window-toolbar">toolbar</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1779: <dd>
1.391 mike 1780: <p>Returns true if the toolbar is visible; otherwise, returns false.</p>
1.1 mike 1781: </dd>
1782:
1783: </dl><div class="impl">
1784:
1785: <p>The <dfn id="dom-barprop-visible" title="dom-BarProp-visible">visible</dfn> attribute, on
1786: getting, must return either true or a value determined by the user
1787: agent to most accurately represent the visibility state of the user
1788: interface element that the object represents, as described below. On
1789: setting, the new value must be discarded.</p>
1790:
1791: <p>The following <code><a href="#barprop">BarProp</a></code> objects exist for each
1.1087 mike 1792: <code><a href="dom.html#document">Document</a></code> object in a <a href="#browsing-context">browsing
1.1 mike 1793: context</a>. Some of the user interface elements represented by
1794: these objects might have no equivalent in some user agents; for
1.409 mike 1795: those user agents, except when otherwise specified, the object must
1796: act as if it was present and visible (i.e. its <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code> attribute must return
1.1 mike 1797: true).</p>
1798:
1799: <dl><dt><dfn id="the-location-bar-barprop-object">The location bar <code>BarProp</code> object</dfn></dt>
1800:
1801: <dd>Represents the user interface element that contains a control
1.1064 mike 1802: that displays the <a href="urls.html#url">URL</a> of the <a href="#active-document">active
1.1 mike 1803: document</a>, or some similar interface concept.</dd>
1804:
1805: <dt><dfn id="the-menu-bar-barprop-object">The menu bar <code>BarProp</code> object</dfn></dt>
1806:
1807: <dd>Represents the user interface element that contains a list of
1808: commands in menu form, or some similar interface concept.</dd>
1809:
1810: <dt><dfn id="the-personal-bar-barprop-object">The personal bar <code>BarProp</code> object</dfn></dt>
1811:
1812: <dd>Represents the user interface element that contains links to
1813: the user's favorite pages, or some similar interface concept.</dd>
1814:
1815: <dt><dfn id="the-scrollbar-barprop-object">The scrollbar <code>BarProp</code> object</dfn></dt>
1816:
1817: <dd>Represents the user interface element that contains a scrolling
1818: mechanism, or some similar interface concept.</dd>
1819:
1820: <dt><dfn id="the-status-bar-barprop-object">The status bar <code>BarProp</code> object</dfn></dt>
1821:
1822: <dd>Represents a user interface element found immediately below or
1.881 mike 1823: after the document, as appropriate for the user's media. If the
1824: user agent has no such user interface element, then the object may
1825: act as if the corresponding user interface element was absent
1826: (i.e. its <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code>
1827: attribute may return false).</dd>
1.1 mike 1828:
1.391 mike 1829: <dt><dfn id="the-toolbar-barprop-object">The toolbar <code>BarProp</code> object</dfn></dt>
1.1 mike 1830:
1831: <dd>Represents the user interface element found immediately above
1.881 mike 1832: or before the document, as appropriate for the user's media. If the
1833: user agent has no such user interface element, then the object may
1834: act as if the corresponding user interface element was absent
1835: (i.e. its <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code>
1836: attribute may return false).</dd>
1.1 mike 1837:
1838: </dl><p>The <dfn id="dom-window-locationbar" title="dom-window-locationbar"><code>locationbar</code></dfn>
1839: attribute must return <a href="#the-location-bar-barprop-object">the location bar <code>BarProp</code>
1840: object</a>.</p>
1841:
1842: <p>The <dfn id="dom-window-menubar" title="dom-window-menubar"><code>menubar</code></dfn>
1843: attribute must return <a href="#the-menu-bar-barprop-object">the menu bar <code>BarProp</code>
1844: object</a>.</p>
1845:
1846: <p>The <dfn id="dom-window-personalbar" title="dom-window-personalbar"><code>personalbar</code></dfn>
1847: attribute must return <a href="#the-personal-bar-barprop-object">the personal bar <code>BarProp</code>
1848: object</a>.</p>
1849:
1850: <p>The <dfn id="dom-window-scrollbars" title="dom-window-scrollbars"><code>scrollbars</code></dfn>
1851: attribute must return <a href="#the-scrollbar-barprop-object">the scrollbar <code>BarProp</code>
1852: object</a>.</p>
1853:
1854: <p>The <dfn id="dom-window-statusbar" title="dom-window-statusbar"><code>statusbar</code></dfn> attribute
1855: must return <a href="#the-status-bar-barprop-object">the status bar <code>BarProp</code>
1856: object</a>.</p>
1857:
1858: <p>The <dfn id="dom-window-toolbar" title="dom-window-toolbar"><code>toolbar</code></dfn>
1.391 mike 1859: attribute must return <a href="#the-toolbar-barprop-object">the toolbar <code>BarProp</code>
1.1 mike 1860: object</a>.</p>
1861:
1.1246 sruby 1862: <!--
1863: <p>For legacy reasons, the <dfn
1864: title="dom-window-directories"><code>directories</code></dfn>
1865: attribute must also return <span>the personal bar
1866: <code>BarProp</code> object</span>.</p>
1867: -->
1.1091 mike 1868:
1.1049 mike 1869: <hr><p>For historical reasons, the <dfn id="dom-window-status" title="dom-window-status"><code>status</code></dfn> attribute on the
1870: <code><a href="#window">Window</a></code> object must return an empty string on getting,
1871: and do nothing on setting.</p>
1872:
1.1172 mike 1873: </div>
1874:
1875:
1876: <div class="impl">
1.1 mike 1877:
1.1004 mike 1878: <h4 id="the-windowproxy-object"><span class="secno">5.2.7 </span>The <code><a href="#windowproxy">WindowProxy</a></code> object</h4>
1.754 mike 1879:
1880:
1881: <p>As mentioned earlier, each <a href="#browsing-context">browsing context</a> has a
1882: <dfn id="windowproxy"><code>WindowProxy</code></dfn> object. This object is unusual
1883: in that all operations that would be performed on it must be
1884: performed on the <code><a href="#window">Window</a></code> object of the <a href="#browsing-context">browsing
1885: context</a>'s <a href="#active-document">active document</a> instead. It is thus
1886: indistinguishable from that <code><a href="#window">Window</a></code> object in every way
1887: until the <a href="#browsing-context">browsing context</a> is navigated.</p>
1888:
1889: <p>There is no <code><a href="#windowproxy">WindowProxy</a></code> interface object.</p>
1890:
1891: <p class="note">The <code><a href="#windowproxy">WindowProxy</a></code> object allows scripts
1892: to act as if each <a href="#browsing-context">browsing context</a> had a single
1893: <code><a href="#window">Window</a></code> object, while still keeping separate
1.1087 mike 1894: <code><a href="#window">Window</a></code> objects for each <code><a href="dom.html#document">Document</a></code>.</p>
1.754 mike 1895:
1896: <div class="example">
1897:
1898: <p>In the following example, the variable <var title="">x</var> is
1899: set to the <code><a href="#windowproxy">WindowProxy</a></code> object returned by the <code title="dom-window"><a href="#dom-window">window</a></code> accessor on the global object. All
1900: of the expressions following the assignment return true, because in
1901: every respect, the <code><a href="#windowproxy">WindowProxy</a></code> object acts like the
1902: underlying <code><a href="#window">Window</a></code> object.</p>
1903:
1904: <pre>var x = window;
1905: x instanceof Window; // true
1906: x === this; // true</pre>
1907:
1908: </div>
1909:
1.1172 mike 1910: </div>
1.1246 sruby 1911: <!--TOPIC:HTML-->
1912:
1913:
1914:
1915: <!--TOPIC:Security-->
1916: <h3 id="origin"><span class="secno">5.3 </span>Origin</h3>
1917: <!-- Hallowed are the Ori -->
1918:
1919: <p>The <dfn id="origin-0">origin</dfn> of a resource and the <dfn id="effective-script-origin">effective script
1920: origin</dfn> of a resource are both either opaque identifiers or
1921: tuples consisting of a scheme component, a host component, a port
1922: component, and optionally extra data.</p>
1923:
1924: <p class="note">The extra data could include the certificate of the
1925: site when using encrypted connections, to ensure that if the site's
1926: secure certificate changes, the origin is considered to change as
1927: well.</p>
1928:
1929: <div class="impl">
1930:
1931: <p>An <a href="#origin-0">origin</a> or <a href="#effective-script-origin">effective script origin</a>
1932: can be defined as an <dfn id="concept-origin-alias" title="concept-origin-alias">alias</dfn>
1933: to another <a href="#origin-0">origin</a> or <a href="#effective-script-origin">effective script
1934: origin</a>. The value of the <a href="#origin-0">origin</a> or
1935: <a href="#effective-script-origin">effective script origin</a> is then the value of the
1936: <a href="#origin-0">origin</a> or <a href="#effective-script-origin">effective script origin</a> to which
1937: it is an alias.</p>
1938:
1939: <p>These characteristics are defined as follows:</p>
1940:
1941: <dl><dt>For URLs</dt>
1942:
1943: <dd>
1944:
1.1267 sruby 1945: <p>The <a href="#origin-0">origin</a> and <a href="#effective-script-origin">effective script
1946: origin</a> of the <a href="urls.html#url">URL</a> are the origin defined in
1947: <cite>The Web Origin Concept</cite>. <a href="references.html#refsORIGIN">[ORIGIN]</a></p>
1.1259 sruby 1948:
1.1267 sruby 1949: </dd>
1.1246 sruby 1950:
1951:
1952: <dt>For <code><a href="dom.html#document">Document</a></code> objects</dt>
1953:
1954: <dd>
1955:
1956: <dl class="switch"><dt id="sandboxOrigin">If a <code><a href="dom.html#document">Document</a></code>'s <a href="#active-sandboxing-flag-set">active
1957: sandboxing flag set</a> has its <a href="#sandboxed-origin-browsing-context-flag">sandboxed origin
1958: browsing context flag</a> set</dt>
1959:
1960: <dd>
1961:
1962: <p>The <a href="#origin-0">origin</a> is a globally unique identifier
1963: assigned when the <code><a href="dom.html#document">Document</a></code> is created.</p>
1964:
1965: <p>The <a href="#effective-script-origin">effective script origin</a> is initially an
1966: <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
1967: <a href="#origin-0">origin</a> of the <code><a href="dom.html#document">Document</a></code>.</p>
1968:
1969: </dd>
1970:
1971:
1972: <dt>If a <code><a href="dom.html#document">Document</a></code> was generated from a <a href="webappapis.html#javascript-protocol" title="javascript protocol"><code>javascript:</code>
1973: URL</a></dt>
1974:
1975: <dd>
1976:
1977: <p>The <a href="#origin-0">origin</a> is an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
1978: <a href="#origin-0">origin</a> of the script of that <a href="webappapis.html#javascript-protocol" title="javascript protocol"><code>javascript:</code>
1979: URL</a>.</p>
1980:
1981: <p>The <a href="#effective-script-origin">effective script origin</a> is initially an
1982: <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
1983: <a href="#origin-0">origin</a> of the <code><a href="dom.html#document">Document</a></code>.</p>
1984:
1985: </dd>
1986:
1987:
1988: <dt>If a <code><a href="dom.html#document">Document</a></code> was served over the network and
1989: has an address that uses a URL scheme with a server-based naming
1990: authority</dt>
1991:
1992: <dd>
1993:
1994: <p>The <a href="#origin-0">origin</a> is an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
1995: <a href="#origin-0">origin</a> of <a href="dom.html#the-document's-address">the <code>Document</code>'s
1996: address</a>.</p>
1997:
1998: <p>The <a href="#effective-script-origin">effective script origin</a> is initially an
1999: <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2000: <a href="#origin-0">origin</a> of the <code><a href="dom.html#document">Document</a></code>.</p>
2001:
2002: </dd>
2003:
2004:
2005: <dt>If a <code><a href="dom.html#document">Document</a></code> was generated from a <a href="infrastructure.html#data-protocol" title="data protocol"><code title="">data:</code> URL</a> that
2006: was returned as the location of an HTTP redirect (<a href="urls.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or equivalent</a> in
2007: other protocols)</dt>
2008:
2009: <dd>
2010:
2011: <p>The <a href="#origin-0">origin</a> is an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2012: <a href="#origin-0">origin</a> of the <a href="urls.html#url">URL</a> that redirected to
2013: the <a href="infrastructure.html#data-protocol" title="data protocol"><code title="">data:</code>
2014: URL</a>.</p>
2015:
2016: <p>The <a href="#effective-script-origin">effective script origin</a> is initially an
2017: <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2018: <a href="#origin-0">origin</a> of the <code><a href="dom.html#document">Document</a></code>.</p>
2019:
2020: </dd>
2021:
2022:
2023: <dt>If a <code><a href="dom.html#document">Document</a></code> was generated from a <a href="infrastructure.html#data-protocol" title="data protocol"><code title="">data:</code> URL</a>
2024: found in another <code><a href="dom.html#document">Document</a></code> or in a script</dt>
2025:
2026: <dd>
2027:
2028: <p>The <a href="#origin-0">origin</a> is an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2029: <a href="#origin-0">origin</a> of the <code><a href="dom.html#document">Document</a></code> or script that
2030: initiated the <a href="history.html#navigate" title="navigate">navigation</a> to that
2031: <a href="urls.html#url">URL</a>.</p>
2032:
2033: <p>The <a href="#effective-script-origin">effective script origin</a> is initially an
2034: <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2035: <a href="#effective-script-origin">effective script origin</a> of the
2036: <code><a href="dom.html#document">Document</a></code> or script that initiated the <a href="history.html#navigate" title="navigate">navigation</a> to that <a href="urls.html#url">URL</a>.</p>
2037:
2038: </dd>
2039:
2040:
2041: <dt>If a <code><a href="dom.html#document">Document</a></code> has the <a href="dom.html#the-document's-address" title="the
2042: document's address">address</a>
2043: "<code><a href="urls.html#about:blank">about:blank</a></code>"</dt>
2044:
2045: <dd>
2046:
2047: <p>The <a href="#origin-0">origin</a> and <a href="#effective-script-origin">effective script
2048: origin</a> of the <code><a href="dom.html#document">Document</a></code> are <a href="#about-blank-origin">those it was assigned when its
2049: browsing context was created</a>.</p>
2050:
2051: </dd>
2052:
2053:
2054: <dt>If a <code><a href="dom.html#document">Document</a></code> is <a href="the-iframe-element.html#an-iframe-srcdoc-document">an <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code> document</a></dt>
2055:
2056: <dd>
2057:
2058: <p>The <a href="#origin-0">origin</a> of the <code><a href="dom.html#document">Document</a></code> is an
2059: <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2060: <a href="#origin-0">origin</a> of the <code><a href="dom.html#document">Document</a></code>'s
2061: <a href="#browsing-context">browsing context</a>'s <a href="#browsing-context-container">browsing context
2062: container</a>'s <code><a href="dom.html#document">Document</a></code>.</p>
2063:
2064: <p>The <a href="#effective-script-origin">effective script origin</a> is initially an
2065: <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2066: <a href="#effective-script-origin">effective script origin</a> of the
2067: <code><a href="dom.html#document">Document</a></code>'s <a href="#browsing-context">browsing context</a>'s
2068: <a href="#browsing-context-container">browsing context container</a>'s
2069: <code><a href="dom.html#document">Document</a></code>.</p>
2070:
2071: </dd>
2072:
2073:
2074: <dt>If a <code><a href="dom.html#document">Document</a></code> was obtained in some other manner
2075: (e.g. a <a href="infrastructure.html#data-protocol" title="data protocol"><code title="">data:</code>
2076: URL</a> typed in by the user, a <code><a href="dom.html#document">Document</a></code> created
2077: using the <code title="dom-DOMImplementation-createDocument"><a href="infrastructure.html#dom-domimplementation-createdocument">createDocument()</a></code>
2078: API, etc)</dt>
2079:
2080: <dd>
2081:
2082: <p>The <a href="#origin-0">origin</a> is a globally unique identifier
2083: assigned when the <code><a href="dom.html#document">Document</a></code> is created.</p>
2084:
2085: <p>The <a href="#effective-script-origin">effective script origin</a> is initially an
2086: <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2087: <a href="#origin-0">origin</a> of the <code><a href="dom.html#document">Document</a></code>.</p>
2088:
2089: </dd>
2090:
2091: </dl><p class="note">The <a href="#effective-script-origin">effective script origin</a> of a
2092: <code><a href="dom.html#document">Document</a></code> can be manipulated using the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> IDL
2093: attribute.</p>
2094:
2095: </dd>
2096:
2097:
2098: <dt>For images</dt>
2099:
2100: <dd>
2101:
2102: <dl class="switch"><dt>If an image is the image of an <code><a href="the-img-element.html#the-img-element">img</a></code> element and
2103: its image data is <a href="urls.html#cors-cross-origin">CORS-cross-origin</a></dt>
2104:
2105: <dd>The <a href="#origin-0">origin</a> is a globally unique identifier
2106: assigned when the image is created.</dd>
2107:
2108:
2109: <dt>If an image is the image of an <code><a href="the-img-element.html#the-img-element">img</a></code> element and
2110: its image data is <a href="urls.html#cors-same-origin">CORS-same-origin</a></dt>
2111:
2112: <dd>The <a href="#origin-0">origin</a> is an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2113: <a href="#origin-0">origin</a> of the <code><a href="the-img-element.html#the-img-element">img</a></code> element's
2114: <code><a href="dom.html#document">Document</a></code>.</dd>
2115:
2116: <!-- all image loads go through the "potentially CORS-enabled
2117: fetch" algorithm so they're all either CORS-cross-origin or
2118: CORS-same-origin if they succeed at all -->
2119:
2120: </dl><p>Images do not have an <a href="#effective-script-origin">effective script origin</a>.</p>
2121:
2122: </dd>
2123:
2124:
2125: <dt>For <code><a href="the-audio-element.html#the-audio-element">audio</a></code> and <code><a href="the-video-element.html#the-video-element">video</a></code> elements</dt>
2126:
2127: <dd>
2128:
2129: <dl class="switch"><dt>If the <a href="media-elements.html#media-data">media data</a> is
2130: <a href="urls.html#cors-cross-origin">CORS-cross-origin</a></dt>
2131:
2132: <dd>The <a href="#origin-0">origin</a> is a globally unique identifier
2133: assigned when the image is created.</dd>
2134:
2135:
2136: <dt>If the <a href="media-elements.html#media-data">media data</a> is
2137: <a href="urls.html#cors-same-origin">CORS-same-origin</a></dt>
2138:
2139: <dd>The <a href="#origin-0">origin</a> is an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2140: <a href="#origin-0">origin</a> of the <a href="media-elements.html#media-element">media element</a>'s
2141: <code><a href="dom.html#document">Document</a></code>.</dd>
2142:
2143: </dl><p><a href="media-elements.html#media-element" title="media element">Media elements</a> do not have
2144: an <a href="#effective-script-origin">effective script origin</a>.</p>
2145:
2146: </dd>
2147:
2148:
2149: <dt>For fonts</dt>
2150:
2151: <dd>
2152:
2153: <p>The <a href="#origin-0">origin</a> of a downloadable Web font is an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2154: <a href="#origin-0">origin</a> of the <a href="urls.html#absolute-url">absolute URL</a> used to
2155: obtain the font (after any redirects). <a href="references.html#refsCSSFONTS">[CSSFONTS]</a></p> <!-- this means you can
2156: get data from a remote site if you can make it redirect to your
2157: own site in some fashion controlled by the data you want to read
2158: -->
2159:
2160: <p>The <a href="#origin-0">origin</a> of a locally installed system font is
2161: an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2162: <a href="#origin-0">origin</a> of the <code><a href="dom.html#document">Document</a></code> in which that
2163: font is being used.</p>
2164:
2165: <p>Fonts do not have an <a href="#effective-script-origin">effective script origin</a>.</p>
2166:
2167: </dd>
2168:
2169:
2170: <dt>For scripts</dt>
2171:
2172: <dd>
2173:
2174: <p>The <a href="#origin-0">origin</a> and <a href="#effective-script-origin">effective script
2175: origin</a> of a script are determined from another resource,
2176: called the <i>owner</i>:</p>
2177:
2178: <dl class="switch"><dt>If a script is in a <code><a href="the-script-element.html#the-script-element">script</a></code> element</dt>
2179:
2180: <dd>The owner is the <code><a href="dom.html#document">Document</a></code> to which the
2181: <code><a href="the-script-element.html#the-script-element">script</a></code> element belongs.</dd>
2182:
2183:
2184: <dt>If a script is in an <a href="webappapis.html#event-handler-content-attributes" title="event handler content
2185: attributes">event handler content attribute</a></dt>
2186:
2187: <dd>The owner is the <code><a href="dom.html#document">Document</a></code> to which the
2188: attribute node belongs.</dd>
2189:
2190:
2191: <dt>If a script is a function or other code reference created by
2192: another script</dt>
2193:
2194: <dd>The owner is the script that created it.</dd>
2195:
2196:
2197: <dt>If a script is a <a href="webappapis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> that was returned as the
2198: location of an HTTP redirect (<a href="urls.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or equivalent</a> in
2199: other protocols)</dt>
2200:
2201: <dd>The owner is the <a href="urls.html#url">URL</a> that redirected to the
2202: <a href="webappapis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a>.</dd>
2203:
2204:
2205: <dt>If a script is a <a href="webappapis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> in an attribute</dt>
2206:
2207: <dd>The owner is the <code><a href="dom.html#document">Document</a></code> of the element on
2208: which the attribute is found.</dd>
2209:
2210:
2211: <dt>If a script is a <a href="webappapis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> in a style sheet</dt>
2212:
2213: <dd>The owner is the <a href="urls.html#url">URL</a> of the style sheet.</dd>
2214:
2215:
2216: <dt>If a script is a <a href="webappapis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> to which a <a href="#browsing-context">browsing
2217: context</a> is being <a href="history.html#navigate" title="navigate">navigated</a>,
2218: the URL having been provided by the user (e.g. by using a
2219: <i>bookmarklet</i>)</dt>
2220:
2221: <dd>The owner is the <code><a href="dom.html#document">Document</a></code> of the <a href="#browsing-context">browsing
2222: context</a>'s <a href="#active-document">active document</a>.</dd>
2223:
2224:
2225: <dt>If a script is a <a href="webappapis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> to which a <a href="#browsing-context">browsing
2226: context</a> is being <a href="history.html#navigate" title="navigate">navigated</a>,
2227: the URL having been declared in markup</dt>
2228:
2229: <dd>The owner is the <code><a href="dom.html#document">Document</a></code> of the element
2230: (e.g. an <code><a href="the-a-element.html#the-a-element">a</a></code> or <code><a href="the-area-element.html#the-area-element">area</a></code> element) that
2231: declared the URL.</dd>
2232:
2233:
2234: <dt>If a script is a <a href="webappapis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> to which a <a href="#browsing-context">browsing
2235: context</a> is being <a href="history.html#navigate" title="navigate">navigated</a>,
2236: the URL having been provided by script</dt>
2237:
2238: <dd>The owner is the script that provided the URL.</dd>
2239:
2240: </dl><p>The <a href="#origin-0">origin</a> of the script is then an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the
2241: <a href="#origin-0">origin</a> of the owner, and the <a href="#effective-script-origin">effective script
2242: origin</a> of the script is an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a> to the <a href="#effective-script-origin">effective
2243: script origin</a> of the owner.</p>
2244:
2245: </dd>
2246:
2247: </dl><p>Other specifications can override the above definitions by
2248: themselves specifying the origin of a particular <a href="urls.html#url">URL</a>,
2249: <code><a href="dom.html#document">Document</a></code>, image, <a href="media-elements.html#media-element">media element</a>, font, or
2250: <a href="webappapis.html#concept-script" title="concept-script">script</a>.</p>
2251:
2252: <!-- e.g.:
2253:
2254: <p>The <span>origin</span> of a <code>Document</code> object
2255: returned by the <code>XMLHttpRequest</code> API is an <span
2256: title="concept-origin-alias">alias</span> to the
2257: <span>XMLHttpRequest origin</span> of the
2258: <code>XMLHttpRequest</code> object.</p>
2259:
2260: -->
2261:
2262: <hr><p>The <dfn id="unicode-serialization-of-an-origin">Unicode serialization of an origin</dfn> is the string
2263: obtained by applying the following algorithm to the given
2264: <a href="#origin-0">origin</a>:</p>
2265:
2266: <ol><li><p>If the <a href="#origin-0">origin</a> in question is not a
2267: scheme/host/port tuple, then return the literal string "<code title="">null</code>" and abort these steps.</p></li>
2268:
2269: <li><p>Otherwise, let <var title="">result</var> be the scheme part
2270: of the <a href="#origin-0">origin</a> tuple.</p></li>
2271:
2272: <li><p>Append the string "<code title="">://</code>" to <var title="">result</var>.</p></li>
2273:
2274: <li><p>Apply the IDNA ToUnicode algorithm to each component of the
2275: host part of the <a href="#origin-0">origin</a> tuple, and append the results
2276: — each component, in the same order, separated by "." (U+002E) characters — to <var title="">result</var>. <a href="references.html#refsRFC3490">[RFC3490]</a></p></li>
2277:
2278: <li><p>If the port part of the <a href="#origin-0">origin</a> tuple gives a port
2279: that is different from the default port for the protocol given by
2280: the scheme part of the <a href="#origin-0">origin</a> tuple, then append a
2281: ":" (U+003A) character and the given port, in base ten, to
2282: <var title="">result</var>.</p></li>
2283:
2284: <li><p>Return <var title="">result</var>.</p></li>
2285:
2286: </ol><p>The <dfn id="ascii-serialization-of-an-origin">ASCII serialization of an origin</dfn> is the string
2287: obtained by applying the following algorithm to the given
2288: <a href="#origin-0">origin</a>:</p>
2289:
2290: <ol><li><p>If the <a href="#origin-0">origin</a> in question is not a
2291: scheme/host/port tuple, then return the literal string "<code title="">null</code>" and abort these steps.</p></li>
2292:
2293: <li><p>Otherwise, let <var title="">result</var> be the scheme part
2294: of the <a href="#origin-0">origin</a> tuple.</p></li>
2295:
2296: <li><p>Append the string "<code title="">://</code>" to <var title="">result</var>.</p></li>
2297:
2298: <li>
2299:
2300: <p>Apply the IDNA ToASCII algorithm the host part of the
2301: <a href="#origin-0">origin</a> tuple, with both the AllowUnassigned and
2302: UseSTD3ASCIIRules flags set, and append the results <var title="">result</var>.</p>
2303:
2304: <p>If ToASCII fails to convert one of the components of the
2305: string, e.g. because it is too long or because it contains invalid
2306: characters, then return the empty string and abort these steps. <a href="references.html#refsRFC3490">[RFC3490]</a></p>
2307:
2308: </li>
2309:
2310: <li><p>If the port part of the <a href="#origin-0">origin</a> tuple gives a port
2311: that is different from the default port for the protocol given by
2312: the scheme part of the <a href="#origin-0">origin</a> tuple, then append a
2313: ":" (U+003A) character and the given port, in base ten, to
2314: <var title="">result</var>.</p></li>
2315:
2316: <li><p>Return <var title="">result</var>.</p></li>
2317:
2318: </ol><p>Two <a href="#origin-0" title="origin">origins</a> are said to be the
2319: <dfn id="same-origin">same origin</dfn> if the following algorithm returns true:</p>
2320:
2321: <ol><li><p>Let <var title="">A</var> be the first <a href="#origin-0">origin</a>
2322: being compared, and <var title="">B</var> be the second
2323: <a href="#origin-0">origin</a> being compared.</p></li>
2324:
2325: <li><p>If <var title="">A</var> and <var title="">B</var> are both
2326: opaque identifiers, and their value is equal, then return
2327: true.</p></li>
2328:
2329: <li><p>Otherwise, if either <var title="">A</var> or <var title="">B</var> or both are opaque identifiers, return
2330: false.</p></li>
2331:
2332: <li><p>If <var title="">A</var> and <var title="">B</var> have
2333: scheme components that are not identical, return false.</p></li>
2334:
2335: <li><p>If <var title="">A</var> and <var title="">B</var> have host
2336: components that are not identical, return false.</p></li>
2337:
2338: <li><p>If <var title="">A</var> and <var title="">B</var> have port
2339: components that are not identical, return false.</p></li>
2340:
2341: <li><p>If either <var title="">A</var> or <var title="">B</var>
2342: have additional data, but that data is not identical for both,
2343: return false.</p></li>
2344:
2345: <li><p>Return true.</p></li>
2346:
2347: </ol></div>
2348:
2349:
2350: <h4 id="relaxing-the-same-origin-restriction"><span class="secno">5.3.1 </span>Relaxing the same-origin restriction</h4>
2351:
2352: <dl class="domintro"><dt><var title="">document</var> . <code title="dom-document-domain"><a href="#dom-document-domain">domain</a></code> [ = <var title="">domain</var> ]</dt>
2353:
2354: <dd>
2355:
2356: <p>Returns the current domain used for security checks.</p>
2357:
2358: <p>Can be set to a value that removes subdomains, to change the
2359: <a href="#effective-script-origin">effective script origin</a> to allow pages on other
2360: subdomains of the same domain (if they do the same thing) to
2361: access each other.</p>
2362:
2363: </dd>
2364:
2365: </dl><div class="impl">
2366:
2367: <p>The <dfn id="dom-document-domain" title="dom-document-domain"><code>domain</code></dfn>
2368: attribute on <code><a href="dom.html#document">Document</a></code> objects must be initialized to
2369: <a href="#the-document's-domain">the document's domain</a>, if it has one, and the empty
2370: string otherwise. If the value is an IPv6 address, then the square
2371: brackets from the host portion of the <a href="urls.html#url-host" title="url-host"><host></a> component must be omitted from
2372: the attribute's value.</p>
2373:
2374: <p>On getting, the attribute must return its current value, unless
2375: the <code><a href="dom.html#document">Document</a></code> has no <a href="#browsing-context">browsing context</a>, in
2376: which case it must return the empty string.</p>
2377:
2378: <p>On setting, the user agent must run the following algorithm:</p>
2379:
2380: <ol><li>
2381:
2382: <p>If the <code><a href="dom.html#document">Document</a></code> has no <a href="#browsing-context">browsing
2383: context</a>, throw a <code><a href="infrastructure.html#securityerror">SecurityError</a></code> exception and
2384: abort these steps.</p>
2385:
2386: </li>
2387:
2388: <li>
2389:
2390: <p>If the new value is an IP address, let <var title="">new
2391: value</var> be the new value. Otherwise, apply the IDNA ToASCII
2392: algorithm to the new value, with both the AllowUnassigned and
2393: UseSTD3ASCIIRules flags set, and let <var title="">new value</var>
2394: be the result of the ToASCII algorithm.</p>
2395:
2396: <p>If ToASCII fails to convert one of the components of the
2397: string, e.g. because it is too long or because it contains invalid
2398: characters, then throw a <code><a href="infrastructure.html#securityerror">SecurityError</a></code> exception and abort
2399: these steps. <a href="references.html#refsRFC3490">[RFC3490]</a></p>
2400:
2401: </li>
2402:
2403: <li>
2404:
2405: <p>If <var title="">new value</var> is not exactly equal to the
2406: current value of the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute, then
2407: run these substeps:</p>
2408:
2409: <ol><li>
2410:
2411: <p>If the current value is an IP address, throw a
2412: <code><a href="infrastructure.html#securityerror">SecurityError</a></code> exception and abort these steps.</p>
2413:
2414: </li>
2415:
2416: <li>
2417:
2418: <p>If <var title="">new value</var>, prefixed by a "." (U+002E), does not exactly match the end of the current value,
2419: throw a <code><a href="infrastructure.html#securityerror">SecurityError</a></code> exception and abort these
2420: steps.</p>
2421:
2422: <!-- this is the step that prevents us from ever setting
2423: document.domain if the >effective script origin< isn't a
2424: scheme/host/port tuple -->
2425:
2426: </li>
2427:
2428: <li>
2429:
2430: <p>If <var title="">new value</var> matches a suffix in the
2431: Public Suffix List, or, if <var title="">new value</var>,
2432: prefixed by a "." (U+002E), matches the end of a
2433: suffix in the Public Suffix List, then throw a
2434: <code><a href="infrastructure.html#securityerror">SecurityError</a></code> exception and abort these steps. <a href="references.html#refsPSL">[PSL]</a></p>
2435:
2436: <p>Suffixes must be compared after applying the IDNA ToASCII
2437: algorithm to them, with both the AllowUnassigned and
2438: UseSTD3ASCIIRules flags set, in an <a href="infrastructure.html#ascii-case-insensitive">ASCII
2439: case-insensitive</a> manner. <a href="references.html#refsRFC3490">[RFC3490]</a></p>
2440:
2441: </li>
2442:
2443: </ol></li>
2444:
2445: <li><p>Release the <a href="webappapis.html#storage-mutex">storage mutex</a>.</p></li>
2446:
2447: <li>
2448:
2449: <p>Set the attribute's value to <var title="">new value</var>.</p>
2450:
2451: </li>
2452:
2453: <li>
2454:
2455: <p>If the <a href="#effective-script-origin">effective script origin</a> of the
2456: <code><a href="dom.html#document">Document</a></code> is an <a href="#concept-origin-alias" title="concept-origin-alias">alias</a>, set it to the value of
2457: the <a href="#effective-script-origin">effective script origin</a> (essentially de-aliasing
2458: the <a href="#effective-script-origin">effective script origin</a>).</p>
2459:
2460: </li>
2461:
2462: <li>
2463:
2464: <p>If <var title="">new value</var> is not the empty string, then
2465: run these substeps:</p>
2466:
2467: <ol><li>
2468:
2469: <p>Set the host part of the <a href="#effective-script-origin">effective script origin</a>
2470: tuple of the <code><a href="dom.html#document">Document</a></code> to <var title="">new
2471: value</var>.</p>
2472:
2473: </li>
2474:
2475: <li>
2476:
2477: <p>Set the port part of the <a href="#effective-script-origin">effective script origin</a>
2478: tuple of the <code><a href="dom.html#document">Document</a></code> to "manual override" (a value
2479: that, for the purposes of <a href="#same-origin" title="same origin">comparing
2480: origins</a>, is identical to "manual override" but not
2481: identical to any other value).</p>
2482:
2483: </li>
2484:
2485: </ol></li>
2486:
2487: </ol><p>The <dfn id="the-document's-domain" title="the document's domain">domain</dfn> of a
2488: <code><a href="dom.html#document">Document</a></code> is the host part of the document's
2489: <a href="#origin-0">origin</a>, if the value of that <a href="#origin-0">origin</a> is a
2490: scheme/host/port tuple. If it isn't, then the document does not have
2491: a domain.</p>
2492:
2493: </div>
2494:
2495: <p class="note">The <code title="dom-document-domain"><a href="#dom-document-domain">domain</a></code>
2496: attribute is used to enable pages on different hosts of a domain to
2497: access each others' DOMs.</p>
2498:
2499: <p class="warning">Do not use the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute when
2500: using shared hosting. If an untrusted third party is able to host an
2501: HTTP server at the same IP address but on a different port, then the
2502: same-origin protection that normally protects two different sites on
2503: the same host will fail, as the ports are ignored when comparing
2504: origins after the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute has
2505: been used.</p>
2506: <!--TOPIC:HTML-->
2507:
2508:
2509:
2510:
2511: <h3 id="sandboxing"><span class="secno">5.4 </span>Sandboxing</h3>
2512:
2513: <p>A <dfn id="sandboxing-flag-set">sandboxing flag set</dfn> is a set of zero or more of the
2514: following flags, which are used to restrict the abilities that
2515: potentially untrusted resources have:</p>
2516:
2517: <dl><dt>The <dfn id="sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context flag</dfn></dt>
2518:
2519: <dd>
2520:
2521: <p>This flag <a href="history.html#sandboxLinks">prevents content from
2522: navigating browsing contexts other than the sandboxed browsing
2523: context itself</a> (or browsing contexts further nested inside
2524: it), <a href="#auxiliary-browsing-context" title="auxiliary browsing context">auxiliary browsing
2525: contexts</a> (which are protected by the <a href="#sandboxed-auxiliary-navigation-browsing-context-flag">sandboxed
2526: auxiliary navigation browsing context flag</a> defined next),
2527: and the <a href="#top-level-browsing-context">top-level browsing context</a> (which is
2528: protected by the <a href="#sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing
2529: context flag</a> defined below).</p>
2530:
2531: <p>If the <a href="#sandboxed-auxiliary-navigation-browsing-context-flag">sandboxed auxiliary navigation browsing context
2532: flag</a> is not set, then in certain cases the restrictions
2533: nonetheless allow popups (new <a href="#top-level-browsing-context" title="top-level browsing
2534: context">top-level browsing contexts</a>) to be opened. These
2535: <a href="#browsing-context" title="browsing context">browsing contexts</a> always
2536: have <dfn id="one-permitted-sandboxed-navigator">one permitted sandboxed navigator</dfn>, set when the
2537: browsing context is created, which allows the <a href="#browsing-context">browsing
2538: context</a> that created them to actually navigate them.
2539: (Otherwise, the <a href="#sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context
2540: flag</a> would prevent them from being navigated even if they
2541: were opened.)</p>
2542:
2543: </dd>
2544:
2545:
2546: <dt>The <dfn id="sandboxed-auxiliary-navigation-browsing-context-flag">sandboxed auxiliary navigation browsing context flag</dfn></dt>
2547:
2548: <dd>
2549:
2550: <p>This flag <a href="#sandboxWindowOpen">prevents content from
2551: creating new auxiliary browsing contexts</a>, e.g. using the <code title="attr-hyperlink-target"><a href="links.html#attr-hyperlink-target">target</a></code> attribute, the <code title="dom-open"><a href="#dom-open">window.open()</a></code> method, or the <code title="dom-showModalDialog"><a href="user-prompts.html#dom-showmodaldialog">showModalDialog()</a></code> method.</p>
2552:
2553: </dd>
2554:
2555:
2556: <dt>The <dfn id="sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing context flag</dfn></dt>
2557:
2558: <dd>
2559:
2560: <p>This flag <a href="history.html#sandboxLinks">prevents content from
2561: navigating their <span>top-level browsing context</span></a>.</p>
2562:
2563: <p>When the <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>
2564: is set, content can navigate its <a href="#top-level-browsing-context">top-level browsing
2565: context</a>, but other <a href="#browsing-context" title="browsing context">browsing
2566: contexts</a> are still protected by the <a href="#sandboxed-navigation-browsing-context-flag">sandboxed
2567: navigation browsing context flag</a> and possibly the
2568: <a href="#sandboxed-auxiliary-navigation-browsing-context-flag">sandboxed auxiliary navigation browsing context
2569: flag</a>.</p>
2570:
2571: </dd>
2572:
2573:
2574: <dt>The <dfn id="sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</dfn></dt>
2575:
2576: <dd>
2577:
2578: <p>This flag prevents content from instantiating <a href="infrastructure.html#plugin" title="plugin">plugins</a>, whether using <a href="the-embed-element.html#sandboxPluginEmbed">the <code>embed</code> element</a>, <a href="the-object-element.html#sandboxPluginObject">the <code>object</code> element</a>,
2579: <a href="obsolete.html#sandboxPluginApplet">the <code>applet</code>
2580: element</a>, or through <a href="history.html#sandboxPluginNavigate">navigation</a> of a <a href="#nested-browsing-context">nested
2581: browsing context</a>, unless those <a href="infrastructure.html#plugin" title="plugin">plugins</a> can be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a>.</p>
2582:
2583: </dd>
2584:
2585:
2586: <dt>The <dfn id="sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</dfn></dt>
2587:
2588: <dd>
2589:
2590: <p>This flag prevents content from using the <code title="attr-iframe-seamless"><a href="the-iframe-element.html#attr-iframe-seamless">seamless</a></code> attribute on
2591: descendant <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code> elements.</p>
2592:
2593: <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>
2594: keyword from using a CSS-selector-based method of probing the DOM
2595: of other pages on the same site (in particular, pages that contain
2596: user-sensitive information).</p>
2597:
2598: <!-- http://lists.w3.org/Archives/Public/public-web-security/2009Dec/thread.html#msg51 -->
2599:
2600: </dd>
2601:
2602:
2603: <dt>The <dfn id="sandboxed-origin-browsing-context-flag">sandboxed origin browsing context flag</dfn></dt>
2604:
2605: <dd>
2606:
2607: <p>This flag <a href="#sandboxOrigin">forces content into a unique
2608: origin</a>, thus preventing it from accessing other content from
2609: the same <a href="#origin-0">origin</a>.</p>
2610:
2611: <p>This flag also <a href="dom.html#sandboxCookies">prevents script from
2612: reading from or writing to the <code title="dom-document-cookie">document.cookie</code> IDL
2613: attribute</a>, and blocks access to <code title="dom-localStorage">localStorage</code>.
2614: <a href="references.html#refsWEBSTORAGE">[WEBSTORAGE]</a>
2615: </p>
2616:
2617: </dd>
2618:
2619:
2620: <dt>The <dfn id="sandboxed-forms-browsing-context-flag">sandboxed forms browsing context flag</dfn></dt>
2621:
2622: <dd>
2623:
2624: <p>This flag <a href="constraints.html#sandboxSubmitBlocked">blocks form
2625: submission</a>.</p>
2626:
2627: </dd>
2628:
2629:
2630: <dt>The <dfn id="sandboxed-scripts-browsing-context-flag">sandboxed scripts browsing context flag</dfn></dt>
2631:
2632: <dd>
2633:
2634: <p>This flag <a href="webappapis.html#sandboxScriptBlocked">blocks script
2635: execution</a>.</p>
2636:
2637: </dd>
2638:
2639:
2640: <dt>The <dfn id="sandboxed-automatic-features-browsing-context-flag">sandboxed automatic features browsing context
2641: flag</dfn></dt>
2642:
2643: <dd>
2644:
2645: <p>This flag blocks features that trigger automatically, such as
2646: <a href="media-elements.html#attr-media-autoplay" title="attr-media-autoplay">automatically playing a
2647: video</a> or <a href="attributes-common-to-form-controls.html#attr-fe-autofocus" title="attr-fe-autofocus">automatically
2648: focusing a form control</a>.</p>
2649:
2650: </dd>
2651:
2652: </dl><p>When the user agent is to <dfn id="parse-a-sandboxing-directive">parse a sandboxing
2653: directive</dfn>, given a string <var title="">input</var> and a
2654: <a href="#sandboxing-flag-set">sandboxing flag set</a> <var title="">output</var>, it must
2655: run the following steps:</p>
2656:
2657: <ol><li><p><a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">Split <var title="">input</var> on spaces</a>, to obtain <var title="">tokens</var>.</p></li>
2658:
2659: <li><p>Let <var title="">output</var> be empty.</p></li>
2660:
2661: <li>
2662:
2663: <p>Add the following flags to <var title="">output</var>:</p>
2664:
2665: <ul><li><p>The <a href="#sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context flag</a></p></li>
2666:
2667: <li><p>The <a href="#sandboxed-auxiliary-navigation-browsing-context-flag">sandboxed auxiliary navigation browsing context
2668: flag</a>, unless <var title="">tokens</var> contains the <dfn id="attr-iframe-sandbox-allow-popups" title="attr-iframe-sandbox-allow-popups"><code>allow-popups</code></dfn>
2669: keyword</p></li>
2670:
2671: <li><p>The <a href="#sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing context
2672: flag</a>, unless <var title="">tokens</var> contains the <dfn id="attr-iframe-sandbox-allow-top-navigation" title="attr-iframe-sandbox-allow-top-navigation"><code>allow-top-navigation</code></dfn>
2673: keyword</p></li>
2674:
2675: <li><p>The <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a></p></li>
2676:
2677: <li><p>The <a href="#sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</a></p></li>
2678:
2679: <li>
2680:
2681: <p>The <a href="#sandboxed-origin-browsing-context-flag">sandboxed origin browsing context flag</a>,
2682: unless the <var title="">tokens</var> contains the <dfn id="attr-iframe-sandbox-allow-same-origin" title="attr-iframe-sandbox-allow-same-origin"><code>allow-same-origin</code></dfn>
2683: keyword</p>
2684:
2685: <div class="note">
2686:
2687: <p>The <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
2688: keyword is intended for two cases.</p>
2689:
2690: <p>First, it can be used to allow content from the same site to
2691: be sandboxed to disable scripting, while still allowing access to
2692: the DOM of the sandboxed content.</p>
2693:
2694: <p>Second, it can be used to embed content from a third-party
2695: site, sandboxed to prevent that site from opening popup windows,
2696: etc, without preventing the embedded page from communicating back
2697: to its originating site, using the database APIs to store data,
2698: etc.</p>
2699:
2700: </div>
2701:
2702: </li>
2703:
2704: <li><p>The <a href="#sandboxed-forms-browsing-context-flag">sandboxed forms browsing context flag</a>,
2705: unless <var title="">tokens</var> contains the <dfn id="attr-iframe-sandbox-allow-forms" title="attr-iframe-sandbox-allow-forms"><code>allow-forms</code></dfn>
2706: keyword</p></li>
2707:
2708: <li><p>The <a href="#sandboxed-scripts-browsing-context-flag">sandboxed scripts browsing context flag</a>,
2709: unless <var title="">tokens</var> contains the <dfn id="attr-iframe-sandbox-allow-scripts" title="attr-iframe-sandbox-allow-scripts"><code>allow-scripts</code></dfn>
2710: keyword</p></li>
2711:
2712: <li>
2713:
2714: <p>The <a href="#sandboxed-automatic-features-browsing-context-flag">sandboxed automatic features browsing context
2715: flag</a>, unless <var title="">tokens</var> contains the
2716: <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
2717: keyword (defined above)</p>
2718:
2719: <p class="note">This flag is relaxed by the same keyword as
2720: scripts, because when scripts are enabled these features are
2721: trivially possible anyway, and it would be unfortunate to force
2722: authors to use script to do them when sandboxed rather than
2723: allowing them to use the declarative features.</p>
2724:
2725: </li>
2726:
2727: </ul></li>
2728:
2729: </ol><hr><p>Every <a href="#top-level-browsing-context">top-level browsing context</a> has a <dfn id="popup-sandboxing-flag-set">popup
2730: sandboxing flag set</dfn>. When a <a href="#browsing-context">browsing context</a> is
2731: created, its <a href="#popup-sandboxing-flag-set">popup sandboxing flag set</a> must be empty.
2732: It is populated by <a href="#the-rules-for-choosing-a-browsing-context-given-a-browsing-context-name">the rules for choosing a browsing context
2733: given a browsing context name</a>.</p>
1.1172 mike 2734:
1.1246 sruby 2735: <p>Every <a href="#nested-browsing-context">nested browsing context</a> has an
2736: <dfn id="iframe-sandboxing-flag-set"><code>iframe</code> sandboxing flag set</dfn>, which is a
2737: <a href="#sandboxing-flag-set">sandboxing flag set</a>. Which flags in a <a href="#nested-browsing-context">nested
2738: browsing context</a>'s <a href="#iframe-sandboxing-flag-set"><code>iframe</code> sandboxing flag
2739: set</a> are set at any particular time is determined by the
2740: <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code> element's <code title="attr-iframe-sandbox"><a href="the-iframe-element.html#attr-iframe-sandbox">sandbox</a></code> attribute.</p>
1.1172 mike 2741:
1.1246 sruby 2742: <p>Every <code><a href="dom.html#document">Document</a></code> has an <dfn id="active-sandboxing-flag-set">active sandboxing flag
2743: set</dfn>, which is a <a href="#sandboxing-flag-set">sandboxing flag set</a>. When the
2744: <code><a href="dom.html#document">Document</a></code> is created, its <a href="#active-sandboxing-flag-set">active sandboxing flag
2745: set</a> must be empty. It is populated by the <a href="history.html#navigate" title="navigate">navigation algorithm</a>.</p>
1.1172 mike 2746:
2747:
2748:
2749: </body></html>
Webmaster
![[BACK]](/https/dev.w3.org/cvsweb/icons/back.gif){kind=icon}
Return to browsers.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