HTML 5

Draft Recommendation — 7 July 2008

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

5.1 Browsing contexts

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

At any one time, one of the Documents in a browsing context is the active document. The collection of Documents is the browsing context's session history.

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]

The document attribute of an AbstractView object representing a view gives the Document object of the view's browsing context's active document. [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]

When a browsing context is first created, it must be created with a single Document in its session history, whose address is about:blank, which is marked as being an HTML document, and whose character encoding is UTF-8. The Document must have a single child html node, which itself has a single child body node. If the browsing context is created specifically to be immediately navigated, then that initial navigation will have replacement enabled.

The origin of the about:blank Document is set when the Document is created, in a manner dependent on whether the browsing context created is a nested browsing context, as follows:

If the new browsing context is a nested browsing context
The origin of the about:blank Document is the origin of the active document of the new browsing context's parent browsing context at the time of its creation.
If the new browsing context is an auxiliary browsing context
The origin of the about:blank Document is the origin of the active document of the new browsing context's opener browsing context at the time of the new browsing context's creation.
Otherwise
The origin of the about:blank Document is a globally unique identifier assigned when the new browsing context is created.

5.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 Documents D that nests another browsing context C inside it, then P is said to be the parent browsing context of C, C is said to be a child browsing context of P, and C is said to be nested through D.

A browsing context A is said to be an ancestor of a browsing context B if there exists a browsing context A' that is a child browsing context of A and that is itself an ancestor of B, or if there is a browsing context P that is a child browsing context of A and that is the parent browsing context of B.

The browsing context with no parent browsing context is the top-level browsing context of all the browsing contexts nested within it (either directly or indirectly through other nested browsing contexts).

The transitive closure of parent browsing contexts for a nested browsing context gives the list of ancestor browsing contexts.

A Document is said to be fully active when it is the active document of its browsing context, and either its browsing context is a top-level browsing context, or the Document through which that browsing context is nested is itself fully active.

Because they are nested through an element, child browsing contexts are always tied to a specific Document in their parent browsing context. User agents must not allow the user to interact with child browsing contexts of elements that are in Documents that are not themselves fully active.

A nested browsing context can have a seamless browsing context flag set, if it is embedded through an iframe element with a seamless attribute.

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

An auxiliary browsing context has an opener browsing context, which is the browsing context from which the auxiliary browsing context was created, and it has a furthest ancestor browsing context, which is the top-level browsing context of the opener browsing context when the auxiliary browsing context was created.

The opener DOM attribute on the Window object must return the Window object of the browsing context from which the current browsing context was created (its opener browsing context), if there is one and it is still available.

5.1.3 Secondary browsing contexts

User agents may support secondary browsing contexts, which are browsing contexts that form part of the user agent's interface, apart from the main content area.

5.1.4 Security

A browsing context A is allowed to navigate a second browsing context B if one of the following conditions is true:

5.1.5 Threads

Each browsing context is defined as having a list of zero or more directly reachable browsing contexts. These are:

The transitive closure of all the browsing contexts that are directly reachable browsing contexts forms a unit of related browsing contexts.

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 serialized so that for each unit of related browsing contexts there is only one script being executed at a time.

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

A valid browsing context name or keyword is any string that is either a valid browsing context name or that case-insensitively matches one of: _blank, _self, _parent, or _top.

The rules for choosing a browsing context given a browsing context name are as follows. The rules assume that they are being applied in the context of a browsing context.

  1. If the given browsing context name is the empty string or _self, then the chosen browsing context must be the current one.

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

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

  4. If the given browsing context name is not _blank and there exists a browsing context whose name is the same as the given browsing context name, and the current browsing context is allowed to navigate that browsing context, and the user agent determines that the two browsing contexts are related enough that it is ok if they reach each other, then that browsing context must be the chosen one. If there are multiple matching browsing contexts, the user agent should select one in some arbitrary consistent manner, such as the most recently opened, most recently focused, or more closely related.

  5. Otherwise, a new browsing context is being requested, and what happens depends on the user agent's configuration and/or abilities:

    If the current browsing context has the sandboxed navigation browsing context flag set.
    The user agent may offer to create a new top-level browsing context or reuse an existing top-level browsing context. If the user picks one of those options, then the designated browsing context must be the chosen one (the browsing context's name isn't set to the given browsing context name). Otherwise (if the user agent doesn't offer the option to the user, or if the user declines to allow a browsing context to be used) there must not be a chosen browsing context.
    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.

5.2 The default view

The AbstractView object of default views must also implement the Window object.

[NoInterfaceObject] interface Window {
  // the current browsing context
  readonly attribute Window window;
  readonly attribute Window self;
           attribute DOMString name;
  [PutForwards=href] readonly attribute Location location;
  readonly attribute History history;
  readonly attribute UndoManager undoManager;
  Selection getSelection();

  // the user agent
  readonly attribute ClientInformation navigator; 
  readonly attribute Storage sessionStorage;
  readonly attribute Storage localStorage;
  Database openDatabase(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize);

  // user prompts
  void alert(in DOMString message);
  boolean confirm(in DOMString message);
  DOMString prompt(in DOMString message);
  DOMString prompt(in DOMString message, in DOMString default);
  void print();
  any showModalDialog(in DOMString url);
  any showModalDialog(in DOMString url, in any arguments);
  void showNotification(in DOMString title, in DOMString subtitle, in DOMString description);
  void showNotification(in DOMString title, in DOMString subtitle, in DOMString description, in VoidCallback onclick);

  // other browsing contexts
  readonly attribute Window frames;
  readonly attribute unsigned long length;
  [IndexGetter] Window XXX4(in unsigned long index); 
  readonly attribute Window opener;
  Window open();
  Window open(in DOMString url);
  Window open(in DOMString url, in DOMString target);
  Window open(in DOMString url, in DOMString target, in DOMString features);
  Window open(in DOMString url, in DOMString target, in DOMString features, in DOMString replace);

  // cross-document messaging
  void postMessage(in DOMString message, in DOMString targetOrigin);

  // event handler DOM attributes
           attribute EventListener onabort;
           attribute EventListener onbeforeunload;
           attribute EventListener onblur;
           attribute EventListener onchange;
           attribute EventListener onclick;
           attribute EventListener oncontextmenu;
           attribute EventListener ondblclick;
           attribute EventListener ondrag;
           attribute EventListener ondragend;
           attribute EventListener ondragenter;
           attribute EventListener ondragleave;
           attribute EventListener ondragover;
           attribute EventListener ondragstart;
           attribute EventListener ondrop;
           attribute EventListener onerror;
           attribute EventListener onfocus;
           attribute EventListener onkeydown;
           attribute EventListener onkeypress;
           attribute EventListener onkeyup;
           attribute EventListener onload;
           attribute EventListener onmessage;
           attribute EventListener onmousedown;
           attribute EventListener onmousemove;
           attribute EventListener onmouseout;
           attribute EventListener onmouseover;
           attribute EventListener onmouseup;
           attribute EventListener onmousewheel;
           attribute EventListener onresize;
           attribute EventListener onscroll;
           attribute EventListener onselect;
           attribute EventListener onstorage;
           attribute EventListener onsubmit;
           attribute EventListener onunload;
};

The window, frames, and self DOM attributes must all return the Window object itself.

The Window object also provides the scope for script execution. Each Document in a browsing context has an associated list of added properties which, when a document is active, are available on the Document's default view Window object. A Document object's list of added properties must be empty when the Document object is created.

Objects implementing the Window interface must also implement the EventTarget interface.

Window objects also have an implicit [[Get]] method which returns nested browsing contexts.

5.2.1 Security

User agents must raise a security exception whenever any of the members of a Window object are accessed by scripts whose effective script origin is not the same as the Window object's browsing context's active document's effective script origin, with the following exceptions:

User agents must not allow scripts to override the location object's setter.

5.2.2 Constructors

All Window objects must provide the following constructors:

Audio()
Audio(src)

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

5.2.3 APIs for creating and navigating browsing contexts by name

The open() method on Window objects provides a mechanism for navigating an existing browsing context or opening and navigating an auxiliary browsing context.

The method has four arguments, though they are all optional.

The first argument, url, must be a valid URL for a page to load in the browsing context. If no arguments are provided, then the url argument defaults to "about:blank". The argument must be resolved to an absolute URL (or an error) when the method is invoked.

The second argument, target, specifies the name of the browsing context that is to be navigated. It must be a valid browsing context name or keyword. If fewer than two arguments are provided, then the name argument defaults to the value "_blank".

The third argument, features, has no effect and is supported for historical reasons only.

The fourth argument, replace, specifies whether or not the new page will replace the page currently loaded in the browsing context, when target identifies an existing browsing context (as opposed to leaving the current page in the browsing context's session history). When three or fewer arguments are provided, replace defaults to false.

When the method is invoked, the user agent must first select a browsing context to navigate by applying the rules for choosing a browsing context given a browsing context name using the target argument as the name and the browsing context of the script as the context in which the algorithm is executed, unless the user has indicated a preference, in which case the browsing context to navigate may instead be the one indicated by the user.

For example, suppose there is a user agent that supports control-clicking a link to open it in a new tab. If a user clicks in that user agent on an element whose onclick handler uses the window.open() API to open a page in an iframe, but, while doing so, holds the control key down, the user agent could override the selection of the target browsing context to instead target a new tab.

Then, the user agent must navigate the selected browsing context to the absolute URL (or error) obtained from resolving url. If the replace is true, then replacement must be enabled; otherwise, it must not be enabled unless the browsing context was just created as part of the the rules for choosing a browsing context given a browsing context name. The navigation must be done with the script browsing context of the script that invoked the method as the source browsing context.

The method must return the Window object of the default view of the browsing context that was navigated, or null if no browsing context was navigated.

The name attribute of the Window object must, on getting, return the current name of the browsing context, and, on setting, set the name of the browsing context to the new value.

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

5.2.4 Accessing other browsing contexts

The length DOM attribute on the Window interface must return the number of child browsing contexts of the active Document.

The XXX4(index) method must return the indexth child browsing context of the active Document, sorted in document order of the elements nesting those browsing contexts.

5.3 Origin

The origin of a resource and the effective script origin of a resource are both either opaque identifiers or tuples consisting of a scheme component, a host component, a port component, and optionally extra data.

The extra data could include the certificate of the site when using encrypted connections, to ensure that if the site's secure certificate changes, the origin is considered to change as well.

These characteristics are defined as follows:

For URLs

The origin and effective script origin of the URL is whatever is returned by the following algorithm:

  1. Let url be the URL for which the origin is being determined.

  2. Parse url.

  3. If url does not use a server-based naming authority, or if parsing url failed, or if url is not an absolute URL, then return a new globally unique identifier.

  4. Let scheme be the <scheme> component of the URI, converted to lowercase.

  5. If the UA doesn't support the protocol given by scheme, then return a new globally unique identifier.

  6. If scheme is "file", then the user agent may return a UA-specific value.

  7. Let host be the <host> component of url.

  8. Apply the IDNA ToASCII algorithm to host, with both the AllowUnassigned and UseSTD3ASCIIRules flags set. Let host be the result of the ToASCII algorithm.

    If ToASCII fails to convert one of the components of the string, e.g. because it is too long or because it contains invalid characters, then return a new globally unique identifier. [RFC3490]

  9. Let host be the result of converting host to lowercase.

  10. If there is no <port> component, then let port be the default port for the protocol given by scheme. Otherwise, let port be the <port> component of url.

  11. Return the tuple (scheme, host, port).

In addition, if the URL is in fact associated with a Document object that was created by parsing the resource obtained from fetching URL, and this was done over a secure connection, then the server's secure certificate may be added to the origin as additional data.

For scripts

The origin and effective script origin of a script are determined from another resource, called the owner:

If a script is in a script element
The owner is the Document to which the script element belongs.
If a script is in an event handler content attribute
The owner is the Document to which the attribute node belongs.
If a script is a function or other code reference created by another script
The owner is the script that created it.
If a script is a javascript: URL that was returned as the location of an HTTP redirect (or equivalent in other protocols)
The owner is the URL that redirected to the javascript: URL.
If a script is a javascript: URL in an attribute
The owner is the Document of the element on which the attribute is found.
If a script is a javascript: URL in a style sheet
The owner is the URL of the style sheet.
If a script is a javascript: URL to which a browsing context is being navigated, the URL having been provided by the user (e.g. by using a bookmarklet)
The owner is the Document of the browsing context's active document.
If a script is a javascript: URL to which a browsing context is being navigated, the URL having been declared in markup
The owner is the Document of the element (e.g. an a or area element) that declared the URL.
If a script is a javascript: URL to which a browsing context is being navigated, the URL having been provided by script
The owner is the script that provided the URL.

The origin of the script is then equal to the origin of the owner, and the effective script origin of the script is equal to the effective script origin of the owner.

For Document objects and images
If a Document is in a browsing context whose sandboxed origin browsing context flag is set
The origin is a globally unique identifier assigned when the Document is created.
If a Document or image was returned by the XMLHttpRequest API
The origin and effective script origin are equal to the origin and effective script origin of the Document object that was the active document of the browsing context of the Window object from which the XMLHttpRequest constructor was invoked. (That is, they track the Document to which the XMLHttpRequest object's Document pointer pointed when it was created.) [XHR]
If a Document or image was generated from a javascript: URL
The origin is equal to the origin of the script of that javascript: URL.
If a Document or image was served over the network and has an address that uses a URL scheme with a server-based naming authority
The origin is the origin of the address of the Document or image.
If a Document or image was generated from a data: URL that was returned as the location of an HTTP redirect (or equivalent in other protocols)
The origin is the origin of the URL that redirected to the data: URL.
If a Document or image was generated from a data: URL found in another Document or in a script
The origin is the origin of the Document or script in which the data: URL was found.
If a Document has the address "about:blank"
The origin of the Document is the origin it was assigned when its browsing context was created.
If a Document or image was obtained in some other manner (e.g. a data: URL typed in by the user, a Document created using the createDocument() API, a data: URL returned as the location of an HTTP redirect, etc)
The origin is a globally unique identifier assigned when the Document or image is created.

When a Document is created, unless stated otherwise above, its effective script origin is initialized to the origin of the Document. However, the document.domain attribute can be used to change it.

The Unicode serialization of an origin is the string obtained by applying the following algorithm to the given origin:

  1. If the origin in question is not a scheme/host/port tuple, then return the empty string and abort these steps.

  2. Otherwise, let result be the scheme part of the origin tuple.

  3. Append the string "://" to result.

  4. Apply the IDNA ToUnicode algorithm to each component of the host part of the origin tuple, and append the results — each component, in the same order, separated by U+002E FULL STOP characters (".") — to result.

  5. If the port part of the origin tuple gives a port that is different from the default port for the protocol given by the scheme part of the origin tuple, then append a U+003A COLON character (":") and the given port, in base ten, to result.

  6. Return result.

The ASCII serialization of an origin is the string obtained by applying the following algorithm to the given origin:

  1. If the origin in question is not a scheme/host/port tuple, then return the empty string and abort these steps.

  2. Otherwise, let result be the scheme part of the origin tuple.

  3. Append the string "://" to result.

  4. Apply the IDNA ToASCII algorithm the host part of the origin tuple, with both the AllowUnassigned and UseSTD3ASCIIRules flags set, and append the results result.

    If ToASCII fails to convert one of the components of the string, e.g. because it is too long or because it contains invalid characters, then return the empty string and abort these steps. [RFC3490]

  5. If the port part of the origin tuple gives a port that is different from the default port for the protocol given by the scheme part of the origin tuple, then append a U+003A COLON character (":") and the given port, in base ten, to result.

  6. Return result.

Two origins are said to be the same origin if the following algorithm returns true:

  1. Let A be the first origin being compared, and B be the second origin being compared.

  2. If A and B are both opaque identifiers, and their value is equal, then return true.

  3. Otherwise, if either A or B or both are opaque identifiers, return false.

  4. If A and B have scheme components that are not identical, return false.

  5. If A and B have host components that are not identical, return false.

  6. If A and B have port components that are not identical, return false.

  7. If either A or B have additional data, but that data is not identical for both, return false.

  8. Return true.

5.3.1 Relaxing the same-origin restriction

The domain attribute on Document objects must be initialized to the document's domain, if it has one, and the empty string otherwise. On getting, the attribute must return its current value, unless the document was created by XMLHttpRequest, in which case it must throw an INVALID_ACCESS_ERR exception. On setting, the user agent must run the following algorithm:

  1. If the document was created by XMLHttpRequest, throw an INVALID_ACCESS_ERR exception and abort these steps.

  2. Apply the IDNA ToASCII algorithm to the new value, with both the AllowUnassigned and UseSTD3ASCIIRules flags set. Let new value be the result of the ToASCII algorithm.

    If ToASCII fails to convert one of the components of the string, e.g. because it is too long or because it contains invalid characters, then throw a security exception and abort these steps. [RFC3490]

  3. If new value is not exactly equal to the current value of the document.domain attribute, then run these substeps:

    1. If the current value is an IP address, throw a security exception and abort these steps.

    2. If new value, prefixed by a U+002E FULL STOP ("."), does not exactly match the end of the current value, throw a security exception and abort these steps.

  4. Set the attribute's value to new value.

  5. Set the host part of the effective script origin tuple of the Document to new value.

  6. Set the port part of the effective script origin tuple of the Document to "manual override" (a value that, for the purposes of comparing origins, is identical to "manual override" but not identical to any other value).

The domain of a Document is the host part of the document's origin, if that is a scheme/host/port tuple. If it isn't, then the document does not have a domain.

The domain attribute is used to enable pages on different hosts of a domain to access each others' DOMs.

5.4 Scripting

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:

When a script is created, it is associated with a script execution context, a script browsing context, and a script document context.

5.4.1 Script execution contexts

The script execution context of a script is defined when that script is created. It is either a Window object or an empty object.

When the script execution context of a script is an empty object, it can't do anything that interacts with the environment.

A script execution context always has an associated browsing context, known as the script browsing context. If the script execution context is a Window object, then that object's browsing context is it. Otherwise, the script execution context is associated explicitly with a browsing context when it is created.

It is said that scripting is disabled in a script execution context when any of the following conditions are true:

A node is said to be without script if either the Document object of the node (the node itself, if it is itself a Document object) does not have an associated browsing context, or scripting is disabled in that browsing context.

A node is said to be with script if it is not without script.

If you can find a better pair of terms than "with script" and "without script" let me know. The only things I can find that are less confusing are also way, way longer.

When a script is to be executed in a script execution context in which scripting is disabled, the script must do nothing and return nothing (a void return value).

Thus, for instance, enabling designMode will disable any event handler attributes, event listeners, timeouts, etc, that were set by scripts in the document.

Every script whose script execution context is a Window object is also associated with a Document object, known as its script document context. It is used to resolve URLs. The document is assigned when the script is created, as with the script browsing context.

5.4.2 Security exceptions

Define security exception.

5.4.3 The javascript: protocol

A URL using the javascript: protocol must, if and when dereferenced, be evaluated by executing the script obtained using the content retrieval operation defined for javascript: URLs. [JSURL]

When a browsing context is navigated to a javascript: URL, and the active document of that browsing context has the same origin as the script given by that URL, the script execution context must be the Window object of the browsing context being navigated, and the script document context must be that active document.

When a browsing context is navigated to a javascript: URL, and the active document of that browsing context has an origin that is not the same as that of the script given by the URL, the script execution context must be an empty object, and the script browsing context must be the browsing context being navigated.

Otherwise, the script execution context must be an empty object, and the script execution context's associated browsing context must be the browsing context of the Document object of the element, attribute, or style sheet from which the javascript: URL was reached.

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

Otherwise, the URL 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 return value converted to a string value.

Certain contexts, in particular img elements, ignore the Content-Type metadata.

So for example a javascript: URL for a src attribute of an img element would be evaluated in the context of an 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: URL in an href attribute of an a element would only be evaluated when the link was followed.

The src attribute of an iframe element would be evaluated in the context of the iframe's own browsing context; once evaluated, its return value (if it was not void) would replace that browsing context's document, thus changing the variables visible in that browsing context.

The rules for handling script execution in a script execution context include 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.

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

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

Objects other than Element objects, in particular Window, only have event handler DOM attribute (since they have no content attributes).

Event handler content attributes, when specified, must contain valid ECMAScript code matching the ECMAScript FunctionBody production. [ECMA262]

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 Window object of the browsing 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]

The script execution context of the event handler must be the Window object at the end of the scope chain. The script document context of the event handler must be the Document object that owns the event handler content attribute that was set.

How do we allow non-JS event handlers?

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.

The onerror handler is also used for reporting script errors.

onfocus

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 a storage event 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.

All 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. (The listener argument is emphatically not the event handler attribute itself.)

5.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 (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), 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 load event means firing a simple event called load. Firing an error event means firing a simple event called error.

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.

5.4.4.3. Events and the Window object

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:

  1. In the capture phase, the event must be dispatched to the Window object before being dispatched to any of the nodes.
  2. In the bubble phase, the event must be dispatched to the Window object at the end of the phase, unless bubbling has been prevented.
5.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 onerror event 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 DOMStrings; the first must give the message that the UA is considering reporting, the second must give the absolute URL of the resource in which the error occurred, and the third must give the line number in that resource on which the error 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.

If the value is null

The error should not reported to the user.

If the value is anything else

The error should be reported to the user.

The initial value of onerror must be undefined.

5.5 User prompts

5.5.1 Simple 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 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 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.

5.5.2 Printing

The print() method, when invoked, must run the printing steps.

User agents should also run the printing steps whenever the user attempts to obtain a physical form (e.g. printed copy), or the representation of a physical form (e.g. PDF copy), of a document.

The printing steps are as follows:

  1. The user agent may display a message to the user and/or may abort these steps.

    For instance, a kiosk browser could silently ignore any invocations of the print() method.

    For instance, a browser on a mobile device could detect that there are no printers in the vicinity and display a message saying so before continuing to offer a "save to PDF" option.

  2. The user agent must fire a simple event called beforeprint at the Window object of the browsing context of the Document that is being printed, as well as any nested browsing contexts in it.

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

  3. 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 wait for the user to either accept or decline before returning; if so, the user agent must pause while the method is waiting. Even 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.

  4. The user agent must fire a simple event called afterprint at the Window object of the browsing context of the Document that is being printed, as well as any nested browsing contexts in it.

    The afterprint event 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.

5.5.3 Dialogs implemented using separate documents

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

  1. If the user agent is configured such that this invocation of showModalDialog() 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.

  2. Let the list of background browsing contexts be a list of all the browsing contexts that:

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

  3. Disable the user interface for all the browsing contexts in the 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 prevent those browsing contexts from receiving events from sources other than the user, from running scripts, from running animations, and so forth.

  4. Create a new auxiliary browsing context, with the opener browsing context being the browsing context of the Window object on which the showModalDialog() method was called. The new auxiliary browsing context has no name.

    This browsing context implements the ModalWindow interface.

  5. Let the dialog arguments of the new browsing context be set to the value of arguments.

  6. Let the dialog arguments' origin be the origin of the script that called the showModalDialog() method.

  7. Navigate the new browsing context to url, with replacement enabled, and with the script browsing context of the script that invoked the method as the source browsing context.

  8. Wait for the browsing context to be closed. (The user agent must allow the user to indicate that the browsing context is to be closed.)

  9. Reenable the user interface for all the browsing contexts in the list of background browsing contexts.

  10. Return the auxiliary browsing context's return value.

Browsing contexts created by the above algorithm must implement the ModalWindow interface:

[XXX] interface ModalWindow {
  readonly attribute any dialogArguments;
           attribute DOMString returnValue;
};

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

The dialogArguments DOM attribute, on getting, must check whether its browsing context's active document's origin is the same as the dialog arguments' origin. If it is, then the browsing context's dialog arguments must be returned unchanged. Otherwise, if the dialog arguments are an object, then the empty string must be returned, and if the dialog arguments are not an object, then the stringification of the dialog arguments must be returned.

These browsing contexts also have an associated return value. The return value of a browsing context must be initialized to the empty string when the browsing context is created.

The returnValue DOM attribute, on getting, must return the return value of its browsing context, and on setting, must set the return value to the given new value.

5.5.4 Notifications

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, each origin can be flagged as being a trusted 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 being trusted 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.

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

If the method was invoked from a script whose script browsing context has the sandboxed annoyances browsing context flag set, then the notification must be shown within that browsing context. The notification is said to be a sandboxed notification.

Otherwise, if the origin of the script browsing context of the script that invoked the method is not flagged as being a trusted notification source, then the notification should be rendered within the top-level browsing context of the script browsing context of the script that invoked the method. The notification is said to be a normal notification. User agents should provide a way to set the origin's trusted notification source flag from the notification, so that the user can benefit from notifications even when the user agent is not the active application.

Otherwise, the origin is flagged as a trusted notification source, and the notification should be shown using the platform conventions for system-wide notifications. The notification is said to be a trusted notification. User agents may provide a way to unset the origin's trusted notification source flag 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 sandboxed iframe and 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.

When a normal notification (but not a sandboxed notification) is shown, the user agent may bring the user's attention to the top-level browsing context of the script browsing context of the script that invoked the method, if that would be useful; but user agents should not use system-wide notification mechanisms to do so.

When a trusted notification is shown, the user agent should bring the user's attention to the notification and the script browsing context of the script that invoked the method, as per the platform conventions for attracting the user's attention to applications.

In the case of normal notifications, typically the only attention-grabbing device that would be employed would be something like flashing the tab's caption, or making it bold, or some such.

In addition, in the case of a trusted notification, the entire window could flash, or the browser's application icon could bounce or flash briefly, or a short sound effect could be played.

Notifications should include the following content:

If a new notification from one browsing context has title, subtitle, and description strings that are identical to the title, subtitle, and description strings of an already-active notification from the same browsing context or another browsing context with the same origin, the user 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 a browsing context that is hidden, it should be shown for its complete lifetime once the user brings that browsing context into 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 the onclick callback argument was present and is not null, then the script browsing context of the function given by onclick should be brought to the user's attention, and the onclick callback should then be invoked.

5.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:

interface ClientInformation {
  readonly attribute boolean onLine;
  void registerProtocolHandler(in DOMString protocol, in DOMString url, in DOMString title);
  void registerContentHandler(in DOMString mimeType, in DOMString url, in DOMString title);
};

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

There is an example of how these methods could be presented to the user below.

The arguments to the methods have the following meanings:

protocol (registerProtocolHandler() only)

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

mimeType (registerContentHandler() only)

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.

url

The URL of the page that will handle the requests. When the user agent uses this URL, it must replace the first occurrence of the exact literal string "%s" with an escaped version of the URL of the content in question (as defined below), then resolve the resulting URL (using the document base URL of the script document context of the script that originally invoked the registerContentHandler() or registerProtocolHandler() method), and then fetch the resulting URL using the GET method (or equivalent for non-HTTP URLs).

To get the escaped version of the URL of the content in question, the user agent must resolve the URL, and then every character in the URL that doesn't match the <query> production defined in RFC 3986 must be replaced by the percent-encoded form of the character. [RFC3986]

If the user had visited a site at http://example.com/ that made the following call:

navigator.registerContentHandler('application/x-soup', 'soup?url=%s', 'SoupWeb™')

...and then, much later, while visiting http://www.example.net/, clicked on a link such as:

<a href="chickenkïwi.soup">Download our Chicken Kiwi soup!</a>

...then, assuming this chickenkïwi.soup file was served with the MIME type application/x-soup, the UA might navigate to the following URL:

http://example.com/soup?url=http://www.example.net/chickenk%C3%AFwi.soup

This site could then fetch the chickenkïwi.soup file and do whatever it is that it does with soup (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 URLs 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 url 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 url 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.

5.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 wholly 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 URLs. The mechanism described in this section can result in secret Intranet URLs being leaked, in the following manner:

  1. The user registers a third-party content handler as the default handler for a content type.
  2. The user then browses his corporate Intranet site and accesses a document that uses that content type.
  3. 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 URLs themselves could contain confidential information. For example, the URL could be http://www.corp.example.com/upcoming-aquisitions/the-sample-company.egf, which might tell the third party that Example Corporation is intending to merge with The Sample Company. Implementors might wish to consider allowing administrators to disable this feature for certain subdomains, content types, or protocols.

Leaking secure URLs. User agents should not send HTTPS URLs 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 URLs that are escaped and included sent to the handler sites. User agents may even avoid attempting to pass to Web-based handlers the URLs 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).

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

The registerProtocolHandler() method could display a modal dialog box:

||[ Protocol Handler Registration ]|||||||||||||||||||||||||||
|                                                            |
| This Web page:                                             |
|                                                            |
|    Kittens at work                                         |
|    http://kittens.example.org/                             |
|                                                            |
| ...would like permission to handle the protocol "x-meow:"  |
| using the following Web-based application:                 |
|                                                            |
|    Kittens-at-work displayer                               |
|    http://kittens.example.org/?show=%s                     |
|                                                            |
| Do you trust the administrators of the "kittens.example.   |
| org" domain?                                               |
|                                                            |
|              ( Trust kittens.example.org )  (( Cancel ))   |
|____________________________________________________________|

...where "Kittens at work" is the title of the page that invoked the method, "http://kittens.example.org/" is the URL 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 (url), 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 URL that uses the "x-meow:" scheme, then it might display a dialog as follows:

||[ Unknown Protocol ]||||||||||||||||||||||||||||||||||||||||
|                                                            |
| You have attempted to access:                              |
|                                                            |
|    x-meow:S2l0dGVucyBhcmUgdGhlIGN1dGVzdCE%3D               |
|                                                            |
| How would you like FerretBrowser to handle this resource?  |
|                                                            |
|  (o) Contact the FerretBrowser plugin registry to see if   |
|      there is an official way to handle this resource.     |
|                                                            |
|  ( ) Pass this URL to a local application:                 |
|      [ /no application selected/             ] ( Choose )  |
|                                                            |
|  ( ) Pass this URL to the "Kittens-at-work displayer"      |
|      application at "kittens.example.org".                 |
|                                                            |
|  [ ] Always do this for resources using the "x-meow"       |
|      protocol in future.                                   |
|                                                            |
|                                     ( Ok )  (( Cancel ))   |
|____________________________________________________________|

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

The registerContentHandler() method would work equivalently, but for unknown MIME types instead of unknown protocols.