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:
script
elements.
javascript:
URLs (e.g. the src
attribute of img
elements, or an @import
rule in a CSS style
element block).addEventListener()
, by explicit event handler content
attributes, by
event handler IDL attributes, or otherwise.Many objects can have event handlers specified. These act as non-capture event listeners for the object on which they are specified. [DOMCORE]
An event handler can
either have the value null or be set to a callback object. This is
defined using the EventHandler
callback interface
type.
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.
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.
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
interface 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, DOMString source, unsigned long lineno, unsigned long column); typedef OnErrorEventHandlerNonNull? OnErrorEventHandler;
Document
objects, and Window
objectsThe following are the event handlers (and their corresponding
event handler event types)
supported by all HTML elements, as both content attributes
and IDL attributes, and on Document
and Window
objects, as IDL attributes.
Event handler | Event handler event type |
---|---|
onabort |
abort |
oncancel |
cancel |
oncanplay |
canplay |
oncanplaythrough |
canplaythrough |
onchange |
change
|
onclick |
click
|
onclose |
close
|
oncontextmenu |
contextmenu
|
oncuechange |
cuechange |
ondblclick |
dblclick
|
ondrag |
drag |
ondragend |
dragend |
ondragenter |
dragenter |
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
|
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 |
onstalled |
stalled |
onsubmit |
submit
|
onsuspend |
suspend |
ontimeupdate |
timeupdate |
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
,
as both content attributes and IDL attributes, and on
Document
objects, as IDL
attributes:
Event handler | Event handler event type |
---|---|
onblur |
blur |
onerror |
error |
onfocus |
focus
|
onload |
load |
onscroll |
scroll |
The following are the event handlers (and their corresponding
event handler event types)
supported by Window
objects, as IDL attributes on the
Window
object, and with corresponding
content attributes and IDL attributes exposed on the body
and frameset
elements:
Event handler | Event handler event type |
---|---|
onafterprint |
afterprint |
onbeforeprint |
beforeprint |
onbeforeunload |
beforeunload |
onblur |
blur |
onerror |
error |
onfocus |
focus |
onhashchange |
hashchange |
onload |
load |
onmessage |
message
|
onoffline |
offline
|
ononline |
online
|
onpagehide |
pagehide |
onpageshow |
pageshow |
onpopstate |
popstate |
onresize |
resize
|
onscroll |
scroll |
onstorage |
storage |
onunload |
unload
|
The onerror
handler is also used for
reporting script errors.
The following are the event handlers (and their corresponding
event handler event types)
supported on Document
objects as IDL attributes:
Event handler | Event handler event type |
---|---|
onreadystatechange |
readystatechange |
The
atob()
and
btoa()
methods allow authors to transform content to and
from the base64 encoding.
[NoInterfaceObject] 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.
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.
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.
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.