Annotation of html5/spec/browsers.html, revision 1.770
1.2 mike 1: <!DOCTYPE HTML>
1.755 mike 2: <!-- when publishing, change bits marked ZZZ --><html lang="en-US-x-Hixie"><head><title>5 Loading Web pages — HTML 5</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; }
21: dt dfn { font-style: italic; }
22: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
23: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
24: pre em { font-weight: bolder; font-style: normal; }
25: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
26: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
27: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
28: table thead { border-bottom: solid; }
29: table tbody th:first-child { border-left: solid; }
1.475 mike 30: table tbody th { text-align: left; }
1.1 mike 31: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
32: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
33:
34: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
35: .matrix, .matrix td { border: none; text-align: right; }
36: .matrix { margin-left: 2em; }
37: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
38: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
39: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
40:
41: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
42: img.extra { float: right; }
43: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; }
44: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
45: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
46: pre.css:first-line { color: #AAAA50; }
47: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #EEFFEE; }
48: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
49: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
50: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
51: dl.domintro dd p { margin: 0.5em 0; }
52: dl.switch { padding-left: 2em; }
53: dl.switch > dt { text-indent: -1.5em; }
54: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
55: dl.triple { padding: 0 0 0 1em; }
56: dl.triple dt, dl.triple dd { margin: 0; display: inline }
57: dl.triple dt:after { content: ':'; }
58: dl.triple dd:after { content: '\A'; white-space: pre; }
59: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
60: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
61: a .diff-new { border-bottom: 1px blue solid; }
62:
63: h2 { page-break-before: always; }
64: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
65: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
66:
67: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]), li > span:not([title=""]):not([class="XXX"]):not([class="impl"]) { border-bottom: solid #9999CC; }
68:
69: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
70: div.head p { margin: 0; }
71: div.head h1 { margin: 0; }
72: div.head .logo { float: right; margin: 0 1em; }
73: div.head .logo img { border: none } /* remove border from top image */
74: div.head dl { margin: 1em 0; }
1.671 mike 75: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
1.1 mike 76:
77: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
78: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
79: body > .toc > li > * { margin-bottom: 0.5em; }
80: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
81: .toc, .toc li { list-style: none; }
82:
83: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
84: .brief li { margin: 0; padding: 0; }
85: .brief li p { margin: 0; padding: 0; }
86:
87: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
88: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
89: .category-list li { display: inline; }
90: .category-list li:not(:last-child)::after { content: ', '; }
91: .category-list li > span, .category-list li > a { text-transform: lowercase; }
92: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
93:
94: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
95: .XXX > :first-child { margin-top: 0; }
96: p .XXX { line-height: 3em; }
1.159 mike 97: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
98: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
99: .annotation :link, .annotation :visited { color: inherit; }
100: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
101: .annotation span { border: none ! important; }
1.1 mike 102: .note { color: green; background: transparent; font-family: sans-serif; }
103: .warning { color: red; background: transparent; }
104: .note, .warning { font-weight: bolder; font-style: italic; }
105: p.note, div.note { padding: 0.5em 2em; }
106: span.note { padding: 0 2em; }
107: .note p:first-child, .warning p:first-child { margin-top: 0; }
108: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
109: .warning:before { font-style: normal; }
110: p.note:before { content: 'Note: '; }
111: p.warning:before { content: '\26A0 Warning! '; }
112:
113: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
114: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
115: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
116:
117: h4 { position: relative; z-index: 3; }
118: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
119: .element {
120: background: #EEEEFF;
121: color: black;
122: margin: 0 0 1em 0.15em;
123: padding: 0 1em 0.25em 0.75em;
124: border-left: solid #9999FF 0.25em;
125: position: relative;
126: z-index: 1;
127: }
128: .element:before {
129: position: absolute;
130: z-index: 2;
131: top: 0;
132: left: -1.15em;
133: height: 2em;
134: width: 0.9em;
135: background: #EEEEFF;
136: content: ' ';
137: border-style: none none solid solid;
138: border-color: #9999FF;
139: border-width: 0.25em;
140: }
141:
1.149 mike 142: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
143: td > .example:only-child { margin: 0 0 0 0.1em; }
1.1 mike 144:
145: .tall-and-narrow {
146: font-size: 0.6em;
147: column-width: 25em;
148: column-gap: 1em;
149: -moz-column-width: 25em;
150: -moz-column-gap: 1em;
151: -webkit-column-width: 25em;
152: -webkit-column-gap: 1em;
153: }
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.267 mike 193: </style><style type="text/css">
194:
1.292 mike 195: .applies thead th > * { display: block; }
196: .applies thead code { display: block; }
197: .applies tbody th { whitespace: nowrap; }
198: .applies td { text-align: center; }
199: .applies .yes { background: yellow; }
200:
1.267 mike 201: .matrix, .matrix td { border: none; text-align: right; }
202: .matrix { margin-left: 2em; }
203:
204: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
205: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
206: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
207:
208: #table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
209: #table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
210: #table-example-1 caption { padding-bottom: 0.5em; }
211: #table-example-1 thead, #table-example-1 tbody { border: none; }
212: #table-example-1 th, #table-example-1 td { border: solid thin; }
213: #table-example-1 th { font-weight: normal; }
214: #table-example-1 td { border-style: none solid; vertical-align: top; }
215: #table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
216: #table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
217: #table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
218: #table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
219: #table-example-1 tbody td:first-child::after { content: leader(". "); }
220: #table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
221: #table-example-1 tbody td:first-child + td { width: 10em; }
222: #table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
223: #table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
224:
225: .apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
226: .apple-table-examples * { font-family: "Times", serif; }
227: .apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
228: .apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
229: .apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
230: .apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
231: .apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
232: .apple-table-examples td { text-align: right; vertical-align: top; }
233: .apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
234: .apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
235: .apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
236: .apple-table-examples sup { line-height: 0; }
237:
1.724 mike 238: .details-example img { vertical-align: top; }
239:
240: </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" id="author" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D" id="highlight" rel="alternate stylesheet" title="Highlight implementation requirements"><script type="text/javascript">
1.671 mike 241: function getCookie(name) {
242: var params = location.search.substr(1).split("&");
243: for (var index = 0; index < params.length; index++) {
244: if (params[index] == name)
245: return "1";
246: var data = params[index].split("=");
247: if (data[0] == name)
248: return unescape(data[1]);
249: }
250: var cookies = document.cookie.split("; ");
251: for (var index = 0; index < cookies.length; index++) {
252: var data = cookies[index].split("=");
253: if (data[0] == name)
254: return unescape(data[1]);
255: }
256: return null;
257: }
258: function load(script) {
259: var e = document.createElement('script');
260: e.setAttribute('src', 'http://www.whatwg.org/specs/web-apps/current-work/' + script + '?' + encodeURIComponent(location) + '&' + encodeURIComponent(document.referrer));
261: document.body.appendChild(e);
262: }
263: function init() {
264: if (location.search == '?slow-browser')
265: return;
266: var configUI = document.createElement('div');
267: configUI.id = 'configUI';
268: document.body.appendChild(configUI);
269: // load('reviewer.js'); // would need cross-site XHR
270: if (document.getElementById('head'))
271: load('toc.js');
272: load('styler.js');
273: // load('updater.js'); // would need cross-site XHR
1.724 mike 274: load('dfn.js'); // doesn't support split-out specs, but, oh well.
1.671 mike 275: // load('status.js'); // would need cross-site XHR
276: if (getCookie('profile') == '1')
277: document.getElementsByTagName('h2')[0].textContent += '; load: ' + (new Date() - loadTimer) + 'ms';
278: fixBrokenLink();
279: }
280: </script><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css">
1.2 mike 281: <script src="link-fixup.js"></script>
1.724 mike 282: <link href="interactive-elements.html" title="4.11 Interactive elements" rel="prev">
1.2 mike 283: <link href="spec.html#contents" title="Table of contents" rel="index">
1.755 mike 284: <link href="history.html" title="5.4 Session history and navigation" rel="next">
1.671 mike 285: </head><body onload="fixBrokenLink(); init()"><div class="head" id="head">
1.1 mike 286: <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.183 mike 287: <h1>HTML5</h1>
1.1 mike 288: <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.642 mike 289:
1.123 mike 290: </div><nav>
1.724 mike 291: <a href="interactive-elements.html">← 4.11 Interactive elements</a> –
1.2 mike 292: <a href="spec.html#contents">Table of contents</a> –
1.755 mike 293: <a href="history.html">5.4 Session history and navigation →</a>
1.770 ! mike 294: </nav><p>This is revision 1.3745.</p>
1.659 mike 295:
1.1 mike 296:
1.755 mike 297: <h2 id="browsers"><span class="secno">5 </span>Loading Web pages</h2><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><div class="impl">
1.1 mike 298:
299: <p>This section describes features that apply most directly to Web
1.409 mike 300: browsers. Having said that, except where specified otherwise, the
1.1 mike 301: requirements defined in this section <em>do</em> apply to all user
302: agents, whether they are Web browsers or not.</p>
303:
1.724 mike 304: </div><h3 id="windows"><span class="secno">5.1 </span>Browsing contexts</h3><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>A <dfn id="browsing-context">browsing context</dfn> is an environment in which
1.123 mike 305: <code>Document</code> objects are presented to the user.</p><p class="note">A tab or window in a Web browser typically contains
1.159 mike 306: a <a href="#browsing-context">browsing context</a>, as does an <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code><span class="impl"> or <code><a href="obsolete.html#frame">frame</a></code>s in a
1.123 mike 307: <code><a href="obsolete.html#frameset">frameset</a></code></span>.</p><p>Each <a href="#browsing-context">browsing context</a> has a corresponding
1.364 mike 308: <code><a href="#windowproxy">WindowProxy</a></code> object.</p><p>A <a href="#browsing-context">browsing context</a> has a <a href="history.html#session-history">session
309: history</a>, which lists the <code>Document</code> objects that
310: that <a href="#browsing-context">browsing context</a> has presented, is presenting, or
311: will present. At any time, one <code>Document</code> in each
312: <a href="#browsing-context">browsing context</a> is designated the <dfn id="active-document">active
313: document</dfn>.</p><p>Each <code>Document</code> has a collection of one or more <a href="#view" title="view">views</a>.</p><p>A <dfn id="view">view</dfn> is a user agent interface tied to a particular
1.1 mike 314: media used for the presentation of a particular
315: <code>Document</code> object in some media. A view may be
316: interactive. Each view is represented by an
1.123 mike 317: <code>AbstractView</code> object. <a href="references.html#refsDOMVIEWS">[DOMVIEWS]</a></p><p>The main <a href="#view">view</a> through which a user primarily
1.1 mike 318: interacts with a user agent is the <dfn id="default-view">default view</dfn>. The
319: <code>AbstractView</code> object that represents this view <span class="impl">must also implement the <code><a href="#window">Window</a></code> interface,
320: and</span> is referred to as the <code>Document</code>'s
321: <code><a href="#window">Window</a></code> object. <code><a href="#windowproxy">WindowProxy</a></code> objects forward
322: everything to the <a href="#active-document">active document</a>'s <a href="#default-view">default
1.123 mike 323: view</a>'s <code><a href="#window">Window</a></code> object.</p><div class="impl">
1.1 mike 324:
325: <p>The <code title="dom-document-defaultView">defaultView</code>
326: attribute on the <code>Document</code> object's
327: <code>DocumentView</code> interface must return the <a href="#browsing-context">browsing
328: context</a>'s <code><a href="#windowproxy">WindowProxy</a></code> object, not the actual
329: <code>AbstractView</code> object of the <a href="#default-view">default
1.104 mike 330: view</a>. <a href="references.html#refsDOMVIEWS">[DOMVIEWS]</a></p>
1.1 mike 331:
1.123 mike 332: </div><p class="note">The <code title="dom-document">document</code>
1.1 mike 333: attribute of an <code>AbstractView</code> object representing a
334: <a href="#view">view</a> gives the view's corresponding
1.123 mike 335: <code>Document</code> object. <a href="references.html#refsDOMVIEWS">[DOMVIEWS]</a></p><p class="note">In general, there is a 1-to-1 mapping from the
1.1 mike 336: <code><a href="#window">Window</a></code> object to the <code>Document</code> object. In
337: one particular case, a set of <a href="#view" title="view">views</a> can be
338: reused for the presentation of a second <code>Document</code> in the
339: same <a href="#browsing-context">browsing context</a>, such that the mapping is then
340: 2:1. This occurs when a <a href="#browsing-context">browsing context</a> is <a href="history.html#navigate" title="navigate">navigated</a> from the initial
341: <code><a href="infrastructure.html#about:blank">about:blank</a></code> <code>Document</code> to another, with
1.123 mike 342: <a href="history.html#replacement-enabled">replacement enabled</a>.</p><div class="impl">
1.1 mike 343:
344: <p>Events that use the <code>UIEvent</code> interface are related to
345: a specific <a href="#view">view</a> (the view in which the event happened);
346: when that <a href="#view">view</a> is the <a href="#default-view">default view</a>, the
347: event object's <code title="">view</code> attribute's must return
348: the <code><a href="#windowproxy">WindowProxy</a></code> object of the <a href="#browsing-context">browsing
349: context</a> of that <a href="#view">view</a>, not the actual
350: <code>AbstractView</code> object of the <a href="#default-view">default
1.104 mike 351: view</a>. <a href="references.html#refsDOMEVENTS">[DOMEVENTS]</a></p>
1.1 mike 352:
1.123 mike 353: </div><p class="note">A typical Web browser has one obvious
1.1 mike 354: <a href="#view">view</a> per <code>Document</code>: the browser's window
355: (screen media). This is typically the <a href="#default-view">default view</a>. If
356: a page is printed, however, a second view becomes evident, that of
357: the print media. The two views always share the same underlying
358: <code>Document</code> object, but they have a different presentation
359: of that object. A speech browser might have a different
1.123 mike 360: <a href="#default-view">default view</a>, using the speech media.</p><p class="note">A <code>Document</code> does not necessarily have a
1.1 mike 361: <a href="#browsing-context">browsing context</a> associated with it. In particular,
362: data mining tools are likely to never instantiate browsing
1.123 mike 363: contexts.</p><hr><p>A <a href="#browsing-context">browsing context</a> can have a <dfn id="creator-browsing-context">creator browsing
1.1 mike 364: context</dfn>, the <a href="#browsing-context">browsing context</a> that was
1.742 mike 365: responsible for its creation. If a <a href="#browsing-context">browsing context</a> has
366: a <a href="#parent-browsing-context">parent browsing context</a>, then that is its
367: <a href="#creator-browsing-context">creator browsing context</a>. Otherwise, if the
368: <a href="#browsing-context">browsing context</a> has an <a href="#opener-browsing-context">opener browsing
369: context</a>, then <em>that</em> is its <a href="#creator-browsing-context">creator browsing
370: context</a>. Otherwise, the <a href="#browsing-context">browsing context</a> has no
371: <a href="#creator-browsing-context">creator browsing context</a>.</p><p>If a <a href="#browsing-context">browsing context</a> <var title="">A</var> has a
1.1 mike 372: <a href="#creator-browsing-context">creator browsing context</a>, then the
373: <code>Document</code> that was the <a href="#active-document">active document</a> of
374: 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.123 mike 375: <code>Document</code></dfn>.</p><div class="impl">
1.1 mike 376:
377: <p>When a <a href="#browsing-context">browsing context</a> is first created, it must be
378: created with a single <code>Document</code> in its session history,
379: whose <a href="dom.html#the-document-s-address" title="the document's address">address</a> is
380: <code><a href="infrastructure.html#about:blank">about:blank</a></code>, which is marked as being an <a href="dom.html#html-documents" title="HTML documents">HTML document</a>, and whose <a href="dom.html#document-s-character-encoding" title="document's character encoding">character encoding</a> is
381: UTF-8. The <code>Document</code> must have a single child
1.159 mike 382: <code><a href="semantics.html#the-html-element-0">html</a></code> node, which itself has a single child
383: <code><a href="semantics.html#the-body-element-0">body</a></code> node.</p>
1.1 mike 384:
385: <p class="note">If the <a href="#browsing-context">browsing context</a> is created
386: specifically to be immediately navigated, then that initial
387: navigation will have <a href="history.html#replacement-enabled">replacement enabled</a>.</p>
388:
1.159 mike 389: <p id="about-blank-origin">The <a href="#origin">origin</a> of the
1.1 mike 390: <code><a href="infrastructure.html#about:blank">about:blank</a></code> <code>Document</code> is set when the
391: <code>Document</code> is created. If the new <a href="#browsing-context">browsing
392: context</a> has a <a href="#creator-browsing-context">creator browsing context</a>, then the
1.159 mike 393: <a href="#origin">origin</a> of the <code><a href="infrastructure.html#about:blank">about:blank</a></code>
394: <code>Document</code> is the <a href="#origin">origin</a> of the
1.1 mike 395: <a href="#creator-document">creator <code>Document</code></a>. Otherwise, the
1.159 mike 396: <a href="#origin">origin</a> of the <code><a href="infrastructure.html#about:blank">about:blank</a></code>
1.1 mike 397: <code>Document</code> is a globally unique identifier assigned when
398: the new <a href="#browsing-context">browsing context</a> is created.</p>
399:
1.724 mike 400: </div><h4 id="nested-browsing-contexts"><span class="secno">5.1.1 </span>Nested browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>Certain elements (for example, <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code> elements) can
1.1 mike 401: instantiate further <a href="#browsing-context" title="browsing context">browsing
402: contexts</a>. These are called <dfn id="nested-browsing-context" title="nested browsing
403: context">nested browsing contexts</dfn>. If a browsing context <var title="">P</var> has an element <var title="">E</var> in one of its
404: <code>Document</code>s <var title="">D</var> that nests another
405: browsing context <var title="">C</var> inside it, then <var title="">P</var> is said to be the <dfn id="parent-browsing-context">parent browsing
406: context</dfn> of <var title="">C</var>, <var title="">C</var> is
407: said to be a <dfn id="child-browsing-context">child browsing context</dfn> of <var title="">P</var>, <var title="">C</var> is said to be <dfn id="browsing-context-nested-through" title="browsing context nested through">nested through</dfn> <var title="">D</var>, and <var title="">E</var> is said to be the
1.123 mike 408: <dfn id="browsing-context-container">browsing context container</dfn> of <var title="">C</var>.</p><p>A browsing context <var title="">A</var> is said to be an
1.1 mike 409: ancestor of a browsing context <var title="">B</var> if there exists
410: a browsing context <var title="">A'</var> that is a <a href="#child-browsing-context">child
411: browsing context</a> of <var title="">A</var> and that is itself
412: an ancestor of <var title="">B</var>, or if there is a browsing
413: context <var title="">P</var> that is a <a href="#child-browsing-context">child browsing
414: context</a> of <var title="">A</var> and that is the <a href="#parent-browsing-context">parent
1.123 mike 415: browsing context</a> of <var title="">B</var>.</p><p>The browsing context with no <a href="#parent-browsing-context">parent browsing context</a>
1.1 mike 416: is the <dfn id="top-level-browsing-context">top-level browsing context</dfn> of all the browsing
417: contexts <a href="#nested-browsing-context" title="nested browsing context">nested</a> within
418: it (either directly or indirectly through other nested browsing
1.123 mike 419: contexts).</p><p>The transitive closure of <a href="#parent-browsing-context" title="parent browsing
1.1 mike 420: context">parent browsing contexts</a> for a <a href="#nested-browsing-context">nested browsing
421: context</a> gives the list of <dfn id="ancestor-browsing-context" title="ancestor browsing
1.698 mike 422: context">ancestor browsing contexts</dfn>.</p><p>The <dfn id="list-of-the-descendant-browsing-contexts">list of the descendant browsing contexts</dfn> of a
423: <code>Document</code> <var title="">d</var> is the list returned by
424: the following algorithm:</p><ol><li><p>Let <var title="">list</var> be an empty list.</p></li>
425:
426: <li><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
427: through">nested through</a> an element that is <a href="infrastructure.html#in-a-document" title="in a
428: 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 of
429: the elements nesting those <a href="#browsing-context" title="browsing context">browsing
430: contexts</a>, append to the list <var title="">list</var> the
431: <a href="#list-of-the-descendant-browsing-contexts">list of the descendant browsing contexts</a> of the
432: <a href="#active-document">active document</a> of that <a href="#child-browsing-context">child browsing
433: context</a>.</p></li>
434:
435: <li><p>Return the constructed <var title="">list</var>.</p></li>
436:
437: </ol><hr><p>A <code>Document</code> is said to be <dfn id="fully-active">fully active</dfn>
1.1 mike 438: when it is the <a href="#active-document">active document</a> of its <a href="#browsing-context">browsing
439: context</a>, and either its browsing context is a <a href="#top-level-browsing-context">top-level
440: browsing context</a>, or the <code>Document</code> <a href="#browsing-context-nested-through" title="browsing context nested through">through which</a> that
441: browsing context is <a href="#nested-browsing-context" title="nested browsing
1.123 mike 442: context">nested</a> is itself <a href="#fully-active">fully active</a>.</p><p>Because they are nested through an element, <a href="#child-browsing-context" title="child
1.1 mike 443: browsing context">child browsing contexts</a> are always tied to
444: a specific <code>Document</code> in their <a href="#parent-browsing-context">parent browsing
445: context</a>. User agents must not allow the user to interact with
446: <a href="#child-browsing-context" title="child browsing context">child browsing contexts</a>
447: of elements that are in <code>Document</code>s that are not
1.159 mike 448: themselves <a href="#fully-active">fully active</a>.</p><p>A <a href="#nested-browsing-context">nested browsing context</a> can have a <a href="text-level-semantics.html#seamless-browsing-context-flag">seamless
1.1 mike 449: browsing context flag</a> set, if it is embedded through an
1.724 mike 450: <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code> element with a <code title="attr-iframe-seamless"><a href="text-level-semantics.html#attr-iframe-seamless">seamless</a></code> attribute.</p><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><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">window</var> . <code title="dom-top"><a href="#dom-top">top</a></code></dt>
1.1 mike 451:
452: <dd>
453:
454: <p>Returns the <code><a href="#windowproxy">WindowProxy</a></code> for the <a href="#top-level-browsing-context">top-level browsing context</a>.</p>
455:
456: </dd>
457:
458: <dt><var title="">window</var> . <code title="dom-parent"><a href="#dom-parent">parent</a></code></dt>
459:
460: <dd>
461:
462: <p>Returns the <code><a href="#windowproxy">WindowProxy</a></code> for the <a href="#parent-browsing-context">parent browsing context</a>.</p>
463:
464: </dd>
465:
466: <dt><var title="">window</var> . <code title="dom-frameElement"><a href="#dom-frameelement">frameElement</a></code></dt>
467:
468: <dd>
469:
470: <p>Returns the <code>Element</code> for the <a href="#browsing-context-container">browsing context container</a>.</p>
471:
472: <p>Returns null if there isn't one.</p>
473:
474: <p>Throws a <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception in cross-origin situations.</p>
475:
476: </dd>
477:
478: </dl><div class="impl">
479:
1.192 mike 480: <p>The <dfn id="dom-top" title="dom-top"><code>top</code></dfn> IDL attribute on
1.1 mike 481: the <code><a href="#window">Window</a></code> object of a <code>Document</code> in a
482: <a href="#browsing-context">browsing context</a> <var title="">b</var> must return the
483: <code><a href="#windowproxy">WindowProxy</a></code> object of its <a href="#top-level-browsing-context">top-level browsing
484: context</a> (which would be its own <code><a href="#windowproxy">WindowProxy</a></code>
485: object if it was a <a href="#top-level-browsing-context">top-level browsing context</a>
486: itself).</p>
487:
1.192 mike 488: <p>The <dfn id="dom-parent" title="dom-parent"><code>parent</code></dfn> IDL
1.1 mike 489: attribute on the <code><a href="#window">Window</a></code> object of a
490: <code>Document</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
491: the <a href="#parent-browsing-context">parent browsing context</a>, if there is one (i.e. if
492: <var title="">b</var> is a <a href="#child-browsing-context">child browsing context</a>), or
493: the <code><a href="#windowproxy">WindowProxy</a></code> object of the <a href="#browsing-context">browsing
494: context</a> <var title="">b</var> itself, otherwise (i.e. if it
495: is a <a href="#top-level-browsing-context">top-level browsing context</a>).</p>
496:
497: <p>The <dfn id="dom-frameelement" title="dom-frameElement"><code>frameElement</code></dfn>
1.192 mike 498: IDL attribute on the <code><a href="#window">Window</a></code> object of a
1.1 mike 499: <code>Document</code> <var title="">d</var>, on getting, must run
500: the following algorithm:</p>
501:
502: <ol><li><p>If <var title="">d</var> is not a <code>Document</code> in a
503: <a href="#child-browsing-context">child browsing context</a>, return null and abort these
504: steps.</p></li>
505:
506: <li><p>If the <a href="#parent-browsing-context">parent browsing context</a>'s <a href="#active-document">active
1.582 mike 507: document</a> does not have the <a href="#same-origin" title="same
508: origin">same</a> <a href="#effective-script-origin">effective script origin</a> as the
1.700 mike 509: <a href="#entry-script">entry script</a>, then throw a <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code>
1.582 mike 510: exception.</p></li>
1.1 mike 511:
512: <li><p>Otherwise, return the <a href="#browsing-context-container">browsing context
513: container</a> for <var title="">b</var>.</p></li>
514:
1.724 mike 515: </ol></div><h4 id="auxiliary-browsing-contexts"><span class="secno">5.1.2 </span>Auxiliary browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>It is possible to create new browsing contexts that are related
1.174 mike 516: to a <a href="#top-level-browsing-context">top-level browsing context</a> without being nested
1.1 mike 517: through an element. Such browsing contexts are called <dfn id="auxiliary-browsing-context" title="auxiliary browsing context">auxiliary browsing
518: contexts</dfn>. Auxiliary browsing contexts are always <a href="#top-level-browsing-context" title="top-level browsing context">top-level browsing
1.123 mike 519: contexts</a>.</p><p>An <a href="#auxiliary-browsing-context">auxiliary browsing context</a> has an <dfn id="opener-browsing-context">opener
1.1 mike 520: browsing context</dfn>, which is the <a href="#browsing-context">browsing context</a>
521: from which the <a href="#auxiliary-browsing-context">auxiliary browsing context</a> was created,
522: and it has a <dfn id="furthest-ancestor-browsing-context">furthest ancestor browsing context</dfn>, which is
523: the <a href="#top-level-browsing-context">top-level browsing context</a> of the <a href="#opener-browsing-context">opener
524: browsing context</a> when the <a href="#auxiliary-browsing-context">auxiliary browsing
1.724 mike 525: context</a> was created.</p><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><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>The <dfn id="dom-opener" title="dom-opener"><code>opener</code></dfn> IDL
1.1 mike 526: attribute on the <code><a href="#window">Window</a></code> object must return the
527: <code><a href="#windowproxy">WindowProxy</a></code> object of the <a href="#browsing-context">browsing context</a>
528: from which the current <a href="#browsing-context">browsing context</a> was created
529: (its <a href="#opener-browsing-context">opener browsing context</a>), if there is one and it
1.724 mike 530: is still available.</p><h4 id="secondary-browsing-contexts"><span class="secno">5.1.3 </span>Secondary browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>User agents may support <dfn id="secondary-browsing-context" title="secondary browsing
1.1 mike 531: context">secondary browsing contexts</dfn>, which are <a href="#browsing-context" title="browsing context">browsing contexts</a> that form part of
1.123 mike 532: the user agent's interface, apart from the main content area.</p><div class="impl">
1.1 mike 533:
1.724 mike 534: <h4 id="security-1"><span class="secno">5.1.4 </span>Security</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 535:
536: <p>A <a href="#browsing-context">browsing context</a> <var title="">A</var> is
537: <dfn id="allowed-to-navigate">allowed to navigate</dfn> a second <a href="#browsing-context">browsing
538: context</a> <var title="">B</var> if one of the following
539: conditions is true:</p>
540:
1.159 mike 541: <ul><li>Either the <a href="#origin">origin</a> of the <a href="#active-document">active
1.1 mike 542: document</a> of <var title="">A</var> is the <a href="#same-origin" title="same
1.159 mike 543: origin">same</a> as the <a href="#origin">origin</a> of the <a href="#active-document">active
1.1 mike 544: document</a> of <var title="">B</var>, or</li>
545:
546: <li>The browsing context <var title="">A</var> is a <a href="#nested-browsing-context">nested
547: browsing context</a> and its <a href="#top-level-browsing-context">top-level browsing
548: context</a> is <var title="">B</var>, or</li>
549:
550: <li>The browsing context <var title="">B</var> is an
551: <a href="#auxiliary-browsing-context">auxiliary browsing context</a> and <var title="">A</var>
552: is <a href="#allowed-to-navigate">allowed to navigate</a> <var title="">B</var>'s
553: <a href="#opener-browsing-context">opener browsing context</a>, or</li>
554:
555: <li>The browsing context <var title="">B</var> is not a
556: <a href="#top-level-browsing-context">top-level browsing context</a>, but there exists an
557: <a href="#ancestor-browsing-context">ancestor browsing context</a> of <var title="">B</var>
558: whose <a href="#active-document">active document</a> has the <a href="#same-origin" title="same
1.159 mike 559: origin">same</a> <a href="#origin">origin</a> as the <a href="#active-document">active
1.1 mike 560: document</a> of <var title="">A</var> (possibly in fact being
561: <var title="">A</var> itself).</li>
562:
1.414 mike 563: </ul><hr><p>An element has a <dfn id="browsing-context-scope-origin">browsing context scope origin</dfn> if its
564: <code>Document</code>'s <a href="#browsing-context">browsing context</a> is a
565: <a href="#top-level-browsing-context">top-level browsing context</a> or if all of its
566: <code>Document</code>'s <a href="#ancestor-browsing-context" title="ancestor browsing
567: context">ancestor browsing contexts</a> all have <a href="#active-document" title="active document">active documents</a> whose
568: <a href="#origin">origin</a> are the <a href="#same-origin">same origin</a> as the
569: element's <code>Document</code>'s <a href="#origin">origin</a>. If an element
570: has a <a href="#browsing-context-scope-origin">browsing context scope origin</a>, then its value is
571: the <a href="#origin">origin</a> of the element's <code>Document</code>.</p>
572:
573: </div><div class="impl">
1.1 mike 574:
1.724 mike 575: <h4 id="groupings-of-browsing-contexts"><span class="secno">5.1.5 </span>Groupings of browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 576:
577: <p>Each <a href="#browsing-context">browsing context</a> is defined as having a list of
578: zero or more <dfn id="directly-reachable-browsing-contexts">directly reachable browsing contexts</dfn>. These
579: are:</p>
580:
581: <ul><li>All the <a href="#browsing-context">browsing context</a>'s <a href="#child-browsing-context" title="child
582: browsing context">child browsing contexts</a>.</li>
583:
584: <li>The <a href="#browsing-context">browsing context</a>'s <a href="#parent-browsing-context">parent browsing
585: context</a>.</li>
586:
587: <li>All the <a href="#browsing-context" title="browsing context">browsing contexts</a>
588: that have the <a href="#browsing-context">browsing context</a> as their <a href="#opener-browsing-context">opener
589: browsing context</a>.</li>
590:
591: <li>The <a href="#browsing-context">browsing context</a>'s <a href="#opener-browsing-context">opener browsing
592: context</a>.</li>
593:
594: </ul><p>The transitive closure of all the <a href="#browsing-context" title="browsing
595: context">browsing contexts</a> that are <a href="#directly-reachable-browsing-contexts">directly reachable
596: browsing contexts</a> forms a <dfn id="unit-of-related-browsing-contexts">unit of related browsing
597: contexts</dfn>.</p>
598:
599: <p>Each <a href="#unit-of-related-browsing-contexts">unit of related browsing contexts</a> is then
600: further divided into the smallest number of groups such that every
601: member of each group has an <a href="#effective-script-origin">effective script origin</a>
602: that, through appropriate manipulation of the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute, could
603: be made to be the same as other members of the group, but could not
604: be made the same as members of any other group. Each such group is a
605: <dfn id="unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing contexts</dfn>.</p>
606:
607: <p>Each <a href="#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing
1.700 mike 608: contexts</a> can have a <dfn id="entry-script">entry script</dfn> which is used to
1.755 mike 609: obtain, amongst other things, the <a href="web-application-apis.html#script-s-base-url">script's base URL</a> to
1.1 mike 610: <a href="infrastructure.html#resolve-a-url" title="resolve a url">resolve</a> relative <a href="infrastructure.html#url" title="URL">URLs</a> used in scripts running in that <a href="#unit-of-related-similar-origin-browsing-contexts">unit
611: of related similar-origin browsing contexts</a>. Initially, there
1.700 mike 612: is no <a href="#entry-script">entry script</a>.</p>
1.1 mike 613:
1.755 mike 614: <p class="note">There is at most one <a href="web-application-apis.html#event-loop">event loop</a> per
1.213 mike 615: <a href="#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing contexts</a>.</p>
616:
1.724 mike 617: </div><h4 id="browsing-context-names"><span class="secno">5.1.6 </span>Browsing context names</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>Browsing contexts can have a <dfn id="browsing-context-name">browsing context name</dfn>. By
1.123 mike 618: default, a browsing context has no name (its name is not set).</p><p>A <dfn id="valid-browsing-context-name">valid browsing context name</dfn> is any string with at
1.1 mike 619: least one character that does not start with a U+005F LOW LINE
620: character. (Names starting with an underscore are reserved for
1.123 mike 621: special keywords.)</p><p>A <dfn id="valid-browsing-context-name-or-keyword">valid browsing context name or keyword</dfn> is any string
1.1 mike 622: that is either a <a href="#valid-browsing-context-name">valid browsing context name</a> or that is
1.123 mike 623: 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><div class="impl">
1.1 mike 624:
625: <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
626: context name</dfn> are as follows. The rules assume that they are
627: being applied in the context of a <a href="#browsing-context">browsing context</a>.</p>
628:
629: <ol><li><p>If the given browsing context name is the empty string or
630: <code title="">_self</code>, then the chosen browsing context must
631: be the current one.</p></li>
632:
633: <li><p>If the given browsing context name is <code title="">_parent</code>, then the chosen browsing context must be
634: the <a href="#parent-browsing-context"><em>parent</em> browsing context</a> of the current
635: one, unless there isn't one, in which case the chosen browsing
636: context must be the current browsing context.</p></li>
637:
638: <li><p>If the given browsing context name is <code title="">_top</code>, then the chosen browsing context must be the
639: most <a href="#top-level-browsing-context">top-level browsing context</a> of the current
640: one.</p></li>
641:
642: <li>
643:
644: <p>If the given browsing context name is not <code title="">_blank</code> and there exists a browsing context whose
645: <a href="#browsing-context-name" title="browsing context name">name</a> is the same as the
646: given browsing context name, and the current browsing context is
647: <a href="#allowed-to-navigate">allowed to navigate</a> that browsing context, and the
648: user agent determines that the two browsing contexts are related
649: enough that it is ok if they reach each other, then that browsing
650: context must be the chosen one. If there are multiple matching
651: browsing contexts, the user agent should select one in some
652: arbitrary consistent manner, such as the most recently opened,
653: most recently focused, or more closely related.</p>
654:
655: </li>
656:
657: <li>
658:
659: <p>Otherwise, a new browsing context is being requested, and what
660: happens depends on the user agent's configuration and/or
661: abilities:</p>
662:
1.724 mike 663: <dl><dt id="sandboxWindowOpen">If the current browsing context had
664: the <a href="text-level-semantics.html#sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context flag</a> set
665: when its <a href="#active-document">active document</a> was created.</dt>
1.1 mike 666:
667: <dd><p>The user agent may offer to create a new <a href="#top-level-browsing-context">top-level
668: browsing context</a> or reuse an existing <a href="#top-level-browsing-context">top-level
669: browsing context</a>. If the user picks one of those options,
670: then the designated browsing context must be the chosen one (the
671: browsing context's name isn't set to the given browsing context
672: name). Otherwise (if the user agent doesn't offer the option to
673: the user, or if the user declines to allow a browsing context to
674: be used) there must not be a chosen browsing context.</p></dd>
675:
1.730 mike 676:
1.1 mike 677: <dt id="noopener">If the user agent has been configured such that
678: in this instance it will create a new browsing context, and the
1.754 mike 679: browsing context is being requested as part of <a href="interactive-elements.html#following-hyperlinks" title="following hyperlinks">following a hyperlink</a> whose
680: <a href="interactive-elements.html#linkTypes">link types</a> include the <code title="rel-noreferrer"><a href="interactive-elements.html#link-type-noreferrer">noreferrer</a></code> keyword</dt>
1.1 mike 681:
682: <dd><p>A new <a href="#top-level-browsing-context">top-level browsing context</a> must be
683: created. If the given browsing context name is not <code title="">_blank</code>, then the new top-level browsing context's
684: name must be the given browsing context name (otherwise, it has
685: no name). The chosen browsing context must be this new browsing
686: context.</p>
687:
688: <p class="note">If it is immediately <a href="history.html#navigate" title="navigate">navigated</a>, then the navigation will be
689: done with <a href="history.html#replacement-enabled">replacement enabled</a>.</p></dd>
690:
1.730 mike 691:
1.1 mike 692: <dt>If the user agent has been configured such that in this
1.754 mike 693: instance it will create a new browsing context, and the <code title="rel-noreferrer"><a href="interactive-elements.html#link-type-noreferrer">noreferrer</a></code> keyword doesn't
1.1 mike 694: apply</dt>
695:
696: <dd><p>A new <a href="#auxiliary-browsing-context">auxiliary browsing context</a> must be
697: created, with the <a href="#opener-browsing-context">opener browsing context</a> being the
698: current one. If the given browsing context name is not <code title="">_blank</code>, then the new auxiliary browsing context's
699: name must be the given browsing context name (otherwise, it has
700: no name). The chosen browsing context must be this new browsing
701: context.</p>
702:
703: <p>If it is immediately <a href="history.html#navigate" title="navigate">navigated</a>,
704: then the navigation will be done with <a href="history.html#replacement-enabled">replacement
705: enabled</a>.</p></dd>
706:
1.730 mike 707:
1.1 mike 708: <dt>If the user agent has been configured such that in this
709: instance it will reuse the current browsing context</dt>
710:
711: <dd><p>The chosen browsing context is the current browsing
712: context.</p></dd>
713:
1.730 mike 714:
1.1 mike 715: <dt>If the user agent has been configured such that in this
716: instance it will not find a browsing context</dt>
717:
718: <dd><p>There must not be a chosen browsing context.</p></dd>
719:
720: </dl><p>User agent implementors are encouraged to provide a way for
721: users to configure the user agent to always reuse the current
722: browsing context.</p>
723:
724: </li>
725:
1.754 mike 726: </ol></div><h3 id="the-window-object"><span class="secno">5.2 </span>The <code><a href="#window">Window</a></code> object</h3><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><pre class="idl">[OverrideBuiltins, ReplaceableNamedProperties] <!-- XXX http://www.w3.org/Bugs/Public/show_bug.cgi?id=8241 -->
1.1 mike 727: interface <dfn id="window">Window</dfn> {
728: // the current browsing context
729: readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-window" title="dom-window">window</a>;
730: readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-self" title="dom-self">self</a>;
731: attribute DOMString <a href="#dom-name" title="dom-name">name</a>;
732: [PutForwards=href] readonly attribute <a href="history.html#location">Location</a> <a href="history.html#dom-location" title="dom-location">location</a>;
1.159 mike 733: readonly attribute <a href="history.html#history-0">History</a> <a href="history.html#dom-history" title="dom-history">history</a>;
1.1 mike 734: readonly attribute <a href="editing.html#undomanager">UndoManager</a> <a href="editing.html#dom-undomanager" title="dom-undoManager">undoManager</a>;
735: <a href="editing.html#selection-0">Selection</a> <a href="editing.html#dom-getselection" title="dom-getSelection">getSelection</a>();
736: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-locationbar" title="dom-window-locationbar">locationbar</a>;
737: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-menubar" title="dom-window-menubar">menubar</a>;
738: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-personalbar" title="dom-window-personalbar">personalbar</a>;
739: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-scrollbars" title="dom-window-scrollbars">scrollbars</a>;
740: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-statusbar" title="dom-window-statusbar">statusbar</a>;
741: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-toolbar" title="dom-window-toolbar">toolbar</a>;<!--
742: [Replaceable] readonly attribute <span>BarProp</span> <span title="dom-window-directories">directories</span>; // legacy (Gecko-only) -->
743: void <a href="#dom-window-close" title="dom-window-close">close</a>();
744: void <a href="editing.html#dom-window-focus" title="dom-window-focus">focus</a>();
745: void <a href="editing.html#dom-window-blur" title="dom-window-blur">blur</a>();
746:
747: // other browsing contexts
1.190 mike 748: [Replaceable] readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-frames" title="dom-frames">frames</a>;
749: [Replaceable] readonly attribute unsigned long <a href="#dom-length" title="dom-length">length</a>;
1.1 mike 750: readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-top" title="dom-top">top</a>;
751: [Replaceable] readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-opener" title="dom-opener">opener</a>;
752: readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-parent" title="dom-parent">parent</a>;
753: readonly attribute <span>Element</span> <a href="#dom-frameelement" title="dom-frameElement">frameElement</a>;
1.401 mike 754: <a href="#windowproxy">WindowProxy</a> <a href="#dom-open" title="dom-open">open</a>(in optional DOMString url, in optional DOMString target, in optional DOMString features, in optional DOMString replace);
1.87 mike 755: <a href="#dom-window-item" title="dom-window-item">getter</a> <a href="#windowproxy">WindowProxy</a> (in unsigned long index);
756: <a href="#dom-window-nameditem" title="dom-window-namedItem">getter</a> <a href="#windowproxy">WindowProxy</a> (in DOMString name);
1.1 mike 757:
758: // the user agent
1.755 mike 759: readonly attribute <a href="web-application-apis.html#navigator">Navigator</a> <a href="web-application-apis.html#dom-navigator" title="dom-navigator">navigator</a>; <!-- IE also has window.clientInformation === window.navigator -->
1.1 mike 760: readonly attribute <a href="offline.html#applicationcache">ApplicationCache</a> <a href="offline.html#dom-applicationcache" title="dom-applicationCache">applicationCache</a>;
761:
762: // user prompts
1.755 mike 763: void <a href="web-application-apis.html#dom-alert" title="dom-alert">alert</a>(in DOMString message);
764: boolean <a href="web-application-apis.html#dom-confirm" title="dom-confirm">confirm</a>(in DOMString message);
765: DOMString <a href="web-application-apis.html#dom-prompt" title="dom-prompt">prompt</a>(in DOMString message, in optional DOMString default);
766: void <a href="web-application-apis.html#dom-print" title="dom-print">print</a>();
767: any <a href="web-application-apis.html#dom-showmodaldialog" title="dom-showModalDialog">showModalDialog</a>(in DOMString url, in optional any argument<!--, in optional DOMString features-->);
768:
769: // <a href="web-application-apis.html#event-handler-idl-attributes">event handler IDL attributes</a>
770: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onabort" title="handler-onabort">onabort</a>;
771: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onafterprint" title="handler-window-onafterprint">onafterprint</a>;
772: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onbeforeprint" title="handler-window-onbeforeprint">onbeforeprint</a>;
773: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onbeforeunload" title="handler-window-onbeforeunload">onbeforeunload</a>;
774: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onblur" title="handler-window-onblur">onblur</a>;
775: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-oncanplay" title="handler-oncanplay">oncanplay</a>;
776: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-oncanplaythrough" title="handler-oncanplaythrough">oncanplaythrough</a>;
777: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onchange" title="handler-onchange">onchange</a>;
778: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onclick" title="handler-onclick">onclick</a>;
779: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-oncontextmenu" title="handler-oncontextmenu">oncontextmenu</a>;
780: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-ondblclick" title="handler-ondblclick">ondblclick</a>;
781: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-ondrag" title="handler-ondrag">ondrag</a>;
782: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-ondragend" title="handler-ondragend">ondragend</a>;
783: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-ondragenter" title="handler-ondragenter">ondragenter</a>;
784: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-ondragleave" title="handler-ondragleave">ondragleave</a>;
785: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-ondragover" title="handler-ondragover">ondragover</a>;
786: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-ondragstart" title="handler-ondragstart">ondragstart</a>;
787: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-ondrop" title="handler-ondrop">ondrop</a>;
788: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-ondurationchange" title="handler-ondurationchange">ondurationchange</a>;
789: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onemptied" title="handler-onemptied">onemptied</a>;
790: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onended" title="handler-onended">onended</a>;
791: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onerror" title="handler-window-onerror">onerror</a>;
792: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onfocus" title="handler-window-onfocus">onfocus</a>;
793: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onformchange" title="handler-onformchange">onformchange</a>;
794: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onforminput" title="handler-onforminput">onforminput</a>;
795: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onhashchange" title="handler-window-onhashchange">onhashchange</a>;
796: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-oninput" title="handler-oninput">oninput</a>;
797: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-oninvalid" title="handler-oninvalid">oninvalid</a>;
798: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onkeydown" title="handler-onkeydown">onkeydown</a>;
799: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onkeypress" title="handler-onkeypress">onkeypress</a>;
800: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onkeyup" title="handler-onkeyup">onkeyup</a>;
801: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onload" title="handler-window-onload">onload</a>;
802: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onloadeddata" title="handler-onloadeddata">onloadeddata</a>;
803: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onloadedmetadata" title="handler-onloadedmetadata">onloadedmetadata</a>;
804: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onloadstart" title="handler-onloadstart">onloadstart</a>;
805: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onmessage" title="handler-window-onmessage">onmessage</a>;
806: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onmousedown" title="handler-onmousedown">onmousedown</a>;
807: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onmousemove" title="handler-onmousemove">onmousemove</a>;
808: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onmouseout" title="handler-onmouseout">onmouseout</a>;
809: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onmouseover" title="handler-onmouseover">onmouseover</a>;
810: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onmouseup" title="handler-onmouseup">onmouseup</a>;
811: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onmousewheel" title="handler-onmousewheel">onmousewheel</a>;
812: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onoffline" title="handler-window-onoffline">onoffline</a>;
813: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-ononline" title="handler-window-ononline">ononline</a>;
814: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onpause" title="handler-onpause">onpause</a>;
815: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onplay" title="handler-onplay">onplay</a>;
816: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onplaying" title="handler-onplaying">onplaying</a>;
817: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onpagehide" title="handler-window-onpagehide">onpagehide</a>;
818: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onpageshow" title="handler-window-onpageshow">onpageshow</a>;
819: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onpopstate" title="handler-window-onpopstate">onpopstate</a>;
820: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onprogress" title="handler-onprogress">onprogress</a>;
821: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onratechange" title="handler-onratechange">onratechange</a>;
822: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onreadystatechange" title="handler-onreadystatechange">onreadystatechange</a>;
823: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onredo" title="handler-window-onredo">onredo</a>;
824: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onresize" title="handler-window-onresize">onresize</a>;
825: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onscroll" title="handler-onscroll">onscroll</a>;
826: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onseeked" title="handler-onseeked">onseeked</a>;
827: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onseeking" title="handler-onseeking">onseeking</a>;
828: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onselect" title="handler-onselect">onselect</a>;
829: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onshow" title="handler-onshow">onshow</a>;
830: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onstalled" title="handler-onstalled">onstalled</a>;
831: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onstorage" title="handler-window-onstorage">onstorage</a>;
832: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onsubmit" title="handler-onsubmit">onsubmit</a>;
833: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onsuspend" title="handler-onsuspend">onsuspend</a>;
834: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-ontimeupdate" title="handler-ontimeupdate">ontimeupdate</a>;
835: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onundo" title="handler-window-onundo">onundo</a>;
836: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-window-onunload" title="handler-window-onunload">onunload</a>;
837: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onvolumechange" title="handler-onvolumechange">onvolumechange</a>;
838: attribute <a href="web-application-apis.html#function">Function</a> <a href="web-application-apis.html#handler-onwaiting" title="handler-onwaiting">onwaiting</a>;
1.343 mike 839: };
1.421 mike 840: <a href="#window">Window</a> implements <span>EventTarget</span>;</pre><!-- for more features to add here, look here:
1.1 mike 841: http://msdn.microsoft.com/workshop/author/dhtml/reference/objects/obj_window.asp
842: http://www.mozilla.org/docs/dom/domref/dom_window_ref.html
843: http://lxr.mozilla.org/mozilla/source/dom/public/idl/base/nsIDOMWindow.idl - scrollBy, etc
844: http://lxr.mozilla.org/mozilla/source/dom/public/idl/base/nsIDOMWindowInternal.idl - DOM level 0
1.123 mike 845: --><dl class="domintro"><dt><var title="">window</var> . <code title="dom-window"><a href="#dom-window">window</a></code></dt>
1.1 mike 846: <dt><var title="">window</var> . <code title="dom-frames"><a href="#dom-frames">frames</a></code></dt>
847: <dt><var title="">window</var> . <code title="dom-self"><a href="#dom-self">self</a></code></dt>
848:
849: <dd>
850:
851: <p>These attributes all return <var title="">window</var>.</p>
852:
853: </dd>
854:
855: </dl><div class="impl">
856:
1.192 mike 857: <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 858: return the <code><a href="#window">Window</a></code> object's <a href="#browsing-context">browsing
859: context</a>'s <code><a href="#windowproxy">WindowProxy</a></code> object.</p>
860:
1.123 mike 861: </div><div class="impl">
1.1 mike 862:
1.754 mike 863: <h4 id="security-2"><span class="secno">5.2.1 </span>Security</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 864:
865: <p>User agents must raise a <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception
866: whenever any of the members of a <code><a href="#window">Window</a></code> object are
867: accessed by scripts whose <a href="#effective-script-origin">effective script origin</a> is
868: not the same as the <code><a href="#window">Window</a></code> object's
869: <code>Document</code>'s <a href="#effective-script-origin">effective script origin</a>, with
870: the following exceptions:</p>
871:
872: <ul><li>The <code title="dom-location"><a href="history.html#dom-location">location</a></code> object
873:
1.724 mike 874: </li><li>The <code title="dom-window-postMessage-2">postMessage()</code>
1.1 mike 875: method with two arguments
876:
1.724 mike 877: </li><li>The <code title="dom-window-postMessage-3">postMessage()</code>
1.1 mike 878: method with three arguments
879:
880: </li><li>The <code title="dom-frames"><a href="#dom-frames">frames</a></code> attribute
881:
882: </li><li>The <a href="#dynamic-nested-browsing-context-properties">dynamic nested browsing context properties</a>
883:
1.138 mike 884: </li></ul><p>When a script whose <a href="#effective-script-origin">effective script origin</a> is not
885: the same as the <code><a href="#window">Window</a></code> object's <code>Document</code>'s
886: <a href="#effective-script-origin">effective script origin</a> attempts to access that
887: <code><a href="#window">Window</a></code> object's methods or attributes, the user agent
888: must act as if any changes to the <code><a href="#window">Window</a></code> object's
889: properties, getters, setters, etc, were not present.</p>
890:
891: <p>For members that return objects (including function objects),
892: each distinct <a href="#effective-script-origin">effective script origin</a> that is not the
893: same as the <code><a href="#window">Window</a></code> object's <code>Document</code>'s
894: <a href="#effective-script-origin">effective script origin</a> must be provided with a
895: separate set of objects. These objects must have the prototype chain
896: appropriate for the script for which the objects are created (not
1.755 mike 897: those that would be appropriate for scripts whose <a href="web-application-apis.html#script-s-global-object">script's
1.138 mike 898: global object</a> is the <code><a href="#window">Window</a></code> object in
899: question).</p>
900:
901: <div class="example">
902:
903: <p>For instance, if two frames containing <code>Document</code>s
1.159 mike 904: from different <a href="#origin" title="origin">origins</a> access the same
1.724 mike 905: <code><a href="#window">Window</a></code> object's <code title="dom-window-postMessage-2">postMessage()</code> method, they
1.138 mike 906: will get distinct objects that are not equal.</p>
907:
908: </div>
1.1 mike 909:
1.754 mike 910: </div><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><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><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 911:
912: <dd>
913:
914: <p>Opens a window to show <var title="">url</var> (defaults to
915: <code><a href="infrastructure.html#about:blank">about:blank</a></code>), and returns it. The <var title="">target</var> argument gives the name of the new
916: window. If a window exists with that name already, it is
917: reused. The <var title="">replace</var> attribute, if true, means
918: that whatever page is currently open in that window will be
919: removed from the window's session history. The <var title="">features</var> argument is ignored.</p>
920:
921: </dd>
922:
923: <dt><var title="">window</var> . <code title="dom-name"><a href="#dom-name">name</a></code> [ = <var title="">value</var> ]</dt>
924:
925: <dd>
926:
927: <p>Returns the name of the window.</p>
928:
929: <p>Can be set, to change the name.</p>
930:
931: </dd>
932:
933: <dt><var title="">window</var> . <code title="dom-close">close</code>()</dt>
934:
935: <dd>
936:
937: <p>Closes the window.</p>
938:
939: </dd>
940:
941: </dl><div class="impl">
942:
943: <p>The <dfn id="dom-open" title="dom-open"><code>open()</code></dfn> method on
944: <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
945: context</a> or opening and navigating an <a href="#auxiliary-browsing-context">auxiliary browsing
946: context</a>.</p>
947:
948: <p>The method has four arguments, though they are all optional.</p>
949:
950: <p>The first argument, <var title="">url</var>, must be a
951: <a href="infrastructure.html#valid-url">valid URL</a> for a page to load in the browsing
952: context. If no arguments are provided, or if the first argument is
953: the empty string, then the <var title="">url</var> argument defaults
954: to "<code><a href="infrastructure.html#about:blank">about:blank</a></code>". The argument must be <a href="infrastructure.html#resolve-a-url" title="resolve a url">resolved</a> to an <a href="infrastructure.html#absolute-url">absolute
1.700 mike 955: URL</a> (or an error), relative to the <a href="#entry-script">entry
1.755 mike 956: script</a>'s <a href="web-application-apis.html#script-s-base-url" title="script's base URL">base URL</a>,
1.1 mike 957: when the method is invoked.</p>
958:
959: <p>The second argument, <var title="">target</var>, specifies the
960: <a href="#browsing-context-name" title="browsing context name">name</a> of the browsing
961: context that is to be navigated. It must be a <a href="#valid-browsing-context-name-or-keyword">valid browsing
962: context name or keyword</a>. If fewer than two arguments are
963: provided, then the <var title="">name</var> argument defaults to the
964: value "<code>_blank</code>".</p>
965:
966: <p>The third argument, <var title="">features</var>, has no effect
967: and is supported for historical reasons only.</p>
968:
969: <p>The fourth argument, <var title="">replace</var>, specifies
970: whether or not the new page will <a href="history.html#replacement-enabled" title="replacement
971: enabled">replace</a> the page currently loaded in the browsing
972: context, when <var title="">target</var> identifies an existing
973: browsing context (as opposed to leaving the current page in the
974: browsing context's <a href="history.html#session-history">session history</a>). When three or
975: fewer arguments are provided, <var title="">replace</var> defaults
976: to false.</p>
977:
978: <p>When the method is invoked, the user agent must first select a
979: <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
980: rules for choosing a browsing context given a browsing context
981: name</a> using the <var title="">target</var> argument as the
982: name and the <a href="#browsing-context">browsing context</a> of the script as the
983: context in which the algorithm is executed, unless the user has
984: indicated a preference, in which case the browsing context to
985: navigate may instead be the one indicated by the user.</p>
986:
987: <p class="example">For example, suppose there is a user agent that
988: supports control-clicking a link to open it in a new tab. If a user
1.755 mike 989: clicks in that user agent on an element whose <code title="handler-onclick"><a href="web-application-apis.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 990: iframe, but, while doing so, holds the control key down, the user
991: agent could override the selection of the target browsing context to
992: instead target a new tab.</p>
993:
994: <p>Then, the user agent must <a href="history.html#navigate">navigate</a> the selected
995: <a href="#browsing-context">browsing context</a> to the <a href="infrastructure.html#absolute-url">absolute URL</a> (or
996: error) obtained from <a href="infrastructure.html#resolve-a-url" title="resolve a url">resolving</a>
997: <var title="">url</var> earlier. If the <var title="">replace</var>
998: is true, then <a href="history.html#replacement-enabled" title="replacement enabled">replacement must be
999: enabled</a>; otherwise, it must not be enabled unless the
1.671 mike 1000: <a href="#browsing-context">browsing context</a> was just created as part of
1.1 mike 1001: <a href="#the-rules-for-choosing-a-browsing-context-given-a-browsing-context-name">the rules for choosing a browsing context given a browsing
1.755 mike 1002: context name</a>. The navigation must be done with the <a href="web-application-apis.html#script-s-browsing-context" title="script's browsing context">browsing context</a> of the
1.700 mike 1003: <a href="#entry-script">entry script</a> as the <a href="history.html#source-browsing-context">source browsing
1.1 mike 1004: context</a>.</p>
1005:
1006: <p>The method must return the <code><a href="#windowproxy">WindowProxy</a></code> object of the
1007: <a href="#browsing-context">browsing context</a> that was navigated, or null if no
1008: browsing context was navigated.</p>
1009:
1010: <hr><p>The <dfn id="dom-name" title="dom-name"><code>name</code></dfn> attribute of
1011: the <code><a href="#window">Window</a></code> object must, on getting, return the current
1012: name of the <a href="#browsing-context">browsing context</a>, and, on setting, set the
1013: name of the <a href="#browsing-context">browsing context</a> to the new value.</p>
1014:
1015: <p class="note">The name <a href="history.html#resetBCName">gets reset</a> when
1016: the browsing context is navigated to another domain.</p>
1017:
1018: <hr><p>The <dfn id="dom-window-close" title="dom-window-close"><code>close()</code></dfn>
1019: method on <code><a href="#window">Window</a></code> objects should, if the corresponding
1020: <a href="#browsing-context">browsing context</a> <var title="">A</var> is an
1021: <a href="#auxiliary-browsing-context">auxiliary browsing context</a> that was created by a script
1.755 mike 1022: (as opposed to by an action of the user), and if the <a href="web-application-apis.html#script-s-browsing-context" title="script's browsing context">browsing context</a> of the
1023: <a href="web-application-apis.html#concept-script" title="concept-script">script</a> that invokes the method
1.1 mike 1024: is <a href="#allowed-to-navigate">allowed to navigate</a> the <a href="#browsing-context">browsing
1025: context</a> <var title="">A</var>, close the <a href="#browsing-context">browsing
1026: context</a> <var title="">A</var> (and may <a href="#a-browsing-context-is-discarded" title="a
1027: browsing context is discarded">discard</a> it too).</p>
1028:
1.754 mike 1029: </div><h4 id="accessing-other-browsing-contexts"><span class="secno">5.2.3 </span>Accessing other browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">window</var> . <code title="dom-length"><a href="#dom-length">length</a></code></dt>
1.1 mike 1030:
1031: <dd>
1032:
1033: <p>Returns the number of <a href="#child-browsing-context" title="child browsing
1034: context">child browsing contexts</a>.</p>
1035:
1036: </dd>
1037:
1038: <dt><var title="">window</var>[<var title="">index</var>]</dt>
1039:
1040: <dd>
1041:
1042: <p>Returns the indicated <a href="#child-browsing-context">child browsing context</a>.</p>
1043:
1044: </dd>
1045:
1046: </dl><div class="impl">
1047:
1.192 mike 1048: <p>The <dfn id="dom-length" title="dom-length"><code>length</code></dfn> IDL
1.1 mike 1049: attribute on the <code><a href="#window">Window</a></code> interface must return the
1050: number of <a href="#child-browsing-context" title="child browsing context">child browsing
1.698 mike 1051: contexts</a> that are <a href="#browsing-context-nested-through" title="browsing context nested
1052: through">nested through</a> elements that are <a href="infrastructure.html#in-a-document" title="in a
1053: document">in the <code>Document</code></a> that is the
1054: <a href="#active-document">active document</a> of that <code><a href="#window">Window</a></code> object, if
1055: that <code><a href="#window">Window</a></code>'s <a href="#browsing-context">browsing context</a> shares the
1.755 mike 1056: same <a href="web-application-apis.html#event-loop">event loop</a> as the <a href="web-application-apis.html#script-s-browsing-context">script's browsing
1.700 mike 1057: context</a> of the <a href="#entry-script">entry script</a> accessing the IDL
1.698 mike 1058: attribute; otherwise, it must return zero.</p>
1.177 mike 1059:
1060: <!-- in other words, frames are only accessible to same-thread processes -->
1.1 mike 1061:
1062: <p>The <span>indices of the supported indexed properties</span> on
1063: the <code><a href="#window">Window</a></code> object at any instant are the numbers in the
1.192 mike 1064: 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 <span>supported indexed
1.177 mike 1065: properties</span>.</p>
1.1 mike 1066:
1067: <p>When a <code><a href="#window">Window</a></code> object is <dfn id="dom-window-item" title="dom-window-item">indexed to retrieve an indexed
1068: property</dfn> <var title="">index</var>, the value returned must be
1069: the <var title="">index</var>th <a href="#child-browsing-context">child browsing context</a>
1.698 mike 1070: of the <code>Document</code> that is nested through an element that
1071: is <a href="infrastructure.html#in-a-document" title="in a document">in the <code>Document</code></a>,
1072: sorted in the <a href="infrastructure.html#tree-order">tree order</a> of the elements nesting those
1073: <a href="#browsing-context" title="browsing context">browsing contexts</a>.</p>
1.1 mike 1074:
1075: <p>These properties are the <dfn id="dynamic-nested-browsing-context-properties">dynamic nested browsing context
1076: properties</dfn>.</p>
1077:
1.754 mike 1078: </div><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><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">window</var>[<var title="">name</var>]</dt>
1.1 mike 1079:
1080: <dd>
1081:
1082: <p>Returns the indicated <a href="#child-browsing-context">child browsing context</a>.</p>
1083:
1084: </dd>
1085:
1086: </dl><div class="impl">
1087:
1088: <p>The <code><a href="#window">Window</a></code> interface <span title="support named
1089: properties">supports named properties</span>. The <span>names of the
1090: supported named properties</span> at any moment consist of:</p>
1091:
1092: <ul><li>The value of the <code title="">name</code> content attribute
1.5 mike 1093: for all <code><a href="text-level-semantics.html#the-a-element">a</a></code>, <code><a href="obsolete.html#the-applet-element">applet</a></code>, <code><a href="the-canvas-element.html#the-area-element">area</a></code>,
1.159 mike 1094: <code><a href="text-level-semantics.html#the-embed-element">embed</a></code>, <code><a href="obsolete.html#frame">frame</a></code>, <code><a href="obsolete.html#frameset">frameset</a></code>,
1095: <code><a href="forms.html#the-form-element">form</a></code>, <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code>, <code><a href="text-level-semantics.html#the-img-element">img</a></code>, and
1096: <code><a href="text-level-semantics.html#the-object-element">object</a></code> elements in the <a href="#active-document">active document</a>
1.1 mike 1097: that have a <code title="">name</code> content attribute, and,</li>
1098:
1099: <li>The value of the <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> content
1100: attribute of any <a href="infrastructure.html#html-elements" title="HTML elements">HTML element</a> in
1101: the <a href="#active-document">active document</a> with an <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> content attribute.</li>
1102:
1103: </ul><p>When <dfn id="dom-window-nameditem" title="dom-window-namedItem">the <code>Window</code>
1104: object is indexed for property retrieval</dfn> using a name <var title="">name</var>, then the user agent must return the value
1105: obtained using the following steps:</p>
1106:
1107: <ol><li>
1108:
1109: <p>Let <var title="">elements</var> be the list of <a href="#dom-window-nameditem-filter" title="dom-window-namedItem-filter">named elements</a> with the
1110: name <var title="">name</var> in the <a href="#active-document">active document</a>.
1111:
1112: </p><p class="note">There will be at least one such element, by
1113: definition.<!-- (If there wasn't, then this algorithm wouldn't
1114: have been invoked by Web IDL.) --></p>
1115:
1116: </li>
1117:
1118: <li>
1119:
1.159 mike 1120: <p>If <var title="">elements</var> contains an <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code>
1.1 mike 1121: element, then return the <code><a href="#windowproxy">WindowProxy</a></code> object of the
1122: <a href="#nested-browsing-context">nested browsing context</a> represented by the first such
1.159 mike 1123: <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code> element in <a href="infrastructure.html#tree-order">tree order</a>, and abort
1.1 mike 1124: these steps.</p>
1125:
1126: </li>
1127:
1128: <li>
1129:
1130: <p>Otherwise, if <var title="">elements</var> has only one
1131: element, return that element and abort these steps.</p>
1132:
1133: </li>
1134:
1135: <li>
1136:
1.159 mike 1137: <p>Otherwise return an <code><a href="infrastructure.html#htmlcollection">HTMLCollection</a></code> rooted at the
1.1 mike 1138: <code>Document</code> node, whose filter matches only <a href="#dom-window-nameditem-filter" title="dom-window-namedItem-filter">named elements</a> with
1139: the name <var title="">name</var>.</p> <!-- the same one each time
1140: is returned, because of the rule under collections -->
1141:
1142: </li>
1143:
1144: </ol><p><dfn id="dom-window-nameditem-filter" title="dom-window-nameditem-filter">Named elements</dfn>
1145: with the name <var title="">name</var>, for the purposes of the
1146: above algorithm, are those that are either:</p>
1147:
1.5 mike 1148: <ul><li><code><a href="text-level-semantics.html#the-a-element">a</a></code>, <code><a href="obsolete.html#the-applet-element">applet</a></code>, <code><a href="the-canvas-element.html#the-area-element">area</a></code>,
1.159 mike 1149: <code><a href="text-level-semantics.html#the-embed-element">embed</a></code>, <code><a href="forms.html#the-form-element">form</a></code>, <code><a href="obsolete.html#frame">frame</a></code>,
1150: <code><a href="obsolete.html#frameset">frameset</a></code>, <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code>, <code><a href="text-level-semantics.html#the-img-element">img</a></code>, or
1151: <code><a href="text-level-semantics.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 1152:
1153: <li><a href="infrastructure.html#html-elements">HTML elements</a> elements that have an <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> content attribute whose value is <var title="">name</var>.</li>
1154:
1.123 mike 1155: </ul></div><div class="impl">
1.1 mike 1156:
1.754 mike 1157: <h4 id="garbage-collection-and-browsing-contexts"><span class="secno">5.2.5 </span>Garbage collection and browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 1158:
1159: <p>A <a href="#browsing-context">browsing context</a> has a strong reference to each of
1160: its <code>Document</code>s and its <code><a href="#windowproxy">WindowProxy</a></code> object,
1161: 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
1162: contexts</a>.</p>
1163:
1164: <p>A <code>Document</code> has a strong reference to each of its
1165: <a href="#view" title="view">views</a> and their <code>AbstractView</code>
1166: objects.</p>
1167:
1168: <p>When a <a href="#browsing-context">browsing context</a> is to <dfn id="discard-a-document">discard a
1169: <code>Document</code></dfn>, that means that it is to lose the
1170: strong reference from the <code>Document</code>'s <a href="#browsing-context">browsing
1.755 mike 1171: context</a> to the <code>Document</code>, that any <a href="web-application-apis.html#concept-task" title="concept-task">tasks</a> associated with the
1172: <code>Document</code> in any <a href="web-application-apis.html#task-source">task source</a> must be
1.698 mike 1173: removed without being run, and that all the <a href="#child-browsing-context" title="child
1174: browsing context">child browsing contexts</a> of the
1175: <code>Document</code> must also be <a href="#a-browsing-context-is-discarded" title="a browsing context
1176: is discarded">discarded</a>.</p>
1.1 mike 1177:
1178: <p class="note">The <a href="#browsing-context">browsing context</a>'s <a href="#default-view">default
1179: view</a>'s <code><a href="#window">Window</a></code> object <a href="infrastructure.html#implied-strong-reference" title="implied strong
1180: reference">has a strong reference</a> to its
1181: <code>Document</code> object through the <code title="dom-document">document</code> attribute of the
1182: <code>AbstractView</code> interface. Thus, references from other
1.104 mike 1183: scripts to either of those objects will keep both alive. <a href="references.html#refsDOMVIEWS">[DOMVIEWS]</a></p>
1.1 mike 1184:
1185: <p class="note">Whenever a <code>Document</code> object is <a href="#discard-a-document" title="discard a Document">discarded</a>, it is also removed from
1186: the list of <span>the worker's <code>Document</code>s</span> of each
1187: worker whose list contains that <code>Document</code>.</p>
1188:
1189: <p>When <dfn id="a-browsing-context-is-discarded">a <em><span>browsing context</span></em> is
1190: discarded</dfn>, the strong reference from the user agent itself to
1191: the <a href="#browsing-context">browsing context</a> must be severed, and all the
1192: <code>Document</code> objects for all the entries in the
1193: <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>
1194:
1195: <p>User agents may <a href="#a-browsing-context-is-discarded" title="a browsing context is
1196: discarded">discard</a> <a href="#top-level-browsing-context" title="top-level browsing
1197: context">top-level browsing contexts</a> at any time (typically,
1198: in response to user requests, e.g. when a user closes a window
1199: containing one or more <a href="#top-level-browsing-context" title="top-level browsing
1200: context">top-level browsing contexts</a>). Other <a href="#browsing-context" title="browsing context">browsing contexts</a> must be discarded
1201: once their <code><a href="#windowproxy">WindowProxy</a></code> object is eligible for garbage
1202: collection.</p>
1203:
1.754 mike 1204: </div><h4 id="browser-interface-elements"><span class="secno">5.2.6 </span>Browser interface elements</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>To allow Web pages to integrate with Web browsers, certain Web
1.1 mike 1205: browser interface elements are exposed in a limited way to scripts
1.123 mike 1206: in Web pages.</p><p>Each interface element is represented by a <code><a href="#barprop">BarProp</a></code>
1207: object:</p><pre class="idl">interface <dfn id="barprop">BarProp</dfn> {
1.1 mike 1208: attribute boolean <a href="#dom-barprop-visible" title="dom-BarProp-visible">visible</a>;
1.123 mike 1209: };</pre><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 1210: <dd>
1211: <p>Returns true if the location bar is visible; otherwise, returns false.</p>
1212: </dd>
1213:
1214: <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>
1215: <dd>
1216: <p>Returns true if the menu bar is visible; otherwise, returns false.</p>
1217: </dd>
1218:
1219: <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>
1220: <!--<dt><var title="">window</var> . <code title="dom-window-directories">directories</code> . <code title="dom-BarProp-visible">visible</code></dt>-->
1221: <dd>
1222: <p>Returns true if the personal bar is visible; otherwise, returns false.</p>
1223: </dd>
1224:
1225: <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>
1226: <dd>
1227: <p>Returns true if the scroll bars are visible; otherwise, returns false.</p>
1228: </dd>
1229:
1230: <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>
1231: <dd>
1232: <p>Returns true if the status bar is visible; otherwise, returns false.</p>
1233: </dd>
1234:
1235: <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>
1236: <dd>
1.391 mike 1237: <p>Returns true if the toolbar is visible; otherwise, returns false.</p>
1.1 mike 1238: </dd>
1239:
1240: </dl><div class="impl">
1241:
1242: <p>The <dfn id="dom-barprop-visible" title="dom-BarProp-visible">visible</dfn> attribute, on
1243: getting, must return either true or a value determined by the user
1244: agent to most accurately represent the visibility state of the user
1245: interface element that the object represents, as described below. On
1246: setting, the new value must be discarded.</p>
1247:
1248: <p>The following <code><a href="#barprop">BarProp</a></code> objects exist for each
1249: <code>Document</code> object in a <a href="#browsing-context">browsing
1250: context</a>. Some of the user interface elements represented by
1251: these objects might have no equivalent in some user agents; for
1.409 mike 1252: those user agents, except when otherwise specified, the object must
1253: 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 1254: true).</p>
1255:
1256: <dl><dt><dfn id="the-location-bar-barprop-object">The location bar <code>BarProp</code> object</dfn></dt>
1257:
1258: <dd>Represents the user interface element that contains a control
1259: that displays the <a href="infrastructure.html#url">URL</a> of the <a href="#active-document">active
1260: document</a>, or some similar interface concept.</dd>
1261:
1262: <dt><dfn id="the-menu-bar-barprop-object">The menu bar <code>BarProp</code> object</dfn></dt>
1263:
1264: <dd>Represents the user interface element that contains a list of
1265: commands in menu form, or some similar interface concept.</dd>
1266:
1267: <dt><dfn id="the-personal-bar-barprop-object">The personal bar <code>BarProp</code> object</dfn></dt>
1268:
1269: <dd>Represents the user interface element that contains links to
1270: the user's favorite pages, or some similar interface concept.</dd>
1271:
1272: <dt><dfn id="the-scrollbar-barprop-object">The scrollbar <code>BarProp</code> object</dfn></dt>
1273:
1274: <dd>Represents the user interface element that contains a scrolling
1275: mechanism, or some similar interface concept.</dd>
1276:
1277: <dt><dfn id="the-status-bar-barprop-object">The status bar <code>BarProp</code> object</dfn></dt>
1278:
1279: <dd>Represents a user interface element found immediately below or
1280: after the document, as appropriate for the <a href="#default-view">default
1281: view</a>'s media. If the user agent has no such user interface
1282: element, then the object may act as if the corresponding user
1283: interface element was absent (i.e. its <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code> attribute may return
1284: false).</dd>
1285:
1.391 mike 1286: <dt><dfn id="the-toolbar-barprop-object">The toolbar <code>BarProp</code> object</dfn></dt>
1.1 mike 1287:
1288: <dd>Represents the user interface element found immediately above
1289: or before the document, as appropriate for the <a href="#default-view">default
1290: view</a>'s media. If the user agent has no such user interface
1291: element, then the object may act as if the corresponding user
1292: interface element was absent (i.e. its <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code> attribute may return
1293: false).</dd>
1294:
1295: </dl><p>The <dfn id="dom-window-locationbar" title="dom-window-locationbar"><code>locationbar</code></dfn>
1296: attribute must return <a href="#the-location-bar-barprop-object">the location bar <code>BarProp</code>
1297: object</a>.</p>
1298:
1299: <p>The <dfn id="dom-window-menubar" title="dom-window-menubar"><code>menubar</code></dfn>
1300: attribute must return <a href="#the-menu-bar-barprop-object">the menu bar <code>BarProp</code>
1301: object</a>.</p>
1302:
1303: <p>The <dfn id="dom-window-personalbar" title="dom-window-personalbar"><code>personalbar</code></dfn>
1304: attribute must return <a href="#the-personal-bar-barprop-object">the personal bar <code>BarProp</code>
1305: object</a>.</p>
1306:
1307: <p>The <dfn id="dom-window-scrollbars" title="dom-window-scrollbars"><code>scrollbars</code></dfn>
1308: attribute must return <a href="#the-scrollbar-barprop-object">the scrollbar <code>BarProp</code>
1309: object</a>.</p>
1310:
1311: <p>The <dfn id="dom-window-statusbar" title="dom-window-statusbar"><code>statusbar</code></dfn> attribute
1312: must return <a href="#the-status-bar-barprop-object">the status bar <code>BarProp</code>
1313: object</a>.</p>
1314:
1315: <p>The <dfn id="dom-window-toolbar" title="dom-window-toolbar"><code>toolbar</code></dfn>
1.391 mike 1316: attribute must return <a href="#the-toolbar-barprop-object">the toolbar <code>BarProp</code>
1.1 mike 1317: object</a>.</p>
1318:
1319: <!--
1320: <p>For legacy reasons, the <dfn
1321: title="dom-window-directories"><code>directories</code></dfn>
1322: attribute must also return <span>the personal bar
1323: <code>BarProp</code> object</span>.</p>
1324: -->
1325:
1.123 mike 1326: </div><div class="impl">
1.1 mike 1327:
1.754 mike 1328: <h4 id="the-windowproxy-object"><span class="secno">5.2.7 </span>The <code><a href="#windowproxy">WindowProxy</a></code> object</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1329:
1330:
1331: <p>As mentioned earlier, each <a href="#browsing-context">browsing context</a> has a
1332: <dfn id="windowproxy"><code>WindowProxy</code></dfn> object. This object is unusual
1333: in that all operations that would be performed on it must be
1334: performed on the <code><a href="#window">Window</a></code> object of the <a href="#browsing-context">browsing
1335: context</a>'s <a href="#active-document">active document</a> instead. It is thus
1336: indistinguishable from that <code><a href="#window">Window</a></code> object in every way
1337: until the <a href="#browsing-context">browsing context</a> is navigated.</p>
1338:
1339: <p>There is no <code><a href="#windowproxy">WindowProxy</a></code> interface object.</p>
1340:
1341: <p class="note">The <code><a href="#windowproxy">WindowProxy</a></code> object allows scripts
1342: to act as if each <a href="#browsing-context">browsing context</a> had a single
1343: <code><a href="#window">Window</a></code> object, while still keeping separate
1344: <code><a href="#window">Window</a></code> objects for each <code>Document</code>.</p>
1345:
1346: <div class="example">
1347:
1348: <p>In the following example, the variable <var title="">x</var> is
1349: 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
1350: of the expressions following the assignment return true, because in
1351: every respect, the <code><a href="#windowproxy">WindowProxy</a></code> object acts like the
1352: underlying <code><a href="#window">Window</a></code> object.</p>
1353:
1354: <pre>var x = window;
1355: x instanceof Window; // true
1356: x === this; // true</pre>
1357:
1358: </div>
1359:
1360: </div><div class="impl">
1361:
1362: <h3 id="origin-0"><span class="secno">5.3 </span>Origin</h3><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 1363: <!-- Hallowed are the Ori -->
1364:
1.159 mike 1365: <p>The <dfn id="origin">origin</dfn> of a resource and the <dfn id="effective-script-origin">effective script
1.1 mike 1366: origin</dfn> of a resource are both either opaque identifiers or
1367: tuples consisting of a scheme component, a host component, a port
1368: component, and optionally extra data.</p>
1369:
1370: <p class="note">The extra data could include the certificate of the
1371: site when using encrypted connections, to ensure that if the site's
1372: secure certificate changes, the origin is considered to change as
1373: well.</p>
1374:
1375: <p>These characteristics are defined as follows:</p>
1376:
1377: <dl><dt>For URLs</dt>
1378:
1379: <dd>
1380:
1.159 mike 1381: <p>The <a href="#origin">origin</a> and <a href="#effective-script-origin">effective script
1.1 mike 1382: origin</a> of the <a href="infrastructure.html#url">URL</a> is whatever is returned by
1383: the following algorithm:</p>
1384:
1385: <ol><li><p>Let <var title="">url</var> be the <a href="infrastructure.html#url">URL</a> for
1.159 mike 1386: which the <a href="#origin">origin</a> is being determined.</p></li>
1.1 mike 1387:
1388: <li><p><a href="infrastructure.html#parse-a-url" title="parse a url">Parse</a> <var title="">url</var>.</p></li>
1389:
1390: <li><p>If <var title="">url</var> identifies a resource that is
1391: its own trust domain (e.g. it identifies an e-mail on an IMAP
1392: server or a post on an NNTP server) then return a globally unique
1393: identifier specific to the resource identified by <var title="">url</var>, so that if this algorithm is invoked again
1.174 mike 1394: for <a href="infrastructure.html#url" title="URL">URLs</a> that identify the same resource,
1.1 mike 1395: the same identifier will be returned.</p></li>
1396:
1397: <li><p>If <var title="">url</var> does not use a server-based
1398: naming authority, or if parsing <var title="">url</var> failed,
1399: or if <var title="">url</var> is not an <a href="infrastructure.html#absolute-url">absolute
1400: URL</a>, then return a new globally unique
1401: identifier.</p></li>
1402:
1403: <li><p>Let <var title="">scheme</var> be the <a href="infrastructure.html#url-scheme" title="url-scheme"><scheme></a> component of <var title="">url</var>, <a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII lowercase</a>.</p></li>
1404:
1405: <li><p>If the UA doesn't support the protocol given by <var title="">scheme</var>, then return a new globally unique
1406: identifier.</p></li>
1407:
1408: <li><p>If <var title="">scheme</var> is "<code title="">file</code>", then the user agent may return a
1409: UA-specific value.</p></li>
1410:
1411: <li><p>Let <var title="">host</var> be the <a href="infrastructure.html#url-host" title="url-host"><host></a> component of <var title="">url</var>.</p></li>
1412:
1413: <li>
1414:
1415: <p>Apply the IDNA ToASCII algorithm to <var title="">host</var>,
1416: with both the AllowUnassigned and UseSTD3ASCIIRules flags
1417: set. Let <var title="">host</var> be the result of the ToASCII
1418: algorithm.</p>
1419:
1420: <p>If ToASCII fails to convert one of the components of the
1421: string, e.g. because it is too long or because it contains
1422: invalid characters, then return a new globally unique
1.104 mike 1423: identifier. <a href="references.html#refsRFC3490">[RFC3490]</a></p>
1.1 mike 1424:
1425: </li>
1426:
1427: <li><p>Let <var title="">host</var> be the result of converting
1428: <var title="">host</var> <a href="infrastructure.html#converted-to-ascii-lowercase" title="converted to ASCII lowercase">to
1429: ASCII lowercase</a>.</p></li>
1430:
1431: <li><p>If there is no <a href="infrastructure.html#url-port" title="url-port"><port></a>
1432: component, then let <var title="">port</var> be the default port
1433: for the protocol given by <var title="">scheme</var>. Otherwise,
1434: let <var title="">port</var> be the <a href="infrastructure.html#url-port" title="url-port"><port></a> component of <var title="">url</var>.</p></li>
1435:
1436: <li><p>Return the tuple (<var title="">scheme</var>, <var title="">host</var>, <var title="">port</var>).</p></li>
1437:
1438: </ol><p>In addition, if the <a href="infrastructure.html#url">URL</a> is in fact associated with
1439: a <code>Document</code> object that was created by parsing the
1440: resource obtained from fetching <a href="infrastructure.html#url">URL</a>, and this was
1441: done over a secure connection, then the server's secure
1442: certificate may be added to the origin as additional data.</p>
1443:
1444: </dd>
1445:
1446: <dt>For scripts</dt>
1447:
1448: <dd>
1449:
1.159 mike 1450: <p>The <a href="#origin">origin</a> and <a href="#effective-script-origin">effective script
1.1 mike 1451: origin</a> of a script are determined from another resource,
1452: called the <i>owner</i>:</p>
1453:
1454: <dl class="switch"><dt>If a script is in a <code><a href="semantics.html#script">script</a></code> element</dt>
1455:
1456: <dd>The owner is the <code>Document</code> to which the
1457: <code><a href="semantics.html#script">script</a></code> element belongs.</dd>
1458:
1459:
1.755 mike 1460: <dt>If a script is in an <a href="web-application-apis.html#event-handler-content-attributes" title="event handler content
1.1 mike 1461: attributes">event handler content attribute</a></dt>
1462:
1463: <dd>The owner is the <code>Document</code> to which the
1464: attribute node belongs.</dd>
1465:
1466:
1467: <dt>If a script is a function or other code reference created by
1468: another script</dt>
1469:
1470: <dd>The owner is the script that created it.</dd>
1471:
1472:
1.755 mike 1473: <dt>If a script is a <a href="web-application-apis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> that was returned as the
1.1 mike 1474: location of an HTTP redirect (<a href="infrastructure.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or equivalent</a> in
1475: other protocols)</dt>
1476:
1477: <dd>The owner is the <a href="infrastructure.html#url">URL</a> that redirected to the
1.755 mike 1478: <a href="web-application-apis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a>.</dd>
1.1 mike 1479:
1480:
1.755 mike 1481: <dt>If a script is a <a href="web-application-apis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> in an attribute</dt>
1.1 mike 1482:
1483: <dd>The owner is the <code>Document</code> of the element on
1484: which the attribute is found.</dd>
1485:
1486:
1.755 mike 1487: <dt>If a script is a <a href="web-application-apis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> in a style sheet</dt>
1.1 mike 1488:
1489: <dd>The owner is the <a href="infrastructure.html#url">URL</a> of the style sheet.</dd>
1490:
1491:
1.755 mike 1492: <dt>If a script is a <a href="web-application-apis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> to which a <a href="#browsing-context">browsing
1.1 mike 1493: context</a> is being <a href="history.html#navigate" title="navigate">navigated</a>,
1494: the URL having been provided by the user (e.g. by using a
1495: <i>bookmarklet</i>)</dt>
1496:
1497: <dd>The owner is the <code>Document</code> of the <a href="#browsing-context">browsing
1498: context</a>'s <a href="#active-document">active document</a>.</dd>
1499:
1500:
1.755 mike 1501: <dt>If a script is a <a href="web-application-apis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> to which a <a href="#browsing-context">browsing
1.1 mike 1502: context</a> is being <a href="history.html#navigate" title="navigate">navigated</a>,
1503: the URL having been declared in markup</dt>
1504:
1505: <dd>The owner is the <code>Document</code> of the element
1506: (e.g. an <code><a href="text-level-semantics.html#the-a-element">a</a></code> or <code><a href="the-canvas-element.html#the-area-element">area</a></code> element) that
1507: declared the URL.</dd>
1508:
1509:
1.755 mike 1510: <dt>If a script is a <a href="web-application-apis.html#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> to which a <a href="#browsing-context">browsing
1.1 mike 1511: context</a> is being <a href="history.html#navigate" title="navigate">navigated</a>,
1512: the URL having been provided by script</dt>
1513:
1514: <dd>The owner is the script that provided the URL.</dd>
1515:
1.159 mike 1516: </dl><p>The <a href="#origin">origin</a> of the script is then equal to the
1517: <a href="#origin">origin</a> of the owner, and the <a href="#effective-script-origin">effective script
1.1 mike 1518: origin</a> of the script is equal to the <a href="#effective-script-origin">effective script
1519: origin</a> of the owner.</p>
1520:
1521: </dd>
1522:
1523: <dt>For <code>Document</code> objects and images</dt>
1524:
1525: <dd>
1526:
1527: <dl class="switch"><dt id="sandboxOrigin">If a <code>Document</code> is in a
1.159 mike 1528: <a href="#browsing-context">browsing context</a> whose <a href="text-level-semantics.html#sandboxed-origin-browsing-context-flag">sandboxed origin
1.1 mike 1529: browsing context flag</a> was set when the
1530: <code>Document</code> was created</dt>
1531:
1.725 mike 1532: <dt>If a <code>Document</code> was generated from a resource
1533: labeled as <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code></dt>
1534:
1.159 mike 1535: <dd>The <a href="#origin">origin</a> is a globally unique identifier
1.1 mike 1536: assigned when the <code>Document</code> is created.</dd>
1537:
1538:
1539: <dt>If a <code>Document</code> or image was returned by the
1540: <code>XMLHttpRequest</code> API</dt>
1541:
1.409 mike 1542: <dd>The <a href="#origin">origin</a> is equal to the <span>XMLHttpRequest
1543: origin</span> of the <code>XMLHttpRequest</code> object. <a href="references.html#refsXHR">[XHR]</a></dd>
1.1 mike 1544:
1545:
1546: <dt>If a <code>Document</code> or image was generated from a
1.755 mike 1547: <a href="web-application-apis.html#javascript-protocol" title="javascript protocol"><code>javascript:</code>
1.1 mike 1548: URL</a></dt>
1549:
1.159 mike 1550: <dd>The <a href="#origin">origin</a> is equal to the <a href="#origin">origin</a>
1.755 mike 1551: of the script of that <a href="web-application-apis.html#javascript-protocol" title="javascript
1.1 mike 1552: protocol"><code>javascript:</code> URL</a>.</dd>
1553:
1554:
1555: <dt>If a <code>Document</code> or image was served over the
1556: network and has an address that uses a URL scheme with a
1557: server-based naming authority</dt>
1558:
1.159 mike 1559: <dd>The <a href="#origin">origin</a> is the <a href="#origin">origin</a> of the
1.1 mike 1560: <a href="dom.html#the-document-s-address" title="the document's address">address</a> of the
1561: <code>Document</code> or the <a href="infrastructure.html#url">URL</a> of the image, as
1562: appropriate.</dd>
1563:
1564:
1565: <dt>If a <code>Document</code> or image was generated from a
1566: <code title="">data:</code> URL that was returned as the location
1567: of an HTTP redirect (<a href="infrastructure.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or equivalent</a> in
1568: other protocols)</dt>
1569:
1.159 mike 1570: <dd>The <a href="#origin">origin</a> is the <a href="#origin">origin</a> of the
1.1 mike 1571: <a href="infrastructure.html#url">URL</a> that redirected to the <code title="">data:</code> URL.</dd>
1572:
1573:
1574: <dt>If a <code>Document</code> or image was generated from a
1575: <code title="">data:</code> URL found in another
1576: <code>Document</code> or in a script</dt>
1577:
1.159 mike 1578: <dd>The <a href="#origin">origin</a> is the <a href="#origin">origin</a> of the
1.726 mike 1579: <code>Document</code> or script that initiated the <a href="history.html#navigate" title="navigate">navigation</a> to that <a href="infrastructure.html#url">URL</a>.</dd>
1.1 mike 1580:
1581:
1582: <dt>If a <code>Document</code> has the <a href="dom.html#the-document-s-address" title="the
1583: document's address">address</a>
1584: "<code><a href="infrastructure.html#about:blank">about:blank</a></code>"</dt>
1585:
1.159 mike 1586: <dd>The <a href="#origin">origin</a> of the <code>Document</code> is <a href="#about-blank-origin">the <span>origin</span> it was
1.1 mike 1587: assigned when its browsing context was created</a>.</dd>
1588:
1589:
1.727 mike 1590: <dt>If a <code>Document</code> is <a href="text-level-semantics.html#an-iframe-srcdoc-document">an <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code> document</a></dt>
1591:
1592: <dd>The <a href="#origin">origin</a> of the <code>Document</code> is the
1593: <a href="#origin">origin</a> of the <code>Document</code>'s <a href="#browsing-context">browsing
1594: context</a>'s <a href="#browsing-context-container">browsing context container</a>'s
1595: <code>Document</code>.</dd>
1596:
1597:
1.1 mike 1598: <dt>If a <code>Document</code> or image was obtained in some
1599: other manner (e.g. a <code title="">data:</code> URL typed in by
1.557 mike 1600: the user, a <code>Document</code> created using the <code title="dom-DOMImplementation-createDocument">createDocument()</code>
1601: API, etc)</dt>
1.1 mike 1602:
1.159 mike 1603: <dd>The <a href="#origin">origin</a> is a globally unique identifier
1.1 mike 1604: assigned when the <code>Document</code> or image is created.</dd>
1605:
1.409 mike 1606: </dl><p>When a <code>Document</code> is created, its <a href="#effective-script-origin">effective
1607: script origin</a> is initialized to the <a href="#origin">origin</a> of
1608: the <code>Document</code>. However, the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute can
1.1 mike 1609: be used to change it.</p>
1610:
1611: </dd>
1612:
1613: <dt>For <code><a href="video.html#audio">audio</a></code> and <code><a href="video.html#video">video</a></code> elements</dt>
1614:
1615: <dd>
1616:
1617: <p>If value of the <a href="video.html#media-element">media element</a>'s <code title="dom-media-currentSrc"><a href="video.html#dom-media-currentsrc">currentSrc</a></code> attribute is the
1.159 mike 1618: empty string, the <a href="#origin">origin</a> is the same as the
1619: <a href="#origin">origin</a> of the element's <code>Document</code>'s
1620: <a href="#origin">origin</a>.</p>
1.1 mike 1621:
1.159 mike 1622: <p>Otherwise, the <a href="#origin">origin</a> is equal to the
1623: <a href="#origin">origin</a> of the <a href="infrastructure.html#absolute-url">absolute URL</a> given by the
1.1 mike 1624: <a href="video.html#media-element">media element</a>'s <code title="dom-media-currentSrc"><a href="video.html#dom-media-currentsrc">currentSrc</a></code> attribute.</p>
1625:
1626: </dd>
1627:
1628: </dl><p>The <dfn id="unicode-serialization-of-an-origin">Unicode serialization of an origin</dfn> is the string
1629: obtained by applying the following algorithm to the given
1.159 mike 1630: <a href="#origin">origin</a>:</p>
1.1 mike 1631:
1.159 mike 1632: <ol><li><p>If the <a href="#origin">origin</a> in question is not a
1.1 mike 1633: scheme/host/port tuple, then return the literal string "<code title="">null</code>" and abort these steps.</p></li>
1634:
1635: <li><p>Otherwise, let <var title="">result</var> be the scheme part
1.159 mike 1636: of the <a href="#origin">origin</a> tuple.</p></li>
1.1 mike 1637:
1638: <li><p>Append the string "<code title="">://</code>" to <var title="">result</var>.</p></li>
1639:
1640: <li><p>Apply the IDNA ToUnicode algorithm to each component of the
1.159 mike 1641: host part of the <a href="#origin">origin</a> tuple, and append the results
1.1 mike 1642: — each component, in the same order, separated by U+002E FULL
1.464 mike 1643: STOP characters (.) — to <var title="">result</var>. <a href="references.html#refsRFC3490">[RFC3490]</a></p></li>
1.1 mike 1644:
1.159 mike 1645: <li><p>If the port part of the <a href="#origin">origin</a> tuple gives a port
1.1 mike 1646: that is different from the default port for the protocol given by
1.159 mike 1647: the scheme part of the <a href="#origin">origin</a> tuple, then append a
1.464 mike 1648: U+003A COLON character (:) and the given port, in base ten, to
1.1 mike 1649: <var title="">result</var>.</p></li>
1650:
1651: <li><p>Return <var title="">result</var>.</p></li>
1652:
1653: </ol><p>The <dfn id="ascii-serialization-of-an-origin">ASCII serialization of an origin</dfn> is the string
1654: obtained by applying the following algorithm to the given
1.159 mike 1655: <a href="#origin">origin</a>:</p>
1.1 mike 1656:
1.159 mike 1657: <ol><li><p>If the <a href="#origin">origin</a> in question is not a
1.1 mike 1658: scheme/host/port tuple, then return the literal string "<code title="">null</code>" and abort these steps.</p></li>
1659:
1660: <li><p>Otherwise, let <var title="">result</var> be the scheme part
1.159 mike 1661: of the <a href="#origin">origin</a> tuple.</p></li>
1.1 mike 1662:
1663: <li><p>Append the string "<code title="">://</code>" to <var title="">result</var>.</p></li>
1664:
1665: <li>
1666:
1667: <p>Apply the IDNA ToASCII algorithm the host part of the
1.159 mike 1668: <a href="#origin">origin</a> tuple, with both the AllowUnassigned and
1.1 mike 1669: UseSTD3ASCIIRules flags set, and append the results <var title="">result</var>.</p>
1670:
1671: <p>If ToASCII fails to convert one of the components of the
1672: string, e.g. because it is too long or because it contains invalid
1.104 mike 1673: characters, then return the empty string and abort these steps. <a href="references.html#refsRFC3490">[RFC3490]</a></p>
1.1 mike 1674:
1675: </li>
1676:
1.159 mike 1677: <li><p>If the port part of the <a href="#origin">origin</a> tuple gives a port
1.1 mike 1678: that is different from the default port for the protocol given by
1.159 mike 1679: the scheme part of the <a href="#origin">origin</a> tuple, then append a
1.464 mike 1680: U+003A COLON character (:) and the given port, in base ten, to
1.1 mike 1681: <var title="">result</var>.</p></li>
1682:
1683: <li><p>Return <var title="">result</var>.</p></li>
1684:
1.159 mike 1685: </ol><p>Two <a href="#origin" title="origin">origins</a> are said to be the
1.1 mike 1686: <dfn id="same-origin">same origin</dfn> if the following algorithm returns true:</p>
1687:
1.159 mike 1688: <ol><li><p>Let <var title="">A</var> be the first <a href="#origin">origin</a>
1.1 mike 1689: being compared, and <var title="">B</var> be the second
1.159 mike 1690: <a href="#origin">origin</a> being compared.</p></li>
1.1 mike 1691:
1692: <li><p>If <var title="">A</var> and <var title="">B</var> are both
1693: opaque identifiers, and their value is equal, then return
1694: true.</p></li>
1695:
1696: <li><p>Otherwise, if either <var title="">A</var> or <var title="">B</var> or both are opaque identifiers, return
1697: false.</p></li>
1698:
1699: <li><p>If <var title="">A</var> and <var title="">B</var> have
1700: scheme components that are not identical, return false.</p></li>
1701:
1702: <li><p>If <var title="">A</var> and <var title="">B</var> have host
1703: components that are not identical, return false.</p></li>
1704:
1705: <li><p>If <var title="">A</var> and <var title="">B</var> have port
1706: components that are not identical, return false.</p></li>
1707:
1708: <li><p>If either <var title="">A</var> or <var title="">B</var>
1709: have additional data, but that data is not identical for both,
1710: return false.</p></li>
1711:
1712: <li><p>Return true.</p></li>
1713:
1.754 mike 1714: </ol></div><h4 id="relaxing-the-same-origin-restriction"><span class="secno">5.3.1 </span>Relaxing the same-origin restriction</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><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>
1.1 mike 1715:
1716: <dd>
1717:
1718: <p>Returns the current domain used for security checks.</p>
1719:
1720: <p>Can be set to a value that removes subdomains, to allow pages
1721: on other subdomains of the same domain (if they do the same thing)
1722: to access each other.</p>
1723:
1724: </dd>
1725:
1726: </dl><div class="impl">
1727:
1728: <p>The <dfn id="dom-document-domain" title="dom-document-domain"><code>domain</code></dfn>
1729: attribute on <code>Document</code> objects must be initialized to
1730: <a href="#the-document-s-domain">the document's domain</a>, if it has one, and the empty
1731: string otherwise. If the value is an IPv6 address, then the square
1732: brackets from the host portion of the <a href="infrastructure.html#url-host" title="url-host"><host></a> component must be omitted from
1733: the attribute's value.</p>
1734:
1735: <p>On getting, the attribute must return its current
1736: value, unless the document was created by
1737: <code>XMLHttpRequest</code>, in which case it must throw an
1738: <code><a href="infrastructure.html#invalid_access_err">INVALID_ACCESS_ERR</a></code> exception.</p>
1739:
1740: <p>On setting, the user agent must run the following algorithm:</p>
1741:
1742: <ol><li>
1743:
1744: <p>If the document was created by <code>XMLHttpRequest</code>,
1745: throw an <code><a href="infrastructure.html#invalid_access_err">INVALID_ACCESS_ERR</a></code> exception and abort these
1746: steps.</p>
1747:
1748: </li>
1749:
1750: <li>
1751:
1752: <p>If the new value is an IP address, let <var title="">new
1753: value</var> be the new value. Otherwise, apply the IDNA ToASCII
1754: algorithm to the new value, with both the AllowUnassigned and
1755: UseSTD3ASCIIRules flags set, and let <var title="">new value</var>
1756: be the result of the ToASCII algorithm.</p>
1757:
1758: <p>If ToASCII fails to convert one of the components of the
1759: string, e.g. because it is too long or because it contains invalid
1760: characters, then throw a <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception and abort
1.104 mike 1761: these steps. <a href="references.html#refsRFC3490">[RFC3490]</a></p>
1.1 mike 1762:
1763: </li>
1764:
1765: <li>
1766:
1767: <p>If <var title="">new value</var> is not exactly equal to the
1768: current value of the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute, then
1769: run these substeps:</p>
1770:
1771: <ol><li>
1772:
1773: <p>If the current value is an IP address, throw a
1774: <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception and abort these steps.</p>
1775:
1776: </li>
1777:
1778: <li>
1779:
1780: <p>If <var title="">new value</var>, prefixed by a U+002E FULL
1.464 mike 1781: STOP (.), does not exactly match the end of the current value,
1.1 mike 1782: throw a <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception and abort these
1783: steps.</p>
1784:
1785: </li>
1786:
1787: <li>
1788:
1789: <p>If <var title="">new value</var> matches a suffix in the
1790: Public Suffix List, or, if <var title="">new value</var>,
1.464 mike 1791: prefixed by a U+002E FULL STOP (.), matches the end of a
1.1 mike 1792: suffix in the Public Suffix List, then throw a
1.104 mike 1793: <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception and abort these steps. <a href="references.html#refsPSL">[PSL]</a></p>
1.1 mike 1794:
1795: <p>Suffixes must be compared after applying the IDNA ToASCII
1796: algorithm to them, with both the AllowUnassigned and
1797: UseSTD3ASCIIRules flags set, in an <a href="infrastructure.html#ascii-case-insensitive">ASCII
1.104 mike 1798: case-insensitive</a> manner. <a href="references.html#refsRFC3490">[RFC3490]</a></p>
1.1 mike 1799:
1800: </li>
1801:
1802: </ol></li>
1803:
1.755 mike 1804: <li><p>Release the <a href="web-application-apis.html#storage-mutex">storage mutex</a>.</p></li>
1.318 mike 1805:
1.1 mike 1806: <li>
1807:
1808: <p>Set the attribute's value to <var title="">new value</var>.</p>
1809:
1810: </li>
1811:
1812: <li>
1813:
1814: <p>Set the host part of the <a href="#effective-script-origin">effective script origin</a>
1815: tuple of the <code>Document</code> to <var title="">new
1816: value</var>.</p>
1817:
1818: </li>
1819:
1820: <li>
1821:
1822: <p>Set the port part of the <a href="#effective-script-origin">effective script origin</a>
1823: tuple of the <code>Document</code> to "manual override" (a value
1824: that, for the purposes of <a href="#same-origin" title="same origin">comparing
1825: origins</a>, is identical to "manual override" but not
1826: identical to any other value).</p>
1827:
1828: </li>
1829:
1830: </ol><p>The <dfn id="the-document-s-domain" title="the document's domain">domain</dfn> of a
1831: <code>Document</code> is the host part of the document's
1.159 mike 1832: <a href="#origin">origin</a>, if that is a scheme/host/port tuple. If it
1.1 mike 1833: isn't, then the document does not have a domain.</p>
1834:
1.123 mike 1835: </div><p class="note">The <code title="dom-document-domain"><a href="#dom-document-domain">domain</a></code>
1.1 mike 1836: attribute is used to enable pages on different hosts of a domain to
1.320 mike 1837: access each others' DOMs.</p><p class="warning">Do not use the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute when
1838: using shared hosting. If an untrusted third party is able to host an
1839: HTTP server at the same IP address but on a different port, then the
1840: same-origin protection that normally protects two different sites on
1841: the same host will fail, as the ports are ignored when comparing
1842: origins after the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute has
1.755 mike 1843: been used.</p></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