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:

8.1.1.1 The ErrorEvent interface
[Constructor(DOMString type, optional ErrorEventInit eventInitDict), Exposed=Window,Worker]
interface ErrorEvent : Event {
  readonly attribute DOMString message;
  readonly attribute DOMString filename;
  readonly attribute unsigned long lineno;
  readonly attribute unsigned long colno;
  readonly attribute any error;
};

dictionary ErrorEventInit : EventInit {
  DOMString message;
  DOMString filename;
  unsigned long lineno;
  unsigned long colno;
  any error;
};

The message attribute must return the value it was initialised to. When the object is created, this attribute must be initialised to the empty string. It represents the error message.

The filename attribute must return the value it was initialised to. When the object is created, this attribute must be initialised to the empty string. It represents the absolute URL of the script in which the error originally occurred.

The lineno attribute must return the value it was initialised to. When the object is created, this attribute must be initialised to zero. It represents the line number where the error occurred in the script.

The colno attribute must return the value it was initialised to. When the object is created, this attribute must be initialised to zero. It represents the column number where the error occurred in the script.

The error attribute must return the value it was initialised to. When the object is created, this attribute must be initialised to null. 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.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 has a name, which always starts with "on" and is followed by the name of the event for which it is intended.

An event handler can either have the value null, or be set to a callback object. The EventHandler callback function type describes how this is exposed to scripts.

Event handlers are exposed in one of 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.

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. [ECMA262]

This example demonstrates the order in which event listeners are invoked. If the button in this example is clicked by the user, the page will show four alerts, with the text "ONE", "TWO", "THREE", and "FOUR" respectively.

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

The EventHandler callback function type represents a callback used for event handlers. It is represented in Web IDL as follows:

[TreatNonCallableAsNull]
callback EventHandlerNonNull = any (Event event);
typedef EventHandlerNonNull? EventHandler;

In JavaScript, any Function object implements this interface.

For example, the following document fragment:

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

...leads to an alert saying "[object Window]" when the document is loaded, and an alert saying "[object HTMLBodyElement]" whenever the user clicks something in the page.

The return value of the function affects whether the event is canceled or not: if the return value is false, the event is canceled (except for mouseover events, where the return value has to be true to cancel the event). With beforeunload events, the value is instead used to determine the message to show the user.

For historical reasons, the onerror handler has different arguments:

[TreatNonCallableAsNull]
callback OnErrorEventHandlerNonNull = any ((Event or DOMString) event, optional DOMString source, optional unsigned long lineno, optional unsigned long column, optional any error);
typedef OnErrorEventHandlerNonNull? OnErrorEventHandler;

Similarly, the onbeforeunload handler has a different return value:

[TreatNonCallableAsNull]
callback OnBeforeUnloadEventHandlerNonNull = DOMString? (Event event);
typedef OnBeforeUnloadEventHandlerNonNull? OnBeforeUnloadEventHandler;
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:

Event handler Event handler event type
onabort abort
onautocomplete autocomplete
onautocompleteerror autocompleteerror
oncancel cancel
oncanplay canplay
oncanplaythrough canplaythrough
onchange change
onclick click
onclose close
oncontextmenu contextmenu
oncuechange cuechange
ondblclick dblclick
ondrag drag
ondragend dragend
ondragenter dragenter
ondragexit dragexit
ondragleave dragleave
ondragover dragover
ondragstart dragstart
ondrop drop
ondurationchange durationchange
onemptied emptied
onended ended
oninput input
oninvalid invalid
onkeydown keydown
onkeypress keypress
onkeyup keyup
onloadeddata loadeddata
onloadedmetadata loadedmetadata
onloadstart loadstart
onmousedown mousedown
onmouseenter mouseenter
onmouseleave mouseleave
onmousemove mousemove
onmouseout mouseout
onmouseover mouseover
onmouseup mouseup
onmousewheel mousewheel
onpause pause
onplay play
onplaying playing
onprogress progress
onratechange ratechange
onreset reset
onseeked seeked
onseeking seeking
onselect select
onshow show
onsort sort
onstalled stalled
onsubmit submit
onsuspend suspend
ontimeupdate timeupdate
ontoggle toggle
onvolumechange volumechange
onwaiting waiting

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 Documents:

Event handler Event handler event type
onblur blur
onerror error
onfocus focus
onload load
onresize resize
onscroll scroll

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 Documents:

Event handler Event handler event type
onafterprint afterprint
onbeforeprint beforeprint
onbeforeunload beforeunload
onhashchange hashchange
onlanguagechange languagechange
onmessage message
onoffline offline
ononline online
onpagehide pagehide
onpageshow pageshow
onpopstate popstate
onstorage storage
onunload unload

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

Event handler Event handler event type
onreadystatechange readystatechange
8.1.2.2.1 IDL definitions
[NoInterfaceObject]
interface GlobalEventHandlers {
           attribute EventHandler onabort;
           attribute EventHandler onautocomplete;
           attribute EventHandler onautocompleteerror;
           attribute EventHandler onblur;
           attribute EventHandler oncancel;
           attribute EventHandler oncanplay;
           attribute EventHandler oncanplaythrough;
           attribute EventHandler onchange;
           attribute EventHandler onclick;
           attribute EventHandler onclose;
           attribute EventHandler oncontextmenu;
           attribute EventHandler oncuechange;
           attribute EventHandler ondblclick;
           attribute EventHandler ondrag;
           attribute EventHandler ondragend;
           attribute EventHandler ondragenter;
           attribute EventHandler ondragexit;
           attribute EventHandler ondragleave;
           attribute EventHandler ondragover;
           attribute EventHandler ondragstart;
           attribute EventHandler ondrop;
           attribute EventHandler ondurationchange;
           attribute EventHandler onemptied;
           attribute EventHandler onended;
           attribute OnErrorEventHandler onerror;
           attribute EventHandler onfocus;
           attribute EventHandler oninput;
           attribute EventHandler oninvalid;
           attribute EventHandler onkeydown;
           attribute EventHandler onkeypress;
           attribute EventHandler onkeyup;
           attribute EventHandler onload;
           attribute EventHandler onloadeddata;
           attribute EventHandler onloadedmetadata;
           attribute EventHandler onloadstart;
           attribute EventHandler onmousedown;
  [LenientThis] attribute EventHandler onmouseenter;
  [LenientThis] attribute EventHandler onmouseleave;
           attribute EventHandler onmousemove;
           attribute EventHandler onmouseout;
           attribute EventHandler onmouseover;
           attribute EventHandler onmouseup;
           attribute EventHandler onmousewheel;
           attribute EventHandler onpause;
           attribute EventHandler onplay;
           attribute EventHandler onplaying;
           attribute EventHandler onprogress;
           attribute EventHandler onratechange;
           attribute EventHandler onreset;
           attribute EventHandler onresize;
           attribute EventHandler onscroll;
           attribute EventHandler onseeked;
           attribute EventHandler onseeking;
           attribute EventHandler onselect;
           attribute EventHandler onshow;
           attribute EventHandler onsort;
           attribute EventHandler onstalled;
           attribute EventHandler onsubmit;
           attribute EventHandler onsuspend;
           attribute EventHandler ontimeupdate;
           attribute EventHandler ontoggle;
           attribute EventHandler onvolumechange;
           attribute EventHandler onwaiting;
};

[NoInterfaceObject]
interface WindowEventHandlers {
           attribute EventHandler onafterprint;
           attribute EventHandler onbeforeprint;
           attribute OnBeforeUnloadEventHandler onbeforeunload;
           attribute EventHandler onhashchange;
           attribute EventHandler onlanguagechange;
           attribute EventHandler onmessage;
           attribute EventHandler onoffline;
           attribute EventHandler ononline;
           attribute EventHandler onpagehide;
           attribute EventHandler onpageshow;
           attribute EventHandler onpopstate;
           attribute EventHandler onstorage;
           attribute EventHandler onunload;
};

8.2 Base64 utility methods

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

[NoInterfaceObject, Exposed=Window,Worker]
interface WindowBase64 {
  DOMString btoa(DOMString btoa);
  DOMString atob(DOMString atob);
};
Window implements WindowBase64;

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 = window . 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 exception if the input string contains any out-of-range characters.

result = window . 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 exception if the input string is not valid base64 data.

8.3 Dynamic markup insertion

APIs for dynamically inserting markup into the document interact with the parser, and thus their behavior varies depending on whether they are used with HTML documents (and the HTML parser) or XHTML in XML documents (and the XML parser).

8.3.1 Opening the input stream

The open() method comes in several variants with different numbers of arguments.

document = document . open( [ type [, replace ] ] )

Causes the Document to be replaced in-place, as if it was a new Document object, but reusing the previous object, which is then returned.

If the type argument is omitted or has the value "text/html", then the resulting Document has an HTML parser associated with it, which can be given data to parse using document.write(). Otherwise, all content passed to document.write() will be parsed as plain text.

If the replace argument is present and has the value "replace", the existing entries in the session history for the Document object are removed.

The method has no effect if the Document is still being parsed.

Throws an InvalidStateError exception if the Document is an XML document.

window = document . open( url, name, features [, replace ] )

Works like the window.open() method.

8.3.2 Closing the input stream

document . close()

Closes the input stream that was opened by the document.open() method.

Throws an InvalidStateError exception if the Document is an XML document.

8.3.3 document.write()

document . write(text...)

In general, adds the given string(s) to the Document's input stream.

This method has very idiosyncratic behavior. In some cases, this method can affect the state of the HTML parser while the parser is running, resulting in a DOM that does not correspond to the source of the document (e.g. if the string written is the string "<plaintext>" or "<!--"). In other cases, the call can clear the current page first, as if document.open() had been called. In yet more cases, the method is simply ignored, or throws an exception. To make matters worse, the exact behavior of this method can in some cases be dependent on network latency, which can lead to failures that are very hard to debug. For all these reasons, use of this method is strongly discouraged.

This method throws an InvalidStateError exception when invoked on XML documents.

8.3.4 document.writeln()

document . writeln(text...)

Adds the given string(s) to the Document's input stream, followed by a newline character. If necessary, calls the open() method implicitly first.

This method throws an InvalidStateError exception when invoked on XML documents.