HTML 5

A vocabulary and
associated APIs for HTML and XHTML

4. Web
browsers

This section describes features that apply most directly to Web
browsers. Having said that, unless specified elsewhere, the
requirements defined in this section do apply to all user
agents, whether they are Web browsers or not.

4.1.4.1
Browsing contexts

A browsing context is a collection of
one or more Document objects, and one or more views .

A view is a user agent interface tied to a
particular media used for the presentation of Document
objects in some media. A view may be interactive. Each view is
represented by an AbstractView object. Each view
belongs to a browsing context . [DOM2VIEWS]

Events that use the UIEvent interface
are related to a specific view (the view in
which the event happened); the AbstractView of that
view is given in the event object's view
attribute. [DOM3EVENTS]

A typical Web browser has one obvious view per browsing context :
the browser's window (screen media). 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 , but
they have a different presentation of that document. A speech
browser also establishes a browsing context, one with a view in 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.

The main view through which a user primarily
interacts with a user agent is the default
view .

The default view of a
Document is given by the defaultView attribute on the Document
object's DocumentView interface. [DOM3VIEWS]

4.1.1.4.1.1
Nested browsing contexts

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 in one of its
Document s 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 , and C is said to be
nested
throughD .

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).

4.1.2.4.1.2
Auxiliary browsing contexts

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 .

All the executable code in a unit of related
browsing contexts must execute on a single conceptual thread.
The dispatch of events fired by the user agent (e.g. in response to
user actions or network activity) and the execution of any scripts
associated with timers must be serialisedserialized
so that for each unit of related browsing
contexts there is only one script being executed at a time.

4.1.5.4.1.6
Browsing context names

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, or, acharacter.
(Names starting with an underscore are reserved for special
keywords.)

Avalid browsing context name or keywordis any string that is either avalid browsing context nameor that case-insensitively matches one of:
_blank
,_self , _parent , or
_top . (Names starting
with an underscore are reserved for special keywords.)

The rules for chosingchoosing 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 one of
the following is true: Either the origin of that browsing context's
active document is the same as the origin of the current
browsing context's active document , Or that
browsing context is an auxiliary
browsing context and its opener browsing contextallowed to navigateis either the current browsing context or a
browsing context that the user agent
considers is closely enough related to the current browsing
context, Or that browsing context is not a
top-level browsing context , and the origin of the active document of the parent browsing
context of that browsing context is the same as the origin of the
current browsing context's active document , ...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
newtop-level
browsing contextor reuse an
existingtop-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.

If the user agent has been configured such that in this
instance it will create a new browsing context

A 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 .

If the user agent has been configured such that in this
instance it will reuse the current browsing context

The chosen browsing context is the current browsing
context.

If the user agent has been configured such that in this
instance it will not find a 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.

4.2.2.4.2.2
Constructors

When invoked as constructors, these must return a new
HTMLAudioElement
object (a new audio element). If
the src argument is present, the object
created must have its src content attribute set to the provided value,
and the user agent must invoke the load() method on the
object before returning.

Image()

Image(in unsigned
long w )

Image(in unsigned
long w , in unsigned long h
)

When invoked as corstructors,constructors, these must return a new
HTMLImageElement
object (a new img element). If the
h argument is present, the new object's
height content attribute must
be set to h . If the w
argument is present, the new object's width content attribute must be set to
w .

Option()

Option(in
DOMString name )

Option(in
DOMString name , in DOMString value )

When invoked as constructors, these must return a new
HTMLOptionElement object (a new option
element). need to define argument
processing

And when constructors are invoked but without
using the constructor syntax...?

4.2.3.4.2.3
APIs for creating and navigating browsing contexts by name

The first argument, url , gives a URI (or
IRI) for a page to load in the browsing context. If no arguments
are provided, then the url argument defaults to
" about:blank ". The argument must be resolved to an
absolute URI by ...

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.

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.

The name gets reset when
the browsing context is navigated to another domain.

4.2.4.4.2.4
Accessing other browsing contexts

In ECMAScript implementations, objects
that implementThelengthDOM
attribute on the Window
interface must have a [[Get]] method that,
when invoked with a property name that is a number i ,
returnsreturn the i thnumber ofchild browsing
contextcontexts of the activeDocument ,
sorted in document order of the elements nesting those browsing
contexts. .

The lengthXXX4(index)DOM attribute
on the Window interfacemethod
must return the number ofindexthchild browsing contextscontext
of the activeDocument . , sorted in document order of the elements nesting those
browsing contexts.

4.3.4.3ScriptingOrigin

4.3.1. Running executable code

Various mechanisms can cause
author-provided executable code to run inTheoriginof a resource
and the contexteffective script
origin of a document. These
mechanisms include, butresource
are probably not limited to: Processingboth either opaque identifiers or tuples
consisting of a scheme component, a
host component, and a port component.

Apply the IDNA ToASCII algorithm tohost ,with both the AllowUnassigned and UseSTD3ASCIIRules
flags set. Lethostbe the
result of technologies like XBL or SVG
that have their own scripting features.the ToASCII algorithm.

User agents may provide a mechanismIf ToASCII fails to enable or disableconvert
one of the executioncomponents of author-provided code. When the user agentstring, e.g.
because it is configured such that
author-provided code does not execute,too long or if the user
agent is implemented so as to never execute author-provided
code,because it is said that scripting is disabled . When
author-provided code does execute, scripting is enabled . A user
agent with scripting disabled iscontains invalid characters, then return a
user agent with no scripting supportnew globally unique identifier.[RFC3490]for the purposes of conformance.4.3.2. Origin

AccessLethostbe the result of
convertinghost to certain
APIslowercase.

If no port is granted or denied to scripts based onexplicitly listed, then letportbe the origindefault port for the protocol given byscheme .Otherwise, letportbe the
<port> component of the script
andURI.

If a Document or image
that was generated fromobtained in
some other manner (e.g. adata:URI typed in by
the user, a Documentcreated using thecreateDocument()API, adata: URI from another sourcereturned
as the location of an HTTP redirect, etc)

Theorigin is a globally unique identifier
assigned when the document is created. The
origin of aDocument or image that was generated fromis
created.

When a javascript:DocumentURIis created, unless stated otherwise above,
itseffective
script origin is initialized
to the same as theorigin of thatthejavascript:Document .However,
thedocument.domainURI.attribute
can be used to change it.

The serialization
of an originis the string
representingobtained by applying the script's domainfollowing
algorithm to the givenorigin :

If theorigin in IDNA formatquestion
is obtained as follows: takenot a scheme/host/port tuple, then
return the domainempty string.

Otherwise, letresultbe the scheme part of the script'sorigintuple and applytuple.

Append the IDNA ToASCII algorithm and thenstring "://" toresult .

Apply the IDNA ToUnicode algorithm
to each component of the domain name (with
bothhost part of the AllowUnassigned and UseSTD3ASCIIRules flags set both
times). [RFC3490]originIf ToASCII
failstuple, and append the results —
each component, in the same order, separated by U+002E FULL STOP
characters (".") — to convert one
ofresult
.

If the componentsport part
of the string, e.g. because it is too long or
because it contains invalid characters, or if theorigin oftuple gives a port that is different from the
script has no domain part, thendefault port for the string representingprotocol
given by the script's domain in IDNA
format cannot be obtained. (ToUnicode is defined to never fail.)
It's been suggested that we should put IP addresses intoscheme part of the origin tuple, to mitigate DNS
rebinding attacks. However that would kill multi-homed systems like
GMail. Should we do something like havethen append a DNS record say
whether or not to includeU+003A COLON
character (":") and the IPgiven port, in the origin for a host? 4.3.3. Unscripted same-origin
checksbase ten, toresult .

Returnresult .

When two URIsTwoorigins are said
to be compared to determine if they
have the same scheme/host/port , it means thatoriginif the
following algorithm must be invoked, where
uri 1 and uri 2 are the two URIs.returns true:

Ifport 1A) and ( scheme 2
,host 2 , port 2B), by
applying the following subalgorithm to each URI:are both opaque identifiers, and their value is equal,
then return true.

LetOtherwise,
if eitheruriAbe the
URI being normalized.orBor both are opaque identifiers, return false.

ParseIfuriAaccording to the
rules described in RFC 3986 and RFC
3987. [RFC3986] [RFC3987]Bhave scheme
components that are not identical, return false.

If uriAandBdoes not use a server-based naming authority, then fail
the overall algorithm — the two URIs do not have the same scheme/host/port.host components that are not identical, return
false.

LetIfschemeAbeandBhave port components
that are not identical, return false.

Return true.

4.3.1Relaxing
the <scheme> component ofsame-origin restriction

Thedomainattribute onDocumentobjects must
be initialized tothe URI. Ifdocument's
domain ,if it has one, and
the UA doesn't supportempty string otherwise. On getting, the
given protocol, then failattribute must return its current value, unless
the overall algorithm —document was created byXMLHttpRequest ,in
which case it must throw anINVALID_ACCESS_ERRexception. On setting, the two URIs do not haveuser
agent must run the same
scheme/host/port .following
algorithm:

Let host be the <host>/<ihost>
component ofIf the URI.document was created
byXMLHttpRequest
,throw anINVALID_ACCESS_ERRexception and abort these steps.

Apply the IDNA ToASCII algorithm to host
,the new value, with both the
AllowUnassigned and UseSTD3ASCIIRules flags set. Let hostnew
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 fail the overall algorithm —
the two URIs do not have the same scheme/host/port.throw asecurity exceptionand abort these steps.[RFC3490]

If no port is explicitly listed, then
letportnew valuebeis not exactly equal
to the default port forcurrent value of the protocol given by scheme . Otherwise, letdocument.domainattribute, then run these substeps:

Set the port ).part of theeffective script
origintuple of theDocumentto "manual override" (a value that, for the purposes
ofcomparing origins ,is
identical to "manual override" but not identical to any other
value).

Thedomainof aDocumentis the host
part of the document'sorigin ,if that is a
scheme/host/port tuple. If scheme
1it isn't, then the document does not
have a domain.

Thedomainattribute is not
case-insensitively identicalused
to scheme 2enable pages on different hosts of a domain to access
each others' DOMs.

,4.3.2The string representing the script's domain in IDNA
format

The string
representing the script's domain in IDNA formatis obtained as follows: take the host part of
the script'sorigintuple and apply
the IDNA ToASCII algorithm and then the IDNA ToUnicode algorithm to
each component of the domain name (with both the AllowUnassigned
and UseSTD3ASCIIRules flags set both times).[RFC3490]

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, or if host
1theoriginof the script is not case-insensitively identicala scheme/host/port tuple, then the string representing
the script's domain in IDNA format cannot be obtained. (ToUnicode
is defined to host 2never fail.)

,4.4Scripting

Various mechanisms can cause
author-provided executable code to run in the context of a
document. These mechanisms include, but are probably not limited
to:

The user has disabled scripting for
thisscript
execution context .(User agents may
provide users with the option to port
2disable scripting globally, on a
per-origin basis, or in other ways down to the granularity of
individualscript execution
contexts .)

Thus, for instance,
enablingdesignModewill disable any event handler attributes,
event listeners, timeouts, etc, that were set by scripts in
the same scheme/host/port.document.

4.3.4.4.4.2
Security exceptions

Define security
exception .

4.3.5.4.4.3The
javascript: protocol

A URI using the javascript: protocol must,
if evaluated,and
when dereferenced, be evaluated by
executing the script obtained using the in-context evaluationcontent retrieval operation defined for
javascript: URIs. [JSURI]

Otherwise, the dereferencescript execution context
must be an empty object, and the
script execution
context's associatedbrowsing
contextmust be thebrowsing context of the Documentto which belongs the element for whichobject of the URI
is being dereferenced,element,
attribute, or to which the style
sheet forfrom which the URI is being
dereferenced applies, whichever is appropriate. URIs using
thejavascript:protocol
should be evaluated when the resource for that URI
is needed, unless scripting is disabled or
the Document corresponding to the dereference context (as defined
above), if any, has designMode enabled.was reached.

If the dereference by-productresult of executing the script is void
(there is no return value), then the URI must be treated in a
manner equivalent to an HTTP resource with an HTTP 204 No Content
response.

Otherwise, the URI must be treated in a manner equivalent to an
HTTP resource with a 200 OK response whose Content-Type metadata is text/html and whose response body is the dereference by-product,return value converted to a string value.

So for example a javascript: URI for a
src attribute
of an img element would be
evaluated in the context of the pagean empty object as soon as the
attribute is set; it would then be sniffed to determine the image
type and decoded as an image.

A javascript: URI in an href attribute of an a element would only be evaluated when the link was
followed
.

The rules for handling script
execution in ascript execution contextinclude making the script not execute (and just return
void) in certain cases, e.g. in a sandbox or when the user has
disabled scripting altogether.

4.3.6.4.4.4
Events

We need to define how to handle events that
are to be fired on a Document that is no longer the active document
of its browsing context, and for Documents that have no browsing
context. Do the events fire? Do the handlers in that document not
fire? Do we just define scripting to be disabled when the document
isn't active, with events still running as is? See also the
script element section, which
says scripts don't run when the document isn't active.

4.3.6.1.4.4.4.1. Event handler attributes

HTML elements can have event handler attributes specified. These act as
bubbling event listeners for the element on which they are
specified.

Each event handler attribute has two parts, an event handler content
attribute and an event handler DOM attribute .
Event handler attributes must initially be set to null. When their
value changes (through the changing of their event handler content
attribute or their event handler DOM attribute), they will either
be null, or have an EventListener object assigned to
them.

When an event handler content attribute is set, its new value
must be interpreted as the body of an anonymous function with a
single argument called event , with the new function's
scope chain being linked from the activation object of the handler,
to the element, to the element's form element if it is
a form control, to the Document object, to the
Windowobject of
thebrowsing context of that
Document . The function's this parameter
must be the Element object representing the element.
The resulting function must then be set as the value of the
corresponding event handler attribute, and the new value must be
set as the value of the content attribute. If the given function
body fails to compile, then the corresponding event handler
attribute must be set to null instead (the content attribute must
still be updated to the new value, though).

See ECMA262 Edition 3, sections 10.1.6 and 10.2.3,
for more details on activation objects. [ECMA262]

Event handler DOM attributes , on
setting, must set the corresponding event handler attribute to
their new value, and on getting, must return whatever the current
value of the corresponding event handler attribute is (possibly
null).

The following are the event handler attributes that must be
supported by all HTML elements , as
both content attributes and DOM attributes, and on Window objects, as DOM attributes:

onabort

Must be invoked whenever an abort event is targeted at or bubbles through
the element.

onbeforeunload

Must be invoked whenever a beforeunload event is targeted at or
bubbles through the element.

onblur

Must be invoked whenever a blur
event is targeted at or bubbles through the element.

onchange

Must be invoked whenever a change event is targeted at or bubbles
through the element.

onclick

Must be invoked whenever a click event is targeted at or bubbles through
the element.

oncontextmenu

Must be invoked whenever a contextmenu event is targeted at or
bubbles through the element.

ondblclick

Must be invoked whenever a dblclick event is targeted at or bubbles
through the element.

ondrag

Must be invoked whenever a drag event is targeted at or bubbles through the
element.

ondragend

Must be invoked whenever a dragend event is targeted at or bubbles
through the element.

ondragenter

Must be invoked whenever a dragenter event
is targeted at or bubbles through the element.

ondragleave

Must be invoked whenever a dragleave event
is targeted at or bubbles through the element.

ondragover

Must be invoked whenever a dragover event is targeted at or bubbles
through the element.

ondragstart

Must be invoked whenever a dragstart event
is targeted at or bubbles through the element.

ondrop

Must be invoked whenever a drop event is targeted at or bubbles through the
element.

onerror

Must be invoked whenever an error event is targeted at or bubbles through
the element.

Must be invoked whenever a focus event is targeted at or bubbles through
the element.

onkeydown

Must be invoked whenever a keydown event is targeted at or bubbles
through the element.

onkeypress

Must be invoked whenever a keypress event is targeted at or bubbles
through the element.

onkeyup

Must be invoked whenever a keyup event is targeted at or bubbles through
the element.

onload

Must be invoked whenever a load event is targeted at or bubbles through
the element.

onmessage

Must be invoked whenever a message event is targeted at or bubbles
through the element.

onmousedown

Must be invoked whenever a mousedown event is targeted at or bubbles
through the element.

onmousemove

Must be invoked whenever a mousemove event is targeted at or bubbles
through the element.

onmouseout

Must be invoked whenever a mouseout event is targeted at or bubbles
through the element.

onmouseover

Must be invoked whenever a mouseover event is targeted at or bubbles
through the element.

onmouseup

Must be invoked whenever a mouseup event is targeted at or bubbles
through the element.

onmousewheel

Must be invoked whenever a mousewheel event is targeted at or
bubbles through the element.

onresize

Must be invoked whenever a resize event is targeted at or bubbles
through the element.

onscroll

Must be invoked whenever a scroll event is targeted at or bubbles
through the element.

onselect

Must be invoked whenever a select event is targeted at or bubbles through
the element.

onstorage

Must be invoked whenever astorageevent is
targeted at or bubbles through the element.

onsubmit

Must be invoked whenever a submit event is targeted at or bubbles
through the element.

onunload

Must be invoked whenever an unload event is targeted at or bubbles
through the element.

When an event handler attribute is invoked, its argument must be
set to the Event object of the event in question. If
the function returns the exact boolean value false, the event's
preventDefault() method must then invoked. Exception:
for historical reasons, for the HTML mouseover event,
the preventDefault() method must be called when the
function returns true instead.

When scripting is disabled , event handler
attributes must do nothing. When scripting is enabled , allAll event handler attributes on an
element, whether set to null or to a function, must be registered
as event listeners on the element, as if the addEventListenerNS()
method on the Element object's
EventTarget interface had been invoked when the
element was created, with the event type ( type argument) equal to the type described
for the event handler attribute in the list above, the namespace (
namespaceURI argument)
set to null, the listener set to be a target and bubbling phase
listener ( useCapture
argument set to false), the event group set to the default group (
evtGroup argument set to
null), and the event listener itself ( listener argument) set to do nothing
while the event handler attribute is null, and set to invoke the
function associated with the event handler attribute otherwise.
(Thelistenerargument is emphaticallynotthe
event handler attribute itself.)

4.3.6.2.4.4.4.2. Event firing

maybe this should be moved higher up
(terminology? conformance? DOM?) Also, the whole terminology thing
should be changed so that we don't define any specific events here,
we only define 'simple event', 'progress event', 'mouse event',
'key event', and the like, and have the actual dispatch use those
generic terms when firing events.

Certain operations and methods are defined as firing events on
elements. For example, the click() method on the HTMLElement interface is defined as
firing a click event on the
element. [DOM3EVENTS]

Firing a
click event means that a
click event with no namespace, which bubbles and is
cancelable, and which uses the MouseEvent interface,
must be dispatched at the given element. The event object must have
its screenX , screenY ,
clientX , clientY , and
button attributes set to 0, its ctrlKey , shiftKey , altKey , and metaKey attributes set
according to the current state of the key input device, if any
(false for any keys that are not available), its detail attribute set to 1, and its relatedTarget attribute set to null. The getModifierState() method on the object must return
values appropriately describing the state of the key input device
at the time the event is created.

Firing a
change event means that a
change event with no namespace, which bubbles but is not
cancelable, and which uses the Event interface, must
be dispatched at the given element. The event object must have its
detail attribute set to 0.

Firing a
contextmenu event
means that a contextmenu
event with no namespace, which bubbles and is cancelable, and which
uses the Event interface, must be dispatched at the
given element. The event object must have its detail attribute set to 0.

Firing a simple
event called e means that an event with
the name e , with no namespace, which does not
bubble but is cancelable,cancelable (unless otherwise stated), and which
uses the Event interface, must be dispatched at the
given element.

Firing a
show event means firing a simple event called
show . Actually this should fire an event that has modifier
information (shift/ctrl etc).etc), as well as having a pointer to the node
on which the menu was fired, and with which the menu was associated
(which could be an ancestor of the former).

Firing a progress event called e means something that hasn't yet been defined, in
the [PROGRESS] spec.

The default action of these event is to do nothing unless
otherwise stated.

If you dispatch a custom "click" event at an
element that would normally have default actions, should they get
triggered? If so, we need to go through the entire spec and make
sure that any default actions are defined in terms of any
event of the right type on that element, not those that are
dispatched in expected ways.

When an event is dispatched at a DOM node in a
Document in a browsing
context , if the event is not a load event, the user agent
must also dispatch the event to the Window , as follows:

In the capture phase, the event must be dispatched to the
Window object before being
dispatched to any of the nodes.

In the bubble phase, the event must be dispatched to the
Window object at the end of the
phase, unless bubbling has been prevented.

4.3.6.4.4.4.4.4. Runtime script errors

This section only applies to user agents that support
scripting in general and ECMAScript in particular.

Whenever a runtime script error occurs in one of the scripts
associated with the document, the value of the onerrorevent
handler DOM attribute of the Window object must be processed, as
follows:

If the value is a function

The function referenced by the onerror attribute
must be invoked with three arguments, before notifying the user of
the error.

The three arguments passed to the function are all
DOMString s; the first must give the message that the
UA is considering reporting, the second must give the URI to the
resource in which the error occured,occurred, and the third must give the
line number in that resource on which the error occured.occurred.

If the function returns false, then the error should not be
reported to the user. Otherwise, if the function returns another
value (or does not return at all), the error should be reported to
the user.

Any exceptions thrown or errors caused by this function must be
reported to the user immediately after the error that the function
was called for, without calling the function again.

4.4.4.5 User
prompts

4.5.1Simple
dialogs

The alert( message ) method, when invoked, must show the
given message to the user. The user agent may
make the method wait for the user to acknowledge the message before
returning; if so, the user agent must pause
while the method is waiting.

The confirm(
message ) method, when invoked,
must show the given message to the user, and
ask the user to respond with a positive or negative response. The
user agent must then pause as the the method waits for the user's response. If the
user responds positively, the method must return true, and if the
user responds negatively, the method must return false.

The prompt(
message , default
) method, when invoked, must show the given
message to the user, and ask the user to either
respond with a string value or abort. The user agent must then
pause as the the
method waits for the user's response. The second argument is
optional. If the second argument ( default ) is
present, then the response must be defaulted to the value given by
default . If the user aborts, then the method
must return null; otherwise, the method must return the string that
the user responded with.

Thebeforeprintevent can be used to annotate the printed
copy, for instance adding the time at which the document was
printed.

The user agent should offer the user
the opportunity to obtain a physical form(or the representation of a physical
form) of the document. The user agent may make the method wait for the user to either accept
or decline before returning; if so, the user agent must pause while the method is waiting. (ThisEven if the user agent
doesn't wait at this point, the user agent must use the state of
the relevant documents as they are at this point in the algorithm
if and when it eventually creates the alternate form.

Theafterprintevent can be used to revert annotations added
in the earlier event, as well as showing post-printing UI. For
instance, if a page is walking the user through the steps of
applying for a home loan, the script could automatically advance to
the next step after having printed a form or other.

4.5.3Dialogs
implemented using separate documents

TheshowModalDialog(url ,arguments)method, when
invoked, must cause the user agent to run the following
steps:

If the user agent is configured such that
this invocation ofshowModalDialog()is somehow disabled, then the method returns the empty
string; abort these steps.

User agents are expected to
disable this method in certain cases to avoid user annoyance. For
instance, a user agent could require that a site be white-listed
before enabling this method, or the user agent could be configured
to only allow one modal dialog at a time.

Letthe list of background browsing contextsbe a list of all the browsing contexts
that:

...aswell as any browsing contexts that
are nested inside any of the browsing contexts matching those
conditions.

Disable the user interface for all the
browsing contexts inthe
list of background browsing contexts .This should prevent the user from navigating those
browsing contexts, causing events to to be sent to those browsing
context, or editing any content in those browsing contexts.
However, it does not,not prevent those browsing contexts from receiving
events from sources other than the user, from running scripts, from
running animations, and so forth.

Such browsing contexts have
associateddialog
arguments ,which are stored along
with thedialog
arguments' origin .These values
are set by theshowModalDialog()method in the algorithm above, when the browsing context
is created, based on the arguments provided to the
method.

These browsing contexts also have an
associatedreturn
value .Thereturn valueof a browsing context must be initialized to the empty
string when the browsing context is created.

ThereturnValueDOM
attribute, on getting, must return thereturn valueof its browsing context, and on setting, must set
thereturn
valueto the given new
value.

4.5.4Notifications

Notifications are short, transient
messages that bring the user's attention to new information, or
remind the user of scheduled events.

Since notifications can be annoying if
abused, this specification defines a mechanism that scopes
notifications to a site's existing rendering area unless the user
explicitly indicates that the site can be trusted.

To this end, eachorigincan be flagged as being atrusted notification
source .By default origins should
not be flagged as such, but user agents may allow users to
whitelist origins or groups of origins as beingtrusted notification sources .Only origins flagged as trusted in this way are allowed
to show notification UI outside of their tab.

For example, a user agent
could allow a user to mark all subdomains and ports of example.org
as trusted notification sources. Then, mail.example.org and
calendar.example.org would both be able to show notifications,
without the user having to flag them individually.

TheshowNotification(title ,subtitle ,description ,onclick)method, when
invoked, must cause the user agent to show a
notification.

Otherwise, theoriginis flagged as atrusted notification source ,and the notification should be shown using the platform
conventions for system-wide notifications. The notification is said
to be atrusted
notification .User agents may
provide a way to unset the origin'strusted notification
sourceflag from within the
notification, so as to allow users to easily disable notifications
from sites that abuse the privilege.

For example, if a site contains a gadget
of a mail application in a sandboxediframeand that frame triggers a notification upon the receipt
of a new e-mail message, that notification would be displayed on
top of the gadget only.

However, if the user then goes to the main
site of that mail application, the notification would be displayed
over the entire rendering area of the tab for the site.

The notification, in this case, would have
a button on it to let the user indicate that he trusts the site. If
the user clicked this button, the next notification would use the
system-wide notification system, appearing even if the tab for the
mail application was buried deep inside a minimised
window.

The style of notifications varies from
platform to platform. On some, it is typically displayed as a
"toast" window that slides in from the bottom right corner. In
others, notifications are shown as semi-transparent white-on-grey
overlays centered over the screen. Other schemes could include
simulated ticker tapes, and speech-synthesis playback.

If a new notification from onebrowsing
contexthastitle ,subtitle ,anddescriptionstrings
that are identical to whatever
mediathetitle ,subtitle ,anddescriptionstrings of
an already-active notification from the samebrowsing contextor anotherbrowsing contextwith the sameorigin , the user
might want.)agent should not display the new notification, but
should instead add an indicator to the already-active notification
that another identical notification would otherwise have been
shown.

For instance, if a user has his mail
application open in three windows, and thus the same "New Mail"
notification is fired three times each time a mail is received,
instead of displaying three identical notifications each time, the
user agent could just show one, with the title "New Mail
x3".

Notifications should have a lifetime based
on the platform conventions for notifications. However, the
lifetime of a notification should not begin until the user has had
the opportunity to see it, so if a notification is spawned for
abrowsing
contextthat is hidden, it should
be shown for its complete lifetime once the user brings thatbrowsing
contextinto view.

User agents should support multiple
notifications at once.

User agents should support user
interaction with notifications, if and as appropriate given the
platform conventions. If a user activates a notification, and
theonclickcallback argument was present and is not
null, then thebrowsing contextassociated with thescript execution contextof the function given byonclickshould be
brought to the user's attention, and theonclickcallback should then be invoked.

4.5.4.6
Browser state

The navigator attribute of the
Window interface must return an
instance of the ClientInformation interface, which
represents the identity and state of the user agent (the client),
and allows Web pages to register themselves as potential protocol
and content handlers:

4.5.1.4.6.1
Custom protocol and content handlers

The registerProtocolHandler()
method allows Web sites to register themselves as possible handlers
for particular protocols. For example, an online fax service could
register itself as a handler of the fax: protocol (
[RFC2806] ), so that if the user clicks
on such a link, he is given the opportunity to use that Web site.
Analogously, the registerContentHandler()
method allows Web sites to register themselves as possible handlers
for content in a particular MIME type. For example, the same online
fax service could register itself as a handler for
image/g3fax files ( [RFC1494] ), so that if the user has no native
application capable of handling G3 Facsimile byte streams, his Web
browser can instead suggest he use that site to view the image.

User agents may, within the constraints described in this
section, do whatever they like when the methods are called. A UA
could, for instance, prompt the user and offer the user the
opportunity to add the site to a shortlist of handlers, or make the
handlers his default, or cancel the request. UAs could provide such
a UI through modal UI or through a non-modal transient notification
interface. UAs could also simply silently collect the information,
providing it only when relevant to the user.

A scheme, such as ftp or fax . The
scheme must be treated case-insensitively by user agents for the
purposes of comparing with the scheme part of URIs that they
consider against the list of registered handlers.

The protocol value, if it contains a colon
(as in " ftp: "), will never match anything, since
schemes don't contain colons.

A MIME type, such as model/vrml or
text/richtext . The MIME type must be treated
case-insensitively by user agents for the purposes of comparing
with MIME types of documents that they consider against the list of
registered handlers.

User agents must compare the given values only to the MIME
type/subtype parts of content types, not to the complete type
including parameters. Thus, if mimeType values
passed to this method include characters such as commas or
whitespace, or include MIME parameters, then the handler being
registered will never be used.

uri

The URI of the page that will handle the requests. When the user
agent uses this URI, it must replace the first occurrence of the
exact literal string " %s " with an escaped version of
the URI of the content in question (as defined below), and then
fetch the resulting URI using the GET method (or equivalent for
non-HTTP URIs).

To get the escaped version of the URI, first, the domain part of
the URI (if any) must be converted to its punycode representation,
and then, every character in the URI that is not in the ranges
given in the next paragraph must be replaced by its UTF-8 byte
representation, each byte being represented by a U+0025 (%)
character and two digits in the range U+0030 (0) to U+0039 (9) and
U+0041 (A) to U+0046 (F) giving the hexadecimal representation of
the byte.

This site could then fetch the chickenkïwi.soup
file and do whatever it is that it does with soup (synthesise(synthesize it and ship it to the user, or
whatever).

title

A descriptive title of the handler, which the UA might use to
remind the user what the site in question is.

User agents should raise security exceptions if the methods are
called with protocol or mimeType values that the UA deems to be "privileged". For
example, a site attempting to register a handler for
http URIs or text/html content in a Web
browser would likely cause an exception to be raised.

User agents must raise a SYNTAX_ERR exception if
the uri argument passed to one of these methods
does not contain the exact literal string " %s ".

User agents must not raise any other exceptions (other than
binding-specific exceptions, such as for an incorrect number of
arguments in an ECMAScript implementation).

This section does not define how the pages registered by these
methods are used, beyond the requirements on how to process the
uri value (see above). To some extent, the
processing model for
navigating across documents defines some cases where these
methods are relevant, but in general UAs may use this information
wherever they would otherwise consider handing content to native
plugins or helper applications.

UAs must not use registered content handlers to handle content
that was returned as part of a non-GET transaction (or rather, as
part of any non-idempotent transaction), as the remote site would
not be able to fetch the same data.

4.5.1.1.4.6.1.1. Security and privacy

These mechanisms can introduce a number of concerns, in
particular privacy concerns.

Hijacking all Web usage. User agents should not
allow protocols that are key to its normal operation, such as
http or https , to be rerouted through
third-party sites. This would allow a user's activities to be
trivially tracked, and would allow user information, even in secure
connections, to be collected.

Hijacking defaults. It is strongly recommended
that user agents do not automatically change any defaults, as this
could lead the user to send data to remote hosts that the user is
not expecting. New handlers registering themselves should never
automatically cause those sites to be used.

Registration spamming. User agents should
consider the possibility that a site will attempt to register a
large number of handlers, possibly from multiple domains (e.g. by
redirecting through a series of pages each on a different domain,
and each registering a handler for video/mpeg —
analogous practices abusing other Web browser features have been
used by pornography Web sites for many years). User agents should
gracefully handle such hostile attempts, protecting the user.

Misleading titles. User agents should not rely
wholywholly on the title argument
to the methods when presenting the registered handlers to the user,
since sites could easily lie. For example, a site
hostile.example.net could claim that it was
registering the "Cuddly Bear Happy Content Handler". User agents
should therefore use the handler's domain in any UI along with any
title.

Hostile handler metadata. User agents should
protect against typical attacks against strings embedded in their
interface, for example ensuring that markup or escape characters in
such strings are not executed, that null bytes are properly
handled, that over-long strings do not cause crashes or buffer
overruns, and so forth.

Leaking Intranet URIs. The mechanism described
in this section can result in secret Intranet URIs being leaked, in
the following manner:

The user registers a third-party content handler as the default
handler for a content type.

The user then browses his corporate Intranet site and accesses
a document that uses that content type.

The user agent contacts the third party and hands the third
party the URI to the Intranet content.

No actual confidential file data is leaked in this manner, but
the URIs themselves could contain confidential information. For
example, the URI could be
https://www.corp.example.com/upcoming-aquisitions/samples.egf
, which might tell the third party that Example Corporation is
intending to merge with Samples LLC. Implementors might wish to
consider allowing administrators to disable this feature for
certain subdomains, content types, or protocols.

Leaking secure URIs. User agents should not
send HTTPS URIs to third-party sites registered as content
handlers, in the same way that user agents do not send
Referer headers from secure sites to third-party
sites.

Leaking credentials. User agents must never
send username or password information in the URIs that are escaped
and included sent to the handler sites. User agents may even avoid
attempting to pass to Web-based handlers the URIs of resources that
are known to require authentication to access, as such sites would
be unable to access the resources in question without prompting the
user for credentials themselves (a practice that would require the
user to know whether to trust the third-party handler, a decision
many users are unable to make or even understand).

4.5.1.2.4.6.1.2. Sample user interface

This section is non-normative.

A simple implementation of this feature for a desktop Web
browser might work as follows.

...where "Kittens at work" is the title of the page that invoked
the method, "http://kittens.example.org/" is the URI of that page,
"x-meow" is the string that was passed to the registerProtocolHandler()
method as its first argument ( protocol ),
"http://kittens.example.org/?show=%s" was the second argument (
uri ), and "Kittens-at-work displayer" was the
third argument ( title ).

If the user clicks the Cancel button, then nothing further
happens. If the user clicks the "Trust" button, then the handler is
remembered.

When the user then attempts to fetch a URI that uses the
"x-meow:" scheme, then it might display a dialog as follows:

...where the third option is the one that was primed by the site
registering itself earlier.

If the user does select that option, then the browser, in
accordance with the requirements described in the previous two
sections, will redirect the user to
"http://kittens.example.org/?show=x-meow%3AS2l0dGVucyBhcmUgdGhlIGN1dGVzdCE%253D".