A string is a valid vevent duration string if it matches the following pattern:
Given a list of nodes nodes in a
Document, a user agent must run the following algorithm
to extract any vEvent data
represented by those nodes:
If none of the nodes in nodes are items with the type http://microformats.org/profile/hcalendar#vevent,
then there is no vEvent data. Abort the algorithm, returning
nothing.
Let output be an empty string.
Add an iCalendar line with the type "BEGIN" and the value "VCALENDAR" to output.
Add an iCalendar line with the type "PRODID" and the value equal to a
user-agent-specific string representing the user agent to output.
Add an iCalendar line with the type "VERSION" and the value "2.0"
to output.
For each node node in nodes that is an item with the type http://microformats.org/profile/hcalendar#vevent,
run the following steps:
Add an iCalendar line with the type "BEGIN" and the value "VEVENT" to output.
Add an iCalendar line with the type "DTSTAMP" and a value consisting of an iCalendar
DATE-TIME string representing the current date and time, with the
annotation "VALUE=DATE-TIME", to output. [RFC2445]
If the item has a
global identifier, add an iCalendar
line with the type "UID" and that
global identifier as the value to output.
For each element element that is a property of the item node: for each name name in element's property names, run the appropriate set of substeps from the following list:
Skip the property.
time
elementLet value be the result of stripping all U+002D HYPHEN-MINUS (-) and U+003A COLON (:) characters from the property's value.
If the property's value is a valid
date string then add an iCalendar line
with the type name and the value value to output, with the
annotation "VALUE=DATE".
Otherwise, if the property's value is a valid
global date and time string then add an iCalendar
line with the type name and the
value value to output,
with the annotation "VALUE=DATE-TIME".
Otherwise skip the property.
Add an iCalendar line with the type name and the property's value to output.
Add an iCalendar line with the type "END" and the value "VEVENT"
to output.
Add an iCalendar line with the type "END" and the value "VCALENDAR" to output.
When the above algorithm says that the user agent is to add an iCalendar line consisting of a type type, a value value, and optionally an annotation, to a string output, it must run the following steps:
Let line be an empty string.
Append type, converted to ASCII uppercase, to line.
If there is an annotation:
Append a U+003B SEMICOLON character (;) to line.
Append the annotation to line.
Append a U+003A COLON character (:) to line.
Prefix every U+005C REVERSE SOLIDUS character (\) in value with another U+005C REVERSE SOLIDUS character (\).
Prefix every U+002C COMMA character (,) in value with a U+005C REVERSE SOLIDUS character (\).
Prefix every U+003B SEMICOLON character (;) in value with a U+005C REVERSE SOLIDUS character (\).
Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF) character in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Append value to line.
Let maximum length be 75.
If and while line is longer than maximum length Unicode code points long, run the following substeps:
Append the first maximum length Unicode code points of line to output.
Remove the first maximum length Unicode code points from line.
Append a U+000D CARRIAGE RETURN character (CR) to output.
Append a U+000A LINE FEED character (LF) to output.
Append a U+0020 SPACE character to output.
Let maximum length be 74.
Append (what remains of) line to output.
Append a U+000D CARRIAGE RETURN character (CR) to output.
Append a U+000A LINE FEED character (LF) to output.
This algorithm can generate invalid iCalendar
output, if the input does not conform to the rules described for the
http://microformats.org/profile/hcalendar#vevent
item type and defined property names.
This section is non-normative.
Here is an example of a page that uses the vEvent vocabulary to mark up an event:
<body itemscope itemtype="http://microformats.org/profile/hcalendar#vevent">
...
<h1 itemprop="summary">Bluesday Tuesday: Money Road</h1>
...
<time itemprop="dtstart" datetime="2009-05-05T19:00:00Z">May 5th @ 7pm</time>
(until <time itemprop="dtend" datetime="2009-05-05T21:00:00Z">9pm</time>)
...
<a href="http://livebrum.co.uk/2009/05/05/bluesday-tuesday-money-road"
rel="bookmark" itemprop="url">Link to this page</a>
...
<p>Location: <span itemprop="location">The RoadHouse</span></p>
...
<p><input type=button value="Add to Calendar"
onclick="location = getCalendar(this)"></p>
...
<meta itemprop="description" content="via livebrum.co.uk">
</body>
The "getCalendar()" method could look like
this:
function getCalendar(node) {
// This function assumes the content is valid.
// It is not a compliant implementation of the algorithm for extracting vEvent data.
while (node && (!node.itemScope || !node.itemType == 'http://microformats.org/profile/hcalendar#vevent'))
node = node.parentNode;
if (!node) {
alert('No event data found.');
return;
}
var stamp = new Date();
var stampString = '' + stamp.getUTCFullYear() + (stamp.getUTCMonth() + 1) + stamp.getUTCDate() + 'T' +
stamp.getUTCHours() + stamp.getUTCMinutes() + stamp.getUTCSeconds() + 'Z';
var calendar = 'BEGIN:VCALENDAR\r\nPRODID:HTML\r\nVERSION:2.0\r\nBEGIN:VEVENT\r\nDTSTAMP:' + stampString + '\r\n';
if (node.itemId)
calendar += 'UID:' + node.itemId + '\r\n';
for (var propIndex = 0; propIndex < node.properties.length; propIndex += 1) {
var prop = node.properties[propIndex];
var value = prop.itemValue;
var parameters = '';
if (prop.localName == 'time') {
value = value.replace(/[:-]/g, '');
if (value.match(/T/))
parameters = ';VALUE=DATE';
else
parameters = ';VALUE=DATE-TIME';
} else {
value = value.replace(/\\/g, '\\n');
value = value.replace(/;/g, '\\;');
value = value.replace(/,/g, '\\,');
value = value.replace(/\n/g, '\\n');
}
for (var nameIndex = 0; nameIndex < prop.itemProp.length; nameIndex += 1) {
var name = prop.itemProp[nameIndex];
if (!name.match(/:/) && !name.match(/\./))
calendar += name.toUpperCase() + parameters + ':' + value + '\r\n';
}
}
calendar += 'END:VEVENT\r\nEND:VCALENDAR\r\n';
return 'data:text/calendar;component=vevent,' + encodeURI(calendar);
}
The same page could offer some markup, such as the following, for copy-and-pasting into blogs:
<div itemscope itemtype="http://microformats.org/profile/hcalendar#vevent">
<p>I'm going to
<strong itemprop="summary">Bluesday Tuesday: Money Road</strong>,
<time itemprop="dtstart" datetime="2009-05-05T19:00:00Z">May 5th at 7pm</time>
to <time itemprop="dtend" content="2009-05-05T21:00:00Z">9pm</time>,
at <span itemprop="location">The RoadHouse</span>!</p>
<p><a href="http://livebrum.co.uk/2009/05/05/bluesday-tuesday-money-road"
itemprop="url">See this event on livebrum.co.uk</a>.</p>
<meta itemprop="description" content="via livebrum.co.uk">
</div>
An item with the item type http://n.whatwg.org/work
represents a work (e.g. an article, an image, a video, a song,
etc). This type is primarily intended to allow authors to include
licensing information for works.
The following are the type's defined property names.
workIdentifies the work being described.
The value must be an absolute URL.
Exactly one property with the name work must be present within each item with the type http://n.whatwg.org/work.
titleGives the name of the work.
A single property with the name title may be present within each
item with the type http://n.whatwg.org/work.
authorGives the name or contact information of one of the authors or creators of the work.
The value must be
either an item with the type
http://microformats.org/profile/hcard, or
text.
Any number of properties with the name author may be present within each
item with the type http://n.whatwg.org/work.
licenseIdentifies one of the licenses under which the work is available.
The value must be an absolute URL.
Any number of properties with the name license may be present within each
item with the type http://n.whatwg.org/work.
For the purposes of RDF processors, the triples obtained from the following Turtle must be applied:
<http://www.w3.org/1999/xhtml/microdata#http%3A%2F%2Fn.whatwg.org%2Fwork%23%3Awork> <http://www.w3.org/2002/07/owl#equivalentProperty> <http://www.w3.org/2002/07/owl#sameAs> . <http://www.w3.org/1999/xhtml/microdata#http%3A%2F%2Fn.whatwg.org%2Fwork%23%3Atitle> <http://www.w3.org/2002/07/owl#equivalentProperty> <http://purl.org/dc/terms/title> . <http://www.w3.org/1999/xhtml/microdata#http%3A%2F%2Fn.whatwg.org%2Fwork%23%3Aauthor> <http://www.w3.org/2002/07/owl#equivalentProperty> <http://creativecommons.org/ns#attributionName> . <http://www.w3.org/1999/xhtml/microdata#http%3A%2F%2Fn.whatwg.org%2Fwork%23%3Alicense> <http://www.w3.org/2002/07/owl#equivalentProperty> <http://www.w3.org/1999/xhtml/vocab#license> .
The subjects of the statements above are the
predicates that result from converting
to RDF an HTML page containing microdata with an item whose
type is "http://n.whatwg.org/work".
This section is non-normative.
This example shows an embedded image entitled My Pond, licensed under the Creative Commons Attribution-Share Alike 3.0 United States License and the MIT license simultaneously.
<figure itemscope itemtype="http://n.whatwg.org/work"> <img itemprop="work" src="mypond.jpeg"> <figcaption> <p><cite itemprop="title">My Pond</cite></p> <p><small>Licensed under the <a itemprop="license" href="http://creativecommons.org/licenses/by-sa/3.0/us/">Creative Commons Attribution-Share Alike 3.0 United States License</a> and the <a itemprop="license" href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</small> </figcaption> </figure>
Given a list of nodes nodes in a
Document, a user agent must run the following algorithm
to extract the microdata from those
nodes into a JSON form:
Let result be an empty object.
Let items be an empty array.
For each node in nodes, check if the element is a top-level microdata item, and if it is then get the object for that element and add it to items.
Add an entry to result called "items" whose value is the array items.
Return the result of serializing result to JSON.
When the user agent is to get the object for an item item, it must run the following substeps:
Let result be an empty object.
If the item has an item
type, add an entry to result called
"type" whose value is the item
type of item.
If the item has an global
identifier, add an entry to result
called "id" whose value is the global
identifier of item.
Let properties be an empty object.
For each element element that has one or more property names and is one of the properties of the item item, in the order those elements are given by the algorithm that returns the properties of an item, run the following substeps:
Let value be the property value of element.
If value is an item, then get the object for value, and then replace value with the object returned from those steps.
For each name name in element's property names, run the following substeps:
If there is no entry named name in properties, then add an entry named name to properties whose value is an empty array.
Append value to the entry named name in properties.
Add an entry to result called "properties" whose value is the object properties.
Return result.
To convert a Document to
RDF, a user agent must run the following algorithm:
If the title element is not null,
then generate the following triple:
http://purl.org/dc/terms/title
title element, in tree order, as a plain literal, with the language information set from the language of the title element, if it is not unknown.
For each a, area, and
link element in the Document, run these
substeps:
If the element does not have a rel
attribute, then skip this element.
If the element does not have an href
attribute, then skip this element.
If resolving the
element's href attribute relative to the
element is not successful, then skip this element.
Otherwise, split
the value of the element's rel attribute on
spaces, obtaining list of tokens.
Convert each token in list of tokens that does not contain a U+003A COLON characters (:) to ASCII lowercase.
If list of tokens contains more than
one instance of the token up, then
remove all such tokens.
Coalesce duplicate tokens in list of tokens.
If list of tokens contains both the
tokens alternate and stylesheet, then remove them both
and replace them with the single (uppercase) token ALTERNATE-STYLESHEET.
For each token token in list of tokens that contains no U+003A COLON characters (:), generate the following triple:
http://www.w3.org/1999/xhtml/vocab#" and token, with any characters in token that are not valid in the <ifragment> production of the IRI syntax being %-escaped [RFC3987]
href attribute relative to the element
For each token token in list of tokens that is an absolute URL, generate the following triple:
href attribute relative to the element
For each meta element in the Document
that has a name attribute and
a content attribute, if the
value of the name attribute
contains no U+003A COLON characters (:), generate the following
triple:
http://www.w3.org/1999/xhtml/vocab#" and the value of the element's name attribute, converted to ASCII lowercase, with any characters in the value that are not valid in the <ifragment> production of the IRI syntax being %-escaped [RFC3987]
content attribute, as a plain literal, with the language information set from the language of the element, if it is not unknown
For each meta element in the Document
that has a name attribute and
a content attribute, if the
value of the name attribute is
an absolute URL, generate the following triple:
name attribute
content attribute, as a plain literal, with the language information set from the language of the element, if it is not unknown
For each blockquote and q element in
the Document that has a cite
attribute that resolves
successfully relative to the element, generate the following
triple:
http://purl.org/dc/terms/source
cite attribute relative to the element
Let memory be a mapping of items to subjects, initially empty.
For each element that is also a top-level microdata item, run the following steps:
Generate the triples for the item. Pass a reference to memory as the item/subject list. Let result be the subject returned.
Generate the following triple:
http://www.w3.org/1999/xhtml/microdata#item
When the user agent is to generate the triples for an item item, given a reference to an item/subject list memory, and optionally given a fallback type fallback type and property name fallback name, it must follow the following steps:
If there is an entry for item in memory, then let subject be the subject of that entry. Otherwise, if item has a global identifier and that global identifier is an absolute URL, let subject be that global identifier. Otherwise, let subject be a new blank node.
Add a mapping from item to subject in memory, if there isn't one already.
If item has an item type and that item type is an absolute URL, let type be that item type. Otherwise, let type be the empty string.
If type is not the empty string, run the following steps:
Generate the following triple:
http://www.w3.org/1999/02/22-rdf-syntax-ns#type
If type does not contain a U+0023 NUMBER SIGN character (#), then append a U+0023 NUMBER SIGN character (#) to type.
If type does not have a U+003A COLON character (:) after its U+0023 NUMBER SIGN character (#), append a U+003A COLON character (:) to type.
If type is the empty string, but fallback type is not, run the following substeps:
Let type have the value of fallback type.
If type does not contain a U+0023 NUMBER SIGN character (#), then append a U+0023 NUMBER SIGN character (#) to type.
If type does not have a U+003A COLON character (:) after its U+0023 NUMBER SIGN character (#), append a U+003A COLON character (:) to type.
If the last character of type is not a U+003A COLON character (:), append a U+0025 PERCENT SIGN character (%), a U+0032 DIGIT TWO character (2), and a U+0030 DIGIT ZERO character (0) to type.
Append the value of fallback name to type, with any characters in fallback name that are not valid in the <ifragment> production of the IRI syntax being %-escaped. [RFC3987]
For each element element that has one or more property names and is one of the properties of the item item, in the order those elements are given by the algorithm that returns the properties of an item, run the following substep:
For each name name in element's property names, run the following substeps:
If type is the empty string and name is not an absolute URL, then abort these substeps.
Let value be the property value of element.
If value is an item, then generate the triples for value. Pass a reference to memory as the item/subject list, and pass type as the fallback type and name as the fallback property name. Replace value by the subject returned from those steps.
Otherwise, if element is not one of the URL property elements, let value be a plain literal, with the language information set from the language of the element, if it is not unknown.
Let predicate be name.
Let s be type.
If the last character of s is not a U+003A COLON character (:), append a U+0025 PERCENT SIGN character (%), a U+0032 DIGIT TWO character (2), and a U+0030 DIGIT ZERO character (0) to s.
Append the value of name to s, with any characters in name that are not valid in the <ifragment> production of the IRI syntax being %-escaped. [RFC3987]
Let predicate be the
concatenation of the string "http://www.w3.org/1999/xhtml/microdata#"
and s, with any characters in s that are not valid in the <ifragment>
production of the IRI syntax being %-escaped. [RFC3987]
Generate the following triple:
Return subject.
This section is non-normative.
Here is an example of some HTML using Microdata to express RDF statements:
<dl itemscope
itemtype="http://purl.org/vocab/frbr/core#Work"
itemid="http://purl.oreilly.com/works/45U8QJGZSQKDH8N">
<dt>Title</dt>
<dd><cite itemprop="http://purl.org/dc/terms/title">Just a Geek</cite></dd>
<dt>By</dt>
<dd><span itemprop="http://purl.org/dc/terms/creator">Wil Wheaton</span></dd>
<dt>Format</dt>
<dd itemprop="http://purl.org/vocab/frbr/core#realization"
itemscope
itemtype="http://purl.org/vocab/frbr/core#Expression"
itemid="http://purl.oreilly.com/products/9780596007683.BOOK">
<link itemprop="http://purl.org/dc/terms/type" href="http://purl.oreilly.com/product-types/BOOK">
Print
</dd>
<dd itemprop="http://purl.org/vocab/frbr/core#realization"
itemscope
itemtype="http://purl.org/vocab/frbr/core#Expression"
itemid="http://purl.oreilly.com/products/9780596802189.EBOOK">
<link itemprop="http://purl.org/dc/terms/type" href="http://purl.oreilly.com/product-types/EBOOK">
Ebook
</dd>
</dl>
This is equivalent to the following Turtle:
@prefix dc: <http://purl.org/dc/terms/> .
@prefix frbr: <http://purl.org/vocab/frbr/core#> .
<http://purl.oreilly.com/works/45U8QJGZSQKDH8N> a frbr:Work ;
dc:creator "Wil Wheaton"@en ;
dc:title "Just a Geek"@en ;
frbr:realization <http://purl.oreilly.com/products/9780596007683.BOOK>,
<http://purl.oreilly.com/products/9780596802189.EBOOK> .
<http://purl.oreilly.com/products/9780596007683.BOOK> a frbr:Expression ;
dc:type <http://purl.oreilly.com/product-types/BOOK> .
<http://purl.oreilly.com/products/9780596802189.EBOOK> a frbr:Expression ;
dc:type <http://purl.oreilly.com/product-types/EBOOK> .
The following snippet of HTML has microdata for two people with the same address:
<p> Both <span itemscope itemtype="http://microformats.org/profile/hcard" itemref="home"><span itemprop="fn">Princeton</span></span> and <span itemscope itemtype="http://microformats.org/profile/hcard" itemref="home"><span itemprop="fn">Trekkie</span></span> live at <span id="home" itemprop="adr" itemscope><span itemprop="street-address">Avenue Q</span>.</span> </p>
It generates these triples expressed in Turtle (including a triple that in this case is expressed twice, though that is not meaningful in RDF):
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix hcard: <http://www.w3.org/1999/xhtml/microdata#http%3A%2F%2Fmicroformats.org%2Fprofile%2Fhcard%23%3A> .
<> <http://www.w3.org/1999/xhtml/microdata#item> _:n0 ;
<http://www.w3.org/1999/xhtml/microdata#item> _:n1 .
_:n0 rdf:type <http://microformats.org/profile/hcard> ;
hcard:fn "Princeton" ;
hcard:adr _:n2 .
_:n1 rdf:type <http://microformats.org/profile/hcard> ;
hcard:fn "Trekkie" ;
hcard:adr _:n2 .
_:n2 hcard:adr%20street-address "Avenue Q" ;
hcard:adr%20street-address "Avenue Q" .
Given a Document source, a user
agent may run the following algorithm to extract an Atom feed. This is not the only algorithm
that can be used for this purpose; for instance, a user agent might
instead use the hAtom algorithm. [HATOM]
If the Document source does
not contain any article elements, then return nothing
and abort these steps. This algorithm can only be used with
documents that contain distinct articles.
Let R be an empty XML Document object whose address is user-agent
defined.
Append a feed element in the
Atom namespace to R.
For each meta element with a name attribute and a content attribute and whose name attribute's value is author, run the following substeps:
Append an author element in the
Atom namespace to the root element of R.
Append a name element in the
Atom namespace to the element created in the
previous step.
Append a text node whose data is the value of the
meta element's content attribute to the element
created in the previous step.
If there is a link element whose rel attribute's value includes the
keyword icon, and that element also
has an href attribute whose
value successfully resolves
relative to the link element, then append an icon element in the Atom namespace to
the root element of R whose contents is a text
node with its data set to the absolute URL resulting
from resolving the value of the
href attribute.
Append an id element in the Atom
namespace to the root element of R
whose contents is a text node with its data set to the
document's current address.
Optionally: Let x be a link element in the Atom
namespace. Add a rel attribute whose
value is the string "self" to x. Append a text node with its data set to the
(user-agent-defined) address of R to x. Append x to the root element
of R.
This step would be skipped when the document R has no convenient address. The presence of the rel="self" link is a "should"-level requirement in
the Atom specification.
Let x be a link
element in the Atom namespace. Add a rel attribute whose value is the string "alternate" to x. If the
document being converted is an HTML
document, add a type attribute whose
value is the string "text/html" to x. Otherwise, the document being converted is an
XML document; add a type attribute whose value is the string
"application/xhtml+xml" to x. Append a text node with its data set to
the document's current address to x. Append x to the root element
of R.
Let subheading text be the empty string.
Let heading be the first element of heading content whose nearest ancestor of sectioning content is the body element, if any, or null if there is none.
Take the appropriate action from the following list, as determined by the type of the heading element:
Let heading text be the
textContent of the title
element, if there is one, or the empty string
otherwise.
hgroup elementIf heading contains no child
h1–h6 elements, let heading text be the empty string.
Otherwise, let headings list be a list of
all the h1–h6 element children
of heading, sorted first by descending
rank and then in tree order (so
h1s first, then h2s, etc, with each
group in the order they appear in the document). Then, let heading text be the textContent of
the first entry in headings list, and if
there are multiple entries, let subheading
text be the textContent of the second entry
in headings list.
h1–h6 elementLet heading text be the
textContent of heading.
Append a title element in the Atom
namespace to the root element of R
whose contents is a text node with its data set to heading text.
If subheading text is not the empty string,
append a subtitle element in the Atom
namespace to the root element of R
whose contents is a text node with its data set to subheading text.
Let global update date have no value.
For each article element article that does not have an ancestor
article element, run the following steps:
Let E be an entry element in the Atom namespace,
and append E to the root element of R.
Let heading be the first element of heading content whose nearest ancestor of sectioning content is article, if any, or null if there is none.
Take the appropriate action from the following list, as determined by the type of the heading element:
Let heading text be the empty string.
hgroup elementIf heading contains no child
h1–h6 elements, let heading text be the empty string.
Otherwise, let headings list be a list
of all the h1–h6 element
children of heading, sorted first by
descending rank and then in tree
order (so h1s first, then
h2s, etc, with each group in the order they
appear in the document). Then, let heading
text be the textContent of the first entry
in headings list.
h1–h6 elementLet heading text be the
textContent of heading.
Append a title element in the
Atom namespace to E whose
contents is a text node with its data set to heading text.
Clone article and its descendants into an
environment that has scripting
disabled, has no plugins, and
fails any attempt to fetch any
resources. Let cloned article be the
resulting clone article element.
Remove from the subtree rooted at cloned
article any article elements other than the
cloned article itself, any
header, footer, or nav
elements whose nearest ancestor of sectioning
content is the cloned article, and
the first element of heading content whose nearest
ancestor of sectioning content is the cloned article, if any.
If cloned article contains any
ins or del elements with datetime attributes whose
values parse
as global date and time strings without errors, then let
update date be the value of the datetime attribute that parses
to the newest global date and
time.
Otherwise, let update date have no value.
This value is used below; it is calculated here because in certain cases the next step mutates the cloned article.
If the document being converted is an HTML document, then: Let x
be a content element in the Atom
namespace. Add a type attribute
whose value is the string "html" to x. Append a text node with its data set to the
result of running the HTML fragment serialization
algorithm on cloned article to x. Append x to E.
Otherwise, the document being converted is an XML document: Let x be a content element in
the Atom namespace. Add a type attribute whose value is the string "xml" to x. Append a
div element to x. Move all the
child nodes of the cloned article node to
that div element, preserving their relative
order. Append x to E.
Establish the value of id and has-alternate from the first of the following to apply:
a or area element with an href attribute that
successfully resolves
relative to that descendant and a rel attribute whose value includes
the bookmark keywordhref
attribute of the first such a or area
element, relative to the element. Let has-alternate be true.id attributeid attribute. Let has-alternate be false.Append an id element in the Atom
namespace to E whose contents is a
text node with its data set to id.
If has-alternate is true: Let x be a link element in the
Atom namespace. Add a rel
attribute whose value is the string "alternate" to x. Append a
text node with its data set to id to x. Append x to E.
If article has a time
element descendant that has a pubdate attribute and whose
nearest ancestor article element is article, and the first such element's date is not unknown, then run
the following substeps, with e being the
first such element:
Let datetime be a global date and time whose date component is the date of e.
If e's time and time-zone offset are not
unknown, then let datetime's time and
time-zone offset components be the time and time-zone offset of e. Otherwise, let them be midnight and no offset
respectively ("00:00Z").
Let publication date be the best representation of the global date and time string datetime.
Otherwise, let publication date have no value.
If update date has no value but publication date does, then let update date have the value of publication date.
Otherwise, if publication date has no value but update date does, then let publication date have the value of update date.
If update date has a value, and global update date has no value or is less recent than update date, then let global update date have the value of update date.
If publication date and update date both still have no value, then let them both value a value that is a valid global date and time string representing the global date and time of the moment that this algorithm was invoked.
Append an published element in the
Atom namespace to E whose
contents is a text node with its data set to publication date.
Append an updated element in the
Atom namespace to E whose
contents is a text node with its data set to update date.
If global update date has no value, then
let it have a value that is a valid global date and time
string representing the global date and time of the date
and time of the Document's source file's last
modification, if it is known, or else of the moment that this
algorithm was invoked.
Insert an updated element in the
Atom namespace into the root element of R before the first entry in
the Atom namespace whose contents is a text node with
its data set to global update date.
Return the Atom document R.
The above algorithm does not guarantee that the
output will be a conforming Atom feed. In particular, if
insufficient information is provided in the document (e.g. if the
document does not have any <meta name="author"
content="..."> elements), then the output will not be
conforming.
The Atom namespace is: http://www.w3.org/2005/Atom
This section describes features that apply most directly to Web browsers. Having said that, except where specified otherwise, the requirements defined in this section do apply to all user agents, whether they are Web browsers or not.
A browsing context is an environment in which
Document objects are presented to the user.
A tab or window in a Web browser typically contains
a browsing context, as does an iframe or frames in a
frameset.
Each browsing context has a corresponding
WindowProxy object.
A browsing context has a session
history, which lists the Document objects that
that browsing context has presented, is presenting, or
will present. At any time, one Document in each
browsing context is designated the active
document.
Each Document has a collection of one or more views.
A view is a user agent interface tied to a particular
media used for the presentation of a particular
Document object in some media. A view may be
interactive. Each view is represented by an
AbstractView object. [DOMVIEWS]
The main view through which a user primarily
interacts with a user agent is the default view. The
AbstractView object that represents this view must also implement the Window interface,
and is referred to as the Document's
Window object. WindowProxy objects forward
everything to the active document's default
view's Window object.
The defaultView
attribute on the Document object's
DocumentView interface must return the browsing
context's WindowProxy object, not the actual
AbstractView object of the default
view. [DOMVIEWS]
The document
attribute of an AbstractView object representing a
view gives the view's corresponding
Document object. [DOMVIEWS]
In general, there is a 1-to-1 mapping from the
Window object to the Document object. In
one particular case, a set of views can be
reused for the presentation of a second Document in the
same browsing context, such that the mapping is then
2-to-1. This occurs when a browsing context is navigated from the initial
about:blank Document to another, with
replacement enabled.
Events that use the UIEvent interface are related to
a specific view (the view in which the event happened);
when that view is the default view, the
event object's view attribute's must return
the WindowProxy object of the browsing
context of that view, not the actual
AbstractView object of the default
view. [DOMEVENTS]
A typical Web browser has one obvious
view per Document: the browser's window
(screen media). This is typically the default view. If
a page is printed, however, a second view becomes evident, that of
the print media. The two views always share the same underlying
Document object, but they have a different presentation
of that object. A speech browser might have a different
default view, using the speech media.
A Document does not necessarily have a
browsing context associated with it. In particular,
data mining tools are likely to never instantiate browsing
contexts.
A browsing context can have a creator browsing context, the browsing context that was responsible for its creation. If a browsing context has a parent browsing context, then that is its creator browsing context. Otherwise, if the browsing context has an opener browsing context, then that is its creator browsing context. Otherwise, the browsing context has no creator browsing context.
If a browsing context A has a
creator browsing context, then the
Document that was the active document of
that creator browsing context at the time A was created is the creator
Document.
When a browsing context is first created, it must be
created with a single Document in its session history,
whose address is
about:blank, which is marked as being an HTML document, and whose character encoding is
UTF-8. The Document must have a single child
html node, which itself has a single child
body node.
If the browsing context is created specifically to be immediately navigated, then that initial navigation will have replacement enabled.
The origin of the
about:blank Document is set when the
Document is created. If the new browsing
context has a creator browsing context, then the
origin of the about:blank
Document is the origin of the
creator Document. Otherwise, the
origin of the about:blank
Document is a globally unique identifier assigned when
the new browsing context is created.
Certain elements (for example, iframe elements) can
instantiate further browsing
contexts. These are called nested browsing contexts. If a browsing context P has an element E in one of its
Documents D that nests another
browsing context C inside it, then P is said to be the parent browsing
context of C, C is
said to be a child browsing context of P, C is said to be nested through D, and E is said to be the
browsing context container of C.
A browsing context A is said to be an ancestor of a browsing context B if there exists a browsing context A' that is a child browsing context of A and that is itself an ancestor of B, or if there is a browsing context P that is a child browsing context of A and that is the parent browsing context of B.
The browsing context with no parent browsing context is the top-level browsing context of all the browsing contexts nested within it (either directly or indirectly through other nested browsing contexts).
The transitive closure of parent browsing contexts for a nested browsing context gives the list of ancestor browsing contexts.
The list of the descendant browsing contexts of a
Document d is the list returned by
the following algorithm:
Let list be an empty list.
For each child browsing context of d that is nested through an element that is in the Document d, in the tree order of the elements of
the elements nesting those browsing
contexts, append to the list list the
list of the descendant browsing contexts of the
active document of that child browsing
context.
Return the constructed list.
A Document is said to be fully active
when it is the active document of its browsing
context, and either its browsing context is a top-level
browsing context, or the Document through which that
browsing context is nested is itself fully active.
Because they are nested through an element, child browsing contexts are always tied to
a specific Document in their parent browsing
context. User agents must not allow the user to interact with
child browsing contexts
of elements that are in Documents that are not
themselves fully active.
A nested browsing context can have a seamless
browsing context flag set, if it is embedded through an
iframe element with a seamless attribute.
topReturns the WindowProxy for the top-level browsing context.
parentReturns the WindowProxy for the parent browsing context.
frameElementReturns the Element for the browsing context container.
Returns null if there isn't one.
Throws a SECURITY_ERR exception in cross-origin situations.
The top IDL attribute on
the Window object of a Document in a
browsing context b must return the
WindowProxy object of its top-level browsing
context (which would be its own WindowProxy
object if it was a top-level browsing context
itself).
The parent IDL
attribute on the Window object of a
Document in a browsing context b must return the WindowProxy object of
the parent browsing context, if there is one (i.e. if
b is a child browsing context), or
the WindowProxy object of the browsing
context b itself, otherwise (i.e. if it
is a top-level browsing context).
The frameElement
IDL attribute on the Window object of a
Document d, on getting, must run
the following algorithm:
If d is not a Document in a
child browsing context, return null and abort these
steps.
If the parent browsing context's active
document does not have the same effective script origin as the
entry script, then throw a SECURITY_ERR
exception.
Otherwise, return the browsing context container for b.
It is possible to create new browsing contexts that are related to a top-level browsing context without being nested through an element. Such browsing contexts are called auxiliary browsing contexts. Auxiliary browsing contexts are always top-level browsing contexts.
An auxiliary browsing context has an opener browsing context, which is the browsing context from which the auxiliary browsing context was created, and it has a furthest ancestor browsing context, which is the top-level browsing context of the opener browsing context when the auxiliary browsing context was created.
The opener IDL
attribute on the Window object must return the
WindowProxy object of the browsing context
from which the current browsing context was created
(its opener browsing context), if there is one and it
is still available.
User agents may support secondary browsing contexts, which are browsing contexts that form part of the user agent's interface, apart from the main content area.
A browsing context A is allowed to navigate a second browsing context B if one of the following conditions is true:
An element has a browsing context scope origin if its
Document's browsing context is a
top-level browsing context or if all of its
Document's ancestor browsing contexts all have active documents whose
origin are the same origin as the
element's Document's origin. If an element
has a browsing context scope origin, then its value is
the origin of the element's Document.
Each browsing context is defined as having a list of zero or more directly reachable browsing contexts. These are:
The transitive closure of all the browsing contexts that are directly reachable browsing contexts forms a unit of related browsing contexts.
Each unit of related browsing contexts is then
further divided into the smallest number of groups such that every
member of each group has an effective script origin
that, through appropriate manipulation of the document.domain attribute, could
be made to be the same as other members of the group, but could not
be made the same as members of any other group. Each such group is a
unit of related similar-origin browsing contexts.
Each unit of related similar-origin browsing contexts can have a entry script which is used to obtain, amongst other things, the script's base URL to resolve relative URLs used in scripts running in that unit of related similar-origin browsing contexts. Initially, there is no entry script.
There is at most one event loop per unit of related similar-origin browsing contexts.
Browsing contexts can have a browsing context name. By default, a browsing context has no name (its name is not set).
A valid browsing context name is any string with at least one character that does not start with a U+005F LOW LINE character. (Names starting with an underscore are reserved for special keywords.)
A valid browsing context name or keyword is any string
that is either a valid browsing context name or that is
an ASCII case-insensitive match for one of: _blank, _self, _parent, or _top.
The rules for choosing a browsing context given a browsing context name are as follows. The rules assume that they are being applied in the context of a browsing context.
If the given browsing context name is the empty string or
_self, then the chosen browsing context must
be the current one.
If the given browsing context name is _parent, then the chosen browsing context must be
the parent browsing context of the current
one, unless there isn't one, in which case the chosen browsing
context must be the current browsing context.
If the given browsing context name is _top, then the chosen browsing context must be the
most top-level browsing context of the current
one.
If the given browsing context name is not _blank and there exists a browsing context whose
name is the same as the
given browsing context name, and the current browsing context is
allowed to navigate that browsing context, and the
user agent determines that the two browsing contexts are related
enough that it is ok if they reach each other, then that browsing
context must be the chosen one. If there are multiple matching
browsing contexts, the user agent should select one in some
arbitrary consistent manner, such as the most recently opened,
most recently focused, or more closely related.
Otherwise, a new browsing context is being requested, and what happens depends on the user agent's configuration and/or abilities:
The user agent may offer to create a new top-level browsing context or reuse an existing top-level browsing context. If the user picks one of those options, then the designated browsing context must be the chosen one (the browsing context's name isn't set to the given browsing context name). Otherwise (if the user agent doesn't offer the option to the user, or if the user declines to allow a browsing context to be used) there must not be a chosen browsing context.
noreferrer keywordA new top-level browsing context must be
created. If the given browsing context name is not _blank, then the new top-level browsing context's
name must be the given browsing context name (otherwise, it has
no name). The chosen browsing context must be this new browsing
context.
If it is immediately navigated, then the navigation will be done with replacement enabled.
noreferrer keyword doesn't
applyA new auxiliary browsing context must be
created, with the opener browsing context being the
current one. If the given browsing context name is not _blank, then the new auxiliary browsing context's
name must be the given browsing context name (otherwise, it has
no name). The chosen browsing context must be this new browsing
context.
If it is immediately navigated, then the navigation will be done with replacement enabled.
The chosen browsing context is the current browsing context.
There must not be a chosen browsing context.
User agent implementors are encouraged to provide a way for users to configure the user agent to always reuse the current browsing context.
Window object[OverrideBuiltins, ReplaceableNamedProperties]
interface Window {
// the current browsing context
readonly attribute WindowProxy window;
readonly attribute WindowProxy self;
attribute DOMString name;
[PutForwards=href] readonly attribute Location location;
readonly attribute History history;
readonly attribute UndoManager undoManager;
Selection getSelection();
[Replaceable] readonly attribute BarProp locationbar;
[Replaceable] readonly attribute BarProp menubar;
[Replaceable] readonly attribute BarProp personalbar;
[Replaceable] readonly attribute BarProp scrollbars;
[Replaceable] readonly attribute BarProp statusbar;
[Replaceable] readonly attribute BarProp toolbar;
void close();
void focus();
void blur();
// other browsing contexts
[Replaceable] readonly attribute WindowProxy frames;
[Replaceable] readonly attribute unsigned long length;
readonly attribute WindowProxy top;
[Replaceable] readonly attribute WindowProxy opener;
readonly attribute WindowProxy parent;
readonly attribute Element frameElement;
WindowProxy open(in optional DOMString url, in optional DOMString target, in optional DOMString features, in optional DOMString replace);
getter WindowProxy (in unsigned long index);
getter WindowProxy (in DOMString name);
// the user agent
readonly attribute Navigator navigator;
readonly attribute ApplicationCache applicationCache;
// user prompts
void alert(in DOMString message);
boolean confirm(in DOMString message);
DOMString prompt(in DOMString message, in optional DOMString default);
void print();
any showModalDialog(in DOMString url, in optional any argument);
// cross-document messaging
void postMessage(in any message, in DOMString targetOrigin);
void postMessage(in any message, in DOMString targetOrigin, in MessagePortArray ports);
// event handler IDL attributes
attribute Function onabort;
attribute Function onafterprint;
attribute Function onbeforeprint;
attribute Function onbeforeunload;
attribute Function onblur;
attribute Function oncanplay;
attribute Function oncanplaythrough;
attribute Function onchange;
attribute Function onclick;
attribute Function oncontextmenu;
attribute Function ondblclick;
attribute Function ondrag;
attribute Function ondragend;
attribute Function ondragenter;
attribute Function ondragleave;
attribute Function ondragover;
attribute Function ondragstart;
attribute Function ondrop;
attribute Function ondurationchange;
attribute Function onemptied;
attribute Function onended;
attribute Function onerror;
attribute Function onfocus;
attribute Function onformchange;
attribute Function onforminput;
attribute Function onhashchange;
attribute Function oninput;
attribute Function oninvalid;
attribute Function onkeydown;
attribute Function onkeypress;
attribute Function onkeyup;
attribute Function onload;
attribute Function onloadeddata;
attribute Function onloadedmetadata;
attribute Function onloadstart;
attribute Function onmessage;
attribute Function onmousedown;
attribute Function onmousemove;
attribute Function onmouseout;
attribute Function onmouseover;
attribute Function onmouseup;
attribute Function onmousewheel;
attribute Function onoffline;
attribute Function ononline;
attribute Function onpause;
attribute Function onplay;
attribute Function onplaying;
attribute Function onpagehide;
attribute Function onpageshow;
attribute Function onpopstate;
attribute Function onprogress;
attribute Function onratechange;
attribute Function onreadystatechange;
attribute Function onredo;
attribute Function onresize;
attribute Function onscroll;
attribute Function onseeked;
attribute Function onseeking;
attribute Function onselect;
attribute Function onshow;
attribute Function onstalled;
attribute Function onstorage;
attribute Function onsubmit;
attribute Function onsuspend;
attribute Function ontimeupdate;
attribute Function onundo;
attribute Function onunload;
attribute Function onvolumechange;
attribute Function onwaiting;
};
Window implements EventTarget;
windowframesselfThese attributes all return window.
The window, frames, and self IDL attributes must all
return the Window object's browsing
context's WindowProxy object.
User agents must raise a
SECURITY_ERR exception whenever any of the members of a
Window object are accessed by scripts whose
effective script origin is not the same as the
Window object's Document's effective
script origin, with the following exceptions:
location object
postMessage()
method with two arguments
postMessage()
method with three arguments
frames attribute
When a script whose effective script origin is not
the same as the Window object's Document's
effective script origin attempts to access that
Window object's methods or attributes, the user agent
must act as if any changes to the Window object's
properties, getters, setters, etc, were not present.
For members that return objects (including function objects),
each distinct effective script origin that is not the
same as the Window object's Document's
effective script origin must be provided with a
separate set of objects. These objects must have the prototype chain
appropriate for the script for which the objects are created (not
those that would be appropriate for scripts whose script's
global object is the Window object in
question).
For instance, if two frames containing Documents
from different origins access the same
Window object's postMessage() method, they
will get distinct objects that are not equal.
open( [ url [, target [, features [, replace ] ] ] ] )Opens a window to show url (defaults to
about:blank), and returns it. The target argument gives the name of the new
window. If a window exists with that name already, it is
reused. The replace attribute, if true, means
that whatever page is currently open in that window will be
removed from the window's session history. The features argument is ignored.
name [ = value ]Returns the name of the window.
Can be set, to change the name.
close()Closes the window.
The open() method on
Window objects provides a mechanism for navigating an existing browsing
context or opening and navigating an auxiliary browsing
context.
The method has four arguments, though they are all optional.
The first argument, url, must be a
valid URL for a page to load in the browsing
context. If no arguments are provided, or if the first argument is
the empty string, then the url argument defaults
to "about:blank". The argument must be resolved to an absolute
URL (or an error), relative to the entry
script's base URL,
when the method is invoked.
The second argument, target, specifies the
name of the browsing
context that is to be navigated. It must be a valid browsing
context name or keyword. If fewer than two arguments are
provided, then the name argument defaults to the
value "_blank".
The third argument, features, has no effect and is supported for historical reasons only.
The fourth argument, replace, specifies whether or not the new page will replace the page currently loaded in the browsing context, when target identifies an existing browsing context (as opposed to leaving the current page in the browsing context's session history). When three or fewer arguments are provided, replace defaults to false.
When the method is invoked, the user agent must first select a browsing context to navigate by applying the rules for choosing a browsing context given a browsing context name using the target argument as the name and the browsing context of the script as the context in which the algorithm is executed, unless the user has indicated a preference, in which case the browsing context to navigate may instead be the one indicated by the user.
For example, suppose there is a user agent that
supports control-clicking a link to open it in a new tab. If a user
clicks in that user agent on an element whose onclick handler uses the window.open() API to open a page in an
iframe, but, while doing so, holds the control key down, the user
agent could override the selection of the target browsing context to
instead target a new tab.
Then, the user agent must navigate the selected browsing context to the absolute URL (or error) obtained from resolving url earlier. If the replace is true, then replacement must be enabled; otherwise, it must not be enabled unless the browsing context was just created as part of the rules for choosing a browsing context given a browsing context name. The navigation must be done with the browsing context of the entry script as the source browsing context.
The method must return the WindowProxy object of the
browsing context that was navigated, or null if no
browsing context was navigated.
The name attribute of
the Window object must, on getting, return the current
name of the browsing context, and, on setting, set the
name of the browsing context to the new value.
The name gets reset when the browsing context is navigated to another domain.
The close()
method on Window objects should, if the corresponding
browsing context A is an
auxiliary browsing context that was created by a script
(as opposed to by an action of the user), and if the browsing context of the
script that invokes the method
is allowed to navigate the browsing
context A, close the browsing
context A (and may discard it too).
lengthReturns the number of child browsing contexts.
Returns the indicated child browsing context.
The length IDL
attribute on the Window interface must return the
number of child browsing
contexts that are nested through elements that are in the Document that is the
active document of that Window object, if
that Window's browsing context shares the
same event loop as the script's browsing
context of the entry script accessing the IDL
attribute; otherwise, it must return zero.
The indices of the supported indexed properties on
the Window object at any instant are the numbers in the
range 0 .. n-1, where n is the number returned by the length IDL attribute. If n is zero then there are no supported indexed
properties.
When a Window object is indexed to retrieve an indexed
property index, the value returned must be
the indexth child browsing context
of the Document that is nested through an element that
is in the Document,
sorted in the tree order of the elements nesting those
browsing contexts.
These properties are the dynamic nested browsing context properties.
Window objectReturns the indicated child browsing context.
The Window interface supports named properties. The names of the
supported named properties at any moment consist of:
name content attribute
for all a, applet, area,
embed, form, frame,
frameset, iframe, img, and
object elements in the active document
that have a name content attribute, andid content
attribute of any HTML element in
the active document with an id content attribute.When the Window
object is indexed for property retrieval using a name name, then the user agent must return the value
obtained using the following steps:
Let elements be the list of named elements with the name name in the active document.
There will be at least one such element, by definition.
If elements contains an iframe
element, then return the WindowProxy object of the
nested browsing context represented by the first such
iframe element in tree order, and abort
these steps.
Otherwise, if elements has only one element, return that element and abort these steps.
Otherwise return an HTMLCollection rooted at the
Document node, whose filter matches only named elements with
the name name.
Named elements with the name name, for the purposes of the above algorithm, are those that are either:
A browsing context has a strong reference to each of
its Documents and its WindowProxy object,
and the user agent itself has a strong reference to its top-level browsing
contexts.
A Document has a strong reference to each of its
views and their AbstractView
objects.
Each script has a strong reference to its browsing context and its document.
When a browsing context is to discard a
Document, the user agent must run the following
steps:
Set the Document's salvageable state to
false.
Run any unloading document cleanup steps for
the Document that are defined by this specification or
any other relevant specifications.
Remove any tasks
associated with the Document in any task
source, without running those tasks.
Discard
all the child browsing
contexts of the Document.
Lose the strong reference from the Document's
browsing context to the
Document.
The browsing context's default
view's Window object has a strong reference to its
Document object through the document attribute of the
AbstractView interface. Thus, references from other
scripts to either of those objects will keep both alive. [DOMVIEWS]
Whenever a Document object is discarded, it is also removed from
the list of the worker's Documents of each
worker whose list contains that Document.
When a browsing context is
discarded, the strong reference from the user agent itself to
the browsing context must be severed, and all the
Document objects for all the entries in the
browsing context's session history must be discarded as well.
User agents may discard top-level browsing contexts at any time (typically,
in response to user requests, e.g. when a user closes a window
containing one or more top-level browsing contexts). Other browsing contexts must be discarded
once their WindowProxy object is eligible for garbage
collection.
To allow Web pages to integrate with Web browsers, certain Web browser interface elements are exposed in a limited way to scripts in Web pages.
Each interface element is represented by a BarProp
object:
interface BarProp {
attribute boolean visible;
};
locationbar . visibleReturns true if the location bar is visible; otherwise, returns false.
menubar . visibleReturns true if the menu bar is visible; otherwise, returns false.
personalbar . visibleReturns true if the personal bar is visible; otherwise, returns false.
scrollbars . visibleReturns true if the scroll bars are visible; otherwise, returns false.
statusbar . visibleReturns true if the status bar is visible; otherwise, returns false.
toolbar . visibleReturns true if the toolbar is visible; otherwise, returns false.
The visible attribute, on getting, must return either true or a value determined by the user agent to most accurately represent the visibility state of the user interface element that the object represents, as described below. On setting, the new value must be discarded.
The following BarProp objects exist for each
Document object in a browsing
context. Some of the user interface elements represented by
these objects might have no equivalent in some user agents; for
those user agents, except when otherwise specified, the object must
act as if it was present and visible (i.e. its visible attribute must return
true).
BarProp objectBarProp objectBarProp objectBarProp objectBarProp objectvisible attribute may return
false).BarProp objectvisible attribute may return
false).The locationbar
attribute must return the location bar BarProp
object.
The menubar
attribute must return the menu bar BarProp
object.
The personalbar
attribute must return the personal bar BarProp
object.
The scrollbars
attribute must return the scrollbar BarProp
object.
The statusbar attribute
must return the status bar BarProp
object.
The toolbar
attribute must return the toolbar BarProp
object.
WindowProxy objectAs mentioned earlier, each browsing context has a
WindowProxy object. This object is unusual
in that all operations that would be performed on it must be
performed on the Window object of the browsing
context's active document instead. It is thus
indistinguishable from that Window object in every way
until the browsing context is navigated.
There is no WindowProxy interface object.
The WindowProxy object allows scripts
to act as if each browsing context had a single
Window object, while still keeping separate
Window objects for each Document.
In the following example, the variable x is
set to the WindowProxy object returned by the window accessor on the global object. All
of the expressions following the assignment return true, because in
every respect, the WindowProxy object acts like the
underlying Window object.
var x = window; x instanceof Window; // true x === this; // true
The origin of a resource and the effective script origin of a resource are both either opaque identifiers or tuples consisting of a scheme component, a host component, a port component, and optionally extra data.
The extra data could include the certificate of the site when using encrypted connections, to ensure that if the site's secure certificate changes, the origin is considered to change as well.
These characteristics are defined as follows:
The origin and effective script origin of the URL is whatever is returned by the following algorithm:
Let url be the URL for which the origin is being determined.
Parse url.
If url identifies a resource that is its own trust domain (e.g. it identifies an e-mail on an IMAP server or a post on an NNTP server) then return a globally unique identifier specific to the resource identified by url, so that if this algorithm is invoked again for URLs that identify the same resource, the same identifier will be returned.
If url does not use a server-based naming authority, or if parsing url failed, or if url is not an absolute URL, then return a new globally unique identifier.
Let scheme be the <scheme> component of url, converted to ASCII lowercase.
If the UA doesn't support the protocol given by scheme, then return a new globally unique identifier.
If scheme is "file", then the user agent may return a
UA-specific value.
Let host be the <host> component of url.
Apply the IDNA ToASCII algorithm to host, with both the AllowUnassigned and UseSTD3ASCIIRules flags set. Let host be the result of the ToASCII algorithm.
If ToASCII fails to convert one of the components of the string, e.g. because it is too long or because it contains invalid characters, then return a new globally unique identifier. [RFC3490]
Let host be the result of converting host to ASCII lowercase.
If there is no <port> component, then let port be the default port for the protocol given by scheme. Otherwise, let port be the <port> component of url.
Return the tuple (scheme, host, port).
In addition, if the URL is in fact associated with
a Document object that was created by parsing the
resource obtained from fetching URL, and this was
done over a secure connection, then the server's secure
certificate may be added to the origin as additional data.
The origin and effective script origin of a script are determined from another resource, called the owner:
script elementDocument to which the
script element belongs.Document to which the
attribute node belongs.javascript: URL that was returned as the
location of an HTTP redirect (or equivalent in
other protocols)javascript: URL.javascript: URL in an attributeDocument of the element on
which the attribute is found.javascript: URL in a style sheetjavascript: URL to which a browsing
context is being navigated,
the URL having been provided by the user (e.g. by using a
bookmarklet)Document of the browsing
context's active document.javascript: URL to which a browsing
context is being navigated,
the URL having been declared in markupDocument of the element
(e.g. an a or area element) that
declared the URL.javascript: URL to which a browsing
context is being navigated,
the URL having been provided by scriptThe origin of the script is then equal to the origin of the owner, and the effective script origin of the script is equal to the effective script origin of the owner.
Document objects and imagesDocument is in a
browsing context whose sandboxed origin
browsing context flag was set when the
Document was createdDocument was generated from a resource
labeled as text/html-sandboxedDocument is created.Document or image was returned by the
XMLHttpRequest APIXMLHttpRequest object. [XHR]Document or image was generated from a
javascript:
URLjavascript: URL.Document or image was served over the
network and has an address that uses a URL scheme with a
server-based naming authorityDocument or the URL of the image, as
appropriate.Document or image was generated from a
data: URL that was returned as the location
of an HTTP redirect (or equivalent in
other protocols)data: URL.Document or image was generated from a
data: URL found in another
Document or in a scriptDocument or script that initiated the navigation to that URL.Document has the address
"about:blank"Document is the origin it was
assigned when its browsing context was created.Document is an iframe srcdoc documentDocument is the
origin of the Document's browsing
context's browsing context container's
Document.Document or image was obtained in some
other manner (e.g. a data: URL typed in by
the user, a Document created using the createDocument()
API, etc)Document or image is created.When a Document is created, its effective
script origin is initialized to the origin of
the Document. However, the document.domain attribute can
be used to change it.
audio and video elementsIf value of the media element's currentSrc attribute is the
empty string, the origin is the same as the
origin of the element's Document's
origin.
Otherwise, the origin is equal to the
origin of the absolute URL given by the
media element's currentSrc attribute.
The Unicode serialization of an origin is the string obtained by applying the following algorithm to the given origin:
If the origin in question is not a
scheme/host/port tuple, then return the literal string "null" and abort these steps.
Otherwise, let result be the scheme part of the origin tuple.
Append the string "://" to result.
Apply the IDNA ToUnicode algorithm to each component of the host part of the origin tuple, and append the results — each component, in the same order, separated by U+002E FULL STOP characters (.) — to result. [RFC3490]
If the port part of the origin tuple gives a port that is different from the default port for the protocol given by the scheme part of the origin tuple, then append a U+003A COLON character (:) and the given port, in base ten, to result.
Return result.
The ASCII serialization of an origin is the string obtained by applying the following algorithm to the given origin:
If the origin in question is not a
scheme/host/port tuple, then return the literal string "null" and abort these steps.
Otherwise, let result be the scheme part of the origin tuple.
Append the string "://" to result.
Apply the IDNA ToASCII algorithm the host part of the origin tuple, with both the AllowUnassigned and UseSTD3ASCIIRules flags set, and append the results result.
If ToASCII fails to convert one of the components of the string, e.g. because it is too long or because it contains invalid characters, then return the empty string and abort these steps. [RFC3490]
If the port part of the origin tuple gives a port that is different from the default port for the protocol given by the scheme part of the origin tuple, then append a U+003A COLON character (:) and the given port, in base ten, to result.
Return result.
Two origins are said to be the same origin if the following algorithm returns true:
Let A be the first origin being compared, and B be the second origin being compared.
If A and B are both opaque identifiers, and their value is equal, then return true.
Otherwise, if either A or B or both are opaque identifiers, return false.
If A and B have scheme components that are not identical, return false.
If A and B have host components that are not identical, return false.
If A and B have port components that are not identical, return false.
If either A or B have additional data, but that data is not identical for both, return false.
Return true.
domain [ = domain ]Returns the current domain used for security checks.
Can be set to a value that removes subdomains, to change the effective script origin to allow pages on other subdomains of the same domain (if they do the same thing) to access each other.
The domain
attribute on Document objects must be initialized to
the document's domain, if it has one, and the empty
string otherwise. If the value is an IPv6 address, then the square
brackets from the host portion of the <host> component must be omitted from
the attribute's value.
On getting, the attribute must return its current
value, unless the document was created by
XMLHttpRequest, in which case it must throw an
INVALID_ACCESS_ERR exception.
On setting, the user agent must run the following algorithm:
If the document was created by XMLHttpRequest,
throw an INVALID_ACCESS_ERR exception and abort these
steps.
If the new value is an IP address, let new value be the new value. Otherwise, apply the IDNA ToASCII algorithm to the new value, with both the AllowUnassigned and UseSTD3ASCIIRules flags set, and let new value be the result of the ToASCII algorithm.
If ToASCII fails to convert one of the components of the
string, e.g. because it is too long or because it contains invalid
characters, then throw a SECURITY_ERR exception and abort
these steps. [RFC3490]
If new value is not exactly equal to the
current value of the document.domain attribute, then
run these substeps:
If the current value is an IP address, throw a
SECURITY_ERR exception and abort these steps.
If new value, prefixed by a U+002E FULL
STOP (.), does not exactly match the end of the current value,
throw a SECURITY_ERR exception and abort these
steps.
If new value matches a suffix in the
Public Suffix List, or, if new value,
prefixed by a U+002E FULL STOP (.), matches the end of a
suffix in the Public Suffix List, then throw a
SECURITY_ERR exception and abort these steps. [PSL]
Suffixes must be compared after applying the IDNA ToASCII algorithm to them, with both the AllowUnassigned and UseSTD3ASCIIRules flags set, in an ASCII case-insensitive manner. [RFC3490]
Release the storage mutex.
Set the attribute's value to new value.
Set the host part of the effective script origin
tuple of the Document to new
value.
Set the port part of the effective script origin
tuple of the Document to "manual override" (a value
that, for the purposes of comparing
origins, is identical to "manual override" but not
identical to any other value).
The domain of a
Document is the host part of the document's
origin, if that is a scheme/host/port tuple. If it
isn't, then the document does not have a domain.
The domain
attribute is used to enable pages on different hosts of a domain to
access each others' DOMs.
Do not use the document.domain attribute when
using shared hosting. If an untrusted third party is able to host an
HTTP server at the same IP address but on a different port, then the
same-origin protection that normally protects two different sites on
the same host will fail, as the ports are ignored when comparing
origins after the document.domain attribute has
been used.
The sequence of Documents in a browsing
context is its session history.
History objects provide a representation of the
pages in the session history of browsing contexts. Each browsing
context, including nested browsing contexts, has a distinct session
history.
Each Document object in a browsing
context's session history is associated with a
unique instance of the History object, although they
all must model the same underlying session history.
The history attribute
of the Window interface must return the object
implementing the History interface for that
Window object's Document.
History objects represent their browsing
context's session history as a flat list of session history entries. Each
session history entry consists of either a
URL or a state object, or both, and may in addition have a title, a
Document object, form data, a scroll position, and
other information associated with it.
This does not imply that the user interface need be linear. See the notes below.
Titles associated with session history entries need not have any relation
with the current title of the
Document. The title of a session history
entry is intended to explain the state of the document at
that point, so that the user can navigate the document's
history.
URLs without associated state objects are added to the session history as the user (or script) navigates from page to page.
A state object is an object representing a user interface state.
Pages can add state objects between their entry in the session history and the next ("forward") entry. These are then returned to the script when the user (or script) goes back in the history, thus enabling authors to use the "navigation" metaphor even in one-page applications.
At any point, one of the entries in the session history is the
current entry. This is the entry representing the
active document of the browsing
context. The current entry is usually an entry
for the location of the
Document. However, it can also be one of the entries
for state objects added to the
history by that document.
Entries that consist of state
objects share the same Document as the entry for
the page that was active when they were added.
Contiguous entries that differ just by fragment identifier also
share the same Document.
All entries that share the same
Document (and that are therefore merely different
states of one particular document) are contiguous by definition.
User agents may discard
the Document objects of entries other than the
current entry 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 Document objects and when they should
cache them.
Entries that have had their Document 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 Document object with it
must share the new object as well.
History interfaceinterface History {
readonly attribute long length;
void go(in optional long delta);
void back();
void forward();
void pushState(in any data, in DOMString title, in optional DOMString url);
void replaceState(in any data, in DOMString title, in optional DOMString url);
};
history . lengthReturns the number of entries in the joint session history.
history . go( [ delta ] )Goes back or forward the specified number of steps in the joint session history.
A zero delta will reload the current page.
If the delta is out of range, does nothing.
history . back()Goes back one step in the joint session history.
If there is no previous page, does nothing.
history . forward()Goes forward one step in the joint session history.
If there is no next page, does nothing.
history . pushState(data, title [, url ] )Pushes the given data onto the session history, with the given title, and, if provided, the given URL.
history . replaceState(data, title [, url ] )Updates the current entry in the session histor to have the given data, title, and, if provided, URL.
The joint session history of a History
object is the union of all the session
histories of all browsing
contexts of all the fully active
Document objects that share the History
object's top-level browsing context, with all the
entries that are current entries
in their respective session
histories removed except for the current entry of the
joint session history.
The current entry of the joint session history is the entry that most recently became a current entry in its session history.
Entries in the joint session history are ordered chronologically by the time they were added to their respective session histories. (Since all these browsing contexts by definition share an event loop, there is always a well-defined sequential order in which their session histories 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).
The length
attribute of the History interface must return the
number of entries in the joint session history.
The actual entries are not accessible from script.
When the go(delta) method is invoked, if the
argument to the method was omitted or has the value zero, the user
agent must act as if the location.reload() method was
called instead. Otherwise, the user agent must traverse the
history by a delta whose value is the value of the method's
argument.
When the back()
method is invoked, the user agent must traverse the history by
a delta −1.
When the forward()method is
invoked, the user agent must traverse the history by a
delta +1.
To traverse the history by a delta delta, the user agent must queue a task to run the following steps. The task source for the queued task is the history traversal task source.
Let delta be the argument to the method.
If the index of the current entry of the joint session history plus delta is less than zero or greater than or equal to the number of items in the joint session history, then the user agent must do nothing.
Let specified entry be the entry in the joint session history whose index is the sum of delta and the index of the current entry of the joint session history.
Let specified browsing context be the browsing context of the specified entry.
Traverse the history of the specified browsing context to the specified entry.
When the user navigates through a browsing context, e.g. using a browser's back and forward buttons, the user agent must traverse the history by a delta equivalent to the action specified by the user.
The pushState(data, title, url) method adds a state object entry to
the history.
The replaceState(data, title, url) method updates the state object,
title, and optionally the URL of the current
entry in the history.
When either of these methods is invoked, the user agent must run the following steps:
Let clone data be a structured clone of the specified data. If this throws an exception, then rethrow that exception and abort these steps.
If a third argument is specified, run these substeps:
SECURITY_ERR exception
and abort these steps.SECURITY_ERR exception and abort these
steps.SECURITY_ERR exception and abort
these steps. (This prevents sandboxed content from spoofing other
pages on the same origin.)For the purposes of the comparisons in the above substeps, the <path> and <query> components can only be the same if the URLs use a hierarchical <scheme>.
If the method invoked was the pushState() method:
Remove all the entries in the browsing context's session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.
This doesn't necessarily have to affect the user agent's user interface.
Remove any tasks queued by the history traversal task source.
Add a state object entry to the session history, after the current entry, with cloned data as the state object, the given title as the title, and, if the third argument is present, the absolute URL that was found earlier in this algorithm as the URL of the entry.
Update the current entry to be the this newly added entry.
Otherwise, if the method invoked was the replaceState() method:
Update the current entry in the session history so that cloned data is the entry's new state object, the given title is the new title, and, if the third argument is present, the absolute URL that was found earlier in this algorithm is the entry's new URL.
If the third argument is present, set the document's current address to the absolute URL that was found earlier in this algorithm.
Since this is neither a navigation of the browsing
context nor a history
traversal, it does not cause a hashchange event to be fired.
The title is purely advisory. User agents might use the title in the user interface.
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 Document 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.)
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.
A static page implementing the x=5 position in such a game could look like the following:
<!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>
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:
<!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)">Advance to 6</a> or
<a href="?x=4" onclick="go(-1)">retreat to 4</a>?
</p>
<script>
var currentPage = 5; // prefilled by server
function go(d) {
history.pushState(currentPage, 'Line Game - ' + currentPage, '?x=' + currentPage);
setupPage(currentPage + d);
}
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>
In systems without script, this still works like the previous example. However, users that do 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.
In the example above, the data argument to
the pushState() 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.
Applications might not use the same title for a session
history entry as the value of the document's
title element at that time. For example, here is a
simple page that shows a block in the title 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.
<!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="recover(event.state)">
<FORM NAME=F>
State: <OUTPUT NAME=I>1</OUTPUT> <INPUT VALUE="Increment" TYPE=BUTTON ONCLICK="inc()">
</FORM>
Location interfaceEach Document object in a browsing
context's session history is associated with a unique
instance of a Location object.
location [ = value ]location [ = value ]Returns a Location object with the current page's location.
Can be set, to navigate to another page.
The location attribute
of the HTMLDocument interface must return the
Location object for that Document object,
if it is in a browsing context, and null otherwise.
The location
attribute of the Window interface must return the
Location object for that Window object's
Document.
Location objects provide a representation of their document's current
address, and allow the current entry of the
browsing context's session history to be changed, by
adding or replacing entries in the history object.
interface Location {
stringifier attribute DOMString href;
void assign(in DOMString url);
void replace(in DOMString url);
void reload();
// URL decomposition IDL attributes
attribute DOMString protocol;
attribute DOMString host;
attribute DOMString hostname;
attribute DOMString port;
attribute DOMString pathname;
attribute DOMString search;
attribute DOMString hash;
// resolving relative URLs
DOMString resolveURL(in DOMString url);
};
href [ = value ]Returns the current page's location.
Can be set, to navigate to another page.
assign(url)Navigates to the given page.
replace(url)Removes the current page from the session history and navigates to the given page.
reload()Reloads the current page.
resolveURL(url)Resolves the given relative URL to an absolute URL.
The href
attribute must return the current address of the associated
Document object, as an absolute URL.
On setting, the user agent
must act as if the assign()
method had been called with the new value as its argument.
When the assign(url) method is invoked, the UA must
resolve the argument, relative to
the entry script's base
URL, and if that is successful, must navigate
the browsing context to the specified url. If the browsing context's
session history contains only one
Document, and that was the about:blank
Document created when the browsing context
was created, then the navigation must be done with
replacement enabled.
When the replace(url) method is invoked, the UA must
resolve the argument, relative to
the entry script's base
URL, and if that is successful, navigate the
browsing context to the specified url with replacement enabled.
Navigation for the assign() and replace() methods must be done
with the browsing
context of the script that invoked the method as the
source browsing context.
If the resolving step of the
assign() and replace() methods is not
successful, then the user agent must instead throw a
SYNTAX_ERR exception.
When the reload() method is
invoked, the user agent must run the appropriate steps from the
following list:
resize event in response to the user
resizing the browsing contextRepaint the browsing context and abort these steps.
Navigate the browsing context to the document's current address with replacement enabled. The source browsing context must be the browsing context being navigated.
When a user requests that the current page be reloaded through a
user interface element, the user agent should navigate
the browsing context to the same resource as
Document, with replacement enabled. 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.
The Location interface also has the complement of
URL decomposition IDL attributes, protocol, host, port, hostname, pathname, search, and hash. These must follow the rules given for URL decomposition IDL
attributes, with the input
being the current
address of the associated Document object, as an
absolute URL (same as the href attribute), and the common setter action being the
same as setting the href
attribute to the new output value.
The resolveURL(url) method must resolve its url argument, relative
to the entry script's base URL, and if that succeeds, return the resulting
absolute URL. If it fails, it must throw a
SYNTAX_ERR exception instead.
User agents must raise a
SECURITY_ERR exception whenever any of the members of a
Location object are accessed by scripts whose
effective script origin is not the same as the Location object's associated
Document's effective script origin, with
the following exceptions:
href setter, if the
script is running in a browsing context that is
allowed to navigate the browsing context with which
the Location object is associated
replace() method,
if the script is running in a browsing context that is
allowed to navigate the browsing context with which
the Location object is associated
This section is non-normative.
The History interface is not meant to place
restrictions on how implementations represent the session history to
the user.
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
history object are derived from the
actual session history as seen from the user's perspective.
Similarly, a page containing two iframes has a history object distinct from the
iframes' history
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.
Security: It is suggested that to avoid letting
a page "hijack" the history navigation facilities of a UA by abusing
pushState(), 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.
In addition, a user agent could ignore calls to pushState() 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.
Certain actions cause the browsing context to navigate to a new resource. Navigation always involves source browsing context, which is the browsing context which was responsible for starting the navigation.
For example, following a hyperlink, form submission, and the window.open() and location.assign() methods can all
cause a browsing context to navigate.
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.
When a browsing context is navigated to a new resource, the user agent must run the following steps:
Release the storage mutex.
If the source browsing context is not the same as the browsing context being navigated, and the source browsing context is not one of the ancestor browsing contexts of the browsing context being navigated, and the browsing context being navigated is not both a top-level browsing context and one of the ancestor browsing contexts of the source browsing context, and the source browsing context had its sandboxed navigation browsing context flag set when its active document was created, then abort these steps.
Otherwise, if the browsing context being navigated is a top-level browsing context, and is one of the ancestor browsing contexts of the source browsing context, and the source browsing context had its sandboxed top-level navigation browsing context flag set when its active document was created, then abort these steps.
In both cases, the user agent may additionally offer to open the new resource in a new top-level browsing context or in the top-level browsing context of the source browsing context, at the user's option, in which case the user agent must navigate that designated top-level browsing context to the new resource as if the user had requested it independently.
If the source browsing context is the same as the browsing context being navigated, and this browsing context has its seamless browsing context flag set, then find the nearest ancestor browsing context that does not have its seamless browsing context flag set, and continue these steps as if that browsing context was the one that was going to be navigated instead.
If there is a preexisting attempt to navigate the browsing context, and the source browsing context is the same as the browsing context being navigated, and that attempt is currently running the unload a document algorithm, and the origin of the URL of the resource being loaded in that navigation is not the same origin as the origin of the URL of the resource being loaded in this navigation, then abort these steps without affecting the preexisting attempt to navigate the browsing context.
If there is a preexisting attempt to navigate the
browsing context, and either that attempt has not yet
matured (i.e. it has
not passed the point of making its Document the
active document), or that navigation's resource is not
to be fetched using HTTP GET or equivalent, or its
resource's absolute URL differs from this attempt's by
more than the presence, absence, or value of the <fragment> component, then cancel
that preexisting attempt to navigate the browsing
context.
Cancel any preexisting attempt to navigate the browsing context.
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.
Prompt to
unload the Document object. If the user
refused to allow the document to be unloaded, then
these steps must be aborted.
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 registered handler for the given scheme, then display the inline content and abort these steps.
In the case of a registered handler being used, the algorithm will be reinvoked with a new URL to handle the request.
If the new resource is to be fetched using HTTP GET or equivalent, then check if there are any relevant application caches that are identified by a URL with the same origin as the URL in question, and that have this URL as one of their entries, excluding entries marked as foreign. If so, then the user agent must then get the resource from the most appropriate application cache of those that match.
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.
Otherwise, fetch the new resource, if it has not already been obtained.
If the resource is being fetched using a method other than one equivalent to HTTP's GET, or, if the navigation algorithm was invoked as a result of the form submission algorithm, then the fetching algorithm must be invoked from the origin of the active document of the source browsing context, if any.
If the browsing context being navigated is a
child browsing context for an iframe or
object element, then the fetching
algorithm must be invoked from the iframe or
object element's browsing context scope
origin, if it has one.
At this point the user agents must return to whatever algorithm invoked the navigation steps and must continue these steps asynchronously.
If fetching the resource results in a redirect, return to the step labeled "fragment identifiers" with the new resource.
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.
If the resource was not fetched from an application cache, and was to be fetched using HTTP GET or equivalent, and its URL matches the fallback namespace of one or more relevant application caches, 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 or equivalent, or there was a DNS error), then:
Let candidate be the fallback resource specified for the fallback namespace in question. If multiple application caches match, the user agent must use the fallback of the most appropriate application cache of those that match.
If candidate is not marked as foreign, then the user agent must discard the failed load and instead continue along these steps using candidate as the resource. The document's address, 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.
If the document's out-of-band metadata (e.g. HTTP headers), not counting any type information (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.
Such processing might be triggered by, amongst other things, the following:
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.
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.
Let type be the sniffed type of the resource.
If the user agent has been configured to process resources of the given type using some mechanism other than rendering the content in a browsing context, then skip this step. Otherwise, if the type is one of the following types, jump to the appropriate entry in the following list, and process the resource as described there:
text/html"text/html-sandboxed"+xml"application/xml"text/xml"text/plain"Setting the document's
address: If there is no override URL, then any
Document created by these steps must have its address set to the
URL that was originally to be fetched, 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 the document's
address, 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 fallback
namespace). However, if there is an override
URL, then any Document created by these steps
must have its address
set to that URL instead.
An override URL
is set when dereferencing a
javascript: URL.
Creating a new
Document object: When a Document
is created as part of the above steps, a new set of views along with the associated
Window object must be created and associated with the
Document, with one exception: if the browsing
context's only entry in its session history is
the about:blank Document that was added
when the browsing context was created, and navigation
is occurring with replacement enabled, and that
Document has the same origin as the new
Document, then the Window object and
associated views of that
Document must be used instead, and the document attribute of the
AbstractView objects of those views must be changed to point to the new
Document instead.
Otherwise, the document's type 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.
Some of the sections below, to which the above algorithm defers in certain cases, require the user agent to update the session history with the new page. When a user agent is required to do this, it must queue a task to run the following steps:
Unload the
Document object of the current entry,
with the recycle parameter set to
false.
Replace the Document of the entry being
updated, and any other entries that referenced the same
document as that entry, with the new
Document.
Traverse the history to the new entry.
This can only happen if the entry being updated
is no the current entry, and can never happen with
replacement enabled. (It happens when the user
tried to traverse to a session history entry that no longer had
a Document object.)
Remove all the entries in the browsing context's session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.
This doesn't necessarily have to affect the user agent's user interface.
Remove any tasks queued by the history traversal task source.
Append a new entry at the end of the History
object representing the new resource and its
Document object and related state.
Traverse the history to the new entry. If the navigation was initiated with replacement enabled, then the traversal must itself be initiated with replacement enabled.
The navigation algorithm has now matured.
Fragment identifier loop: Spin the event loop 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.)
If the Document object has no parser, or its
parser has stopped parsing, or
the user agent has reason to believe the user is no longer
interested in scrolling to the fragment identifier, then abort
these steps.
Scroll to the fragment identifier given in the document's current address. If this fails to find an indicated part of the document, then return to the fragment identifier loop step.
The task source for this task is the networking task source.
When an HTML document is to be loaded in a browsing
context, the user agent must queue a task to
create a Document object, mark it as being
an HTML document, create an
HTML parser, and associate it with the document. Each
task that the networking
task source places on the task queue while the
fetching algorithm runs must then fill
the parser's input stream with the fetched bytes and
cause the HTML parser to perform the appropriate
processing of the input stream.
The input stream converts bytes into characters for use in the tokenizer. This process relies, in part, on character encoding information found in the real Content-Type metadata of the resource; the "sniffed type" is not used for this purpose.
When no more bytes are available, the user agent must queue
a task for the parser to process the implied EOF character,
which eventually causes a load event
to be fired.
After creating the Document object, but before any
script execution, certainly before the parser stops, the user agent must update the session
history with the new page.
Application cache selection happens in the HTML parser.
The task source for the two tasks mentioned in this section must be the networking task source.
When faced with displaying an XML file inline, user agents must
first create a Document object, following
the requirements of the XML and Namespaces in XML recommendations,
RFC 3023, DOM3 Core, and other relevant specifications. [XML] [XMLNS] [RFC3023] [DOMCORE]
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 document's character encoding must be set to that character encoding.
If the root element, as parsed according to the XML
specifications cited above, is found to be an html
element with an attribute manifest whose value is not the
empty string, then, as soon as the element is inserted into the document, the user
agent must resolve the value of
that attribute relative to that element, and if that is successful,
must run the application cache
selection algorithm with the resulting absolute
URL with any <fragment> component removed as
the manifest URL, and passing in the newly-created
Document. 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 inserted into the document, the user agent must run
the application cache selection
algorithm with no manifest, and passing in the
Document.
Because the processing of the manifest attribute happens
only once the root element is parsed, any URLs referenced by
processing instructions before the root element (such as <?xml-stylesheet?> and <?xbl?> PIs) will be fetched from the network and
cannot be cached.
User agents may examine the namespace of the root
Element node of this Document 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 the next step (labeled
"non-document content") in the navigate steps
above.
Otherwise, then, with the newly created Document,
the user agents must update the session history with the new
page. User agents may do this before the complete document
has been parsed (thus achieving incremental rendering), and
must do this before any scripts are to be executed.
Error messages from the parse process (e.g. XML namespace
well-formedness errors) may be reported inline by mutating the
Document.
When a plain text document is to be loaded in a browsing
context, the user agent should queue a task to
create a Document object, mark it as being
an HTML document, create an
HTML parser, 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 HTML parser's tokenizer
to the PLAINTEXT state. Each task that the networking task
source places on the task queue while the fetching algorithm runs must then fill the
parser's input stream with the fetched bytes and cause
the HTML parser to perform the appropriate processing
of the input stream.
The rules for how to convert the bytes of the plain text document into actual characters are defined in RFC 2046, RFC 2646, and subsequent versions thereof. [RFC2046] [RFC2646]
The document's character encoding must be set to the character encoding used to decode the document.
Upon creation of the Document object, the user agent
must run the application cache
selection algorithm with no manifest, and passing in the
newly-created Document.
When no more bytes are available, the user agent must queue
a task for the parser to process the implied EOF character,
which eventually causes a load event
to be fired.
After creating the Document object, but potentially
before the page has finished parsing, the user agent must
update the session history with the new page.
User agents may add content to the head element of
the Document, e.g. linking to a style sheet or an XBL
binding, providing script, giving the document a title,
etc.
The task source for the two tasks mentioned in this section must be the networking task source.
When an image resource is to be loaded in a browsing
context, the user agent should create a
Document object, mark it as being an HTML document, append an
html element to the Document, append a
head element and a body element to the
html element, append an img to the
body element, and set the src attribute of the img
element to the address of the image.
Then, the user agent must act as if it had stopped parsing.
Upon creation of the Document object, the user agent
must run the application cache
selection algorithm with no manifest, and passing in the
newly-created Document.
After creating the Document object, but potentially
before the page has finished fully loading, the user agent must
update the session history with the new page.
User agents may add content to the head element of
the Document, or attributes to the img
element, e.g. to link to a style sheet or an XBL binding, to provide
a script, to give the document a title, etc.
When a resource that requires an external resource to be rendered
is to be loaded in a browsing context, the user agent
should create a Document object, mark it
as being an HTML document,
append an html element to the Document,
append a head element and a body element
to the html element, append an embed to
the body element, and set the src attribute of the
embed element to the address of the resource.
Then, the user agent must act as if it had stopped parsing.
Upon creation of the Document object, the user agent
must run the application cache
selection algorithm with no manifest, and passing in the
newly-created Document.
After creating the Document object, but potentially
before the page has finished fully loading, the user agent must
update the session history with the new page.
User agents may add content to the head element of
the Document, or attributes to the embed
element, e.g. to link to a style sheet or an XBL binding, or to give
the document a title.
When the user agent is to display a user agent page inline in a
browsing context, the user agent should create a
Document object, mark it as being an HTML document, and then either
associate that Document with a custom rendering that is
not rendered using the normal Document rendering rules,
or mutate that Document until it represents the content
the user agent wants to render.
Once the page has been set up, the user agent must act as if it had stopped parsing.
Upon creation of the Document object, the user agent
must run the application cache
selection algorithm with no manifest, passing in the
newly-created Document.
After creating the Document object, but potentially
before the page has been completely set up, the user agent must
update the session history with the new page.
When a user agent is supposed to navigate to a fragment identifier, then the user agent must queue a task to run the following steps:
Remove all the entries in the browsing context's session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.
This doesn't necessarily have to affect the user agent's user interface.
Remove any tasks queued by the history traversal task source.
Append a new entry at the end of the History
object representing the new resource and its Document
object and related state. Its URL must be set to the
address to which the user agent was navigating. The title must be left
unset.
Traverse the history to the new entry. This will scroll to the fragment identifier given in what is now the document's current address.
If the scrolling fails because the relevant ID has not yet been parsed, then the original navigation algorithm will take care of the scrolling instead, as the last few steps of its update the session history with the new page algorithm.
When the user agent is required to scroll to the fragment identifier, it must change the scrolling position of the document, or perform some other action, such that the indicated part of the document is brought to the user's attention. If there is no indicated part, then the user agent must not scroll anywhere.
The indicated part of the document 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 MIME type
used by the Document (for example, the processing of
fragment identifiers for XML MIME
types is the responsibility of RFC3023). [RFC3023]
For HTML documents (and HTML MIME types), the following processing model must be followed to determine what the indicated part of the document is.
Parse the URL, and let fragid be the <fragment> component of the URL.
If fragid is the empty string, then the indicated part of the document is the top of the document; stop the algorithm here.
Let decoded fragid be the result of expanding any sequences of percent-encoded octets in fragid 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.
If this step was not skipped and there is an element in the DOM that has an ID exactly equal to decoded fragid, then the first such element in tree order is the indicated part of the document; stop the algorithm here.
If there is an a element in the DOM that has a
name attribute whose value is
exactly equal to fragid (not decoded fragid), then the first such element in tree
order is the indicated part of the document; stop the
algorithm here.
If fragid is an ASCII
case-insensitive match for the string top, then the indicated part of the
document is the top of the document; stop the algorithm
here.
Otherwise, there is no indicated part of the document.
For the purposes of the interaction of HTML with Selectors' :target pseudo-class, the
target element is the indicated part of the
document, if that is an element; otherwise there is no
target element. [SELECTORS]