← 5.6 Offline Web applicationsTable of contents6.3 Timers →
  1. 6 Web application APIs
    1. 6.1 Scripting
      1. 6.1.1 Introduction
      2. 6.1.2 Events
    2. 6.2 Base64 utility methods

6 Web application APIs

6.1 Scripting

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

6.1.2 Events

Many objects can have event handlers specified. These act as bubbling event listeners for the object on which they are specified.

An event handler can either have the value null or be set to a Function object.

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

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

When an event handler content attribute is set on an element owned by a Document that is not in a browsing context, the corresponding event handler is not changed.

Event handlers always fire before event listeners attached using addEventListener().


The Function interface represents a function in the scripting language being used. It is represented in IDL as follows:

[Callback=FunctionOnly, NoInterfaceObject]
interface Function {
  any call(in any... arguments);
};

The call(...) method is the object's callback.

In JavaScript, any Function object implements this interface.

If the Function object is a JavaScript Function, then when it is invoked by the user agent, the user agent must set the thisArg (as defined by ECMAScript edition 5 section 10.4.3 Entering Function Code) to the event handler's object. [ECMA262]

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.

6.2 Base64 utility methods

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

[Supplemental, NoInterfaceObject]
interface WindowBase64 {
  DOMString btoa(in DOMString btoa);
  DOMString atob(in 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 INVALID_CHARACTER_ERR 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 INVALID_CHARACTER_ERR exception if the input string is not valid base64 data.

Some base64 encoders add newlines or other whitespace to their output. The atob() method throws an exception if its input contains characters other than those described by the regular expression bracket expression [+/=0-9A-Za-z], so other characters need to be removed before atob() is used for decoding.