HTML: The Living Standard

Developer's Edition — Last Updated 17 October 2018

1. 8 Web application APIs
   1. 8.1 Scripting
      1. 8.1.1 Introduction
         1. 8.1.1.1 Runtime script errors
         2. 8.1.1.2 Unhandled promise rejections
            1. 8.1.1.2.1 HostPromiseRejectionTracker(promise, operation)
            2. 8.1.1.2.2 The PromiseRejectionEvent interface
         3. 8.1.1.3 HostEnsureCanCompileStrings(callerRealm, calleeRealm)
      2. 8.1.2 Events
         1. 8.1.2.1 Event handlers
         2. 8.1.2.2 Event handlers on elements, Document objects, and Window objects
   2. 8.2 The WindowOrWorkerGlobalScope mixin
   3. 8.3 Base64 utility methods

8 Web application APIs

8.1 Scripting

8.1.1 Introduction

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:

• Processing of script elements.
• Navigating to javascript: URLs.
• Event handlers, whether registered through the DOM using addEventListener(), by explicit event handler content attributes, by event handler IDL attributes, or otherwise.
• Processing of technologies like SVG that have their own scripting features.

8.1.1.1 Runtime script errors

The message attribute must return the value it was initialized to. It represents the error message.

The filename attribute must return the value it was initialized to. It represents the URL of the script in which the error originally occurred.

The lineno attribute must return the value it was initialized to. It represents the line number where the error occurred in the script.

The colno attribute must return the value it was initialized to. It represents the column number where the error occurred in the script.

The error attribute must return the value it was initialized to. Where appropriate, it is set to the object representing the error (e.g., the exception object in the case of an uncaught DOM exception).

8.1.1.2 Unhandled promise rejections

In addition to synchronous runtime script errors, scripts may experience asynchronous promise rejections, tracked via the unhandledrejection and rejectionhandled events.

When the user agent is to notify about rejected promises on a given environment settings object settings object, it must run these steps:

1. Let list be a copy of settings object's about-to-be-notified rejected promises list.

2. If list is empty, return.

3. Clear settings object's about-to-be-notified rejected promises list.

4. Queue a task to run the following substep:

   1. For each promise p in list:

      1. If p's [[PromiseIsHandled]] internal slot is true, continue to the next iteration of the loop.

      2. Let notHandled be the result of firing an event named unhandledrejection at settings object's global object, using PromiseRejectionEvent, with the cancelable attribute initialized to true, the promise attribute initialized to p, and the reason attribute initialized to the value of p's [[PromiseResult]] internal slot.

      3. If notHandled is false, then the promise rejection is handled. Otherwise, the promise rejection is not handled.

      4. If p's [[PromiseIsHandled]] internal slot is false, add p to settings object's outstanding rejected promises weak set.

This algorithm results in promise rejections being marked as handled or not handled. These concepts parallel handled and not handled script errors. If a rejection is still not handled after this, then the rejection may be reported to a developer console.

8.1.1.2.1 HostPromiseRejectionTracker(promise, operation)

JavaScript contains an implementation-defined HostPromiseRejectionTracker(promise, operation) abstract operation. User agents must use the following implementation: [JAVASCRIPT]

1. Let script be the running script.

2. If script's muted errors is true, terminate these steps.

3. Let settings object be script's settings object.

4. If operation is "reject",

   1. Add promise to settings object's about-to-be-notified rejected promises list.

5. If operation is "handle",

   1. If settings object's about-to-be-notified rejected promises list contains promise, then remove promise from that list and return.

   2. If settings object's outstanding rejected promises weak set does not contain promise, then return.

   3. Remove promise from settings object's outstanding rejected promises weak set.

   4. Queue a task to fire an event named rejectionhandled at settings object's global object, using PromiseRejectionEvent, with the promise attribute initialized to promise, and the reason attribute initialized to the value of promise's [[PromiseResult]] internal slot.

8.1.1.2.2 The PromiseRejectionEvent interface

The promise attribute must return the value it was initialized to. It represents the promise which this notification is about.

The reason attribute must return the value it was initialized to. It represents the rejection reason for the promise.

8.1.1.3 HostEnsureCanCompileStrings(callerRealm, calleeRealm)

JavaScript contains an implementation-defined HostEnsureCanCompileStrings(callerRealm, calleeRealm) abstract operation. User agents must use the following implementation: [JAVASCRIPT]

1. Perform ? EnsureCSPDoesNotBlockStringCompilation(callerRealm, calleeRealm). [CSP]

8.1.2 Events

8.1.2.1 Event handlers

Many objects can have event handlers specified. These act as non-capture event listeners for the object on which they are specified. [DOM]

An event handler is a struct with two items:

• a value, which is either null or a callback object. The EventHandler callback function type describes how this is exposed to scripts.

• a listener, which is either null or an event listener.

Event handlers are exposed in two ways.

The first way, common to all event handlers, is as an event handler IDL attribute.

The second way is as an event handler content attribute. Event handlers on HTML elements and some of the event handlers on Window objects are exposed in this way.

For both of these two ways, the event handler is exposed through a name, which is a string that always starts with "on" and is followed by the name of the event for which the handler is intended.

Most of the time, the object that exposes an event handler is the same as the object on which the corresponding event listener is added. However, the body and frameset elements expose several event handlers that act upon the element's Window object, if one exists. In either case, we call the object an event handler acts upon the target of that event handler.

An event handler IDL attribute is an IDL attribute for a specific event handler. The name of the IDL attribute is the same as the name of the event handler.

An event handler content attribute is a content attribute for a specific event handler. The name of the content attribute is the same as the name of the event handler.

Event handler content attributes, when specified, must contain valid JavaScript code which, when parsed, would match the FunctionBody production after automatic semicolon insertion.

<button id="test">Start Demo</button>
<script>
 var button = document.getElementById('test');
 button.addEventListener('click', function () { alert('ONE') }, false);
 button.setAttribute('onclick', "alert('NOT CALLED')"); // event handler listener is registered here
 button.addEventListener('click', function () { alert('THREE') }, false);
 button.onclick = function () { alert('TWO'); };
 button.addEventListener('click', function () { alert('FOUR') }, false);
</script>

<button id="test">Start Demo</button>
<script>
 var button = document.getElementById('test');
 button.addEventListener('click', function () { alert('ONE') }, false);
 button.setAttribute('onclick', "alert('NOT CALLED')"); // event handler is activated here
 button.addEventListener('click', function () { alert('TWO') }, false);
 button.onclick = null;                                 // but deactivated here
 button.addEventListener('click', function () { alert('THREE') }, false);
 button.onclick = function () { alert('FOUR'); };       // and re-activated here
 button.addEventListener('click', function () { alert('FIVE') }, false);
</script>

The EventHandler callback function type represents a callback used for event handlers.

In JavaScript, any Function object implements this interface.

<body onload="alert(this)" onclick="alert(this)">

For historical reasons, the onerror handler has different arguments:

window.onerror = (message, source, lineno, colno, error) => { … };

Similarly, the onbeforeunload handler has a different return value: it will be cast to a string.

8.1.2.2 Event handlers on elements, Document objects, and Window objects

The following are the event handlers (and their corresponding event handler event types) supported by all HTML elements, as both event handler content attributes and event handler IDL attributes; and supported by all Document and Window objects, as event handler IDL attributes:

The following are the event handlers (and their corresponding event handler event types) supported by all HTML elements other than body and frameset elements, as both event handler content attributes and event handler IDL attributes; supported by all Document objects, as event handler IDL attributes; and supported by all Window objects, as event handler IDL attributes on the Window objects themselves, and with corresponding event handler content attributes and event handler IDL attributes exposed on all body and frameset elements that are owned by that Window object's associated Document:

We call the set of the names of the event handlers listed in the first column of this table the Window-reflecting body element event handler set.

The following are the event handlers (and their corresponding event handler event types) supported by Window objects, as event handler IDL attributes on the Window objects themselves, and with corresponding event handler content attributes and event handler IDL attributes exposed on all body and frameset elements that are owned by that Window object's associated Document:

The following are the event handlers (and their corresponding event handler event types) supported by all HTML elements, as both event handler content attributes and event handler IDL attributes; and supported by all Document objects, as event handler IDL attributes:

The following are the event handlers (and their corresponding event handler event types) supported on Document objects as event handler IDL attributes:

8.2 The WindowOrWorkerGlobalScope mixin

The WindowOrWorkerGlobalScope mixin is for use of APIs that are to be exposed on Window and WorkerGlobalScope objects.

Other standards are encouraged to further extend it using partial interface mixin WindowOrWorkerGlobalScope { … }; along with an appropriate reference.

origin = self . origin

Returns the global object's origin, serialized as string.

var frame = document.createElement("iframe")
frame.onload = function() {
  var frameWin = frame.contentWindow
  console.log(frameWin.location.origin) // "null"
  console.log(frameWin.origin) // "https://stargate.example"
}
document.body.appendChild(frame)

The origin attribute's getter must return this object's relevant settings object's origin, serialized.

8.3 Base64 utility methods

The atob() and btoa() methods allow developers to transform content to and from the base64 encoding.

In these APIs, for mnemonic purposes, the "b" can be considered to stand for "binary", and the "a" for "ASCII". In practice, though, for primarily historical reasons, both the input and output of these functions are Unicode strings.

result = self . btoa( data )

Takes the input data, in the form of a Unicode string containing only characters in the range U+0000 to U+00FF, each representing a binary byte with values 0x00 to 0xFF respectively, and converts it to its base64 representation, which it returns.

Throws an "InvalidCharacterError" DOMException exception if the input string contains any out-of-range characters.

result = self . atob( data )

Takes the input data, in the form of a Unicode string containing base64-encoded binary data, decodes it, and returns a string consisting of characters in the range U+0000 to U+00FF, each representing a binary byte with values 0x00 to 0xFF respectively, corresponding to that binary data.

Throws an "InvalidCharacterError" DOMException if the input string is not valid base64 data.