Toolkit:event handling

From Surebert wiki

Handling Events in surebert is done using sb.events which handle the cross platform translation of the event code.

Contents

DOM Event overview

DOM 1 Events

Inline defined or javascript defined DOM 1 events such as onclick, onmouseover, etc have one major problem. They cannot have other actions added to the same event. E.g. once you define a DOM nodes onclick property, you can either redefine to remove it but you cannot simple add a second onclick event to the same node.

Another disadvantage is that it works differently in IE vs everything else and that having inline javascript function are messy and difficult to maintain. You should strive to remove all inline javascript the same way you removed all inline defined styles and style markup in favor of external CSS. Here is an example of this older technique - DO NOT USE!!

html4strict code

<a id="myLink" href="http://www.surebert.com" onclick="function(e){alert(this.href);};">test</a>

DOM 2 events

To fix this situation DOM 2 events are added using addEventListener (standard) or attachEvent (IE 6/7). One problem with this technique is that you constantly have to say, if IE do this, else do that. Another problem is that events added in this way end up firing in random order when the event happens. As you can see this is no fun.

javascript code

function doSomething(){
	alert(this.href);
}
if(document.all){
	el.attachEvent("onclick", doSomething);
} else {
	el.addEventListener("click", doSomething, false); 
}

Surebert Events

To solve having to constantly deal with the inconsistencies, surebert offers sb.events.

Advantages

  • Single syntax, easy to use syntax, regardless of browser
  • Surebert events fire in the order in which they were added.
  • You can add as many of the same type of events as you want. e.g. you could add three click events to the same node.
  • automatically removed events added when leaving page in IE6

Events to Handle

  • blur - fires when a DOM element loses focus
  • click - fires when the use mouses down and then up on an element
  • contextmenu - fires when the user right-clicks on a DOM element - Not in opera
  • focus - fires when a DOM element gains focus
  • keydown - fires when the user presses a key when in a DOM element
  • keyup - fires when the user lets the key return to the up position in a DOM element
  • keypress - fires when the key is pressed and then returns to the upstate in a DOM element
  • mouseover - fires when the user hovers over a DOM element
  • mouseout - fires when the user moves the mouse out from over a DOM element
  • mousedown - fires when the user press the mouse button down over a DOM element
  • mouseup - fires when the user lets the mouse button return to the up position over a DOM element
  • onload - when a element such as body or img loads
  • onunload - when user naviagtes away from the page
  • submit - fires when a form is submitted
  • change - fires when an input value changes, 4.991+ of the toolkit can handle this event for select elements in IE

Surebert Event "handler(e)" Properties

sb.events always pass a variable "e" to the event handler function that represents the event. Properties of the event include

  • this - The element that the event is assigned to
  • clientX - The x position mouse when event fired
  • clientY - The y position mouse when event fired
  • target - The target of the event. This may be different than the "this." Think of the exmaple of having a click event on an unordered list. When you click a list item within the list, the "this" is the unordered list but the target is the list item you clicked.
  • relatedTarget - For mouseover this represents the target that the mouse left when entering the element, for mouseout it represents the target to which the mouse if leaving toward when exiting the element.
  • preventDefault() - e.preventDefault(); Used to prevent default action from happening, e.g. link changing page to href when clicked, etc
  • stopPropagation() - e.stopPropagation(); Used to stop event bubbling, so that when say an image is clicked in a

    tag the event stops there and does not bubble up to the <p> firing no click events for it

Adding an event using sb.events.add

Adding an event using this method returns a reference to the event that can be used when canceling the event. See below.

javascript code

var myEvent = sb.events.add('#myList', 'click', function(e){
	alert(this.innerHTML);
});

Removing an event using sb.events.remove()

Cancels the event added above

javascript code

sb.events.remove(myEvent);
//or
myEvent.remove();

Adding events to an sb.element or $ selected node

Adding an event using sb.element.prototype.event

Adding an event using this method returns an event object that can be removed using the .remove() method of the returned event

javascript code

var myDiv = $('#myDiv');
var myEvent = myDiv.event('click', function(e){
	//alerts the x value of the click 
	alert(e.clientX);
	//alerts the innerHTML of myElement
	alert(this.innerHTML);
 
	//the node that was actually clicked in the div
	alert(e.target);
});
 
//to remove the event, simply use and it will not fire anymore
myEvent.remove();

Adding multiple events using sb.element.prototype.events

javascript code

$('#myDiv').events({
	mousedown : function(e){
		alert('down');
	},
	mouseup : function(e){
		alert('up');
	}
}));

Notes

  • To remove all events

javascript code

sb.events.removeAll();
  • Surebert automatically handles removing all events when leaving the page in IE6 to prevent memory leaks.

Retrieved from "http://wiki.surebert.com/index.php/Toolkit:event_handling"