This is revision 1.2852.
Status: Working draft
The sequence of Document
s 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 context, 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.
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.
When state object entries are added, a URL can be provided. This
URL is used to replace the state object entry if the
Document
is evicted.
History
interfaceinterface History { readonly attribute long length; void go(optional in long delta); void back(); void forward(); void pushState(in any data, in DOMString title, optional in DOMString url); void clearState(); };
history
. length
Returns 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
. clearState
()Removes all state objects for the current page from the session history.
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.
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 current entry of the joint session history is the entry that was the most recently became a current entry in its session history.
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.
The go(delta)
method causes the UA to run the
following steps:
If the argument to the method was omitted or has the value
zero, then act as if the location.reload()
method was
called instead, and abort these steps.
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
translate this action into the equivalent invocations of the history.go(delta)
method on the various affected window
objects.
Some of the other members of the History
interface
are defined in terms of the go()
method, as follows:
Member | Definition |
---|---|
back() |
Must do the same as go(-1) |
forward() |
Must do the same as go(1) |
The pushState(data, title, url)
method adds a state object to the
history.
When this method 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 the pushState()
steps.SECURITY_ERR
exception and abort the pushState()
steps.For the purposes of the comparison in the above substeps, the <path> and <query> components can only be the same if the URLs use a hierarchical <scheme>.
Remove from the session history any entries for
the Document
from the entry after the current
entry up to the last entry in the session history that
references the same Document
object, if any. If the
current entry is the last entry in the session
history, or if there are no entries after the current
entry that reference the same Document
object,
then no entries are removed.
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.
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 not a navigation of the browsing
context, it does not cause a hashchange
event to be fired.
Update the current entry to be the this newly added entry.
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.)
The clearState()
method removes all the state objects for the Document
object from the session history.
When this method is invoked, the user agent must remove from the
session history all the entries from the first state object entry
for that Document
object up to the last entry that
references that same Document
object, if any.
Then, if the current entry was removed in the
previous step, the current entry must be set to the
last entry for that Document
object in the session
history.
When an entry in the session history is activated (which happens during session history traversal, as described above), the user agent must run the following steps:
If the entry is a state object entry, let state be a structured clone of that state object. Otherwise, let state be null.
Run the appropriate steps according to the conditions described:
Queue a task to fire a popstate
event in no
namespace on the Window
object of the
Document
, using the PopStateEvent
interface, with the state
attribute set to the
value of state. This event must bubble but
not be cancelable and has no default action. The task
source for this task is the DOM manipulation task
source.
Let the Document
's pending state
object be state. (If there was already
a pending state object, the previous one is
discarded.)
The event will then be fired just after the load
event.
The pending state object must be initially null.
interface PopStateEvent : Event { readonly attribute any state; void initPopStateEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in any stateArg); void initPopStateEventNS(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in any stateArg); };
state
Returns the information that was provided to pushState()
.
The initPopStateEvent()
and initPopStateEventNS()
methods must initialize the event in a manner analogous to the
similarly-named methods in the DOM Events interfaces. [DOMEVENTS]
The state
attribute represents the context information for the event, or null,
if the state represented is the initial state of the
Document
.
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 readonly attribute DOMString href; void assign(in DOMString url); void replace(in DOMString url); void reload(); // URL decomposition 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 first 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 first 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 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 attributes, protocol
, host
, port
, hostname
, pathname
, search
, and hash
. These must follow the rules given for URL decomposition
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 first 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 iframe
s has a history
object distinct from the
iframe
s' 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 handlers that do not represent a clear user
action, or that are invoked in rapid succession.
Status: Last call for comments
ISSUE-63 (origin-req-scope) blocks progress to Last Call
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:
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 source browsing context has its sandboxed navigation browsing context flag set, then abort these steps. The user agent may 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.
Cancel any preexisting attempt to navigate the browsing context.
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 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.
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 HTTP, and the method
is not GET, then the user
agent must include an Origin
header whose value is determined as follows:
null
".If fetching the resource is synchronous (i.e. for javascript:
URLs and about:blank
), then this must be
synchronous, but if fetching the resource depends on external
resources, as it usually does for URLs that use HTTP or other
networking protocols, then at this point the user agents must
yield to whatever script invoked the navigation steps, if they
were invoked by script.
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
"+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 entry being updated with a new entry
representing the new resource and its Document
object and related state. The user agent may propagate state from
the old entry to the new entry (e.g. scroll position).
Traverse the history to the new entry.
Remove all the entries after the current
entry in the browsing context's
Document
object's History
object.
This doesn't necessarily have to affect the user agent's user interface.
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, remove the entry immediately before the new current entry in the session history.
If the document's address has a fragment identifier, then run these substeps:
Wait 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 substeps.
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 first step of these substeps.
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 create a
Document
object, mark it as being an HTML document, create an HTML
parser, associate it with the document, and begin to use the
bytes provided for the document as the input stream for
that parser.
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, an EOF character is implied,
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.
Application cache selection happens in the HTML parser.
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
, 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 or
resolving it 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).
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 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", set
the tokenization stage's content model
flag to PLAINTEXT, and begin to pass the stream of
characters in the plain text document to that tokenizer.
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 character are available, an EOF character is
implied, 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 stylesheet or an XBL
binding, providing script, giving the document a title
,
etc.
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 stylesheet 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 stylesheet 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 after the current entry
in the browsing context's Document
object's History
object.
This doesn't necessarily have to affect the user agent's user interface.
Append a new entry at the end of the History
object representing the new resource and its Document
object and related state, and set its URL to the address to which
the user agent was navigating. (This
will be the same as the document's address, but with a
new fragment identifier.)
Traverse the history to the new entry. This will scroll to the fragment identifier given in the document's current address.
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).
For HTML documents (and the text/html
MIME type),
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.
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.
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]
Status: First draft
When a user agent is required to traverse the history to a specified entry, the user agent must act as follows:
If there is no longer a Document
object for the
entry in question, the user agent must navigate the
browsing context to the location for that entry to perform an
entry update of that entry, and abort these steps. The
"navigate" algorithm reinvokes this "traverse"
algorithm to complete the traversal, at which point there
is a Document
object and so this step gets
skipped. The navigation must be done using the same source
browsing context as was used the first time this entry was
created.
If appropriate, update the current entry in the
browsing context's Document
object's
History
object to reflect any state that the user
agent wishes to persist.
For example, some user agents might want to persist the scroll position, or the values of form controls.
If the specified entry has a different
Document
object than the current entry
then the user agent must run the following substeps:
Document
of the specified entry is not the
same as the origin
of the Document
of the current entry,
then the following sub-sub-steps must be run:
Document
objects with the same
origin as the active document and
that are contiguous with the current entry.Document
object the
active document of the browsing
context.Document
objects with the same origin
as the new active document, and that are
contiguous with the specified entry, must be cleared.Set the document's current address to the URL of the specified entry.
If the specified entry is a state object or the
first entry for a Document
, the user agent must activate that
entry.
If the specified entry has a URL that differs from
the current entry's only by its fragment identifier,
and the two share the same Document
object, then
first, queue a
task to fire a simple event with the name hashchange
at the browsing
context's Window
object; and second, if the new
URL has a fragment identifier, scroll to the fragment
identifier. The task source for the task that
fires the hashchange
event is
the DOM manipulation task source.
User agents may also update other aspects of the document view when the location changes in this way, for instance the scroll position, values of form fields, etc.
The current entry is now the specified entry.
When a user agent is to unload a document, it must run
the following steps. These steps are passed an argument, recycle, which is either true or false, indicating
whether the Document
object is going to be
re-used. (This is set by the document.open()
method.)
Set salvageable to true.
Let event be a new
BeforeUnloadEvent
event object with the name beforeunload
, with no namespace,
which does not bubble but is cancelable.
Dispatch event at the
Document
's Window
object.
If any event listeners were triggered by the previous step, then set salvageable to false.
If the returnValue
attribute of the event object is not the empty
string, or if the event was canceled, then the user agent should
ask the user to confirm that they wish to unload the document.
The prompt shown by the user agent may include the string of
the returnValue
attribute, or some leading subset thereof. (A user agent may want
to truncate the string to 1024 characters for display, for
instance.)
The user agent must pause while waiting for the user's response.
If the user refused to allow the document to be unloaded then these steps must be aborted.
Fire a simple event called unload
at the Document
's
Window
object.
If any event listeners were triggered by the previous step, then set salvageable to false.
If there are any outstanding transactions that have
callbacks that involve scripts
whose global object is
the Document
's Window
object, roll them
back (without invoking any of the callbacks) and set salvageable to false.
Empty the Document
's Window
's
list of active timeouts and its list of active
intervals.
If salvageable and recycle are both false, discard the Document
.
interface BeforeUnloadEvent : Event { attribute DOMString returnValue; };
returnValue
[ = value ]Returns the current return value of the event (the message to show the user).
Can be set, to update the message.
There are no BeforeUnloadEvent
-specific
initialization methods.
The returnValue
attribute represents the message to show the user. When the event is
created, the attribute must be set to the empty string. On getting,
it must return the last value it was set to. On setting, the
attribute must be set to the new value.
Status: Controversial Working Draft
The a
, area
, and link
elements can, in certain situations described in the definitions of
those elements, represent hyperlinks.
The href
attribute on a hyperlink element must have a value that is a
valid URL. This URL is the destination
resource of the hyperlink.
The href
attribute on
a
and area
elements is not required; when
those elements do not have href
attributes they do not
represent hyperlinks.
The href
attribute on the
link
element is required, but whether a
link
element represents a hyperlink or not depends on
the value of the rel
attribute
of that element.
The target
attribute, if present, must be a valid browsing context name
or keyword. It gives the name of the browsing
context that will be used. User agents use
this name when following hyperlinks.
The ping
attribute, if
present, gives the URLs of the resources that are interested in
being notified if the user follows the hyperlink. The value must be
a space separated list of one or more valid URLs. The value is used by the user agent for hyperlink
auditing.
For a
and area
elements that represent
hyperlinks, the relationship between the document containing the
hyperlink and the destination resource indicated by the hyperlink is
given by the value of the element's rel
attribute, which
must be a set of space-separated tokens. The allowed values and their meanings are defined
below. The rel
attribute has
no default value. If the attribute is omitted or if none of the
values in the attribute are recognized by the user agent, then the
document has no particular relationship with the destination
resource other than there being a hyperlink between the two.
The media
attribute describes for which media the target document was
designed. It is purely advisory. The value must be a valid media query. [MQ] The default,
if the media
attribute is
omitted, is all
.
The hreflang
attribute on hyperlink elements, if present, gives the language of
the linked resource. It is purely advisory. The value must be a
valid BCP 47 language code. [BCP47]
User agents must not consider this attribute
authoritative — upon fetching the resource, user agents must
use only language information associated with the resource to
determine its language, not metadata included in the link to the
resource.
The type
attribute, if present, gives the MIME type of the linked
resource. It is purely advisory. The value must be a valid
MIME type, optionally with parameters. User agents must not consider the type
attribute authoritative
— upon fetching the resource, user agents must not use
metadata included in the link to the resource to determine its
type.
When a user follows a hyperlink, the user agent must
resolve the URL
given by the href
attribute
of that hyperlink, relative to the hyperlink element, and if that is
successful, must navigate a browsing
context to the resulting absolute URL. In the
case of server-side image maps, the URL of the hyperlink must
further have its hyperlink suffix appended to it.
If resolving the URL fails, the user agent may report the error to the user in a user-agent-specific manner, may navigate to an error page to report the error, or may ignore the error and do nothing.
If the user indicated a specific browsing context when following the hyperlink, or if the user agent is configured to follow hyperlinks by navigating a particular browsing context, then that must be the browsing context that is navigated.
Otherwise, if the hyperlink element is an a
or
area
element that has a target
attribute, then the
browsing context that is navigated must be chosen by
applying the rules for choosing a browsing context given a
browsing context name, using the value of the target
attribute as the
browsing context name. If these rules result in the creation of a
new browsing context, it must be navigated with
replacement enabled.
Otherwise, if the hyperlink element is a sidebar hyperlink and the user agent implements a feature that can be considered a secondary browsing context, such a secondary browsing context may be selected as the browsing context to be navigated.
Otherwise, if the hyperlink element is an a
or
area
element with no target
attribute, but one of
the child nodes of the head
element is a
base
element with a target
attribute, then the browsing
context that is navigated must be chosen by applying the rules
for choosing a browsing context given a browsing context name,
using the value of the target
attribute of the first such base
element as the
browsing context name. If these rules result in the creation of a
new browsing context, it must be navigated with
replacement enabled.
Otherwise, the browsing context that must be navigated is the same browsing context as the one which the hyperlink element itself is in.
The navigation must be done with the browsing
context that contains the Document
object with
which the hyperlink's element in question is associated as the
source browsing context.
Status: Controversial Working Draft. ISSUE-1 (PINGPOST), ISSUE-2 (PINGUI) and ISSUE-63 (origin-req-scope) block progress to Last Call
If an a
or area
hyperlink element has a
ping
attribute, and the
user follows the hyperlink, and the hyperlink's URL can
be resolved, relative to the
hyperlink element, without failure, then the user agent must take
the ping
attribute's value,
split that string on
spaces, resolve each
resulting token relative to the hyperlink element, and then should
send a request (as described below) to each of the resulting absolute URLs. (Tokens that fail to
resolve are ignored.) This may be done in parallel with the primary
request, and is independent of the result of that request.
User agents should allow the user to adjust this behavior, for
example in conjunction with a setting that disables the sending of
HTTP Referer
(sic) headers. Based
on the user's preferences, UAs may either ignore the
ping
attribute altogether,
or selectively ignore URLs in the list (e.g. ignoring any
third-party URLs).
For URLs that are HTTP URLs, the requests must be performed by
fetching the specified URLs using the
POST method, with an entity body with the MIME type
text/ping
consisting of the four-character string
"PING
". All relevant cookie and HTTP
authentication headers must be included in the request. Which other
headers are required depends on the URLs involved.
Document
object containing the hyperlink being
audited and the ping URL have the same originPing-From
HTTP header with, as its
value, the address of
the document containing the hyperlink, and a Ping-To
HTTP header with, as its value,
the address of the absolute URL of the target of the
hyperlink. The request must not include a Referer
(sic) HTTP header. Referer
(sic)
HTTP header [sic] with, as its value, the current address of the document
containing the hyperlink, a Ping-From
HTTP header with the same
value, and a Ping-To
HTTP header
with, as its value, the address of the target of the
hyperlink.Ping-To
HTTP header with, as its value,
the address of the target of the hyperlink. The request must
neither include a Referer
(sic) HTTP header
nor include a Ping-From
HTTP
header.In addition, an Origin
header
must always be included, whose value is the ASCII serialization of the
origin of the Document
containing the
hyperlink.
To save bandwidth, implementors might also wish to
consider omitting optional headers such as Accept
from
these requests.
User agents must, unless otherwise specified by the user, honor the HTTP headers (including, in particular, redirects and HTTP cookie headers), but must ignore any entity bodies returned in the responses. User agents may close the connection prematurely once they start receiving an entity body. [RFC2109] [COOKIES]
For URLs that are not HTTP URLs, the requests must be performed by fetching the specified URL normally, and discarding the results.
When the ping
attribute is
present, user agents should clearly indicate to the user that
following the hyperlink will also cause secondary requests to be
sent in the background, possibly including listing the actual target
URLs.
For example, a visual user agent could include the hostnames of the target ping URLs along with the hyperlink's actual URL in a status bar or tooltip.
The ping
attribute is redundant
with pre-existing technologies like HTTP redirects and JavaScript
in allowing Web pages to track which off-site links are most
popular or allowing advertisers to track click-through rates.
However, the ping
attribute
provides these advantages to the user over those alternatives:
Thus, while it is possible to track users without this feature,
authors are encouraged to use the ping
attribute so that the user
agent can make the user experience more transparent.
Status: Last call for comments
The following table summarizes the link types that are defined by this specification. This table is non-normative; the actual definitions for the link types are given in the next few sections.
In this section, the term referenced document refers to the resource identified by the element representing the link, and the term current document refers to the resource within which the element representing the link finds itself.
To determine which link types apply to a link
,
a
, or area
element, the element's rel
attribute must be split on spaces. The resulting tokens are the link
types that apply to that element.
Unless otherwise specified, a keyword must not be specified more
than once per rel
attribute.
The link types are ASCII case-insensitive values, and must be compared as such.
Thus, rel="next"
is the
same as rel="NEXT"
.
Link type | Effect on... | Brief description | |
---|---|---|---|
link |
a and area |
||
alternate |
Hyperlink | Hyperlink | Gives alternate representations of the current document. |
archives |
Hyperlink | Hyperlink | Provides a link to a collection of records, documents, or other materials of historical interest. |
author |
Hyperlink | Hyperlink | Gives a link to the current document's author. |
bookmark |
not allowed | Hyperlink | Gives the permalink for the nearest ancestor section. |
external |
not allowed | Hyperlink | Indicates that the referenced document is not part of the same site as the current document. |
feed |
Hyperlink | Hyperlink | Gives the address of a syndication feed for the current document. |
first |
Hyperlink | Hyperlink | Indicates that the current document is a part of a series, and that the first document in the series is the referenced document. |
help |
Hyperlink | Hyperlink | Provides a link to context-sensitive help. |
icon |
External Resource | not allowed | Imports an icon to represent the current document. |
index |
Hyperlink | Hyperlink | Gives a link to the document that provides a table of contents or index listing the current document. |
last |
Hyperlink | Hyperlink | Indicates that the current document is a part of a series, and that the last document in the series is the referenced document. |
license |
Hyperlink | Hyperlink | Indicates that the main content of the current document is covered by the copyright license described by the referenced document. |
next |
Hyperlink | Hyperlink | Indicates that the current document is a part of a series, and that the next document in the series is the referenced document. |
nofollow |
not allowed | Hyperlink | Indicates that the current document's original author or publisher does not endorse the referenced document. |
noreferrer |
not allowed | Hyperlink | Requires that the user agent not send an HTTP Referer (sic) header if the user follows the hyperlink. |
pingback |
External Resource | not allowed | Gives the address of the pingback server that handles pingbacks to the current document. |
prefetch |
External Resource | not allowed | Specifies that the target resource should be preemptively cached. |
prev |
Hyperlink | Hyperlink | Indicates that the current document is a part of a series, and that the previous document in the series is the referenced document. |
search |
Hyperlink | Hyperlink | Gives a link to a resource that can be used to search through the current document and its related pages. |
stylesheet |
External Resource | not allowed | Imports a stylesheet. |
sidebar |
Hyperlink | Hyperlink | Specifies that the referenced document, if retrieved, is intended to be shown in the browser's sidebar (if it has one). |
tag |
Hyperlink | Hyperlink | Gives a tag (identified by the given address) that applies to the current document. |
up |
Hyperlink | Hyperlink | Provides a link to a document giving the context for the current document. |
Some of the types described below list synonyms for these values. These are to be handled as specified by user agents, but must not be used in documents.
alternate
"Status: Last call for comments
The alternate
keyword may be
used with link
, a
, and area
elements. For link
elements, if the rel
attribute does not also contain the
keyword stylesheet
, it creates a
hyperlink; but if it
does also contain the keyword stylesheet
, the alternate
keyword instead modifies the
meaning of the stylesheet
keyword in the way described for that keyword, and the rest of this
subsection doesn't apply.
The alternate
keyword
indicates that the referenced document is an alternate
representation of the current document.
The nature of the referenced document is given by the media
, hreflang
, and type
attributes.
If the alternate
keyword is
used with the media
attribute, it indicates that the referenced document is intended for
use with the media specified.
If the alternate
keyword is
used with the hreflang
attribute, and that attribute's value differs from the root
element's language, it indicates that the
referenced document is a translation.
If the alternate
keyword is
used with the type
attribute, it indicates that the referenced document is a
reformulation of the current document in the specified format.
The media
, hreflang
, and type
attributes can be combined
when specified with the alternate
keyword.
For example, the following link is a French translation that uses the PDF format:
<link rel=alternate type=application/pdf hreflang=fr href=manual-fr>
If the alternate
keyword is
used with the type
attribute set to the value application/rss+xml
or the value application/atom+xml
, then the
user agent must treat the link as it would if it had the feed
keyword specified as well.
The alternate
link
relationship is transitive — that is, if a document links to
two other documents with the link type "alternate
", then, in addition to
implying that those documents are alternative representations of the
first document, it is also implying that those two documents are
alternative representations of each other.
archives
"Status: Last call for comments
The archives
keyword may be
used with link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The archives
keyword indicates
that the referenced document describes a collection of records,
documents, or other materials of historical interest.
A blog's index page could link to an index of the
blog's past posts with rel="archives"
.
Synonyms: For historical reasons, user agents
must also treat the keyword "archive
" like the
archives
keyword.
author
"Status: Last call for comments
The author
keyword may be
used with link
, a
, and area
elements. For link
elements, it creates a hyperlink.
For a
and area
elements, the author
keyword indicates that the
referenced document provides further information about the author of
the nearest article
element ancestor of the element
defining the hyperlink, if there is one, or of the page as a whole,
otherwise.
For link
elements, the author
keyword indicates that the
referenced document provides further information about the author
for the page as a whole.
The "referenced document" can be, and often is, a
mailto:
URL giving the e-mail address of the
author. [MAILTO]
Synonyms: For historical reasons, user agents
must also treat link
, a
, and
area
elements that have a rev
attribute with the value "made
" as having the author
keyword specified as a link
relationship.
bookmark
"Status: Last call for comments
The bookmark
keyword may be
used with a
and area
elements.
The bookmark
keyword gives a
permalink for the nearest ancestor article
element of
the linking element in question, or of the section the linking element is most
closely associated with, if there are no ancestor
article
elements.
The following snippet has three permalinks. A user agent could determine which permalink applies to which part of the spec by looking at where the permalinks are given.
... <body> <h1>Example of permalinks</h1> <div id="a"> <h2>First example</h2> <p><a href="a.html" rel="bookmark">This</a> permalink applies to only the content from the first H2 to the second H2. The DIV isn't exactly that section, but it roughly corresponds to it.</p> </div> <h2>Second example</h2> <article id="b"> <p><a href="b.html" rel="bookmark">This</a> permalink applies to the outer ARTICLE element (which could be, e.g., a blog post).</p> <article id="c"> <p><a href="c.html" rel="bookmark">This</a> permalink applies to the inner ARTICLE element (which could be, e.g., a blog comment).</p> </article> </article> </body> ...
external
"Status: Last call for comments
The external
keyword may be
used with a
and area
elements.
The external
keyword indicates
that the link is leading to a document that is not part of the site
that the current document forms a part of.
feed
"Status: Last call for comments
The feed
keyword may be used with
link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The feed
keyword indicates that the
referenced document is a syndication feed. If the alternate
link type is also specified,
then the feed is specifically the feed for the current document;
otherwise, the feed is just a syndication feed, not necessarily
associated with a particular Web page.
The first link
, a
, or area
element in the document (in tree order) that creates a hyperlink
with the link type feed
must be
treated as the default syndication feed for the purposes of feed
autodiscovery.
The feed
keyword is
implied by the alternate
link
type in certain cases (q.v.).
The following two link
elements are equivalent:
both give the syndication feed for the current page:
<link rel="alternate" type="application/atom+xml" href="data.xml">
<link rel="feed alternate" href="data.xml">
The following extract offers various different syndication feeds:
<p>You can access the planets database using Atom feeds:</p> <ul> <li><a href="recently-visited-planets.xml" rel="feed">Recently Visited Planets</a></li> <li><a href="known-bad-planets.xml" rel="feed">Known Bad Planets</a></li> <li><a href="unexplored-planets.xml" rel="feed">Unexplored Planets</a></li> </ul>
help
"Status: Last call for comments
The help
keyword may be used with
link
, a
, and area
elements. For link
elements, it creates a hyperlink.
For a
and area
elements, the help
keyword indicates that the referenced
document provides further help information for the parent of the
element defining the hyperlink, and its children.
In the following example, the form control has associated context-sensitive help. The user agent could use this information, for example, displaying the referenced document if the user presses the "Help" or "F1" key.
<p><label> Topic: <input name=topic> <a href="help/topic.html" rel="help">(Help)</a></label></p>
For link
elements, the help
keyword indicates that the referenced
document provides help for the page as a whole.
icon
"Status: Last call for comments
The icon
keyword may be used with
link
elements, for which it creates an external resource link.
The specified resource is an icon representing the page or site, and should be used by the user agent when representing the page in the user interface.
Icons could be auditory icons, visual icons, or other kinds of
icons. If multiple icons are provided, the user
agent must select the most appropriate icon according to the type
, media
, and sizes
attributes. If there are
multiple equally appropriate icons, user agents must use the last
one declared in tree order. If the user agent tries to
use an icon but that icon is determined, upon closer examination, to
in fact be inappropriate (e.g. because it uses an unsupported
format), then the user agent must try the next-most-appropriate icon
as determined by the attributes.
There is no default type for resources given by the icon
keyword. However, for the purposes of
determining the type of the
resource, user agents must expect the resource to be an image.
The sizes
attribute gives the sizes of icons for visual media.
If specified, the attribute must have a value that is an
unordered set of unique space-separated tokens. The
values must all be either any
or a value that consists of
two valid non-negative
integers that do not have a leading U+0030 DIGIT ZERO (0)
character and that are separated by a single U+0078 LATIN SMALL
LETTER X character.
The keywords represent icon sizes.
To parse and process the attribute's value, the user agent must first split the attribute's value on spaces, and must then parse each resulting keyword to determine what it represents.
The any
keyword
represents that the resource contains a scalable icon, e.g. as
provided by an SVG image.
Other keywords must be further parsed as follows to determine what they represent:
If the keyword doesn't contain exactly one U+0078 LATIN SMALL LETTER X character, then this keyword doesn't represent anything. Abort these steps for that keyword.
Let width string be the string before
the "x
".
Let height string be the string after the
"x
".
If either width string or height string start with a U+0030 DIGIT ZERO (0) character or contain any characters other than characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), then this keyword doesn't represent anything. Abort these steps for that keyword.
Apply the rules for parsing non-negative integers to width string to obtain width.
Apply the rules for parsing non-negative integers to height string to obtain height.
The keyword represents that the resource contains a bitmap icon with a width of width device pixels and a height of height device pixels.
The keywords specified on the sizes
attribute must not represent
icon sizes that are not actually available in the linked
resource.
If the attribute is not specified, then the user agent must assume that the given icon is appropriate, but less appropriate than an icon of a known and appropriate size.
The following snippet shows the top part of an application with several icons.
<!DOCTYPE HTML> <html> <head> <title>lsForums — Inbox</title> <link rel=icon href=favicon.png sizes="16x16"> <link rel=icon href=windows.ico sizes="32x32 48x48"> <link rel=icon href=mac.icns sizes="128x128 512x512 8192x8192 32768x32768"> <link rel=icon href=iphone.png sizes="59x60"> <link rel=icon href=gnome.svg sizes="any"> <link rel=stylesheet href=lsforums.css> <script src=lsforums.js></script> <meta name=application-name content="lsForums"> </head> <body> ...
license
"Status: Last call for comments
The license
keyword may be used
with link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The license
keyword indicates
that the referenced document provides the copyright license terms
under which the main content of the current document is
provided.
This specification does not specify how to distinguish between the main content of a document and content that is not deemed to be part of that main content. The distinction should be made clear to the user.
Consider a photo sharing site. A page on that site might describe and show a photograph, and the page might be marked up as follows:
<!DOCTYPE HTML> <html> <head> <title>Exampl Pictures: Kissat</title> <link rel="stylesheet href="/style/default"> </head> <body> <h1>Kissat</h1> <nav> <a href="../">Return to photo index</a> </nav> <figure> <img src="/pix/39627052_fd8dcd98b5.jpg"> <legend>Kissat</legend> </figure> <p>One of them has six toes!</p> <p><small><a rel="license" href="http://www.opensource.org/licenses/mit-license.php">MIT Licensed</a></small></p> <footer> <a href="/">Home</a> | <a href="../">Photo index</a> <p><small>© copyright 2009 Exampl Pictures. All Rights Reserved.</small></p> </footer> </body> </html>
In this case the license
applies to just the photo (the main content of the document), not
the whole document. In particular not the design of the page
itself, which is covered by the copyright given at the bottom of
the document. This could be made clearer in the styling
(e.g. making the license link prominently positioned near the
photograph, while having the page copyright in light small text at
the foot of the page.
Synonyms: For historical reasons, user agents
must also treat the keyword "copyright
" like
the license
keyword.
nofollow
"Status: Last call for comments
The nofollow
keyword may be
used with a
and area
elements.
The nofollow
keyword indicates
that the link is not endorsed by the original author or publisher of
the page, or that the link to the referenced document was included
primarily because of a commercial relationship between people
affiliated with the two pages.
noreferrer
"Status: Last call for comments
The noreferrer
keyword may be
used with a
and area
elements.
It indicates that the no referrer information is to be leaked when following the link.
If a user agent follows a link defined by an a
or
area
element that has the noreferrer
keyword, the user agent
must not include a Referer
(sic) HTTP header
(or equivalent
for other protocols) in the request.
This keyword also causes the opener
attribute to remain null if the
hyperlink creates a new browsing context.
pingback
"Status: Last call for comments
The pingback
keyword may be
used with link
elements, for which it creates an external resource link.
For the semantics of the pingback
keyword, see the Pingback 1.0
specification. [PINGBACK]
prefetch
"Status: Last call for comments
The prefetch
keyword may be
used with link
elements, for which it creates an external resource link.
The prefetch
keyword indicates
that preemptively fetching and caching the specified resource is
likely to be beneficial, as it is highly likely that the user will
require this resource.
There is no default type for resources given by the prefetch
keyword.
search
"Status: Last call for comments
The search
keyword may be used
with link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The search
keyword indicates that
the referenced document provides an interface specifically for
searching the document and its related resources.
OpenSearch description documents can be used with
link
elements and the search
link type to enable user agents to
autodiscover search interfaces. [OPENSEARCH]
stylesheet
"Status: Implemented and widely deployed
The stylesheet
keyword may be
used with link
elements, for which it creates an external resource link that
contributes to the styling processing model.
The specified resource is a resource that describes how to present the document. Exactly how the resource is to be processed depends on the actual type of the resource.
If the alternate
keyword is
also specified on the link
element, then the link
is an alternative stylesheet; in this case, the title
attribute must be specified on the
link
element, with a non-empty value.
The default type for resources given by the stylesheet
keyword is text/css
.
Quirk: If the document has been set to
quirks mode and the Content-Type metadata of the external
resource is not a supported style sheet type, the user agent must
instead assume it to be text/css
.
sidebar
"Status: Last call for comments
The sidebar
keyword may be used
with link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The sidebar
keyword indicates
that the referenced document, if retrieved, is intended to be shown
in a secondary browsing context (if possible), instead
of in the current browsing context.
A hyperlink element with the sidebar
keyword specified is a sidebar hyperlink.
tag
"Status: Last call for comments
The tag
keyword may be used
with link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The tag
keyword indicates that the
tag that the referenced document represents applies to the
current document.
Since it indicates that the tag applies to the current document, it would be inappropriate to use this keyword in the markup of a tag cloud, which lists the popular tag across a set of pages.
Some documents form part of a hierarchical structure of documents.
A hierarchical structure of documents is one where each document can have various subdocuments. The document of which a document is a subdocument is said to be the document's parent. A document with no parent forms the top of the hierarchy.
A document may be part of multiple hierarchies.
index
"Status: Last call for comments
The index
keyword may be used with
link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The index
keyword indicates that
the document is part of a hierarchical structure, and that the link
is leading to the document that is the top of the hierarchy. It
conveys more information when used with the up
keyword (q.v.).
Synonyms: For historical reasons, user agents
must also treat the keywords "top
", "contents
", and "toc
" like the
index
keyword.
up
"Status: Last call for comments
The up
keyword may be used with
link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The up
keyword indicates that the
document is part of a hierarchical structure, and that the link is
leading to the document that is the parent of the current
document.
The up
keyword may be repeated within
a rel
attribute to indicate
the hierarchical distance from the current document to the
referenced document. Each occurrence of the keyword represents one
further level. If the index
keyword
is also present, then the number of up
keywords is the depth of the current page relative to the top of the
hierarchy. Only one link is created for the set of one or more up
keywords and, if present, the index
keyword.
If the page is part of multiple hierarchies, then they should be
described in different paragraphs. User agents
must scope any interpretation of the up
and index
keywords together
indicating the depth of the hierarchy to the paragraph
in which the link finds itself, if any, or to the document
otherwise.
When two links have both the up
and
index
keywords specified together in
the same scope and contradict each other by having a different
number of up
keywords, the link with the
greater number of up
keywords must be
taken as giving the depth of the document.
This can be used to mark up a navigation style sometimes known as bread crumbs. In the following example, the current page can be reached via two paths.
<nav> <p> <a href="/" rel="index up up up">Main</a> > <a href="/products/" rel="up up">Products</a> > <a href="/products/dishwashers/" rel="up">Dishwashers</a> > <a>Second hand</a> </p> <p> <a href="/" rel="index up up">Main</a> > <a href="/second-hand/" rel="up">Second hand</a> > <a>Dishwashers</a> </p> </nav>
The relList
DOM
attribute (e.g. on the a
element) does not currently
represent multiple up
keywords (the
interface hides duplicates).
Some documents form part of a sequence of documents.
A sequence of documents is one where each document can have a previous sibling and a next sibling. A document with no previous sibling is the start of its sequence, a document with no next sibling is the end of its sequence.
A document may be part of multiple sequences.
first
"Status: Last call for comments
The first
keyword may be used with
link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The first
keyword indicates that
the document is part of a sequence, and that the link is leading to
the document that is the first logical document in the sequence.
Synonyms: For historical reasons, user agents
must also treat the keywords "begin
" and
"start
" like the first
keyword.
last
"Status: Last call for comments
The last
keyword may be used with
link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The last
keyword indicates that the
document is part of a sequence, and that the link is leading to the
document that is the last logical document in the sequence.
Synonyms: For historical reasons, user agents
must also treat the keyword "end
" like the
last
keyword.
next
"Status: Last call for comments
The next
keyword may be used with
link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The next
keyword indicates that the
document is part of a sequence, and that the link is leading to the
document that is the next logical document in the sequence.
prev
"Status: Last call for comments
The prev
keyword may be used with
link
, a
, and area
elements. For link
elements, it creates a hyperlink.
The prev
keyword indicates that the
document is part of a sequence, and that the link is leading to the
document that is the previous logical document in the sequence.
Synonyms: For historical reasons, user agents
must also treat the keyword "previous
" like
the prev
keyword.
Other than the types defined above, only types defined as
extensions in the WHATWG Wiki
RelExtensions page may be used with the rel
attribute on link
, a
,
and area
elements. [WHATWGWIKI]
Anyone is free to edit the WHATWG Wiki RelExtensions page at any time to add a type. Extension types must be specified with the following information:
The actual value being defined. The value should not be confusingly similar to any other defined value (e.g. differing only in case).
link
One of the following:
link
elements.link
element;
it creates a hyperlink
link.link
element;
it creates a external
resource link.a
and area
One of the following:
a
and area
elements.a
and
area
elements.A short description of what the keyword's meaning is.
A link to a more detailed description of the keyword's semantics and requirements. It could be another page on the Wiki, or a link to an external page.
A list of other keyword values that have exactly the same processing requirements. Authors must not use the values defined to be synonyms, they are only intended to allow user agents to support legacy content.
One of the following:
link
" and "Effect on... a
and
area
" information should be set to "not
allowed".If a keyword is added with the "proposal" status and found to be redundant with existing values, it should be removed and listed as a synonym for the existing value. If a keyword is added with the "proposal" status and found to be harmful, then it should be changed to "rejected" status, and its "Effect on..." information should be changed accordingly.
Conformance checkers must use the information given on the WHATWG Wiki RelExtensions page to establish if a value not explicitly defined in this specification is allowed or not. Conformance checkers may cache this information (e.g. for performance reasons or to avoid the use of unreliable network connectivity).
When an author uses a new type not defined by either this specification or the Wiki page, conformance checkers should offer to add the value to the Wiki, with the details described above, with the "proposal" status.
This specification does not define how new values will get approved. It is expected that the Wiki will have a community that addresses this.