HTML Event Tutorial

This tutorial will look at the basics of attaching events to HTML elements in a cross browser manner using the Nitobi Ajax Toolkit. The HTML content for this tutorial looks like this:

<html>
<head>
    <script type="text/javascript" src="nitobi.toolkit.js"></script>
    <script type="text/javascript">
    // Custom code goes here
    </script>
</head>
<body>
    <div id="Customer1">John Doe</div>
    <div id="Customer2">Jane Doe</div>
</body>
</html>

Attaching Events

The first thing to be aware of when using HTML events is that events cannot be registered on HTML elements until the HTML element is parsed and available through the DOM API. The most simple method of ensuring that the HTML DOM has been parsed and is ready to use is the onload event on the window object or <body> element. Each of these methods can be used in the following ways:

These can be bad since they are only available to be specified once and doing so may destroy previously defined event handlers. Instead you can use the nitobi.html.attachEvent static function to attach the initilization and destruction events such as:

nitobi.html.attachEvent(window, "load", myInitFunction);
nitobi.html.attachEvent(window, "unload", myDestroyFunction);

It should be noted that the unload event is rarely needed since the Nitobi Ajax Toolkit manages all the HTML events internally and removes all attached events when the page is unloaded.

The nitobi.html.attachEvent method expects the following arguments:

element (HTMLElement, required) - the HTML element to which the event is to be attached
type (String, required) - the name of the event to have the handler fired on _without_ the "on" prefix such as click or mouseover
handler (Function, required) - a reference to the function that is to be executed when the even occurs
context (Object, optional) - the object that the handler function is to be executed in the context of (this is particularly important when writing object oriented JavaScript - though the handler may also use the nitobi.lang.close function)
capture (Boolean, optional) - specifies if the event should use capturing rather than bubbling

Now we can wire up an event to the HTML element with id Customer1 in the short HTML sample we have already looked at.

function myInitFunction()
{
nitobi.html.attachEvent($("Customer1"), "mouseover", handleMouseover);
nitobi.html.attachEvent($("Customer1"), "mouseout", handleMouseout);
}

function handleMouseover(eventObj, eventSrc)
{
this.style.color = 'red';
}

function handleMouseout(eventObj, eventSrc)
{
this.style.color = 'black';
}

This should cause the HTML element with ID "Customer1" to turn red when the user moves the mouse over the element and black when the user moves the mouse out of the element.

Event Handler Arguments and Event Object

The eventObj argument to the event handler function is the native browser Event object, although in Mozilla based browsers it is mutated to inlcude access to properties expected in Internet Explorer such as srcElement (target in Mozilla), fromElement (relatedTarget in Mozilla), and toElement (relatedTarget in Mozilla) where fromElement and toElement useful depending on the event such as drag operations. Another property added to the Event object is the eventSrc property that can be used to access the HTML element to which the event as actually attached - this may differ from the element that the event was actually triggered on. The eventSrc is also passed to the event handler function as the second argument. As well as being passed as an arugment to the event handler function, the event object for the event is accessible through the global object nitobi.html.Event.

Cancelling Events

To cancel an event or prevent it from bubbling up to ancestor elements in the HTML hierarchy, the nitobi.html.cancelEvent(event) function can be used. This function takes the Event object for the event that is to be cancelled as the single argument and prevents the default action and bubbling in a cross browser manner.

Accessing Event Coordinates

Similarly, there are some other event helper methods such as nitobi.html.getEventCoords(event) that will return the coordinates of the event in a cross browser manner and independent of the web page DOCTYPE.

Attaching Multiple Events

If there were multiple events to attach to a single HTML element we could also use the nitobi.html.attachEvents function which accepts an element an array of events to attach and the context that the handlers for each event should be executed in. Each object in the array of events is a struct such as:

{"type":"click","handler":handleClick,"capture":false}

and it can be called like this:

var events = [
{"type":"mouseout","handler":handleMouseout,"capture":false}
{"type":"mouseover","handler":handleMouseover,"capture":false}
];
nitobi.html.attachEvents("Customer1", events);

We have also taken advantage of the fact that we can also pass just the ID of the HTML element that we want to attach the event to rather than a reference to the HTML element itself.

Detaching Events

If we wanted to manually remove the events at an time we could also do that by using the nitobi.html.detachEvent function.

function myDetachFunction()
{
nitobi.html.detachEvent($("Customer1"), "mouseover", handleMouseover);
nitobi.html.detachEvent($("Customer1"), "mouseout", handleMouseout);
}

Again the detachEvent function expects the same arguments as the attachEvent function.

View Printable Version

Nitobi Product Knowledgebase