You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2395 lines
151 KiB
2395 lines
151 KiB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html lang="en-US-x-Hixie" ><head><title>5.4 Session history and navigation — HTML5 </title><style type="text/css">
|
|
pre { margin-left: 2em; white-space: pre-wrap; }
|
|
h2 { margin: 3em 0 1em 0; }
|
|
h3 { margin: 2.5em 0 1em 0; }
|
|
h4 { margin: 2.5em 0 0.75em 0; }
|
|
h5, h6 { margin: 2.5em 0 1em; }
|
|
h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
|
|
h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
|
|
p { margin: 1em 0; }
|
|
hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
|
|
dl, dd { margin-top: 0; margin-bottom: 0; }
|
|
dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
|
|
dt + dt { margin-top: 0; }
|
|
dd dt { margin-top: 0.25em; margin-bottom: 0; }
|
|
dd p { margin-top: 0; }
|
|
dd dl + p { margin-top: 1em; }
|
|
dd table + p { margin-top: 1em; }
|
|
p + * > li, dd li { margin: 1em 0; }
|
|
dt, dfn { font-weight: bold; font-style: normal; }
|
|
dt dfn { font-style: italic; }
|
|
pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
|
|
pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
|
|
pre em { font-weight: bolder; font-style: normal; }
|
|
@media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
|
|
var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
|
|
table { border-collapse: collapse; border-style: hidden hidden none hidden; }
|
|
table thead, table tbody { border-bottom: solid; }
|
|
table tbody th:first-child { border-left: solid; }
|
|
table tbody th { text-align: left; }
|
|
table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
|
|
blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
|
|
|
|
.bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
|
|
.matrix, .matrix td { border: none; text-align: right; }
|
|
.matrix { margin-left: 2em; }
|
|
.dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
|
|
.dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
|
|
.dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
|
|
|
|
.toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
|
|
img.extra { float: right; }
|
|
pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; }
|
|
pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
|
|
pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
|
|
pre.css:first-line { color: #AAAA50; }
|
|
dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
|
|
hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
|
|
dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
|
|
dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
|
|
dl.domintro dd p { margin: 0.5em 0; }
|
|
dl.switch { padding-left: 2em; }
|
|
dl.switch > dt { text-indent: -1.5em; }
|
|
dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
|
|
dl.triple { padding: 0 0 0 1em; }
|
|
dl.triple dt, dl.triple dd { margin: 0; display: inline }
|
|
dl.triple dt:after { content: ':'; }
|
|
dl.triple dd:after { content: '\A'; white-space: pre; }
|
|
.diff-old { text-decoration: line-through; color: silver; background: transparent; }
|
|
.diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
|
|
a .diff-new { border-bottom: 1px blue solid; }
|
|
|
|
h2 { page-break-before: always; }
|
|
h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
|
|
h1 + h2, hr + h2.no-toc { page-break-before: auto; }
|
|
|
|
p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
|
|
li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
|
|
|
|
div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
|
|
div.head p { margin: 0; }
|
|
div.head h1 { margin: 0; }
|
|
div.head .logo { float: right; margin: 0 1em; }
|
|
div.head .logo img { border: none } /* remove border from top image */
|
|
div.head dl { margin: 1em 0; }
|
|
div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
|
|
|
|
body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
|
|
body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
|
|
body > .toc > li > * { margin-bottom: 0.5em; }
|
|
body > .toc > li > * > li > * { margin-bottom: 0.25em; }
|
|
.toc, .toc li { list-style: none; }
|
|
|
|
.brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
|
|
.brief li { margin: 0; padding: 0; }
|
|
.brief li p { margin: 0; padding: 0; }
|
|
|
|
.category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
|
|
.category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
|
|
.category-list li { display: inline; }
|
|
.category-list li:not(:last-child)::after { content: ', '; }
|
|
.category-list li > span, .category-list li > a { text-transform: lowercase; }
|
|
.category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
|
|
|
|
.XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
|
|
.XXX > :first-child { margin-top: 0; }
|
|
p .XXX { line-height: 3em; }
|
|
.annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
|
|
.annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
|
|
.annotation :link, .annotation :visited { color: inherit; }
|
|
.annotation :link:hover, .annotation :visited:hover { background: transparent; }
|
|
.annotation span { border: none ! important; }
|
|
.note { color: green; background: transparent; font-family: sans-serif; }
|
|
.warning { color: red; background: transparent; }
|
|
.note, .warning { font-weight: bolder; font-style: italic; }
|
|
p.note, div.note { padding: 0.5em 2em; }
|
|
span.note { padding: 0 2em; }
|
|
.note p:first-child, .warning p:first-child { margin-top: 0; }
|
|
.note p:last-child, .warning p:last-child { margin-bottom: 0; }
|
|
.warning:before { font-style: normal; }
|
|
p.note:before { content: 'Note: '; }
|
|
p.warning:before { content: '\26A0 Warning! '; }
|
|
|
|
.bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
|
|
.bookkeeping { font-size: 0.8em; margin: 2em 0; }
|
|
.bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
|
|
.bookkeeping dt { margin: 0.5em 2em 0; }
|
|
.bookkeeping dd { margin: 0 3em 0.5em; }
|
|
|
|
h4 { position: relative; z-index: 3; }
|
|
h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
|
|
.element {
|
|
background: #EEEEFF;
|
|
color: black;
|
|
margin: 0 0 1em 0.15em;
|
|
padding: 0 1em 0.25em 0.75em;
|
|
border-left: solid #9999FF 0.25em;
|
|
position: relative;
|
|
z-index: 1;
|
|
}
|
|
.element:before {
|
|
position: absolute;
|
|
z-index: 2;
|
|
top: 0;
|
|
left: -1.15em;
|
|
height: 2em;
|
|
width: 0.9em;
|
|
background: #EEEEFF;
|
|
content: ' ';
|
|
border-style: none none solid solid;
|
|
border-color: #9999FF;
|
|
border-width: 0.25em;
|
|
}
|
|
|
|
.example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
|
|
td > .example:only-child { margin: 0 0 0 0.1em; }
|
|
|
|
ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
|
|
ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
|
|
ul.domTree li li { list-style: none; }
|
|
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; }
|
|
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; }
|
|
ul.domTree span { font-style: italic; font-family: serif; }
|
|
ul.domTree .t1 code { color: purple; font-weight: bold; }
|
|
ul.domTree .t2 { font-style: normal; font-family: monospace; }
|
|
ul.domTree .t2 .name { color: black; font-weight: bold; }
|
|
ul.domTree .t2 .value { color: blue; font-weight: normal; }
|
|
ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
|
|
ul.domTree .t7 code, .domTree .t8 code { color: green; }
|
|
ul.domTree .t10 code { color: teal; }
|
|
|
|
body.dfnEnabled dfn { cursor: pointer; }
|
|
.dfnPanel {
|
|
display: inline;
|
|
position: absolute;
|
|
z-index: 10;
|
|
height: auto;
|
|
width: auto;
|
|
padding: 0.5em 0.75em;
|
|
font: small sans-serif, Droid Sans Fallback;
|
|
background: #DDDDDD;
|
|
color: black;
|
|
border: outset 0.2em;
|
|
}
|
|
.dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
|
|
.dfnPanel :link, .dfnPanel :visited { color: black; }
|
|
.dfnPanel p { font-weight: bolder; }
|
|
.dfnPanel * + p { margin-top: 0.25em; }
|
|
.dfnPanel li { list-style-position: inside; }
|
|
|
|
#configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
|
|
#configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
|
|
#configUI p label { display: block; }
|
|
#configUI #updateUI, #configUI .loginUI { text-align: center; }
|
|
#configUI input[type=button] { display: block; margin: auto; }
|
|
|
|
fieldset { margin: 1em; padding: 0.5em 1em; }
|
|
fieldset > legend + * { margin-top: 0; }
|
|
fieldset > :last-child { margin-bottom: 0; }
|
|
fieldset p { margin: 0.5em 0; }
|
|
|
|
.stability {
|
|
position: fixed;
|
|
bottom: 0;
|
|
left: 0; right: 0;
|
|
margin: 0 auto 0 auto !important;
|
|
z-index: 1000;
|
|
width: 50%;
|
|
background: maroon; color: yellow;
|
|
-webkit-border-radius: 1em 1em 0 0;
|
|
-moz-border-radius: 1em 1em 0 0;
|
|
border-radius: 1em 1em 0 0;
|
|
-moz-box-shadow: 0 0 1em #500;
|
|
-webkit-box-shadow: 0 0 1em #500;
|
|
box-shadow: 0 0 1em red;
|
|
padding: 0.5em 1em;
|
|
text-align: center;
|
|
}
|
|
.stability strong {
|
|
display: block;
|
|
}
|
|
.stability input {
|
|
appearance: none; margin: 0; border: 0; padding: 0.25em 0.5em; background: transparent; color: black;
|
|
position: absolute; top: -0.5em; right: 0; font: 1.25em sans-serif; text-align: center;
|
|
}
|
|
.stability input:hover {
|
|
color: white;
|
|
text-shadow: 0 0 2px black;
|
|
}
|
|
.stability input:active {
|
|
padding: 0.3em 0.45em 0.2em 0.55em;
|
|
}
|
|
.stability :link, .stability :visited,
|
|
.stability :link:hover, .stability :visited:hover {
|
|
background: transparent;
|
|
color: white;
|
|
}
|
|
|
|
</style><link href="data:text/css,.impl%20%7B%20display:%20none;%20%7D%0Ahtml%20%7B%20border:%20solid%20yellow;%20%7D%20.domintro:before%20%7B%20display:%20none;%20%7D" id="author" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D%20.domintro:before%20%7B%20background:%20%23FFEEEE;%20%7D" id="highlight" rel="alternate stylesheet" title="Highlight implementation
|
|
requirements"><link href="http://www.w3.org/StyleSheets/TR/W3C-WD" rel="stylesheet" type="text/css"><style type="text/css">
|
|
|
|
.applies thead th > * { display: block; }
|
|
.applies thead code { display: block; }
|
|
.applies tbody th { whitespace: nowrap; }
|
|
.applies td { text-align: center; }
|
|
.applies .yes { background: yellow; }
|
|
|
|
.matrix, .matrix td { border: hidden; text-align: right; }
|
|
.matrix { margin-left: 2em; }
|
|
|
|
.dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
|
|
.dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
|
|
.dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
|
|
|
|
td.eg { border-width: thin; text-align: center; }
|
|
|
|
#table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
|
|
#table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
|
|
#table-example-1 caption { padding-bottom: 0.5em; }
|
|
#table-example-1 thead, #table-example-1 tbody { border: none; }
|
|
#table-example-1 th, #table-example-1 td { border: solid thin; }
|
|
#table-example-1 th { font-weight: normal; }
|
|
#table-example-1 td { border-style: none solid; vertical-align: top; }
|
|
#table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
|
|
#table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
|
|
#table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
|
|
#table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
|
|
#table-example-1 tbody td:first-child::after { content: leader(". "); }
|
|
#table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
|
|
#table-example-1 tbody td:first-child + td { width: 10em; }
|
|
#table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
|
|
#table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
|
|
|
|
.apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
|
|
.apple-table-examples * { font-family: "Times", serif; }
|
|
.apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
|
|
.apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
|
|
.apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
|
|
.apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
|
|
.apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
|
|
.apple-table-examples td { text-align: right; vertical-align: top; }
|
|
.apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
|
|
.apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
|
|
.apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
|
|
.apple-table-examples sup { line-height: 0; }
|
|
|
|
.details-example img { vertical-align: top; }
|
|
|
|
#base64-table {
|
|
white-space: nowrap;
|
|
font-size: 0.6em;
|
|
column-width: 6em;
|
|
column-count: 5;
|
|
column-gap: 1em;
|
|
-moz-column-width: 6em;
|
|
-moz-column-count: 5;
|
|
-moz-column-gap: 1em;
|
|
-webkit-column-width: 6em;
|
|
-webkit-column-count: 5;
|
|
-webkit-column-gap: 1em;
|
|
}
|
|
#base64-table thead { display: none; }
|
|
#base64-table * { border: none; }
|
|
#base64-table tbody td:first-child:after { content: ':'; }
|
|
#base64-table tbody td:last-child { text-align: right; }
|
|
|
|
#named-character-references-table {
|
|
white-space: nowrap;
|
|
font-size: 0.6em;
|
|
column-width: 30em;
|
|
column-gap: 1em;
|
|
-moz-column-width: 30em;
|
|
-moz-column-gap: 1em;
|
|
-webkit-column-width: 30em;
|
|
-webkit-column-gap: 1em;
|
|
}
|
|
#named-character-references-table > table > tbody > tr > td:first-child + td,
|
|
#named-character-references-table > table > tbody > tr > td:last-child { text-align: center; }
|
|
#named-character-references-table > table > tbody > tr > td:last-child:hover > span { position: absolute; top: auto; left: auto; margin-left: 0.5em; line-height: 1.2; font-size: 5em; border: outset; padding: 0.25em 0.5em; background: white; width: 1.25em; height: auto; text-align: center; }
|
|
#named-character-references-table > table > tbody > tr#entity-CounterClockwiseContourIntegral > td:first-child { font-size: 0.5em; }
|
|
|
|
.glyph.control { color: red; }
|
|
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743.ttf');
|
|
}
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
font-weight: bold;
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Bold.ttf');
|
|
}
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
font-style: italic;
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Italic.ttf');
|
|
}
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
font-style: italic;
|
|
font-weight: bold;
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-BoldItalic.ttf');
|
|
}
|
|
|
|
</style><style type="text/css">
|
|
.domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; }
|
|
</style><script type="text/javascript">
|
|
function getCookie(name) {
|
|
var params = location.search.substr(1).split("&");
|
|
for (var index = 0; index < params.length; index++) {
|
|
if (params[index] == name)
|
|
return "1";
|
|
var data = params[index].split("=");
|
|
if (data[0] == name)
|
|
return unescape(data[1]);
|
|
}
|
|
var cookies = document.cookie.split("; ");
|
|
for (var index = 0; index < cookies.length; index++) {
|
|
var data = cookies[index].split("=");
|
|
if (data[0] == name)
|
|
return unescape(data[1]);
|
|
}
|
|
return null;
|
|
}
|
|
</script>
|
|
<script src="link-fixup.js" type="text/javascript"></script>
|
|
<link href="style.css" rel="stylesheet"><link href="origin-0.html" title="5.3 Origin" rel="prev">
|
|
<link href="spec.html#contents" title="Table of contents" rel="index">
|
|
<link href="offline.html" title="5.6 Offline Web applications" rel="next">
|
|
</head><body><div class="head" id="head">
|
|
<div id="multipage-common">
|
|
<p class="stability" id="wip"><strong>This is a work in
|
|
progress!</strong> For the latest updates from the HTML WG, possibly
|
|
including important bug fixes, please look at the <a href="http://dev.w3.org/html5/spec/Overview.html">editor's draft</a> instead.
|
|
There may also be a more
|
|
<a href="http://www.w3.org/TR/html5">up-to-date Working Draft</a>
|
|
with changes based on resolution of Last Call issues.
|
|
<input onclick="closeWarning(this.parentNode)" type="button" value="╳⃝"></p>
|
|
<script type="text/javascript">
|
|
function closeWarning(element) {
|
|
element.parentNode.removeChild(element);
|
|
var date = new Date();
|
|
date.setDate(date.getDate()+4);
|
|
document.cookie = 'hide-obsolescence-warning=1; expires=' + date.toGMTString();
|
|
}
|
|
if (getCookie('hide-obsolescence-warning') == '1')
|
|
setTimeout(function () { document.getElementById('wip').parentNode.removeChild(document.getElementById('wip')); }, 2000);
|
|
</script></div>
|
|
|
|
<p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
|
|
|
|
<h1>HTML5</h1>
|
|
</div><div>
|
|
<a href="origin-0.html" class="prev">5.3 Origin</a> –
|
|
<a href="spec.html#contents">Table of contents</a> –
|
|
<a href="offline.html" class="next">5.6 Offline Web applications</a>
|
|
<ol class="toc"><li><ol><li><a href="history.html#history"><span class="secno">5.4 </span>Session history and navigation</a>
|
|
<ol><li><a href="history.html#the-session-history-of-browsing-contexts"><span class="secno">5.4.1 </span>The session history of browsing contexts</a></li><li><a href="history.html#the-history-interface"><span class="secno">5.4.2 </span>The <code>History</code> interface</a></li><li><a href="history.html#the-location-interface"><span class="secno">5.4.3 </span>The <code>Location</code> interface</a>
|
|
<ol><li><a href="history.html#security-location"><span class="secno">5.4.3.1 </span>Security</a></li></ol></li><li><a href="history.html#history-notes"><span class="secno">5.4.4 </span>Implementation notes for session history</a></li></ol></li><li><a href="history.html#browsing-the-web"><span class="secno">5.5 </span>Browsing the Web</a>
|
|
<ol><li><a href="history.html#navigating-across-documents"><span class="secno">5.5.1 </span>Navigating across documents</a></li><li><a href="history.html#read-html"><span class="secno">5.5.2 </span>Page load processing model for HTML files</a></li><li><a href="history.html#read-xml"><span class="secno">5.5.3 </span>Page load processing model for XML files</a></li><li><a href="history.html#read-text"><span class="secno">5.5.4 </span>Page load processing model for text files</a></li><li><a href="history.html#read-image"><span class="secno">5.5.5 </span>Page load processing model for images</a></li><li><a href="history.html#read-plugin"><span class="secno">5.5.6 </span>Page load processing model for content that uses plugins</a></li><li><a href="history.html#read-ua-inline"><span class="secno">5.5.7 </span>Page load processing model for inline content that doesn't have a DOM</a></li><li><a href="history.html#scroll-to-fragid"><span class="secno">5.5.8 </span>Navigating to a fragment identifier</a></li><li><a href="history.html#history-traversal"><span class="secno">5.5.9 </span>History traversal</a>
|
|
<ol><li><a href="history.html#event-definitions"><span class="secno">5.5.9.1 </span>Event definitions</a></li></ol></li><li><a href="history.html#unloading-documents"><span class="secno">5.5.10 </span>Unloading documents</a>
|
|
<ol><li><a href="history.html#event-definition"><span class="secno">5.5.10.1 </span>Event definition</a></li></ol></li><li><a href="history.html#aborting-a-document-load"><span class="secno">5.5.11 </span>Aborting a document load</a></li></ol></li></ol></li></ol></div>
|
|
|
|
<h3 id="history"><span class="secno">5.4 </span>Session history and navigation</h3><h4 id="the-session-history-of-browsing-contexts"><span class="secno">5.4.1 </span>The session history of browsing contexts</h4><p>The sequence of <code><a href="infrastructure.html#document">Document</a></code>s in a <a href="browsers.html#browsing-context">browsing
|
|
context</a> is its <dfn id="session-history">session history</dfn>.</p><p><code><a href="#history-0">History</a></code> objects provide a representation of the
|
|
pages in the session history of <a href="browsers.html#browsing-context" title="browsing
|
|
context">browsing contexts</a>. Each <a href="browsers.html#browsing-context">browsing
|
|
context</a>, including <a href="browsers.html#nested-browsing-context" title="nested browsing
|
|
context">nested browsing contexts</a>, has a distinct session
|
|
history.</p><p>Each <code><a href="infrastructure.html#document">Document</a></code> object in a <a href="browsers.html#browsing-context">browsing
|
|
context</a>'s <a href="#session-history">session history</a> is associated with a
|
|
unique instance of the <code><a href="#history-0">History</a></code> object, although they
|
|
all must model the same underlying <a href="#session-history">session history</a>.</p><div class="impl">
|
|
|
|
<p>The <dfn id="dom-history" title="dom-history"><code>history</code></dfn> attribute
|
|
of the <code><a href="browsers.html#window">Window</a></code> interface must return the object
|
|
implementing the <code><a href="#history-0">History</a></code> interface for that
|
|
<code><a href="browsers.html#window">Window</a></code> object's <code><a href="infrastructure.html#document">Document</a></code>.</p>
|
|
|
|
</div><p><code><a href="#history-0">History</a></code> objects represent their <a href="browsers.html#browsing-context">browsing
|
|
context</a>'s session history as a flat list of <a href="#session-history-entry" title="session history entry">session history entries</a>. Each
|
|
<dfn id="session-history-entry">session history entry</dfn> consists of either a
|
|
<a href="urls.html#url">URL</a> or a <a href="#state-object">state object</a>, or both<span class="impl">, and may in addition have a title, a
|
|
<code><a href="infrastructure.html#document">Document</a></code> object, form data, a scroll position, and
|
|
other information associated with it</span>.</p><div class="impl">
|
|
|
|
<p class="note">This does not imply that the user interface need be
|
|
linear. See the <a href="#history-notes">notes below</a>.</p>
|
|
|
|
</div><p class="note">Titles associated with <a href="#session-history-entry" title="session history
|
|
entry">session history entries</a> need not have any relation
|
|
with the current <code><a href="semantics.html#the-title-element">title</a></code> of the
|
|
<code><a href="infrastructure.html#document">Document</a></code>. The title of a <a href="#session-history-entry">session history
|
|
entry</a> is intended to explain the state of the document at
|
|
that point, so that the user can navigate the document's
|
|
history.</p><p>URLs without associated <a href="#state-object" title="state object">state
|
|
objects</a> are added to the session history as the user (or
|
|
script) navigates from page to page.</p><p>A <dfn id="state-object">state object</dfn> is an object representing a user
|
|
interface state.</p><p>Pages can <a href="#dom-history-pushstate" title="dom-history-pushState">add</a> <a href="#state-object" title="state object">state objects</a> between their entry in the
|
|
session history and the next ("forward") entry. These are then <a href="#event-popstate" title="event-popstate">returned to the script</a> when the user
|
|
(or script) goes back in the history, thus enabling authors to use
|
|
the "navigation" metaphor even in one-page applications.</p><div class="note">
|
|
|
|
<p><a href="#state-object" title="state object">State objects</a> are intended to
|
|
be used for two main purposes: first, storing a preparsed
|
|
description of the state in the <a href="urls.html#url">URL</a> so that in the
|
|
simple case an author doesn't have to do the parsing (though one
|
|
would still need the parsing for handling <a href="urls.html#url" title="URL">URLs</a> passed around by users, so it's only a minor
|
|
optimization), and second, so that the author can store state that
|
|
one wouldn't store in the URL because it only applies to the current
|
|
<code><a href="infrastructure.html#document">Document</a></code> instance and it would have to be reconstructed
|
|
if a new <code><a href="infrastructure.html#document">Document</a></code> were opened.</p>
|
|
|
|
<p>An example of the latter would be something like keeping track of
|
|
the precise coordinate from which a popup <code><a href="grouping-content.html#the-div-element">div</a></code> was made
|
|
to animate, so that if the user goes back, it can be made to animate
|
|
to the same location. Or alternatively, it could be used to keep a
|
|
pointer into a cache of data that would be fetched from the server
|
|
based on the information in the <a href="urls.html#url">URL</a>, so that when going
|
|
back and forward, the information doesn't have to be fetched
|
|
again.</p>
|
|
|
|
</div><hr><p>At any point, one of the entries in the session history is the
|
|
<dfn id="current-entry">current entry</dfn>. This is the entry representing the
|
|
<a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing
|
|
context</a>. The <a href="#current-entry">current entry</a> is usually an entry
|
|
for the <a href="#dom-location-href" title="dom-location-href">location</a> of the
|
|
<code><a href="infrastructure.html#document">Document</a></code>. However, it can also be one of the entries
|
|
for <a href="#state-object" title="state object">state objects</a> added to the
|
|
history by that document.</p><p><dfn id="an-entry-with-persisted-user-state">An entry with persisted user state</dfn> is one that also
|
|
has user-agent defined state. This specification does not specify
|
|
what kind of state can be stored.</p><p class="example">For example, some user agents might want to
|
|
persist the scroll position, or the values of form controls.</p><p>Entries that consist of <a href="#state-object" title="state object">state
|
|
objects</a> share the same <code><a href="infrastructure.html#document">Document</a></code> as the entry for
|
|
the page that was active when they were added.</p><p>Contiguous entries that differ just by fragment identifier also
|
|
share the same <code><a href="infrastructure.html#document">Document</a></code>.</p><p class="note">All entries that share the same
|
|
<code><a href="infrastructure.html#document">Document</a></code> (and that are therefore merely different
|
|
states of one particular document) are contiguous by definition.</p><div class="impl">
|
|
|
|
<p>User agents may <a href="browsers.html#discard-a-document" title="discard a Document">discard</a>
|
|
the <code><a href="infrastructure.html#document">Document</a></code> objects of entries other than the
|
|
<a href="#current-entry">current entry</a> that are not referenced from any script,
|
|
reloading the pages afresh when the user or script navigates back to
|
|
such pages. This specification does not specify when user agents
|
|
should discard <code><a href="infrastructure.html#document">Document</a></code> objects and when they should
|
|
cache them.</p>
|
|
|
|
<p>Entries that have had their <code><a href="infrastructure.html#document">Document</a></code> objects
|
|
discarded must, for the purposes of the algorithms given below, act
|
|
as if they had not. When the user or script navigates back or
|
|
forwards to a page which has no in-memory DOM objects, any other
|
|
entries that shared the same <code><a href="infrastructure.html#document">Document</a></code> object with it
|
|
must share the new object as well.</p>
|
|
|
|
</div><h4 id="the-history-interface"><span class="secno">5.4.2 </span>The <code><a href="#history-0">History</a></code> interface</h4><pre class="idl">interface <dfn id="history-0">History</dfn> {
|
|
readonly attribute long <a href="#dom-history-length" title="dom-history-length">length</a>;
|
|
readonly attribute any <a href="#dom-history-state" title="dom-history-state">state</a>;
|
|
void <a href="#dom-history-go" title="dom-history-go">go</a>(in optional long delta);
|
|
void <a href="#dom-history-back" title="dom-history-back">back</a>();
|
|
void <a href="#dom-history-forward" title="dom-history-forward">forward</a>();
|
|
void <a href="#dom-history-pushstate" title="dom-history-pushState">pushState</a>(in any data, in DOMString title, in optional DOMString url);
|
|
void <a href="#dom-history-replacestate" title="dom-history-replaceState">replaceState</a>(in any data, in DOMString title, in optional DOMString url);
|
|
};</pre><dl class="domintro"><dt><var title="">window</var> . <code title="dom-history"><a href="#dom-history">history</a></code> . <code title="dom-history-length"><a href="#dom-history-length">length</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the number of entries in the <a href="#joint-session-history">joint session history</a>.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">window</var> . <code title="dom-history"><a href="#dom-history">history</a></code> . <code title="dom-history-state"><a href="#dom-history-state">state</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the current <a href="#state-object">state object</a>.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">window</var> . <code title="dom-history"><a href="#dom-history">history</a></code> . <code title="dom-history-go"><a href="#dom-history-go">go</a></code>( [ <var title="">delta</var> ] )</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Goes back or forward the specified number of steps in the <a href="#joint-session-history">joint session history</a>.</p>
|
|
|
|
<p>A zero delta will reload the current page.</p>
|
|
|
|
<p>If the delta is out of range, does nothing.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">window</var> . <code title="dom-history"><a href="#dom-history">history</a></code> . <code title="dom-history-back"><a href="#dom-history-back">back</a></code>()</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Goes back one step in the <a href="#joint-session-history">joint session history</a>.</p>
|
|
|
|
<p>If there is no previous page, does nothing.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">window</var> . <code title="dom-history"><a href="#dom-history">history</a></code> . <code title="dom-history-forward"><a href="#dom-history-forward">forward</a></code>()</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Goes forward one step in the <a href="#joint-session-history">joint session history</a>.</p>
|
|
|
|
<p>If there is no next page, does nothing.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">window</var> . <code title="dom-history"><a href="#dom-history">history</a></code> . <code title="dom-history-pushState"><a href="#dom-history-pushstate">pushState</a></code>(<var title="">data</var>, <var title="">title</var> [, <var title="">url</var> ] )</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Pushes the given data onto the session history, with the given title, and, if provided, the given URL.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">window</var> . <code title="dom-history"><a href="#dom-history">history</a></code> . <code title="dom-history-replaceState"><a href="#dom-history-replacestate">replaceState</a></code>(<var title="">data</var>, <var title="">title</var> [, <var title="">url</var> ] )</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Updates the current entry in the session history to have the given data, title, and, if provided, URL.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><p>The <dfn id="joint-session-history">joint session history</dfn> of a <code><a href="#history-0">History</a></code>
|
|
object is the union of all the <a href="#session-history" title="session history">session
|
|
histories</a> of all <a href="browsers.html#browsing-context" title="browsing context">browsing
|
|
contexts</a> of all the <a href="browsers.html#fully-active">fully active</a>
|
|
<code><a href="infrastructure.html#document">Document</a></code> objects that share the <code><a href="#history-0">History</a></code>
|
|
object's <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>, with all the
|
|
entries that are <a href="#current-entry" title="current entry">current entries</a>
|
|
in their respective <a href="#session-history" title="session history">session
|
|
histories</a> removed except for the <a href="#current-entry-of-the-joint-session-history">current entry of the
|
|
joint session history</a>.</p><p>The <dfn id="current-entry-of-the-joint-session-history">current entry of the joint session history</dfn> is the
|
|
entry that most recently became a <a href="#current-entry">current entry</a> in its
|
|
<a href="#session-history">session history</a>.</p><p>Entries in the <a href="#joint-session-history">joint session history</a> are ordered
|
|
chronologically by the time they were added to their respective
|
|
<a href="#session-history" title="session history">session histories</a>. (Since all
|
|
these <a href="browsers.html#browsing-context" title="browsing context">browsing contexts</a> by
|
|
definition share an <a href="webappapis.html#event-loop">event loop</a>, there is always a
|
|
well-defined sequential order in which their <a href="#session-history" title="session
|
|
history">session histories</a> had their entries added.) Each
|
|
entry has an index; the earliest entry has index 0, and the
|
|
subsequent entries are numbered with consecutively increasing
|
|
integers (1, 2, 3, etc).</p><div class="impl">
|
|
|
|
<p>The <dfn id="dom-history-length" title="dom-history-length"><code>length</code></dfn>
|
|
attribute of the <code><a href="#history-0">History</a></code> interface must return the
|
|
number of entries in the <a href="#joint-session-history">joint session history</a>.</p>
|
|
|
|
<p>The actual entries are not accessible from script.</p>
|
|
|
|
<p>The <dfn id="dom-history-state" title="dom-history-state"><code>state</code></dfn>
|
|
attribute of the <code><a href="#history-0">History</a></code> interface must return the last
|
|
value it was set to by the user agent. Initially, its value must be
|
|
null.</p>
|
|
|
|
<p>When the <dfn id="dom-history-go" title="dom-history-go"><code>go(<var title="">delta</var>)</code></dfn> method is invoked, if the
|
|
argument to the method was omitted or has the value zero, the user
|
|
agent must act as if the <code title="dom-location-reload"><a href="#dom-location-reload">location.reload()</a></code> method was
|
|
called instead. Otherwise, the user agent must <a href="#traverse-the-history-by-a-delta">traverse the
|
|
history by a delta</a> whose value is the value of the method's
|
|
argument.</p>
|
|
|
|
<p>When the <dfn id="dom-history-back" title="dom-history-back"><code>back()</code></dfn>
|
|
method is invoked, the user agent must <a href="#traverse-the-history-by-a-delta">traverse the history by
|
|
a delta</a> −1.</p>
|
|
|
|
<p>When the <dfn id="dom-history-forward" title="dom-history-forward"><code>forward()</code></dfn>method is
|
|
invoked, the user agent must <a href="#traverse-the-history-by-a-delta">traverse the history by a
|
|
delta</a> +1.</p>
|
|
|
|
<p>To <dfn id="traverse-the-history-by-a-delta">traverse the history by a delta</dfn> <var title="">delta</var>, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
|
|
to run the following steps. The <a href="webappapis.html#task-source">task source</a> for the
|
|
queued task is the <a href="webappapis.html#history-traversal-task-source">history traversal task source</a>.</p>
|
|
|
|
<ol><li><p>Let <var title="">delta</var> be the argument to the
|
|
method.</p></li>
|
|
|
|
<li><p>If the index of the <a href="#current-entry-of-the-joint-session-history">current entry of the joint session
|
|
history</a> plus <var title="">delta</var> is less than zero or
|
|
greater than or equal to the number of items in the <a href="#joint-session-history">joint
|
|
session history</a>, then abort these steps.</p>
|
|
|
|
</li><li><p>Let <var title="">specified entry</var> be the entry in the
|
|
<a href="#joint-session-history">joint session history</a> whose index is the sum of <var title="">delta</var> and the index of the <a href="#current-entry-of-the-joint-session-history">current entry of
|
|
the joint session history</a>.</p></li>
|
|
|
|
<li><p>Let <var title="">specified browsing context</var> be the
|
|
<a href="browsers.html#browsing-context">browsing context</a> of the <var title="">specified
|
|
entry</var>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If the <var title="">specified browsing context</var>'s
|
|
<a href="browsers.html#active-document">active document</a> is not the same <code><a href="infrastructure.html#document">Document</a></code>
|
|
as the <code><a href="infrastructure.html#document">Document</a></code> of the <var title="">specified
|
|
entry</var>, then run these substeps:</p>
|
|
|
|
<ol><li><p><a href="#prompt-to-unload-a-document" title="prompt to unload a document">Prompt to
|
|
unload</a> the <a href="browsers.html#active-document">active document</a> of the <var title="">specified browsing context</var>. If the user
|
|
<a href="#refused-to-allow-the-document-to-be-unloaded">refused to allow the document to be unloaded</a>, then
|
|
abort these steps.</p></li>
|
|
|
|
<li><p><a href="#unload-a-document" title="unload a document">Unload</a> the
|
|
<a href="browsers.html#active-document">active document</a> of the <var title="">specified
|
|
browsing context</var> with the <var title="">recycle</var>
|
|
parameter set to false.</p></li>
|
|
|
|
</ol></li>
|
|
|
|
<li><p><a href="#traverse-the-history">Traverse the history</a> of the <var title="">specified browsing context</var> to the <var title="">specified entry</var>.</p>
|
|
|
|
</li></ol><p>When the user navigates through a <a href="browsers.html#browsing-context">browsing context</a>,
|
|
e.g. using a browser's back and forward buttons, the user agent must
|
|
<a href="#traverse-the-history-by-a-delta">traverse the history by a delta</a> equivalent to the
|
|
action specified by the user.</p>
|
|
|
|
<hr><p>The <dfn id="dom-history-pushstate" title="dom-history-pushState"><code>pushState(<var title="">data</var>, <var title="">title</var>, <var title="">url</var>)</code></dfn> method adds a state object entry to
|
|
the history.</p>
|
|
|
|
<p>The <dfn id="dom-history-replacestate" title="dom-history-replaceState"><code>replaceState(<var title="">data</var>, <var title="">title</var>, <var title="">url</var>)</code></dfn> method updates the state object,
|
|
title, and optionally the <a href="urls.html#url">URL</a> of the <a href="#current-entry">current
|
|
entry</a> in the history.</p>
|
|
|
|
<p>When either of these methods is invoked, the user agent must run
|
|
the following steps:</p>
|
|
|
|
<ol><li><p>Let <var title="">clone data</var> be a <a href="common-dom-interfaces.html#structured-clone">structured
|
|
clone</a> of the specified <var title="">data</var>. If this
|
|
throws an exception, then rethrow that exception and abort these
|
|
steps.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If a third argument is specified, run these substeps:</p>
|
|
|
|
<ol><li><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the value of the
|
|
third argument, relative to the <a href="browsers.html#entry-script">entry script</a>'s <a href="webappapis.html#script-s-base-url" title="script's base URL">base URL</a>.</li>
|
|
|
|
<li>If that fails, raise a <code><a href="common-dom-interfaces.html#security_err">SECURITY_ERR</a></code> exception
|
|
and abort these steps.</li>
|
|
|
|
<li>Compare the resulting <a href="urls.html#absolute-url">absolute URL</a> to <a href="dom.html#the-document-s-address">the
|
|
document's address</a>. If any part of these two <a href="urls.html#url" title="URL">URLs</a> differ other than the <a href="urls.html#url-path" title="url-path"><path></a>, <a href="urls.html#url-query" title="url-query"><query></a>, and <a href="urls.html#url-fragment" title="url-fragment"><fragment></a> components, then
|
|
raise a <code><a href="common-dom-interfaces.html#security_err">SECURITY_ERR</a></code> exception and abort these
|
|
steps.</li>
|
|
|
|
<li>If the <a href="origin-0.html#origin">origin</a> of the resulting <a href="urls.html#absolute-url">absolute
|
|
URL</a> is not the same as the <a href="origin-0.html#origin">origin</a> of the
|
|
<a href="browsers.html#entry-script">entry script</a>'s <a href="webappapis.html#script-s-document" title="script's
|
|
document">document</a>, and either the <a href="urls.html#url-path" title="url-path"><path></a> or <a href="urls.html#url-query" title="url-query"><query></a> components of the two
|
|
<a href="urls.html#url" title="URL">URLs</a> compared in the previous step
|
|
differ, raise a <code><a href="common-dom-interfaces.html#security_err">SECURITY_ERR</a></code> exception and abort
|
|
these steps. (This prevents sandboxed content from spoofing other
|
|
pages on the same origin.)</li>
|
|
|
|
</ol><p>For the purposes of the comparisons in the above substeps, the
|
|
<a href="urls.html#url-path" title="url-path"><path></a> and <a href="urls.html#url-query" title="url-query"><query></a> components can only be the
|
|
same if the URLs are both <a href="urls.html#hierarchical-url" title="hierarchical
|
|
URL">hierarchical URLs</a>.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If the method invoked was the <code title="dom-history-pushState"><a href="#dom-history-pushstate">pushState()</a></code> method:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>Remove all the entries in the <a href="browsers.html#browsing-context">browsing context</a>'s
|
|
<a href="#session-history">session history</a> after the <a href="#current-entry">current
|
|
entry</a>. If the <a href="#current-entry">current entry</a> is the last
|
|
entry in the session history, then no entries are
|
|
removed.</p>
|
|
|
|
<p class="note">This <a href="#history-notes">doesn't
|
|
necessarily have to affect</a> the user agent's user
|
|
interface.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Remove any <a href="webappapis.html#concept-task" title="concept-task">tasks</a> queued
|
|
by the <a href="webappapis.html#history-traversal-task-source">history traversal task source</a>.</p></li>
|
|
|
|
<li><p>If appropriate, update the <a href="#current-entry">current entry</a> to
|
|
reflect any state that the user agent wishes to persist. The
|
|
entry is then said to be <a href="#an-entry-with-persisted-user-state">an entry with persisted user
|
|
state</a>.</p></li>
|
|
|
|
<li><p>Add a state object entry to the session history, after the
|
|
<a href="#current-entry">current entry</a>, with <var title="">cloned data</var> as
|
|
the state object, the given <var title="">title</var> as the title,
|
|
and, if the third argument is present, the <a href="urls.html#absolute-url">absolute
|
|
URL</a> that was found earlier in this algorithm as the
|
|
<a href="urls.html#url">URL</a> of the entry.</p></li>
|
|
|
|
<li><p>Update the <a href="#current-entry">current entry</a> to be this newly
|
|
added entry.</p></li>
|
|
|
|
</ol><p>Otherwise, if the method invoked was the <code title="dom-history-replaceState"><a href="#dom-history-replacestate">replaceState()</a></code> method:</p>
|
|
|
|
<ol><li><p>Update the <a href="#current-entry">current entry</a> in the session
|
|
history so that <var title="">cloned data</var> is the entry's
|
|
new state object, the given <var title="">title</var> is the new
|
|
title, and, if the third argument is present, the <a href="urls.html#absolute-url">absolute
|
|
URL</a> that was found earlier in this algorithm is the
|
|
entry's new <a href="urls.html#url">URL</a>.</p></li>
|
|
|
|
</ol></li>
|
|
|
|
<li>
|
|
|
|
<p>If the third argument is present, set <a href="dom.html#the-document-s-current-address">the document's
|
|
current address</a> to the <a href="urls.html#absolute-url">absolute URL</a> that was
|
|
found earlier in this algorithm.</p>
|
|
|
|
<p class="note">Since this is neither a <a href="#navigate" title="navigate">navigation</a> of the <a href="browsers.html#browsing-context">browsing
|
|
context</a> nor a <a href="#traverse-the-history" title="traverse the history">history
|
|
traversal</a>, it does not cause a <code title="event-hashchange"><a href="#event-hashchange">hashchange</a></code> event to be fired.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>Set <code title="dom-history-state"><a href="#dom-history-state">history.state</a></code> to
|
|
another <a href="common-dom-interfaces.html#structured-clone">structured clone</a> of the specified <var title="">data</var>.</p>
|
|
|
|
</li>
|
|
|
|
</ol><p class="note">The <var title="">title</var> is purely
|
|
advisory. User agents might use the title in the user interface.</p>
|
|
|
|
<p>User agents may limit the number of state objects added to the
|
|
session history per page. If a page hits the UA-defined limit, user
|
|
agents must remove the entry immediately after the first entry for
|
|
that <code><a href="infrastructure.html#document">Document</a></code> object in the session history after
|
|
having added the new entry. (Thus the state history acts as a FIFO
|
|
buffer for eviction, but as a LIFO buffer for navigation.)</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>Consider a game where the user can navigate along a line, such
|
|
that the user is always at some coordinate, and such that the user
|
|
can bookmark the page corresponding to a particular coordinate, to
|
|
return to it later.</p>
|
|
|
|
<p>A static page implementing the x=5 position in such a game could
|
|
look like the following:</p>
|
|
|
|
<pre><!DOCTYPE HTML>
|
|
<!-- this is http://example.com/line?x=5 -->
|
|
<title>Line Game - 5</title>
|
|
<p>You are at coordinate 5 on the line.</p>
|
|
<p>
|
|
<a href="?x=6">Advance to 6</a> or
|
|
<a href="?x=4">retreat to 4</a>?
|
|
</p></pre>
|
|
|
|
<p>The problem with such a system is that each time the user
|
|
clicks, the whole page has to be reloaded. Here instead is another
|
|
way of doing it, using script:</p>
|
|
|
|
<pre><!DOCTYPE HTML>
|
|
<!-- this starts off as http://example.com/line?x=5 -->
|
|
<title>Line Game - 5</title>
|
|
<p>You are at coordinate <span id="coord">5</span> on the line.</p>
|
|
<p>
|
|
<a href="?x=6" onclick="go(1); return false;">Advance to 6</a> or
|
|
<a href="?x=4" onclick="go(-1); return false;">retreat to 4</a>?
|
|
</p>
|
|
<script>
|
|
var currentPage = 5; // prefilled by server
|
|
function go(d) {
|
|
setupPage(currentPage + d);
|
|
history.pushState(currentPage, document.title, '?x=' + currentPage);
|
|
}
|
|
onpopstate = function(event) {
|
|
setupPage(event.state);
|
|
}
|
|
function setupPage(page) {
|
|
currentPage = page;
|
|
document.title = 'Line Game - ' + currentPage;
|
|
document.getElementById('coord').textContent = currentPage;
|
|
document.links[0].href = '?x=' + (currentPage+1);
|
|
document.links[0].textContent = 'Advance to ' + (currentPage+1);
|
|
document.links[1].href = '?x=' + (currentPage-1);
|
|
document.links[1].textContent = 'retreat to ' + (currentPage-1);
|
|
}
|
|
</script></pre>
|
|
|
|
<p>In systems without script, this still works like the previous
|
|
example. However, users that <em>do</em> have script support can
|
|
now navigate much faster, since there is no network access for the
|
|
same experience. Furthermore, contrary to the experience the user
|
|
would have with just a naïve script-based approach,
|
|
bookmarking and navigating the session history still work.</p>
|
|
|
|
<p>In the example above, the <var title="">data</var> argument to
|
|
the <code title="dom-history-pushState"><a href="#dom-history-pushstate">pushState()</a></code> method
|
|
is the same information as would be sent to the server, but in a
|
|
more convenient form, so that the script doesn't have to parse the
|
|
URL each time the user navigates.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>Applications might not use the same title for a <a href="#session-history-entry">session
|
|
history entry</a> as the value of the document's
|
|
<code><a href="semantics.html#the-title-element">title</a></code> element at that time. For example, here is a
|
|
simple page that shows a block in the <code><a href="semantics.html#the-title-element">title</a></code> element.
|
|
Clearly, when navigating backwards to a previous state the user
|
|
does not go back in time, and therefore it would be inappropriate
|
|
to put the time in the session history title.</p>
|
|
|
|
<pre><!DOCTYPE HTML>
|
|
<TITLE>Line</TITLE>
|
|
<SCRIPT>
|
|
setInterval(function () { document.title = 'Line - ' + new Date(); }, 1000);
|
|
var i = 1;
|
|
function inc() {
|
|
set(i+1);
|
|
history.pushState(i, 'Line - ' + i);
|
|
}
|
|
function set(newI) {
|
|
i = newI;
|
|
document.forms.F.I.value = newI;
|
|
}
|
|
</SCRIPT>
|
|
<BODY ONPOPSTATE="set(event.state)">
|
|
<FORM NAME=F>
|
|
State: <OUTPUT NAME=I>1</OUTPUT> <INPUT VALUE="Increment" TYPE=BUTTON ONCLICK="inc()">
|
|
</FORM></pre>
|
|
|
|
</div><h4 id="the-location-interface"><span class="secno">5.4.3 </span>The <code><a href="#location">Location</a></code> interface</h4><p>Each <code><a href="infrastructure.html#document">Document</a></code> object in a <a href="browsers.html#browsing-context">browsing
|
|
context</a>'s session history is associated with a unique
|
|
instance of a <code><a href="#location">Location</a></code> object.</p><dl class="domintro"><dt><var title="">document</var> . <code title="dom-document-location"><a href="#dom-document-location">location</a></code> [ = <var title="">value</var> ]</dt>
|
|
<dt><var title="">window</var> . <code title="dom-location"><a href="#dom-location">location</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="#location">Location</a></code> object with the current page's location.</p>
|
|
|
|
<p>Can be set, to navigate to another page.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-document-location" title="dom-document-location"><code>location</code></dfn> attribute
|
|
of the <code><a href="dom.html#htmldocument">HTMLDocument</a></code> interface must return the
|
|
<code><a href="#location">Location</a></code> object for that <code><a href="infrastructure.html#document">Document</a></code> object,
|
|
if it is in a <a href="browsers.html#browsing-context">browsing context</a>, and null otherwise.</p>
|
|
|
|
<p>The <dfn id="dom-location" title="dom-location"><code>location</code></dfn>
|
|
attribute of the <code><a href="browsers.html#window">Window</a></code> interface must return the
|
|
<code><a href="#location">Location</a></code> object for that <code><a href="browsers.html#window">Window</a></code> object's
|
|
<code><a href="infrastructure.html#document">Document</a></code>.</p>
|
|
|
|
</div><p><code><a href="#location">Location</a></code> objects provide a representation of <a href="dom.html#the-document-s-current-address" title="the document's current address">their document's current
|
|
address</a>, and allow the <a href="#current-entry">current entry</a> of the
|
|
<a href="browsers.html#browsing-context">browsing context</a>'s session history to be changed, by
|
|
adding or replacing entries in the <code title="dom-history"><a href="#dom-history">history</a></code> object.</p><pre class="idl">interface <dfn id="location">Location</dfn> {
|
|
stringifier attribute DOMString <a href="#dom-location-href" title="dom-location-href">href</a>;
|
|
void <a href="#dom-location-assign" title="dom-location-assign">assign</a>(in DOMString url);
|
|
void <a href="#dom-location-replace" title="dom-location-replace">replace</a>(in DOMString url);
|
|
void <a href="#dom-location-reload" title="dom-location-reload">reload</a>();
|
|
|
|
// <a href="urls.html#url-decomposition-idl-attributes">URL decomposition IDL attributes</a>
|
|
attribute DOMString <a href="#dom-location-protocol" title="dom-location-protocol">protocol</a>;
|
|
attribute DOMString <a href="#dom-location-host" title="dom-location-host">host</a>;
|
|
attribute DOMString <a href="#dom-location-hostname" title="dom-location-hostname">hostname</a>;
|
|
attribute DOMString <a href="#dom-location-port" title="dom-location-port">port</a>;
|
|
attribute DOMString <a href="#dom-location-pathname" title="dom-location-pathname">pathname</a>;
|
|
attribute DOMString <a href="#dom-location-search" title="dom-location-search">search</a>;
|
|
attribute DOMString <a href="#dom-location-hash" title="dom-location-hash">hash</a>;
|
|
|
|
// resolving relative URLs
|
|
DOMString <a href="#dom-location-resolveurl" title="dom-location-resolveURL">resolveURL</a>(in DOMString url);
|
|
};</pre><dl class="domintro"><dt><var title="">location</var> . <code title="dom-location-href"><a href="#dom-location-href">href</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the current page's location.</p>
|
|
|
|
<p>Can be set, to navigate to another page.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">location</var> . <code title="dom-location-assign"><a href="#dom-location-assign">assign</a></code>(<var title="">url</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Navigates to the given page.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">location</var> . <code title="dom-location-replace"><a href="#dom-location-replace">replace</a></code>(<var title="">url</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Removes the current page from the session history and navigates to the given page.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">location</var> . <code title="dom-location-reload"><a href="#dom-location-reload">reload</a></code>()</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Reloads the current page.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">url</var> = <var title="">location</var> . <code title="dom-location-resolveURL"><a href="#dom-location-resolveurl">resolveURL</a></code>(<var title="">url</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Resolves the given relative URL to an absolute URL.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-location-href" title="dom-location-href"><code>href</code></dfn>
|
|
attribute must return <a href="dom.html#the-document-s-current-address" title="the document's current
|
|
address">the current address</a> of the associated
|
|
<code><a href="infrastructure.html#document">Document</a></code> object, as an <a href="urls.html#absolute-url">absolute URL</a>.</p>
|
|
|
|
<p>On setting, if the <code><a href="#location">Location</a></code> object's associated
|
|
<code><a href="infrastructure.html#document">Document</a></code> object has <a href="the-end.html#completely-loaded">completely loaded</a>,
|
|
then the user agent must act as if the <code title="dom-location-assign"><a href="#dom-location-assign">assign()</a></code> method had been called
|
|
with the new value as its argument. Otherwise, the user agent must
|
|
act as if the <code title="dom-location-replace"><a href="#dom-location-replace">replace()</a></code>
|
|
method had been called with the new value as its argument.</p>
|
|
|
|
|
|
<p>When the <dfn id="dom-location-assign" title="dom-location-assign"><code>assign(<var title="">url</var>)</code></dfn> method is invoked, the UA must
|
|
<a href="urls.html#resolve-a-url" title="resolve a url">resolve</a> the argument, relative to
|
|
the <a href="browsers.html#entry-script">entry script</a>'s <a href="webappapis.html#script-s-base-url" title="script's base URL">base
|
|
URL</a>, and if that is successful, must
|
|
<a href="#navigate">navigate</a> the
|
|
<a href="browsers.html#browsing-context">browsing context</a> to the specified <var title="">url</var>. If the <a href="browsers.html#browsing-context">browsing context</a>'s
|
|
<a href="#session-history">session history</a> contains only one
|
|
<code><a href="infrastructure.html#document">Document</a></code>, and that was the <code><a href="fetching-resources.html#about:blank">about:blank</a></code>
|
|
<code><a href="infrastructure.html#document">Document</a></code> created when the <a href="browsers.html#browsing-context">browsing context</a>
|
|
was created, then the navigation must be done with <a href="#replacement-enabled">replacement
|
|
enabled</a>.</p>
|
|
<p>When the <dfn id="dom-location-replace" title="dom-location-replace"><code>replace(<var title="">url</var>)</code></dfn> method is invoked, the UA must
|
|
<a href="urls.html#resolve-a-url" title="resolve a url">resolve</a> the argument, relative to
|
|
the <a href="browsers.html#entry-script">entry script</a>'s <a href="webappapis.html#script-s-base-url" title="script's base URL">base
|
|
URL</a>, and if that is successful,
|
|
<a href="#navigate">navigate</a> the
|
|
<a href="browsers.html#browsing-context">browsing context</a> to the specified <var title="">url</var> with <a href="#replacement-enabled">replacement enabled</a>.</p>
|
|
|
|
<p>Navigation for the <code title="dom-location-assign"><a href="#dom-location-assign">assign()</a></code> and <code title="dom-location-replace"><a href="#dom-location-replace">replace()</a></code> methods must be done
|
|
with the <a href="webappapis.html#script-s-browsing-context" title="script's browsing context">browsing
|
|
context</a> of the script that invoked the method as the
|
|
<a href="#source-browsing-context">source browsing context</a>.</p>
|
|
|
|
<p>If the <a href="urls.html#resolve-a-url" title="resolve a url">resolving</a> step of the
|
|
<code title="dom-location-assign"><a href="#dom-location-assign">assign()</a></code> and <code title="dom-location-replace"><a href="#dom-location-replace">replace()</a></code> methods is not
|
|
successful, then the user agent must instead throw a
|
|
<code><a href="common-dom-interfaces.html#syntax_err">SYNTAX_ERR</a></code> exception.</p>
|
|
|
|
<p>When the <dfn id="dom-location-reload" title="dom-location-reload"><code>reload()</code></dfn> method is
|
|
invoked, the user agent must run the appropriate steps from the
|
|
following list:</p>
|
|
|
|
<dl class="switch"><dt>If the currently executing <a href="webappapis.html#concept-task" title="concept-task">task</a> is the dispatch of a <code title="event-resize">resize</code> event in response to the user
|
|
resizing the <a href="browsers.html#browsing-context">browsing context</a></dt>
|
|
|
|
<dd><p>Repaint the <a href="browsers.html#browsing-context">browsing context</a> and abort these
|
|
steps.</p></dd>
|
|
<dt>If the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active
|
|
document</a> is <a href="the-iframe-element.html#an-iframe-srcdoc-document">an <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code> document</a></dt>
|
|
|
|
<dd><p><a href="the-iframe-element.html#process-the-iframe-attributes" title="process the iframe attributes">Reprocess the
|
|
<code>iframe</code> attributes</a> of the <a href="browsers.html#browsing-context">browsing
|
|
context</a>'s <a href="browsers.html#browsing-context-container">browsing context container</a>.</p></dd>
|
|
|
|
<dt>If the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active
|
|
document</a> has its <a href="dom.html#reload-override-flag">reload override
|
|
flag</a> set</dt>
|
|
|
|
<dd><p>Perform <a href="dom.html#an-overridden-reload">an overridden reload</a>.</p></dd>
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd><p><a href="#navigate">Navigate</a> the
|
|
<a href="browsers.html#browsing-context">browsing context</a> to <a href="dom.html#the-document-s-current-address">the document's current
|
|
address</a> with <a href="#replacement-enabled">replacement enabled</a>. The
|
|
<a href="#source-browsing-context">source browsing context</a> must be the <a href="browsers.html#browsing-context">browsing
|
|
context</a> being navigated.</p></dd>
|
|
|
|
|
|
</dl><p>When a user requests that the current page of a <a href="browsers.html#browsing-context">browsing
|
|
context</a> be reloaded through a user interface element, the
|
|
user agent should <a href="#navigate">navigate</a> the
|
|
<a href="browsers.html#browsing-context">browsing context</a> to the same resource as
|
|
<code><a href="infrastructure.html#document">Document</a></code>, with <a href="#replacement-enabled">replacement enabled</a>. In the
|
|
case of non-idempotent methods (e.g. HTTP POST), the user agent
|
|
should prompt the user to confirm the operation first, since
|
|
otherwise transactions (e.g. purchases or database modifications)
|
|
could be repeated. User agents may allow the user to explicitly
|
|
override any caches when reloading. If <a href="browsers.html#browsing-context">browsing
|
|
context</a>'s <a href="browsers.html#active-document">active document</a>'s <a href="dom.html#reload-override-flag">reload
|
|
override flag</a> is set, then the user agent may instead perform
|
|
<a href="dom.html#an-overridden-reload">an overridden reload</a> rather than the navigation
|
|
described in this paragraph.</p>
|
|
|
|
</div><p>The <code><a href="#location">Location</a></code> interface also has the complement of
|
|
<a href="urls.html#url-decomposition-idl-attributes">URL decomposition IDL attributes</a>, <dfn id="dom-location-protocol" title="dom-location-protocol"><code>protocol</code></dfn>, <dfn id="dom-location-host" title="dom-location-host"><code>host</code></dfn>, <dfn id="dom-location-port" title="dom-location-port"><code>port</code></dfn>, <dfn id="dom-location-hostname" title="dom-location-hostname"><code>hostname</code></dfn>, <dfn id="dom-location-pathname" title="dom-location-pathname"><code>pathname</code></dfn>, <dfn id="dom-location-search" title="dom-location-search"><code>search</code></dfn>, and <dfn id="dom-location-hash" title="dom-location-hash"><code>hash</code></dfn>. <span class="impl">These must follow the rules given for <a href="urls.html#url-decomposition-idl-attributes">URL
|
|
decomposition IDL attributes</a>, with the <a href="urls.html#concept-uda-input" title="concept-uda-input">input</a> being <a href="dom.html#the-document-s-current-address" title="the
|
|
document's current address">the current address</a> of the
|
|
associated <code><a href="infrastructure.html#document">Document</a></code> object, as an <a href="urls.html#absolute-url">absolute
|
|
URL</a> (same as the <code title="dom-location-href"><a href="#dom-location-href">href</a></code>
|
|
attribute), and the <a href="urls.html#concept-uda-setter" title="concept-uda-setter">common setter
|
|
action</a> being the same as setting the <code title="dom-location-href"><a href="#dom-location-href">href</a></code> attribute to the new output
|
|
value.</span></p><div class="impl">
|
|
|
|
<hr><p>The <dfn id="dom-location-resolveurl" title="dom-location-resolveURL"><code>resolveURL(<var title="">url</var>)</code></dfn> method must <a href="urls.html#resolve-a-url" title="resolve a
|
|
url">resolve</a> its <var title="">url</var> argument, relative
|
|
to the <a href="browsers.html#entry-script">entry script</a>'s <a href="webappapis.html#script-s-base-url" title="script's base
|
|
URL">base URL</a>, and if that succeeds, return the resulting
|
|
<a href="urls.html#absolute-url">absolute URL</a>. If it fails, it must throw a
|
|
<code><a href="common-dom-interfaces.html#syntax_err">SYNTAX_ERR</a></code> exception instead.</p>
|
|
|
|
</div><div class="impl">
|
|
|
|
<h5 id="security-location"><span class="secno">5.4.3.1 </span>Security</h5>
|
|
|
|
<p id="security-3">User agents must raise a
|
|
<code><a href="common-dom-interfaces.html#security_err">SECURITY_ERR</a></code> exception whenever any of the members of a
|
|
<code><a href="#location">Location</a></code> object are accessed by scripts whose
|
|
<a href="origin-0.html#effective-script-origin">effective script origin</a> is not the <a href="origin-0.html#same-origin" title="same
|
|
origin">same</a> as the <code><a href="#location">Location</a></code> object's associated
|
|
<code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#effective-script-origin">effective script origin</a>, with
|
|
the following exceptions:</p>
|
|
|
|
<ul><li>The <code title="dom-location-href"><a href="#dom-location-href">href</a></code> setter, if the
|
|
script is running in a <a href="browsers.html#browsing-context">browsing context</a> that is
|
|
<a href="browsers.html#allowed-to-navigate">allowed to navigate</a> the browsing context with which
|
|
the <code><a href="#location">Location</a></code> object is associated
|
|
|
|
</li><li>The <code title="dom-location-replace"><a href="#dom-location-replace">replace()</a></code> method,
|
|
if the script is running in a <a href="browsers.html#browsing-context">browsing context</a> that is
|
|
<a href="browsers.html#allowed-to-navigate">allowed to navigate</a> the browsing context with which
|
|
the <code><a href="#location">Location</a></code> object is associated
|
|
|
|
</li></ul></div><div class="impl">
|
|
|
|
<h4 id="history-notes"><span class="secno">5.4.4 </span>Implementation notes for session history</h4>
|
|
|
|
|
|
<p><i>This section is non-normative.</i></p>
|
|
|
|
<p>The <code><a href="#history-0">History</a></code> interface is not meant to place
|
|
restrictions on how implementations represent the session history to
|
|
the user.</p>
|
|
|
|
<p>For example, session history could be implemented in a tree-like
|
|
manner, with each page having multiple "forward" pages. This
|
|
specification doesn't define how the linear list of pages in the
|
|
<code title="dom-history"><a href="#dom-history">history</a></code> object are derived from the
|
|
actual session history as seen from the user's perspective.</p>
|
|
|
|
<p>Similarly, a page containing two <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code>s has a <code title="dom-history"><a href="#dom-history">history</a></code> object distinct from the
|
|
<code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code>s' <code title="dom-history"><a href="#dom-history">history</a></code>
|
|
objects, despite the fact that typical Web browsers present the user
|
|
with just one "Back" button, with a session history that interleaves
|
|
the navigation of the two inner frames and the outer page.</p>
|
|
|
|
<p><strong>Security</strong>: It is suggested that to avoid letting
|
|
a page "hijack" the history navigation facilities of a UA by abusing
|
|
<code title="dom-history-pushState"><a href="#dom-history-pushstate">pushState()</a></code>, the UA
|
|
provide the user with a way to jump back to the previous page
|
|
(rather than just going back to the previous state). For example,
|
|
the back button could have a drop down showing just the pages in the
|
|
session history, and not showing any of the states. Similarly, an
|
|
aural browser could have two "back" commands, one that goes back to
|
|
the previous state, and one that jumps straight back to the previous
|
|
page.</p>
|
|
|
|
<p>In addition, a user agent could ignore calls to <code title="dom-history-pushState"><a href="#dom-history-pushstate">pushState()</a></code> that are invoked on
|
|
a timer, or from event listeners that are not triggered in response
|
|
to a clear user action, or that are invoked in rapid succession.</p>
|
|
|
|
</div><h3 id="browsing-the-web"><span class="secno">5.5 </span>Browsing the Web</h3><div class="impl">
|
|
|
|
<h4 id="navigating-across-documents"><span class="secno">5.5.1 </span>Navigating across documents</h4>
|
|
|
|
<p>Certain actions cause the <a href="browsers.html#browsing-context">browsing context</a> to
|
|
<i><a href="#navigate">navigate</a></i> to a new resource. Navigation always involves
|
|
<dfn id="source-browsing-context">source browsing context</dfn>, which is the browsing context
|
|
which was responsible for starting the navigation.</p>
|
|
|
|
<p class="example">For example, <a href="links.html#following-hyperlinks" title="following
|
|
hyperlinks">following a hyperlink</a>, <a href="association-of-controls-and-forms.html#concept-form-submit" title="concept-form-submit">form submission</a>, and the <code title="dom-open"><a href="browsers.html#dom-open">window.open()</a></code> and <code title="dom-location-assign"><a href="#dom-location-assign">location.assign()</a></code> methods can all
|
|
cause a browsing context to navigate.</p>
|
|
|
|
<p>A user agent may provide various ways for the user to explicitly
|
|
cause a browsing context to navigate, in addition to those defined
|
|
in this specification.</p>
|
|
|
|
|
|
<p>When a browsing context is <dfn id="navigate" title="navigate">navigated</dfn>
|
|
to a new resource, the user agent must run the following steps:</p>
|
|
|
|
<ol><li><p>Release the <a href="webappapis.html#storage-mutex">storage mutex</a>.</p></li>
|
|
|
|
<li id="sandboxLinks">
|
|
|
|
<p>If the <a href="#source-browsing-context">source browsing context</a> is not the same as
|
|
the <a href="browsers.html#browsing-context">browsing context</a> being navigated, and the
|
|
<a href="#source-browsing-context">source browsing context</a> is not one of the <a href="browsers.html#ancestor-browsing-context" title="ancestor browsing context">ancestor browsing
|
|
contexts</a> of the <a href="browsers.html#browsing-context">browsing context</a> being
|
|
navigated, and the <a href="browsers.html#browsing-context">browsing context</a> being navigated is
|
|
not both a <a href="browsers.html#top-level-browsing-context">top-level browsing context</a> and one of the
|
|
<a href="browsers.html#ancestor-browsing-context" title="ancestor browsing context">ancestor browsing
|
|
contexts</a> of the <a href="#source-browsing-context">source browsing context</a>, and
|
|
the <a href="#source-browsing-context">source browsing context</a> had its <a href="the-iframe-element.html#sandboxed-navigation-browsing-context-flag">sandboxed
|
|
navigation browsing context flag</a> set when its <a href="browsers.html#active-document">active
|
|
document</a> was created, then abort these steps.</p>
|
|
|
|
<p>Otherwise, if the <a href="browsers.html#browsing-context">browsing context</a> being navigated
|
|
is a <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>, and is one of the
|
|
<a href="browsers.html#ancestor-browsing-context" title="ancestor browsing context">ancestor browsing
|
|
contexts</a> of the <a href="#source-browsing-context">source browsing context</a>, and
|
|
the <a href="#source-browsing-context">source browsing context</a> had its <a href="the-iframe-element.html#sandboxed-top-level-navigation-browsing-context-flag">sandboxed
|
|
top-level navigation browsing context flag</a> set when its
|
|
<a href="browsers.html#active-document">active document</a> was created, then abort these
|
|
steps.</p>
|
|
|
|
<p>In both cases, the user agent may additionally offer to open
|
|
the new resource in a new <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>
|
|
or in the <a href="browsers.html#top-level-browsing-context">top-level browsing context</a> of the
|
|
<a href="#source-browsing-context">source browsing context</a>, at the user's option, in
|
|
which case the user agent must <a href="#navigate">navigate</a> that designated <a href="browsers.html#top-level-browsing-context">top-level browsing
|
|
context</a> to the new resource as if the user had requested it
|
|
independently.</p>
|
|
|
|
</li>
|
|
|
|
<li id="seamlessLinks"><p>If the <a href="#source-browsing-context">source browsing
|
|
context</a> is the same as the <a href="browsers.html#browsing-context">browsing context</a>
|
|
being navigated, and this browsing context has its <a href="the-iframe-element.html#seamless-browsing-context-flag">seamless
|
|
browsing context flag</a> set, and the <a href="browsers.html#browsing-context">browsing
|
|
context</a> being navigated was not chosen using an
|
|
<a href="browsers.html#explicit-self-navigation-override">explicit self-navigation override</a>, then find the
|
|
nearest <a href="browsers.html#ancestor-browsing-context">ancestor browsing context</a> that does not have
|
|
its <a href="the-iframe-element.html#seamless-browsing-context-flag">seamless browsing context flag</a> set, and continue
|
|
these steps as if <em>that</em> <a href="browsers.html#browsing-context">browsing context</a> was
|
|
the one that was going to be <a href="#navigate" title="navigate">navigated</a> instead.</p></li>
|
|
|
|
<li><p>If there is a preexisting attempt to navigate the
|
|
<a href="browsers.html#browsing-context">browsing context</a>, and the <a href="#source-browsing-context">source browsing
|
|
context</a> is the same as the <a href="browsers.html#browsing-context">browsing context</a>
|
|
being navigated, and that attempt is currently
|
|
running the <a href="#unload-a-document">unload a document</a> algorithm, and the
|
|
<a href="origin-0.html#origin">origin</a> of the <a href="urls.html#url">URL</a> of the resource being
|
|
loaded in that navigation is not the <a href="origin-0.html#same-origin">same origin</a> as
|
|
the <a href="origin-0.html#origin">origin</a> of the <a href="urls.html#url">URL</a> of the resource
|
|
being loaded in <em>this</em> navigation, then abort these steps
|
|
without affecting the preexisting attempt to navigate the
|
|
<a href="browsers.html#browsing-context">browsing context</a>.</p></li>
|
|
|
|
|
|
<li><p>If a <a href="webappapis.html#concept-task" title="concept-task">task</a> queued by the
|
|
<a href="#traverse-the-history-by-a-delta">traverse the history by a delta</a> algorithm is running
|
|
the <a href="#unload-a-document">unload a document</a> algorithm for the <a href="browsers.html#active-document">active
|
|
document</a> of the <a href="browsers.html#browsing-context">browsing context</a> being
|
|
navigated, then abort these steps without affecting the
|
|
<a href="#unload-a-document">unload a document</a> algorithm or the aforementioned
|
|
history traversal task.</p></li>
|
|
<li><p>If there is a preexisting attempt to navigate the
|
|
<a href="browsers.html#browsing-context">browsing context</a>, and either that attempt has not yet
|
|
<a href="#concept-navigate-mature" title="concept-navigate-mature">matured</a> (i.e. it has
|
|
not passed the point of making its <code><a href="infrastructure.html#document">Document</a></code> the
|
|
<a href="browsers.html#active-document">active document</a>), or that navigation's resource is not
|
|
to be fetched using HTTP GET <a href="fetching-resources.html#concept-http-equivalent-get" title="concept-http-equivalent-get">or equivalent</a>, or its
|
|
resource's <a href="urls.html#absolute-url">absolute URL</a> differs from this attempt's by
|
|
more than the presence, absence, or value of the <a href="urls.html#url-fragment" title="url-fragment"><fragment></a> component, then cancel
|
|
that preexisting attempt to navigate the <a href="browsers.html#browsing-context">browsing
|
|
context</a>.</p></li>
|
|
|
|
<li id="navigate-fragid-step"><p><i>Fragment identifiers</i>: If
|
|
the <a href="urls.html#absolute-url">absolute URL</a> of the new resource is the same as
|
|
the <a href="dom.html#the-document-s-address" title="the document's address">address</a> of the
|
|
<a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing context</a>
|
|
being navigated, ignoring any <a href="urls.html#url-fragment" title="url-fragment"><fragment></a> components of those
|
|
<a href="urls.html#url" title="URL">URLs</a>, and the new resource is to be
|
|
fetched using HTTP GET <a href="fetching-resources.html#concept-http-equivalent-get" title="concept-http-equivalent-get">or
|
|
equivalent</a>, and the <a href="urls.html#absolute-url">absolute URL</a> of the new
|
|
resource has a <a href="urls.html#url-fragment" title="url-fragment"><fragment></a>
|
|
component (even if it is empty), then <a href="#scroll-to-fragid" title="navigate-fragid">navigate to that fragment identifier</a>
|
|
and abort these steps.</p></li>
|
|
|
|
<li><p>Cancel <em>any</em> preexisting attempt to navigate the
|
|
<a href="browsers.html#browsing-context">browsing context</a>.</p></li>
|
|
|
|
<li><p>If the new resource is to be handled using a mechanism that
|
|
does not affect the browsing context, e.g. ignoring the navigation
|
|
request altogether because the specified scheme is not one of the
|
|
supported protocols, then abort these steps and proceed with that
|
|
mechanism instead.</p></li>
|
|
|
|
<li><p><a href="#prompt-to-unload-a-document" title="prompt to unload a document">Prompt to
|
|
unload</a> the <code><a href="infrastructure.html#document">Document</a></code> object. If the user
|
|
<a href="#refused-to-allow-the-document-to-be-unloaded">refused to allow the document to be unloaded</a>, then
|
|
these steps must be aborted.</p></li>
|
|
|
|
<li><p><a href="#abort-a-document" title="abort a document">Abort</a> the
|
|
<a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing
|
|
context</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If the new resource is to be handled by displaying some sort of
|
|
inline content, e.g. an error message because the specified scheme
|
|
is not one of the supported protocols, or an inline prompt to
|
|
allow the user to select <a href="timers.html#dom-navigator-registerprotocolhandler" title="dom-navigator-registerProtocolHandler">a registered
|
|
handler</a> for the given scheme, then <a href="#read-ua-inline" title="navigate-ua-inline">display the inline content</a> and
|
|
abort these steps.</p>
|
|
|
|
<p class="note">In the case of a registered handler being used,
|
|
the algorithm will be reinvoked with a new URL to handle the
|
|
request.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If the resource has already been obtained (e.g. because it is
|
|
being used to populate an <code><a href="the-iframe-element.html#the-object-element">object</a></code> element's new
|
|
<a href="browsers.html#child-browsing-context">child browsing context</a>), then skip this step.</p>
|
|
|
|
<p>Otherwise:</p>
|
|
|
|
<p>If the new resource is to be fetched using HTTP GET <a href="fetching-resources.html#concept-http-equivalent-get" title="concept-http-equivalent-get">or equivalent</a>, and
|
|
there are <a href="offline.html#relevant-application-cache" title="relevant application cache">relevant
|
|
application caches</a> that are identified by a URL with the
|
|
<a href="origin-0.html#same-origin">same origin</a> as the URL in question, and that have
|
|
this URL as one of their entries, excluding entries marked as
|
|
<a href="offline.html#concept-appcache-foreign" title="concept-appcache-foreign">foreign</a>, then get
|
|
the resource from the <a href="offline.html#concept-appcache-selection" title="concept-appcache-selection">most appropriate application
|
|
cache</a> of those that match.</p>
|
|
|
|
<p class="example">For example, imagine an HTML page with an
|
|
associated application cache displaying an image and a form, where
|
|
the image is also used by several other application caches. If the
|
|
user right-clicks on the image and chooses "View Image", then the
|
|
user agent could decide to show the image from any of those
|
|
caches, but it is likely that the most useful cache for the user
|
|
would be the one that was used for the aforementioned HTML
|
|
page. On the other hand, if the user submits the form, and the
|
|
form does a POST submission, then the user agent will not use an
|
|
application cache at all; the submission will be made to the
|
|
network.</p>
|
|
|
|
<p>Otherwise, <a href="fetching-resources.html#fetch">fetch</a> the new resource, with the
|
|
<i>manual redirect flag</i> set.</p>
|
|
|
|
<p>If the resource is being fetched using a method other than one
|
|
<a href="fetching-resources.html#concept-http-equivalent-get" title="concept-http-equivalent-get">equivalent to</a>
|
|
HTTP's GET, or, if the
|
|
<a href="#navigate" title="navigate">navigation algorithm</a> was invoked as
|
|
a result of the <a href="association-of-controls-and-forms.html#concept-form-submit" title="concept-form-submit">form submission
|
|
algorithm</a>, then the <a href="fetching-resources.html#fetch" title="fetch">fetching
|
|
algorithm</a> must be invoked from the <a href="origin-0.html#origin">origin</a> of
|
|
the <a href="browsers.html#active-document">active document</a> of the <a href="#source-browsing-context">source browsing
|
|
context</a>, if any.</p>
|
|
<p>If the <a href="browsers.html#browsing-context">browsing context</a> being navigated is a
|
|
<a href="browsers.html#child-browsing-context">child browsing context</a> for an <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code> or
|
|
<code><a href="the-iframe-element.html#the-object-element">object</a></code> element, then the <a href="fetching-resources.html#fetch" title="fetch">fetching
|
|
algorithm</a> must be invoked from the <code><a href="the-iframe-element.html#the-iframe-element">iframe</a></code> or
|
|
<code><a href="the-iframe-element.html#the-object-element">object</a></code> element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope
|
|
origin</a>, if it has one.</p>
|
|
<p>The <a href="fetching-resources.html#fetch">fetch</a> algorithm must <a href="the-end.html#delay-the-load-event">delay the load
|
|
event</a> of the <a href="browsers.html#browsing-context">browsing context</a>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>At this point, unless this step has already been reached once
|
|
before in the execution of this instance of the algorithm, the
|
|
user agents must return to whatever algorithm invoked the
|
|
navigation steps and must continue these steps asynchronously.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If fetching the resource results in a redirect, and either the
|
|
<a href="urls.html#url">URL</a> of the target of the redirect has the <a href="origin-0.html#same-origin">same
|
|
origin</a> as the original resource, or the resource is being
|
|
obtained using the POST method or a safe method (in HTTP terms),
|
|
return to <a href="#navigate-fragid-step">the step labeled
|
|
"fragment identifiers"</a> with the new resource.</p>
|
|
|
|
<p>Otherwise, if fetching the resource results in a redirect but
|
|
the <a href="urls.html#url">URL</a> of the target of the redirect does not have
|
|
the <a href="origin-0.html#same-origin">same origin</a> as the original resource and the
|
|
resource is being obtained using a method that is neither the POST
|
|
method nor a safe method (in HTTP terms), then abort these
|
|
steps. The user agent may indicate to the user that the navigation
|
|
has been aborted for security reasons.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Wait for one or more bytes to be available or for the user
|
|
agent to establish that the resource in question is empty. During
|
|
this time, the user agent may allow the user to cancel this
|
|
navigation attempt or start other navigation attempts.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If the resource was not fetched from an <a href="offline.html#application-cache">application
|
|
cache</a>, and was to be fetched using HTTP GET <a href="fetching-resources.html#concept-http-equivalent-get" title="concept-http-equivalent-get">or equivalent</a>, and its
|
|
URL <a href="offline.html#concept-appcache-matches-fallback" title="concept-appcache-matches-fallback">matches the
|
|
fallback namespace</a> of one or more <a href="offline.html#relevant-application-cache" title="relevant
|
|
application cache">relevant application caches</a>, and the
|
|
<a href="offline.html#concept-appcache-selection" title="concept-appcache-selection">most appropriate
|
|
application cache</a> of those that match does not have an
|
|
entry in its <a href="offline.html#concept-appcache-onlinewhitelist" title="concept-appcache-onlinewhitelist">online
|
|
whitelist</a> that has the <a href="origin-0.html#same-origin">same origin</a> as the
|
|
resource's URL and that is a <a href="infrastructure.html#prefix-match">prefix match</a> for the
|
|
resource's URL, and the user didn't cancel the navigation attempt
|
|
during the previous step, and the navigation attempt failed (e.g.
|
|
the server returned a 4xx or 5xx status code <a href="fetching-resources.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or equivalent</a>, or
|
|
there was a DNS error), then:</p>
|
|
<p>Let <var title="">candidate</var> be the <a href="offline.html#concept-appcache-fallback" title="concept-appcache-fallback">fallback resource</a>
|
|
specified for the <a href="offline.html#concept-appcache-fallback-ns" title="concept-appcache-fallback-ns">fallback namespace</a> in
|
|
question. If multiple application caches match, the user agent
|
|
must use the fallback of the <a href="offline.html#concept-appcache-selection" title="concept-appcache-selection">most appropriate application
|
|
cache</a> of those that match.</p>
|
|
|
|
<p>If <var title="">candidate</var> is not marked as <a href="offline.html#concept-appcache-foreign" title="concept-appcache-foreign">foreign</a>, then the user
|
|
agent must discard the failed load and instead continue along
|
|
these steps using <var title="">candidate</var> as the
|
|
resource. <a href="dom.html#the-document-s-address">The document's address</a>, if appropriate,
|
|
will still be the originally requested URL, not the fallback URL,
|
|
but the user agent may indicate to the user that the original page
|
|
load failed, that the page used was a fallback resource, and what
|
|
the URL of the fallback resource actually is.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>If the document's out-of-band metadata (e.g. HTTP headers),
|
|
not counting any <a href="fetching-resources.html#content-type" title="Content-Type">type information</a>
|
|
(such as the Content-Type HTTP header), requires some sort of
|
|
processing that will not affect the browsing context, then perform
|
|
that processing and abort these steps.</p>
|
|
|
|
<div class="note">
|
|
<p>Such processing might be triggered by, amongst other things, the
|
|
following:</p>
|
|
<ul class="brief"><li>HTTP status codes (e.g. 204 No Content or 205 Reset Content)</li>
|
|
<li>HTTP Content-Disposition headers</li>
|
|
<li>Network errors</li>
|
|
</ul></div>
|
|
|
|
|
|
<p>HTTP 401 responses that do not include a challenge recognized
|
|
by the user agent must be processed as if they had no challenge,
|
|
e.g. rendering the entity body as if the response had been 200
|
|
OK.</p>
|
|
|
|
<p>User agents may show the entity body of an HTTP 401 response
|
|
even when the response do include a recognized challenge, with the
|
|
option to login being included in a non-modal fashion, to enable
|
|
the information provided by the server to be used by the user
|
|
before authenticating. Similarly, user agents should allow the
|
|
user to authenticate (in a non-modal fashion) against
|
|
authentication challenges included in other responses such as HTTP
|
|
200 OK responses, effectively allowing resources to present HTTP
|
|
login forms without requiring their use.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Let <var title="">type</var> be <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type
|
|
sniffing">the sniffed type of the resource</a>.</p></li>
|
|
|
|
<li><p>If the user agent has been configured to process resources
|
|
of the given <var title="">type</var> using some mechanism other
|
|
than rendering the content in a <a href="browsers.html#browsing-context">browsing context</a>, then
|
|
skip this step. Otherwise, if the <var title="">type</var> is one
|
|
of the following types, jump to the appropriate entry in the
|
|
following list, and process the resource as described there:</p>
|
|
|
|
<dl class="switch"><dt>"<code><a href="iana.html#text-html">text/html</a></code>"</dt>
|
|
<dt>"<code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code>"</dt>
|
|
<dd>Follow the steps given in the <a href="#read-html" title="navigate-html">HTML document</a> section, and abort
|
|
these steps.</dd>
|
|
|
|
|
|
<dt>Any type ending in "<code title="">+xml</code>"</dt>
|
|
<dt>"<code>application/xml</code>"</dt>
|
|
<dt>"<code>text/xml</code>"</dt>
|
|
<dd>Follow the steps given in the <a href="#read-xml" title="navigate-xml">XML
|
|
document</a> section. If that section determines that the
|
|
content is <em>not</em> to be displayed as a generic XML
|
|
document, then proceed to the next step in this overall set of
|
|
steps. Otherwise, abort these steps.</dd>
|
|
|
|
<dt>"<code>text/plain</code>"</dt>
|
|
<dd>Follow the steps given in the <a href="#read-text" title="navigate-text">plain text file</a> section, and abort
|
|
these steps.</dd>
|
|
|
|
<dt>A supported image type</dt>
|
|
<dd>Follow the steps given in the <a href="#read-image" title="navigate-image">image</a> section, and abort these
|
|
steps.</dd>
|
|
|
|
<dt>A type that will use an external application to render the
|
|
content in the <a href="browsers.html#browsing-context">browsing context</a></dt>
|
|
<dd>Follow the steps given in the <a href="#read-plugin" title="navigate-plugin">plugin</a> section, and abort these
|
|
steps.</dd>
|
|
|
|
</dl><p><dfn id="set-the-document-s-address" title="set the document's address">Setting the document's
|
|
address</dfn>: If there is no <dfn id="override-url">override URL</dfn>, then any
|
|
<code><a href="infrastructure.html#document">Document</a></code> created by these steps must have its <a href="dom.html#the-document-s-address" title="the document's address">address</a> set to the
|
|
<a href="urls.html#url">URL</a> that was originally to be <a href="fetching-resources.html#fetch" title="fetch">fetched</a>, ignoring any other data that was
|
|
used to obtain the resource (e.g. the entity body in the case of a
|
|
POST submission is not part of <a href="dom.html#the-document-s-address">the document's
|
|
address</a>, nor is the URL of the fallback resource in the
|
|
case of the original load having failed and that URL having been
|
|
found to match a <a href="offline.html#concept-appcache-fallback-ns" title="concept-appcache-fallback-ns">fallback
|
|
namespace</a>). However, if there <em>is</em> an <a href="#override-url">override
|
|
URL</a>, then any <code><a href="infrastructure.html#document">Document</a></code> created by these steps
|
|
must have its <a href="dom.html#the-document-s-address" title="the document's address">address</a>
|
|
set to that <a href="urls.html#url">URL</a> instead.</p>
|
|
|
|
<p class="note">An <a href="#override-url" title="override URL">override URL</a>
|
|
is set when <a href="webappapis.html#concept-js-deref" title="concept-js-deref">dereferencing a
|
|
<code>javascript:</code> URL</a>.</p>
|
|
|
|
<p><dfn id="create-a-document-object" title="create a Document object">Creating a new
|
|
<code>Document</code> object</dfn>: When a <code><a href="infrastructure.html#document">Document</a></code>
|
|
is created as part of the above steps, a new <code><a href="browsers.html#window">Window</a></code>
|
|
object must be created and associated with the
|
|
<code><a href="infrastructure.html#document">Document</a></code>, with one exception: if the <a href="browsers.html#browsing-context">browsing
|
|
context</a>'s only entry in its <a href="#session-history">session history</a> is
|
|
the <code><a href="fetching-resources.html#about:blank">about:blank</a></code> <code><a href="infrastructure.html#document">Document</a></code> that was added
|
|
when the <a href="browsers.html#browsing-context">browsing context</a> was created, and navigation
|
|
is occurring with <a href="#replacement-enabled">replacement enabled</a>, and that
|
|
<code><a href="infrastructure.html#document">Document</a></code> has the <a href="origin-0.html#same-origin">same origin</a> as the new
|
|
<code><a href="infrastructure.html#document">Document</a></code>, then the <code><a href="browsers.html#window">Window</a></code> object of that
|
|
<code><a href="infrastructure.html#document">Document</a></code> must be used instead, and the <code title="dom-document"><a href="browsers.html#dom-document">document</a></code> attribute of the
|
|
<code><a href="browsers.html#window">Window</a></code> object must be changed to point to the new
|
|
<code><a href="infrastructure.html#document">Document</a></code> instead.</p>
|
|
|
|
</li>
|
|
|
|
<li id="navigate-non-Document">
|
|
|
|
<p><i>Non-document content</i>: If, given <var title="">type</var>, the new resource is to be handled by
|
|
displaying some sort of inline content, e.g. a native rendering of
|
|
the content, an error message because the specified type is not
|
|
supported, or an inline prompt to allow the user to select <a href="timers.html#dom-navigator-registercontenthandler" title="dom-navigator-registerContentHandler">a registered
|
|
handler</a> for the given type, then <a href="#read-ua-inline" title="navigate-ua-inline">display the inline content</a> and
|
|
abort these steps.</p>
|
|
|
|
<p class="note">In the case of a registered handler being used,
|
|
the algorithm will be reinvoked with a new URL to handle the
|
|
request.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Otherwise, the document's <var title="">type</var> is such
|
|
that the resource will not affect the browsing context,
|
|
e.g. because the resource is to be handed to an external
|
|
application. Process the resource appropriately.</p>
|
|
|
|
</li></ol><hr><p>Some of the sections below, to which the above algorithm defers
|
|
in certain cases, require the user agent to <dfn id="update-the-session-history-with-the-new-page">update the session
|
|
history with the new page</dfn>. When a user agent is required to do
|
|
this, it must <a href="webappapis.html#queue-a-task">queue a task</a> (associated with the
|
|
<code><a href="infrastructure.html#document">Document</a></code> object of the <a href="#current-entry">current entry</a>, not
|
|
the new one) to run the following steps:</p>
|
|
|
|
<ol><li><p><a href="#unload-a-document" title="unload a document">Unload</a> the
|
|
<code><a href="infrastructure.html#document">Document</a></code> object of the <a href="#current-entry">current entry</a>,
|
|
with the <var title="">recycle</var> parameter set to
|
|
false.</p></li>
|
|
|
|
<li>
|
|
|
|
<dl><dt>If the navigation was initiated for <dfn id="entry-update">entry update</dfn> of
|
|
an entry</dt>
|
|
|
|
<dd>
|
|
|
|
<ol><li><p>Replace the <code><a href="infrastructure.html#document">Document</a></code> of the entry being
|
|
updated, and any other entries that referenced the same
|
|
document as that entry, with the new
|
|
<code><a href="infrastructure.html#document">Document</a></code>.</p></li>
|
|
|
|
<li><p><a href="#traverse-the-history">Traverse the history</a> to the new
|
|
entry.</p></li>
|
|
|
|
</ol><p class="note">This can only happen if the entry being updated
|
|
is no the <a href="#current-entry">current entry</a>, and can never happen with
|
|
<a href="#replacement-enabled">replacement enabled</a>. (It happens when the user
|
|
tried to traverse to a session history entry that no longer had
|
|
a <code><a href="infrastructure.html#document">Document</a></code> object.)</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd>
|
|
|
|
<ol><li>
|
|
|
|
<p>Remove all the entries in the <a href="browsers.html#browsing-context">browsing
|
|
context</a>'s <a href="#session-history">session history</a> after the
|
|
<a href="#current-entry">current entry</a>. If the <a href="#current-entry">current entry</a>
|
|
is the last entry in the session history, then no entries are
|
|
removed.</p>
|
|
|
|
<p class="note">This <a href="#history-notes">doesn't
|
|
necessarily have to affect</a> the user agent's user
|
|
interface.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Remove any <a href="webappapis.html#concept-task" title="concept-task">tasks</a>
|
|
queued by the <a href="webappapis.html#history-traversal-task-source">history traversal task
|
|
source</a>.</p></li>
|
|
<li><p>Append a new entry at the end of the <code><a href="#history-0">History</a></code>
|
|
object representing the new resource and its
|
|
<code><a href="infrastructure.html#document">Document</a></code> object and related state.</p></li>
|
|
|
|
<li><p><a href="#traverse-the-history">Traverse the history</a> to the new entry. If
|
|
the navigation was initiated with <a href="#replacement-enabled">replacement
|
|
enabled</a>, then the traversal must itself be initiated
|
|
with <a href="#replacement-enabled">replacement enabled</a>.</p>
|
|
|
|
</li>
|
|
|
|
</ol></dd>
|
|
|
|
</dl></li>
|
|
|
|
<li><p>The <a href="#navigate" title="navigate">navigation algorithm</a> has
|
|
now <dfn id="concept-navigate-mature" title="concept-navigate-mature">matured</dfn>.</p></li>
|
|
|
|
<li><p><i>Fragment identifier loop</i>: <a href="webappapis.html#spin-the-event-loop">Spin the event
|
|
loop</a> for a user-agent-defined amount of time, as desired by
|
|
the user agent implementor. (This is intended to allow the user
|
|
agent to optimize the user experience in the face of performance
|
|
concerns.)</p></li>
|
|
|
|
<li><p>If the <code><a href="infrastructure.html#document">Document</a></code> object has no parser, or its
|
|
parser has <a href="the-end.html#stop-parsing" title="stop parsing">stopped parsing</a>, or
|
|
the user agent has reason to believe the user is no longer
|
|
interested in scrolling to the fragment identifier, then abort
|
|
these steps.</p></li>
|
|
|
|
<li><p><a href="#scroll-to-the-fragment-identifier">Scroll to the fragment identifier</a> given in
|
|
<a href="dom.html#the-document-s-current-address">the document's current address</a>. If this fails to find
|
|
<a href="#the-indicated-part-of-the-document" title="the indicated part of the document">an indicated part
|
|
of the document</a>, then return to the <i>fragment identifier
|
|
loop</i> step.</p></li>
|
|
|
|
</ol><p>The <a href="webappapis.html#task-source">task source</a> for this <a href="webappapis.html#concept-task" title="concept-task">task</a> is the <a href="webappapis.html#networking-task-source">networking task
|
|
source</a>.</p>
|
|
|
|
|
|
<h4 id="read-html"><span class="secno">5.5.2 </span><dfn title="navigate-html">Page load processing model for HTML files</dfn></h4>
|
|
|
|
<p>When an HTML document is to be loaded in a <a href="browsers.html#browsing-context">browsing
|
|
context</a>, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
|
|
<a href="#create-a-document-object">create a <code>Document</code> object</a>, mark it as being
|
|
an <a href="dom.html#html-documents" title="HTML documents">HTML document</a>, create an
|
|
<a href="parsing.html#html-parser">HTML parser</a>, and associate it with the document. Each
|
|
<a href="webappapis.html#concept-task" title="concept-task">task</a> that the <a href="webappapis.html#networking-task-source">networking
|
|
task source</a> places on the <a href="webappapis.html#task-queue">task queue</a> while the
|
|
<a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> runs must then fill
|
|
the parser's <a href="parsing.html#the-input-stream">input stream</a> with the fetched bytes and
|
|
cause the <a href="parsing.html#html-parser">HTML parser</a> to perform the appropriate
|
|
processing of the input stream.</p>
|
|
|
|
<p class="note">The <a href="parsing.html#the-input-stream">input stream</a> converts bytes into
|
|
characters for use in the <a href="tokenization.html#tokenization" title="tokenization">tokenizer</a>. This process relies, in part,
|
|
on character encoding information found in the real <a href="fetching-resources.html#content-type" title="Content-Type">Content-Type metadata</a> of the resource;
|
|
the "sniffed type" is not used for this purpose.</p>
|
|
|
|
|
|
<p>When no more bytes are available, the user agent must <a href="webappapis.html#queue-a-task">queue
|
|
a task</a> for the parser to process the implied EOF character,
|
|
which eventually causes a <code title="event-load">load</code> event
|
|
to be fired.</p>
|
|
|
|
<p>After creating the <code><a href="infrastructure.html#document">Document</a></code> object, but before any
|
|
script execution, certainly before the parser <a href="the-end.html#stop-parsing" title="stop
|
|
parsing">stops</a>, the user agent must <a href="#update-the-session-history-with-the-new-page">update the session
|
|
history with the new page</a>.</p>
|
|
|
|
<p class="note"><a href="offline.html#concept-appcache-init" title="concept-appcache-init">Application
|
|
cache selection</a> happens <a href="tree-construction.html#parser-appcache">in the
|
|
HTML parser</a>.</p>
|
|
|
|
<p>The <a href="webappapis.html#task-source">task source</a> for the two tasks mentioned in this
|
|
section must be the <a href="webappapis.html#networking-task-source">networking task source</a>.</p>
|
|
|
|
|
|
|
|
<h4 id="read-xml"><span class="secno">5.5.3 </span><dfn title="navigate-xml">Page load processing model for XML files</dfn></h4>
|
|
|
|
<p>When faced with displaying an XML file inline, user agents must
|
|
first <a href="#create-a-document-object">create a <code>Document</code> object</a>, following
|
|
the requirements of the XML and Namespaces in XML recommendations,
|
|
RFC 3023, DOM3 Core, and other relevant specifications. <a href="references.html#refsXML">[XML]</a> <a href="references.html#refsXMLNS">[XMLNS]</a> <a href="references.html#refsRFC3023">[RFC3023]</a> <a href="references.html#refsDOMCORE">[DOMCORE]</a></p>
|
|
|
|
<p>The actual HTTP headers and other metadata, not the headers as
|
|
mutated or implied by the algorithms given in this specification,
|
|
are the ones that must be used when determining the character
|
|
encoding according to the rules given in the above
|
|
specifications. Once the character encoding is established, the
|
|
<a href="dom.html#document-s-character-encoding">document's character encoding</a> must be set to that
|
|
character encoding.</p>
|
|
|
|
<p>If the root element, as parsed according to the XML
|
|
specifications cited above, is found to be an <code><a href="semantics.html#the-html-element">html</a></code>
|
|
element with an attribute <code title="attr-html-manifest"><a href="semantics.html#attr-html-manifest">manifest</a></code> whose value is not the
|
|
empty string, then, as soon as the element is <a href="infrastructure.html#insert-an-element-into-a-document" title="insert an
|
|
element into a document">inserted into the document</a>, the user
|
|
agent must <a href="urls.html#resolve-a-url" title="resolve a url">resolve</a> the value of
|
|
that attribute relative to that element, and if that is successful,
|
|
must run the <a href="offline.html#concept-appcache-init" title="concept-appcache-init">application cache
|
|
selection algorithm</a> with the resulting <a href="urls.html#absolute-url">absolute
|
|
URL</a> with any <a href="urls.html#url-fragment" title="url-fragment"><fragment></a> component removed as
|
|
the manifest URL, and passing in the newly-created
|
|
<code><a href="infrastructure.html#document">Document</a></code>. Otherwise, if the attribute is absent, its
|
|
value is the empty string, or resolving its value fails, then as
|
|
soon as the root element is <a href="infrastructure.html#insert-an-element-into-a-document" title="insert an element into a
|
|
document">inserted into the document</a>, the user agent must run
|
|
the <a href="offline.html#concept-appcache-init" title="concept-appcache-init">application cache selection
|
|
algorithm</a> with no manifest, and passing in the
|
|
<code><a href="infrastructure.html#document">Document</a></code>.</p>
|
|
|
|
<p class="note">Because the processing of the <code title="attr-html-manifest"><a href="semantics.html#attr-html-manifest">manifest</a></code> attribute happens
|
|
only once the root element is parsed, any URLs referenced by
|
|
processing instructions before the root element (such as <code title=""><?xml-stylesheet?></code> and <code title=""><?xbl?></code> PIs) will be fetched from the network and
|
|
cannot be cached.</p>
|
|
|
|
<p>User agents may examine the namespace of the root
|
|
<code><a href="infrastructure.html#element">Element</a></code> node of this <code><a href="infrastructure.html#document">Document</a></code> object to
|
|
perform namespace-based dispatch to alternative processing tools,
|
|
e.g. determining that the content is actually a syndication feed and
|
|
passing it to a feed handler. If such processing is to take place,
|
|
abort the steps in this section, and jump to <a href="#navigate-non-Document">the next step</a> (labeled
|
|
"non-document content") in the <a href="#navigate">navigate</a> steps
|
|
above.</p>
|
|
|
|
<p>Otherwise, then, with the newly created <code><a href="infrastructure.html#document">Document</a></code>,
|
|
the user agents must <a href="#update-the-session-history-with-the-new-page">update the session history with the new
|
|
page</a>. User agents may do this before the complete document
|
|
has been parsed (thus achieving <i>incremental rendering</i>), and
|
|
must do this before any scripts are to be executed.</p>
|
|
|
|
<p>Error messages from the parse process (e.g. XML namespace
|
|
well-formedness errors) may be reported inline by mutating the
|
|
<code><a href="infrastructure.html#document">Document</a></code>.</p>
|
|
|
|
|
|
<h4 id="read-text"><span class="secno">5.5.4 </span><dfn title="navigate-text">Page load processing model for text files</dfn></h4>
|
|
|
|
<p>When a plain text document is to be loaded in a <a href="browsers.html#browsing-context">browsing
|
|
context</a>, the user agent should <a href="webappapis.html#queue-a-task">queue a task</a> to
|
|
<a href="#create-a-document-object">create a <code>Document</code> object</a>, mark it as being
|
|
an <a href="dom.html#html-documents" title="HTML documents">HTML document</a>, create an
|
|
<a href="parsing.html#html-parser">HTML parser</a>, associate it with the document, act as if
|
|
the tokenizer had emitted a start tag token with the tag name "pre"
|
|
followed by a single U+000A LINE FEED (LF) character, and switch the <a href="parsing.html#html-parser">HTML parser</a>'s tokenizer
|
|
to the <a href="tokenization.html#plaintext-state">PLAINTEXT state</a>. Each <a href="webappapis.html#concept-task" title="concept-task">task</a> that the <a href="webappapis.html#networking-task-source">networking task
|
|
source</a> places on the <a href="webappapis.html#task-queue">task queue</a> while the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> runs must then fill the
|
|
parser's <a href="parsing.html#the-input-stream">input stream</a> with the fetched bytes and cause
|
|
the <a href="parsing.html#html-parser">HTML parser</a> to perform the appropriate processing
|
|
of the input stream.</p>
|
|
|
|
<p>The rules for how to convert the bytes of the plain text document
|
|
into actual characters, and the rules for actually rendering the
|
|
text to the user, are defined in RFC 2046, RFC 3676, and subsequent
|
|
versions thereof. <a href="references.html#refsRFC2046">[RFC2046]</a> <a href="references.html#refsRFC3676">[RFC3676]</a></p>
|
|
|
|
<p>The <a href="dom.html#document-s-character-encoding">document's character encoding</a> must be set to the
|
|
character encoding used to decode the document.</p>
|
|
|
|
<p>Upon creation of the <code><a href="infrastructure.html#document">Document</a></code> object, the user agent
|
|
must run the <a href="offline.html#concept-appcache-init" title="concept-appcache-init">application cache
|
|
selection algorithm</a> with no manifest, and passing in the
|
|
newly-created <code><a href="infrastructure.html#document">Document</a></code>.</p>
|
|
|
|
|
|
<p>When no more bytes are available, the user agent must <a href="webappapis.html#queue-a-task">queue
|
|
a task</a> for the parser to process the implied EOF character,
|
|
which eventually causes a <code title="event-load">load</code> event
|
|
to be fired.</p>
|
|
|
|
<p>After creating the <code><a href="infrastructure.html#document">Document</a></code> object, but potentially
|
|
before the page has finished parsing, the user agent must
|
|
<a href="#update-the-session-history-with-the-new-page">update the session history with the new page</a>.</p>
|
|
|
|
<p>User agents may add content to the <code><a href="semantics.html#the-head-element">head</a></code> element of
|
|
the <code><a href="infrastructure.html#document">Document</a></code>, e.g. linking to a style sheet or an XBL
|
|
binding, providing script, giving the document a <code><a href="semantics.html#the-title-element">title</a></code>,
|
|
etc.</p>
|
|
|
|
<p class="note">In particular, if the user agent supports the <code title="">Format=Flowed</code> feature of RFC 3676 then the user
|
|
agent would need to apply extra styling to cause the text to wrap
|
|
correctly and to handle the quoting feature. This could be performed
|
|
using, e.g., an XBL binding or a CSS extension.</p>
|
|
|
|
<p>The <a href="webappapis.html#task-source">task source</a> for the two tasks mentioned in this
|
|
section must be the <a href="webappapis.html#networking-task-source">networking task source</a>.</p>
|
|
|
|
|
|
<h4 id="read-image"><span class="secno">5.5.5 </span><dfn title="navigate-image">Page load processing model for images</dfn></h4>
|
|
|
|
<p>When an image resource is to be loaded in a <a href="browsers.html#browsing-context">browsing
|
|
context</a>, the user agent should <a href="#create-a-document-object">create a
|
|
<code>Document</code> object</a>, mark it as being an <a href="dom.html#html-documents" title="HTML documents">HTML document</a>, append an
|
|
<code><a href="semantics.html#the-html-element">html</a></code> element to the <code><a href="infrastructure.html#document">Document</a></code>, append a
|
|
<code><a href="semantics.html#the-head-element">head</a></code> element and a <code><a href="sections.html#the-body-element">body</a></code> element to the
|
|
<code><a href="semantics.html#the-html-element">html</a></code> element, append an <code><a href="embedded-content-1.html#the-img-element">img</a></code> to the
|
|
<code><a href="sections.html#the-body-element">body</a></code> element, and set the <code title="attr-img-src"><a href="embedded-content-1.html#attr-img-src">src</a></code> attribute of the <code><a href="embedded-content-1.html#the-img-element">img</a></code>
|
|
element to the address of the image.</p>
|
|
|
|
|
|
<p>Then, the user agent must act as if it had <a href="the-end.html#stop-parsing" title="stop
|
|
parsing">stopped parsing</a>.</p>
|
|
|
|
<p>Upon creation of the <code><a href="infrastructure.html#document">Document</a></code> object, the user agent
|
|
must run the <a href="offline.html#concept-appcache-init" title="concept-appcache-init">application cache
|
|
selection algorithm</a> with no manifest, and passing in the
|
|
newly-created <code><a href="infrastructure.html#document">Document</a></code>.</p>
|
|
|
|
<p>After creating the <code><a href="infrastructure.html#document">Document</a></code> object, but potentially
|
|
before the page has finished fully loading, the user agent must
|
|
<a href="#update-the-session-history-with-the-new-page">update the session history with the new page</a>.</p>
|
|
|
|
<p>User agents may add content to the <code><a href="semantics.html#the-head-element">head</a></code> element of
|
|
the <code><a href="infrastructure.html#document">Document</a></code>, or attributes to the <code><a href="embedded-content-1.html#the-img-element">img</a></code>
|
|
element, e.g. to link to a style sheet or an XBL binding, to provide
|
|
a script, to give the document a <code><a href="semantics.html#the-title-element">title</a></code>, etc.</p>
|
|
|
|
|
|
<h4 id="read-plugin"><span class="secno">5.5.6 </span><dfn title="navigate-plugin">Page load processing model for content that uses plugins</dfn></h4>
|
|
|
|
<p>When a resource that requires an external resource to be rendered
|
|
is to be loaded in a <a href="browsers.html#browsing-context">browsing context</a>, the user agent
|
|
should <a href="#create-a-document-object">create a <code>Document</code> object</a>, mark it
|
|
as being an <a href="dom.html#html-documents" title="HTML documents">HTML document</a>,
|
|
append an <code><a href="semantics.html#the-html-element">html</a></code> element to the <code><a href="infrastructure.html#document">Document</a></code>,
|
|
append a <code><a href="semantics.html#the-head-element">head</a></code> element and a <code><a href="sections.html#the-body-element">body</a></code> element
|
|
to the <code><a href="semantics.html#the-html-element">html</a></code> element, append an <code><a href="the-iframe-element.html#the-embed-element">embed</a></code> to
|
|
the <code><a href="sections.html#the-body-element">body</a></code> element, and set the <code title="attr-embed-src"><a href="the-iframe-element.html#attr-embed-src">src</a></code> attribute of the
|
|
<code><a href="the-iframe-element.html#the-embed-element">embed</a></code> element to the address of the resource.</p>
|
|
|
|
|
|
<p>Then, the user agent must act as if it had <a href="the-end.html#stop-parsing" title="stop
|
|
parsing">stopped parsing</a>.</p>
|
|
|
|
<p>Upon creation of the <code><a href="infrastructure.html#document">Document</a></code> object, the user agent
|
|
must run the <a href="offline.html#concept-appcache-init" title="concept-appcache-init">application cache
|
|
selection algorithm</a> with no manifest, and passing in the
|
|
newly-created <code><a href="infrastructure.html#document">Document</a></code>.</p>
|
|
|
|
<p>After creating the <code><a href="infrastructure.html#document">Document</a></code> object, but potentially
|
|
before the page has finished fully loading, the user agent must
|
|
<a href="#update-the-session-history-with-the-new-page">update the session history with the new page</a>.</p>
|
|
|
|
<p>User agents may add content to the <code><a href="semantics.html#the-head-element">head</a></code> element of
|
|
the <code><a href="infrastructure.html#document">Document</a></code>, or attributes to the <code><a href="the-iframe-element.html#the-embed-element">embed</a></code>
|
|
element, e.g. to link to a style sheet or an XBL binding, or to give
|
|
the document a <code><a href="semantics.html#the-title-element">title</a></code>.</p>
|
|
|
|
<p class="note" id="sandboxPluginNavigate">If the <a href="the-iframe-element.html#sandboxed-plugins-browsing-context-flag">sandboxed
|
|
plugins browsing context flag</a> was set on the <a href="browsers.html#browsing-context">browsing
|
|
context</a> when the <code><a href="infrastructure.html#document">Document</a></code> was created, the
|
|
synthesized <code><a href="the-iframe-element.html#the-embed-element">embed</a></code> element will <a href="the-iframe-element.html#sandboxPluginEmbed">fail to render the content</a>.</p>
|
|
|
|
|
|
<h4 id="read-ua-inline"><span class="secno">5.5.7 </span><dfn title="navigate-ua-inline">Page load processing model for inline content that doesn't have a DOM</dfn></h4>
|
|
|
|
<p>When the user agent is to display a user agent page inline in a
|
|
<a href="browsers.html#browsing-context">browsing context</a>, the user agent should <a href="#create-a-document-object">create a
|
|
<code>Document</code> object</a>, mark it as being an <a href="dom.html#html-documents" title="HTML documents">HTML document</a>, and then either
|
|
associate that <code><a href="infrastructure.html#document">Document</a></code> with a custom rendering that is
|
|
not rendered using the normal <code><a href="infrastructure.html#document">Document</a></code> rendering rules,
|
|
or mutate that <code><a href="infrastructure.html#document">Document</a></code> until it represents the content
|
|
the user agent wants to render.</p>
|
|
|
|
|
|
<p>Once the page has been set up, the user agent must act as if it
|
|
had <a href="the-end.html#stop-parsing" title="stop parsing">stopped parsing</a>.</p>
|
|
|
|
<p>Upon creation of the <code><a href="infrastructure.html#document">Document</a></code> object, the user agent
|
|
must run the <a href="offline.html#concept-appcache-init" title="concept-appcache-init">application cache
|
|
selection algorithm</a> with no manifest, passing in the
|
|
newly-created <code><a href="infrastructure.html#document">Document</a></code>.</p>
|
|
|
|
<p>After creating the <code><a href="infrastructure.html#document">Document</a></code> object, but potentially
|
|
before the page has been completely set up, the user agent must
|
|
<a href="#update-the-session-history-with-the-new-page">update the session history with the new page</a>.</p>
|
|
|
|
|
|
|
|
<h4 id="scroll-to-fragid"><span class="secno">5.5.8 </span><dfn title="navigate-fragid">Navigating to a fragment identifier</dfn></h4>
|
|
|
|
<p>When a user agent is supposed to navigate to a fragment
|
|
identifier, then the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
|
|
run the following steps:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>Remove all the entries in the <a href="browsers.html#browsing-context">browsing context</a>'s
|
|
<a href="#session-history">session history</a> after the <a href="#current-entry">current
|
|
entry</a>. If the <a href="#current-entry">current entry</a> is the last entry
|
|
in the session history, then no entries are removed.</p>
|
|
|
|
<p class="note">This <a href="#history-notes">doesn't necessarily
|
|
have to affect</a> the user agent's user interface.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Remove any <a href="webappapis.html#concept-task" title="concept-task">tasks</a> queued by
|
|
the <a href="webappapis.html#history-traversal-task-source">history traversal task source</a>.</p></li>
|
|
|
|
<li><p>Append a new entry at the end of the <code><a href="#history-0">History</a></code>
|
|
object representing the new resource and its <code><a href="infrastructure.html#document">Document</a></code>
|
|
object and related state. Its <a href="urls.html#url">URL</a> must be set to the
|
|
address to which the user agent was <a href="#navigate" title="navigate">navigating</a>. The title must be left
|
|
unset.</p></li>
|
|
|
|
<li><p><a href="#traverse-the-history">Traverse the history</a> to the new entry. This
|
|
will <a href="#scroll-to-the-fragment-identifier">scroll to the fragment identifier</a> given in what
|
|
is now <a href="dom.html#the-document-s-current-address">the document's current address</a>.</p></li>
|
|
|
|
</ol><p class="note">If the scrolling fails because the relevant <a href="elements.html#concept-id" title="concept-id">ID</a> has
|
|
not yet been parsed, then the original <a href="#navigate" title="navigate">navigation</a> algorithm will take care of the
|
|
scrolling instead, as the last few steps of its <a href="#update-the-session-history-with-the-new-page">update the
|
|
session history with the new page</a> algorithm.</p>
|
|
|
|
<hr><p>When the user agent is required to <dfn id="scroll-to-the-fragment-identifier">scroll to the fragment
|
|
identifier</dfn>, it must change the scrolling position of the
|
|
document using the <span>scroll an element into view</span>
|
|
algorithm defined in the CSSOM View specification, or perform some
|
|
other action, such that <a href="#the-indicated-part-of-the-document">the indicated part of the
|
|
document</a> is brought to the user's attention. If there is no
|
|
indicated part, then the user agent must not scroll anywhere. <a href="references.html#refsCSSOMVIEW">[CSSOMVIEW]</a></p>
|
|
|
|
<p><dfn id="the-indicated-part-of-the-document">The indicated part of the document</dfn> is the one that the
|
|
fragment identifier, if any, identifies. The semantics of the
|
|
fragment identifier in terms of mapping it to a specific DOM Node is
|
|
defined by the specification that defines the <a href="infrastructure.html#mime-type">MIME type</a>
|
|
used by the <code><a href="infrastructure.html#document">Document</a></code> (for example, the processing of
|
|
fragment identifiers for <a href="infrastructure.html#xml-mime-type" title="XML MIME type">XML MIME
|
|
types</a> is the responsibility of RFC3023). <a href="references.html#refsRFC3023">[RFC3023]</a></p>
|
|
|
|
<p>For HTML documents (and <a href="infrastructure.html#html-mime-type" title="HTML MIME type">HTML MIME
|
|
types</a>), the following processing model must be followed to
|
|
determine what <a href="#the-indicated-part-of-the-document">the indicated part of the document</a>
|
|
is.</p>
|
|
|
|
<ol><li><p><a href="urls.html#parse-a-url" title="parse a url">Parse</a> the <a href="urls.html#url">URL</a>,
|
|
and let <var title="">fragid</var> be the <a href="urls.html#url-fragment" title="url-fragment"><fragment></a> component of the
|
|
URL.</p></li>
|
|
<li><p>If <var title="">fragid</var> is the empty string, then
|
|
<a href="#the-indicated-part-of-the-document">the indicated part of the document</a> is the top of the
|
|
document; stop the algorithm here.</p></li>
|
|
|
|
<li><p>Let <var title="">decoded fragid</var> be the result of
|
|
expanding any sequences of percent-encoded octets in <var title="">fragid</var> that are valid UTF-8 sequences into Unicode
|
|
characters as defined by UTF-8. If any percent-encoded octets in
|
|
that string are not valid UTF-8 sequences, then skip this step and
|
|
the next one.</p>
|
|
|
|
</li><li><p>If this step was not skipped and there is an element in the
|
|
DOM that has an <a href="elements.html#concept-id" title="concept-id">ID</a> exactly equal to <var title="">decoded
|
|
fragid</var>, then the first such element in tree order is
|
|
<a href="#the-indicated-part-of-the-document">the indicated part of the document</a>; stop the algorithm
|
|
here.</p></li>
|
|
|
|
<li><p>If there is an <code><a href="text-level-semantics.html#the-a-element">a</a></code> element in the DOM that has a
|
|
<code title="attr-a-name"><a href="obsolete.html#attr-a-name">name</a></code> attribute whose value is
|
|
exactly equal to <var title="">fragid</var> (<em>not</em> <var title="">decoded fragid</var>), then the first such element in tree
|
|
order is <a href="#the-indicated-part-of-the-document">the indicated part of the document</a>; stop the
|
|
algorithm here.</p></li>
|
|
|
|
<li><p>If <var title="">fragid</var> is an <a href="infrastructure.html#ascii-case-insensitive">ASCII
|
|
case-insensitive</a> match for the string <code title="">top</code>, then <a href="#the-indicated-part-of-the-document">the indicated part of the
|
|
document</a> is the top of the document; stop the algorithm
|
|
here.</p></li>
|
|
|
|
<li><p>Otherwise, there is no <a href="#the-indicated-part-of-the-document" title="the indicated part of
|
|
the document">indicated part of the document</a>.</p></li>
|
|
|
|
</ol><p>For the purposes of the interaction of HTML with Selectors' <code title="selector-target">:target</code> pseudo-class, the
|
|
<dfn id="target-element"><i>target element</i></dfn> is <a href="#the-indicated-part-of-the-document">the indicated part of the
|
|
document</a>, if that is an element; otherwise there is no
|
|
<i><a href="#target-element">target element</a></i>. <a href="references.html#refsSELECTORS">[SELECTORS]</a></p>
|
|
|
|
</div><h4 id="history-traversal"><span class="secno">5.5.9 </span>History traversal</h4><div class="impl">
|
|
|
|
<p>When a user agent is required to <dfn id="traverse-the-history">traverse the history</dfn>
|
|
to a <i>specified entry</i>, optionally with <a href="#replacement-enabled">replacement
|
|
enabled</a>, the user agent must act as follows.</p>
|
|
|
|
<p class="note">This algorithm is not just invoked when <a href="#traverse-the-history-by-a-delta" title="traverse the history by a delta">explicitly going back or
|
|
forwards in the session history</a> — it is also invoked in
|
|
other situations, for example when <a href="#navigate" title="navigate">navigating
|
|
a browsing context</a>, as part of <a href="#update-the-session-history-with-the-new-page" title="update the session
|
|
history with the new page">updating the session history with the new
|
|
page</a>.</p>
|
|
|
|
<ol><li><p>If there is no longer a <code><a href="infrastructure.html#document">Document</a></code> object for the
|
|
entry in question, the user agent must
|
|
<a href="#navigate">navigate</a>
|
|
the browsing context to the location for that entry to perform an
|
|
<a href="#entry-update">entry update</a> of that entry, and abort these steps. The
|
|
"<a href="#navigate">navigate</a>" algorithm reinvokes this "traverse"
|
|
algorithm to complete the traversal, at which point there
|
|
<em>is</em> a <code><a href="infrastructure.html#document">Document</a></code> object and so this step gets
|
|
skipped. The navigation must be done using the same <a href="#source-browsing-context">source
|
|
browsing context</a> as was used the first time this entry was
|
|
created. (This can never happen with <a href="#replacement-enabled">replacement
|
|
enabled</a>.)</p></li>
|
|
|
|
<li><p>If the <a href="#current-entry">current entry</a>'s title was not set by the
|
|
<code title="dom-history-pushState"><a href="#dom-history-pushstate">pushState()</a></code> or <code title="dom-history-replaceState"><a href="#dom-history-replacestate">replaceState()</a></code> methods,
|
|
then set its title to the value returned by the <code title="dom-document-title"><a href="dom.html#document.title">document.title</a></code> IDL
|
|
attribute.</p></li>
|
|
|
|
<li><p>If appropriate, update the <a href="#current-entry">current entry</a> in the
|
|
<a href="browsers.html#browsing-context">browsing context</a>'s <code><a href="infrastructure.html#document">Document</a></code> object's
|
|
<code><a href="#history-0">History</a></code> object to reflect any state that the user
|
|
agent wishes to persist. The entry is then said to be <a href="#an-entry-with-persisted-user-state">an
|
|
entry with persisted user state</a>.</p></li>
|
|
|
|
<li><p>If the <i>specified entry</i> has a different
|
|
<code><a href="infrastructure.html#document">Document</a></code> object than the <a href="#current-entry">current entry</a>
|
|
then the user agent must run the following substeps:</p>
|
|
|
|
<ol><li>If the browsing context is a <a href="browsers.html#top-level-browsing-context">top-level browsing
|
|
context</a>, but not an <a href="browsers.html#auxiliary-browsing-context">auxiliary browsing
|
|
context</a>, and the <a href="origin-0.html#origin">origin</a> of the
|
|
<code><a href="infrastructure.html#document">Document</a></code> of the <i>specified entry</i> is not the
|
|
<a href="origin-0.html#same-origin" title="same origin">same</a> as the <a href="origin-0.html#origin">origin</a>
|
|
of the <code><a href="infrastructure.html#document">Document</a></code> of the <a href="#current-entry">current entry</a>,
|
|
then the following sub-sub-steps must be run:
|
|
|
|
<ol><li>The current <a href="browsers.html#browsing-context-name">browsing context name</a> must be
|
|
stored with all the entries in the history that are associated
|
|
with <code><a href="infrastructure.html#document">Document</a></code> objects with the <a href="origin-0.html#same-origin">same
|
|
origin</a> as the <a href="browsers.html#active-document">active document</a> <em>and</em>
|
|
that are contiguous with the <a href="#current-entry">current entry</a>.</li>
|
|
|
|
<li id="resetBCName">The browsing context's <a href="browsers.html#browsing-context-name">browsing
|
|
context name</a> must be unset.</li>
|
|
|
|
</ol></li>
|
|
|
|
<li id="appcache-history-2">The user agent must make the
|
|
<i>specified entry</i>'s <code><a href="infrastructure.html#document">Document</a></code> object the
|
|
<a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing
|
|
context</a>.</li>
|
|
|
|
<li>If the <i>specified entry</i> has a <a href="browsers.html#browsing-context-name">browsing
|
|
context name</a> stored with it, then the following
|
|
sub-sub-steps must be run:
|
|
|
|
<ol><li>The browsing context's <a href="browsers.html#browsing-context-name">browsing context name</a>
|
|
must be set to the name stored with the specified entry.</li>
|
|
|
|
<li>Any <a href="browsers.html#browsing-context-name">browsing context name</a> stored with the
|
|
entries in the history that are associated with
|
|
<code><a href="infrastructure.html#document">Document</a></code> objects with the <a href="origin-0.html#same-origin">same origin</a>
|
|
as the new <a href="browsers.html#active-document">active document</a>, and that are
|
|
contiguous with the specified entry, must be cleared.</li>
|
|
|
|
</ol></li>
|
|
|
|
<li id="history-autocomplete"><p>If the <i>specified entry</i>'s
|
|
<code><a href="infrastructure.html#document">Document</a></code> has any <code><a href="the-input-element.html#the-input-element">input</a></code> elements whose
|
|
<a href="common-input-element-attributes.html#resulting-autocompletion-state">resulting autocompletion state</a> is <i title="">off</i>, invoke the <a href="association-of-controls-and-forms.html#concept-form-reset-control" title="concept-form-reset-control">reset algorithm</a> of each
|
|
of those elements.</p></li>
|
|
|
|
<li><p>If the <a href="dom.html#current-document-readiness">current document readiness</a> of the
|
|
<i>specified entry</i>'s <code><a href="infrastructure.html#document">Document</a></code> is "complete",
|
|
<a href="webappapis.html#queue-a-task">queue a task</a> to fire a <code title="event-pageshow"><a href="#event-pageshow">pageshow</a></code> event at the
|
|
<code><a href="browsers.html#window">Window</a></code> object of that <code><a href="infrastructure.html#document">Document</a></code>, but
|
|
with its <code title="dom-event-target"><a href="infrastructure.html#dom-event-target">target</a></code> set to the
|
|
<code><a href="infrastructure.html#document">Document</a></code> object (and the <code title="dom-event-currentTarget">currentTarget</code> set to the
|
|
<code><a href="browsers.html#window">Window</a></code> object), using the
|
|
<code><a href="#pagetransitionevent">PageTransitionEvent</a></code> interface, with the <code title="dom-PageTransitionEvent-persisted"><a href="#dom-pagetransitionevent-persisted">persisted</a></code>
|
|
attribute set to true. This event must not bubble, must not be
|
|
cancelable, and has no default action.</p></li>
|
|
|
|
|
|
</ol></li>
|
|
|
|
<li><p>Set <a href="dom.html#the-document-s-current-address">the document's current address</a> to the URL
|
|
of the <i>specified entry</i>.</p></li>
|
|
|
|
<li><p>If the <i>specified entry</i> has a URL whose fragment
|
|
identifier differs from that of the <a href="#current-entry">current entry</a>'s
|
|
when compared in a <a href="infrastructure.html#case-sensitive">case-sensitive</a> manner, and the two
|
|
share the same <code><a href="infrastructure.html#document">Document</a></code> object, then let <var title="">hash changed</var> be true, and let <var title="">old
|
|
URL</var> be the URL of the <a href="#current-entry">current entry</a> and <var title="">new URL</var> be the URL of the <i>specified entry</i>.
|
|
Otherwise, let <var title="">hash changed</var> be false.</p></li>
|
|
|
|
<li><p>If the traversal was initiated with <dfn id="replacement-enabled">replacement
|
|
enabled</dfn>, remove the entry immediately before the
|
|
<var title="">specified entry</var> in the session history.</p>
|
|
|
|
</li><li><p>If the <i>specified entry</i> is not <a href="#an-entry-with-persisted-user-state">an entry with
|
|
persisted user state</a>, but its URL has a fragment identifier,
|
|
<a href="#scroll-to-the-fragment-identifier">scroll to the fragment identifier</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If the entry is <a href="#an-entry-with-persisted-user-state">an entry with persisted user
|
|
state</a>, the user agent may update aspects of the document
|
|
and its rendering, for instance the scroll position or values of
|
|
form fields, that it had previously recorded.</p>
|
|
|
|
|
|
<p class="note">This can even include updating the <code title="attr-dir"><a href="elements.html#the-dir-attribute">dir</a></code> attribute of <code><a href="the-button-element.html#the-textarea-element">textarea</a></code>
|
|
elements or <code><a href="the-input-element.html#the-input-element">input</a></code> elements whose <code title="attr-input-type"><a href="the-input-element.html#attr-input-type">type</a></code> attribute is in either the
|
|
<a href="states-of-the-type-attribute.html#text-state-and-search-state" title="attr-input-type-text">Text</a> state or the <a href="states-of-the-type-attribute.html#text-state-and-search-state" title="attr-input-type-search">Search</a> state, if the
|
|
persisted state includes the directionality of user input in such
|
|
controls.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>If the entry is a <a href="#state-object">state object</a> entry, let <var title="">state</var> be a <a href="common-dom-interfaces.html#structured-clone">structured clone</a> of that
|
|
state object. Otherwise, let <var title="">state</var> be
|
|
null.</p></li>
|
|
|
|
<li><p>Set <code title="dom-history-state"><a href="#dom-history-state">history.state</a></code> to <var title="">state</var>.</p></li>
|
|
|
|
<li><p>Fire a <code title="event-popstate"><a href="#event-popstate">popstate</a></code> event at
|
|
the <code><a href="browsers.html#window">Window</a></code> object of the <code><a href="infrastructure.html#document">Document</a></code>, using
|
|
the <code><a href="#popstateevent">PopStateEvent</a></code> interface, with the <code title="dom-PopStateEvent-state"><a href="#dom-popstateevent-state">state</a></code> attribute set to the
|
|
value of <var title="">state</var>. This event must bubble but not
|
|
be cancelable and has no default action.</p></li>
|
|
|
|
<li><p>If <var title="">hash changed</var> is true, then fire a
|
|
<code title="event-hashchange"><a href="#event-hashchange">hashchange</a></code> event at the
|
|
<a href="browsers.html#browsing-context">browsing context</a>'s <code><a href="browsers.html#window">Window</a></code> object, using
|
|
the <code><a href="#hashchangeevent">HashChangeEvent</a></code> interface, with the <code title="dom-HashChangeEvent-oldURL"><a href="#dom-hashchangeevent-oldurl">oldURL</a></code> attribute set to
|
|
<var title="">old URL</var> and the <code title="dom-HashChangeEvent-newURL"><a href="#dom-hashchangeevent-newurl">newURL</a></code> attribute set to
|
|
<var title="">new URL</var>. This event must bubble but not be
|
|
cancelable and has no default action.</p></li>
|
|
|
|
<li><p>The <a href="#current-entry">current entry</a> is now the <i>specified
|
|
entry</i>.</p></li>
|
|
|
|
</ol><p>The <a href="webappapis.html#task-source">task source</a> for the tasks mentioned above is the
|
|
<a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
|
|
|
|
|
|
<h5 id="event-definitions"><span class="secno">5.5.9.1 </span>Event definitions</h5>
|
|
|
|
</div><p>The <dfn id="event-popstate" title="event-popstate"><code>popstate</code></dfn> event
|
|
is fired in certain cases when navigating to a <a href="#session-history-entry">session history
|
|
entry</a>.</p><pre class="idl">interface <dfn id="popstateevent">PopStateEvent</dfn> : <a href="infrastructure.html#event">Event</a> {
|
|
readonly attribute any <a href="#dom-popstateevent-state" title="dom-PopStateEvent-state">state</a>;
|
|
void <a href="#dom-popstateevent-initpopstateevent" title="dom-PopStateEvent-initPopStateEvent">initPopStateEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in any stateArg);
|
|
};</pre><dl class="domintro"><dt><var title="">event</var> . <code title="dom-PopStateEvent-state"><a href="#dom-popstateevent-state">state</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a copy of the information that was provided to <code title="dom-history-pushState"><a href="#dom-history-pushstate">pushState()</a></code> or <code title="dom-history-replaceState"><a href="#dom-history-replacestate">replaceState()</a></code>.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-popstateevent-initpopstateevent" title="dom-PopStateEvent-initPopStateEvent"><code>initPopStateEvent()</code></dfn>
|
|
method must initialize the event in a manner analogous to the
|
|
similarly-named method in the DOM Events interfaces. <a href="references.html#refsDOMEVENTS">[DOMEVENTS]</a></p>
|
|
|
|
<p>The <dfn id="dom-popstateevent-state" title="dom-PopStateEvent-state"><code>state</code></dfn>
|
|
attribute represents the context information for the event, or null,
|
|
if the state represented is the initial state of the
|
|
<code><a href="infrastructure.html#document">Document</a></code>.</p>
|
|
|
|
</div><hr><p>The <dfn id="event-hashchange" title="event-hashchange"><code>hashchange</code></dfn>
|
|
event is fired when navigating to a <a href="#session-history-entry">session history
|
|
entry</a> whose <a href="urls.html#url">URL</a> differs from that of the
|
|
previous one only in the fragment identifier.</p><pre class="idl">interface <dfn id="hashchangeevent">HashChangeEvent</dfn> : <a href="infrastructure.html#event">Event</a> {
|
|
readonly attribute DOMString <a href="#dom-hashchangeevent-oldurl" title="dom-HashChangeEvent-oldURL">oldURL</a>;
|
|
readonly attribute DOMString <a href="#dom-hashchangeevent-newurl" title="dom-HashChangeEvent-newURL">newURL</a>;
|
|
void <a href="#dom-hashchangeevent-inithashchangeevent" title="dom-HashChangeEvent-initHashChangeEvent">initHashChangeEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString oldURLArg, in DOMString newURLArg);
|
|
};</pre><dl class="domintro"><dt><var title="">event</var> . <code title="dom-HashChangeEvent-oldURL"><a href="#dom-hashchangeevent-oldurl">oldURL</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the <a href="urls.html#url">URL</a> of the <a href="#session-history-entry">session history
|
|
entry</a> that was previously current.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">event</var> . <code title="dom-HashChangeEvent-newURL"><a href="#dom-hashchangeevent-newurl">newURL</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the <a href="urls.html#url">URL</a> of the <a href="#session-history-entry">session history
|
|
entry</a> that is now current.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-hashchangeevent-inithashchangeevent" title="dom-HashChangeEvent-initHashChangeEvent"><code>initHashChangeEvent()</code></dfn>
|
|
method must initialize the event in a manner analogous to the
|
|
similarly-named method in the DOM Events interfaces. <a href="references.html#refsDOMEVENTS">[DOMEVENTS]</a></p>
|
|
|
|
<p>The <dfn id="dom-hashchangeevent-oldurl" title="dom-HashChangeEvent-oldURL"><code>oldURL</code></dfn>
|
|
attribute represents context information for the event, specifically
|
|
the URL of the <a href="#session-history-entry">session history entry</a> that was traversed
|
|
from.</p>
|
|
|
|
<p>The <dfn id="dom-hashchangeevent-newurl" title="dom-HashChangeEvent-newURL"><code>newURL</code></dfn>
|
|
attribute represents context information for the event, specifically
|
|
the URL of the <a href="#session-history-entry">session history entry</a> that was traversed
|
|
to.</p>
|
|
|
|
</div><hr><p>The <dfn id="event-pageshow" title="event-pageshow"><code>pageshow</code></dfn> event
|
|
is fired when traversing <em>to</em> a <a href="#session-history-entry">session history
|
|
entry</a>.</p><p>The <dfn id="event-pagehide" title="event-pagehide"><code>pagehide</code></dfn>
|
|
event is fired when traversing <em>from</em> a <a href="#session-history-entry">session history
|
|
entry</a>.</p><pre class="idl">interface <dfn id="pagetransitionevent">PageTransitionEvent</dfn> : <a href="infrastructure.html#event">Event</a> {
|
|
readonly attribute boolean <a href="#dom-pagetransitionevent-persisted" title="dom-PageTransitionEvent-persisted">persisted</a>;
|
|
void <a href="#dom-pagetransitionevent-initpagetransitionevent" title="dom-PageTransitionEvent-initPageTransitionEvent">initPageTransitionEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in boolean persistedArg);
|
|
};</pre><dl class="domintro"><dt><var title="">event</var> . <code title="dom-PageTransitionEvent-persisted"><a href="#dom-pagetransitionevent-persisted">persisted</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns false if the page is newly being loaded (and the <code title="event-load">load</code> event will fire). Otherwise, returns true.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-pagetransitionevent-initpagetransitionevent" title="dom-PageTransitionEvent-initPageTransitionEvent"><code>initPageTransitionEvent()</code></dfn>
|
|
method must initialize the event in a manner analogous to the
|
|
similarly-named method in the DOM Events interfaces. <a href="references.html#refsDOMEVENTS">[DOMEVENTS]</a></p>
|
|
|
|
<p>The <dfn id="dom-pagetransitionevent-persisted" title="dom-PageTransitionEvent-persisted"><code>persisted</code></dfn>
|
|
attribute represents the context information for the event.</p>
|
|
|
|
</div><h4 id="unloading-documents"><span class="secno">5.5.10 </span>Unloading documents</h4><div class="impl">
|
|
|
|
<p>A <code><a href="infrastructure.html#document">Document</a></code> has a <var title="concept-document-salvageable">salvageable</var> state, which
|
|
is initially true.</p>
|
|
|
|
<p>When a user agent is to <dfn id="prompt-to-unload-a-document">prompt to unload a document</dfn>,
|
|
it must run the following steps.</p>
|
|
|
|
<ol><li><p>Let <var title="">event</var> be a new
|
|
<code><a href="#beforeunloadevent">BeforeUnloadEvent</a></code> event object with the name <code title="event-beforeunload">beforeunload</code>, which does not
|
|
bubble but is cancelable.</p></li>
|
|
|
|
<li><p><i>Dispatch</i>: Dispatch <var title="">event</var> at the
|
|
<code><a href="infrastructure.html#document">Document</a></code>'s <code><a href="browsers.html#window">Window</a></code> object.</p></li>
|
|
|
|
<li><p>Release the <a href="webappapis.html#storage-mutex">storage mutex</a>.</p></li>
|
|
|
|
<li><p>If any event listeners were triggered by the earlier
|
|
<i>dispatch</i> step, then set the <code><a href="infrastructure.html#document">Document</a></code>'s <var title="concept-document-salvageable">salvageable</var> state to
|
|
false.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If the <code title="dom-BeforeUnloadEvent-returnValue"><a href="#dom-beforeunloadevent-returnvalue">returnValue</a></code>
|
|
attribute of the <var title="">event</var> object is not the empty
|
|
string, or if the event was canceled, then the user agent should
|
|
ask the user to confirm that they wish to unload the document.</p>
|
|
|
|
<p>The prompt shown by the user agent may include the string of
|
|
the <code title="dom-BeforeUnloadEvent-returnValue"><a href="#dom-beforeunloadevent-returnvalue">returnValue</a></code>
|
|
attribute, or some leading subset thereof. (A user agent may want
|
|
to truncate the string to 1024 characters for display, for
|
|
instance.)</p>
|
|
|
|
<p>The user agent must <a href="webappapis.html#pause">pause</a> while waiting for the
|
|
user's response.</p>
|
|
|
|
<p>If the user did not confirm the page navigation, then the user
|
|
agent <dfn id="refused-to-allow-the-document-to-be-unloaded">refused to allow the document to be unloaded</dfn>.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>If this algorithm was invoked by another instance of the
|
|
"prompt to unload a document" algorithm (i.e. through the steps
|
|
below that invoke this algorithm for all descendant browsing
|
|
contexts), then abort these steps here.</p></li>
|
|
|
|
<li><p>Let <var title="">descendants</var> be the <a href="browsers.html#list-of-the-descendant-browsing-contexts">list of the
|
|
descendant browsing contexts</a> of the
|
|
<code><a href="infrastructure.html#document">Document</a></code>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If <var title="">descendants</var> is not an empty list, then
|
|
for each <a href="browsers.html#browsing-context">browsing context</a> <var title="">b</var> in
|
|
<var title="">descendants</var> run the following substeps:</p>
|
|
|
|
<ol><li><p><a href="#prompt-to-unload-a-document" title="prompt to unload a document">Prompt to
|
|
unload</a> the <a href="browsers.html#active-document">active document</a> of the
|
|
<a href="browsers.html#browsing-context">browsing context</a> <var title="">b</var>. If the user
|
|
<a href="#refused-to-allow-the-document-to-be-unloaded">refused to allow the document to be unloaded</a>, then
|
|
the user implicitly also <a href="#refused-to-allow-the-document-to-be-unloaded" title="refused to allow the
|
|
document to be unloaded">refused to allow <em>this</em> document
|
|
to be unloaded</a>; abort these steps.</p>
|
|
|
|
</li><li><p>If <var title="concept-document-salvageable">salvageable</var> state of
|
|
the <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing
|
|
context</a> <var title="">b</var> is false, then set the <var title="concept-document-salvageable">salvageable</var> state of
|
|
<em>this</em> document to false also.</p></li>
|
|
|
|
</ol></li>
|
|
|
|
</ol><p>When a user agent is to <dfn id="unload-a-document">unload a document</dfn>, it must run
|
|
the following steps. These steps are passed an argument, <var title="">recycle</var>, which is either true or false, indicating
|
|
whether the <code><a href="infrastructure.html#document">Document</a></code> object is going to be
|
|
re-used. (This is set by the <code title="dom-document-open"><a href="apis-in-html-documents.html#dom-document-open">document.open()</a></code> method.)</p>
|
|
|
|
<ol><li><p>Fire a <code title="event-pagehide"><a href="#event-pagehide">pagehide</a></code> event at
|
|
the <code><a href="browsers.html#window">Window</a></code> object of the <code><a href="infrastructure.html#document">Document</a></code>, but
|
|
with its <code title="dom-event-target"><a href="infrastructure.html#dom-event-target">target</a></code> set to the
|
|
<code><a href="infrastructure.html#document">Document</a></code> object (and the <code title="dom-event-currentTarget">currentTarget</code> set to the
|
|
<code><a href="browsers.html#window">Window</a></code> object), using the
|
|
<code><a href="#pagetransitionevent">PageTransitionEvent</a></code> interface, with the <code title="dom-PageTransitionEvent-persisted"><a href="#dom-pagetransitionevent-persisted">persisted</a></code>
|
|
attribute set to true. This event must not bubble, must not be
|
|
cancelable, and has no default action.</p></li>
|
|
|
|
<li><p><i>Unload event</i>: <a href="webappapis.html#fire-a-simple-event">Fire a simple event</a> named
|
|
<code title="event-unload">unload</code> at the
|
|
<code><a href="infrastructure.html#document">Document</a></code>'s <code><a href="browsers.html#window">Window</a></code> object.</p></li>
|
|
|
|
<li><p>Release the <a href="webappapis.html#storage-mutex">storage mutex</a>.</p></li>
|
|
|
|
<li><p>If any event listeners were triggered by the earlier
|
|
<i>unload event</i> step, then set the <code><a href="infrastructure.html#document">Document</a></code>
|
|
object's <var title="concept-document-salvageable">salvageable</var> state to
|
|
false.</p></li>
|
|
|
|
<li><p>Run any <a href="#unloading-document-cleanup-steps">unloading document cleanup steps</a> for
|
|
<code><a href="infrastructure.html#document">Document</a></code> that are defined by this specification and
|
|
<a href="infrastructure.html#other-applicable-specifications">other applicable specifications</a>.</p></li>
|
|
|
|
<li><p>If this algorithm was invoked by another instance of the
|
|
"unload a document" algorithm (i.e. through the steps below that
|
|
invoke this algorithm for all descendant browsing contexts), then
|
|
abort these steps here.</p></li>
|
|
|
|
<li><p>Let <var title="">descendants</var> be the <a href="browsers.html#list-of-the-descendant-browsing-contexts">list of the
|
|
descendant browsing contexts</a> of the
|
|
<code><a href="infrastructure.html#document">Document</a></code>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If <var title="">descendants</var> is not an empty list, then
|
|
for each <a href="browsers.html#browsing-context">browsing context</a> <var title="">b</var> in
|
|
<var title="">descendants</var> run the following substeps:</p>
|
|
|
|
<ol><li><p><a href="#unload-a-document" title="unload a document">Unload</a> the
|
|
<a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing context</a>
|
|
<var title="">b</var> with the <var title="">recycle</var>
|
|
parameter set to false.</p></li>
|
|
|
|
<li><p>If <var title="concept-document-salvageable">salvageable</var> state of
|
|
the <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing
|
|
context</a> <var title="">b</var> is false, then set the <var title="concept-document-salvageable">salvageable</var> state of
|
|
<em>this</em> document to false also.</p></li>
|
|
|
|
</ol></li>
|
|
|
|
<li><p>If <var title="concept-document-salvageable">salvageable</var> and <var title="">recycle</var> are both false, then the
|
|
<code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> must <a href="browsers.html#discard-a-document" title="discard a document">discard the
|
|
<code>Document</code></a>.</p></li>
|
|
|
|
</ol><p>This specification defines the following <dfn id="unloading-document-cleanup-steps">unloading document
|
|
cleanup steps</dfn>. Other specifications can define more.</p>
|
|
|
|
<ol><li><p><span>Close the WebSocket connection</span> of any
|
|
<code>WebSocket</code> objects that were created by the <code title="dom-WebSocket">WebSocket()</code> constructor visible on the
|
|
<code><a href="infrastructure.html#document">Document</a></code>'s <code><a href="browsers.html#window">Window</a></code> object. If this
|
|
affected any <code>WebSocket</code> objects, the set
|
|
<code><a href="infrastructure.html#document">Document</a></code>'s <var title="concept-document-salvageable">salvageable</var> state to
|
|
false.
|
|
|
|
<a href="references.html#refsWEBSOCKET">[WEBSOCKET]</a>
|
|
|
|
</p></li>
|
|
|
|
<li><p>If the <code><a href="infrastructure.html#document">Document</a></code>'s <var title="concept-document-salvageable">salvageable</var> state is
|
|
false, empty the <code><a href="infrastructure.html#document">Document</a></code>'s <code><a href="browsers.html#window">Window</a></code>'s
|
|
<a href="timers.html#list-of-active-timeouts">list of active timeouts</a> and its <a href="timers.html#list-of-active-intervals">list of active
|
|
intervals</a>.</p></li>
|
|
|
|
</ol><h5 id="event-definition"><span class="secno">5.5.10.1 </span>Event definition</h5>
|
|
|
|
</div><pre class="idl">interface <dfn id="beforeunloadevent">BeforeUnloadEvent</dfn> : <a href="infrastructure.html#event">Event</a> {
|
|
attribute DOMString <a href="#dom-beforeunloadevent-returnvalue" title="dom-BeforeUnloadEvent-returnValue">returnValue</a>;
|
|
};</pre><dl class="domintro"><dt><var title="">event</var> . <code title="dom-BeforeUnloadEvent-returnValue"><a href="#dom-beforeunloadevent-returnvalue">returnValue</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the current return value of the event (the message to show the user).</p>
|
|
|
|
<p>Can be set, to update the message.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><p class="note">There are no <code><a href="#beforeunloadevent">BeforeUnloadEvent</a></code>-specific
|
|
initialization methods.</p><div class="impl">
|
|
|
|
<p>The <dfn id="dom-beforeunloadevent-returnvalue" title="dom-BeforeUnloadEvent-returnValue"><code>returnValue</code></dfn>
|
|
attribute represents the message to show the user. When the event is
|
|
created, the attribute must be set to the empty string. On getting,
|
|
it must return the last value it was set to. On setting, the
|
|
attribute must be set to the new value.</p>
|
|
|
|
</div><div class="impl">
|
|
|
|
<h4 id="aborting-a-document-load"><span class="secno">5.5.11 </span>Aborting a document load</h4>
|
|
|
|
<p>If a <code><a href="infrastructure.html#document">Document</a></code> is <dfn id="abort-a-document" title="abort a
|
|
document">aborted</dfn>, the user agent must run the following
|
|
steps:</p>
|
|
|
|
<ol><li><p><a href="#abort-a-document" title="abort a document">Abort</a> the <a href="browsers.html#active-document" title="active document">active documents</a> of every
|
|
<a href="browsers.html#child-browsing-context">child browsing context</a>.</p></li>
|
|
|
|
<li><p>Cancel any instances of the <a href="fetching-resources.html#fetch" title="fetch">fetch</a>
|
|
algorithm in the context of this <code><a href="infrastructure.html#document">Document</a></code>, discarding
|
|
any <a href="webappapis.html#concept-task" title="concept-task">tasks</a> <a href="webappapis.html#queue-a-task" title="queue a
|
|
task">queued</a> for them, and discarding any further data
|
|
received from the network for them.</p></li>
|
|
|
|
<li><p>If the <code><a href="infrastructure.html#document">Document</a></code> has an <a href="dom.html#active-parser">active
|
|
parser</a>, then <a href="the-end.html#abort-a-parser" title="abort a parser">abort that
|
|
parser</a>.</p></li>
|
|
|
|
|
|
|
|
</ol><p>User agents may allow users to explicitly invoke the <a href="#abort-a-document" title="abort a document">abort a document</a> algorithm for a
|
|
<code><a href="infrastructure.html#document">Document</a></code>. If the user does so, then, if that
|
|
<code><a href="infrastructure.html#document">Document</a></code> is an <a href="browsers.html#active-document">active document</a>, the user
|
|
agent should <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
|
|
event</a> named <code title="event-abort">abort</code> at that
|
|
<code><a href="infrastructure.html#document">Document</a></code>'s <code><a href="browsers.html#window">Window</a></code> object before invoking
|
|
the <a href="#abort-a-document" title="abort a document">abort</a> algorithm.</p>
|
|
|
|
|
|
</div></body></html>
|