JavaScript

$e.add Function

Syntax

$e.add(ele as object/string/array, type as string, eventHandler as function [, scope as object, scopeOverride as logical, groupName as string])

Arguments

eleobject|string|array

An HTML element, an ID or NAME, or an array of HTML elements, IDs, and/or NAMEs

typestring

The event's type. These events are standard DOM events (minus the "on"), like 'click', 'mousedown', 'mouseup', 'keydown', 'blur' etc. Possible values are:

click

When the user clicks on an element.

dblclick

When the user double clicks on an element.

mousedown

When the user presses the mouse down on an element.

mouseup

When the user releases the mouse button after pressing mouse down on an element.

mouseover

When the mouse cursor moves over an element.

mousemove

When the mouse cursor is being moved over an element.

mouseout

When the mouse cursor leaves an element.

keypress

When the user presses a key. Will fire repeatedly while the key is being pressed.

keydown

When the user presses a key. Fires on the key down.

keyup

When the user presses a key and then releases it.

focus

When the user gives focus to an element.

blur

When a user 'blurs' an element. I.e. when an element looses focus.

change

When the user makes a change in a form element.

reset

When the user resets the data in a form using a 'Reset' button.

submit

When the user clicks a form's 'Submit' button.

scroll

When the user scrolls a scrollable element. This could be the page itself, of a DIV that has scroll bars.

resize

When the user resizes the browser window.

load

When the page is loaded.

unload

When the page is unloaded (i.e. when you navigate to another page, or the browser is closed).

eventHandlerfunction(e, scope)

The Javascript function you would liked to have called when the event occurs. The function will have access to the following parameters:

eobject

The DOM event object. See The DOM 'Event' Object below.

scopeobject

The scope object (see scope below.)

scopeobject

An object scope to be passed into the function that handles the event. The scope object is passed in as the second parameter to the event handler function (the DOM event object is passed in as the first parameter).

This is an advanced parameter.
scopeOverridelogical

A true/false value for whether or not you would like the passed in scope to take the place of the HTML element in the "this." namespace.

This is an advanced parameter.
groupNamestring

A group name for the event. Can be used with $e.removeGroup() function to remove multiple events from multiple objects.

Your page might contain elements that have had events bound to them using the $e.add() function. If any of these elements are subsequently removed from the page (through setting innerHTML of a parent element, or through DOM manipulation), it is important to remove the events from these elements, or else a memory leak might occur.

Description

Add one or more event listeners to an HTML element.

Discussion

The $e.add() function allows you to add an event to a single or multiple HTML elements. You can call the $e.add() function multiple times for a given element and event, allowing you to add multiple event handlers for the same event. For example:

$e.add('firstname','blur',validate1);
$e.add('firstname','blur',validate2);

When the 'firstname' element loses focus, the validate2() function will be called first (since it was the most recent event handler to be added), and then the validate1() function will be called next.

When you add an event to an element that already has an event defined in the HTML, the event defined in the HTML will still execute, and will be executed before any events that are added using the $e.add() function.

The DOM 'Event' Object 

When a DOM event (such as 'blur', 'keypress' etc.) occurs, the browser automatically stores relevant information about the event (such as what key was pressed, what is the mouse position, etc.) in the DOM event object. This object is automatically passed in as the first parameter to the Javascript function that is handling the event.

The DOM event object can also be used to stop an event from 'bubbling' (i.e. a 'click' event on a button that was contained in a DIV will first cause the button's onclick event to fire, then will cause the DIVs onclick event to fire and the will cause the page's onclick event to fire). You might want to prevent the event from bubbling up to the DIV and the page. You can do this by using the $e.stopEvent() function, passing in the DOM event object to this function.

Example 1 

Assume you have the following HTML page. Notice that the HTML has two input controls ('id_fn' and 'id_ln') and that there are no Javascript events defined in the HTML.

We want to add a handler for the 'onblur' event for both of these controls. When either of the controls looses focus, we want to call the blurred() function.

Notice that in the definition of the blurred() function, we show a parameter that is passed in (function blurred(e)). The argument is the DOM Event object that is automatically passed in to the event handler. The DOM Event object has information about the event that triggered the function call.

<html>
    <head>
    </head>
    <body>
        <input id="id_fn" name="firstname"/>
        <input id="id_ln" name="lastname"/>
    </body>
</html>
<script type="text/Javascript"  src="Javascript/core.js"></script>

<script type="text/Javascript">
    function blurred(e) {
        alert('ID:' + this.id + '\n Event type: ' +e.type + '\n Value in control: ' + this.value);
    }

    /*Add the event handler for the 'blur' event to the 'id_fn' and 'id_ln' elements.*/
    $e.add(['id_fn','id_ln'],'blur',blurred);
</script>

Example 2 

This example demonstrates how you can bind multiple event handlers to an event, and shows the order in which the event handlers are executed.

In this example, the HTML contains a definition for the onblur event for the 'id_fn' element. In addition to the event handler defined in the HTML, the Javascript code binds the msg2() function and then the msg3() function to the blur event for 'id_fn'.

If you load this page in a browser, when focus leaves the 'id_fn' element you will notice the following:

  • First, a dialog showing 'msg1' is shown, indicating that the event handler defined in the HTML executes first

  • Next, a dialog showing 'msg3' is shown, indicating that the most recent event handler added using $e.add() is executed next.

  • Finally, a dialog showing the control ID is shown, indicating that t he events added by $e.add() are executed in a 'last in - first out' order.

Notice that in the definition of the msg2() function we pass in the DOM event object and so the message box can display e.type (the type of the event that caused the event handler to be invoked). Also notice that the 'this' alias is implicitly passed in and can be used to get information about the control (such as it's ID - 'this.id', or current value - 'this.value')

<html>
    <head>
    </head>
    <body>
        <input id="id_fn" name="firstname"  onblur="alert('msg1'); return false;" />
        <input id="id_ln"  name="lastname"/>
    </body>
</html>
<script type="text/Javascript" src="Javascript/core.js"></script>

<script type="text/Javascript">
    function msg2(e) {
        alert('ID:' + this.id + '\n Event type: ' +e.type + '\n Value in control: ' + this.value);
    }

    function msg3(e) {
        alert('msg3');
    }

    /*Bind the msg2() function call to the 'blur' event on the 'id_fn' and 'id_ln' elements.*/
    $e.add(['id_fn','id_ln'],'blur',msg2);
    $e.add('id_fn','blur',msg3);
</script>
Use {dialog.object}.getPointer() to get the DOM element for a control.

See Also