mrspoonzy at gmail Cube by Noah Ellman A powerful javascript toolkit, in research © by Noah Ellman

Learn Jwee > API > Events

wee.event add(...)
During an event

With javascript events you can create interaction on your website. Events allow you to react to mouse movement, clicking, key-strokes, scrolling, and hellava lot more. Jwee's event toolkit makes working with Javascript events much easier.

  • The wee.event object contains all the functions and properties about events
  • The observe() method on html elements can also be used as a shortcut for adding events

Jwee's event handling engine is of course your choice to use or not to use. It is always possible to use the simple "element.onclick=" methodology from old-fasion DHTML, and in fact in some instances this may be even the better solution. The only main issue with the old style of events is that you can only have ONE event of that type per element, and that the event only fires on THAT element, and not on all the elements within.


  • Event handlers will always receive the event object as the first parameter.
  • You can add events to DOM elements even before the page has loaded. Frodo will quietly wait until the DOM is ready and then install your event. This would only make sense if you were passing the element's ID as instead of the element itself.
  • It doesn't matter weather you say onclick or click or onkeydown or keydown, etc.
  • Returning false in your event function will stop bubbling, cancel the event, prevent default, and return false all at once.
  • You can access document.loaded to see if the DOM is ready and/or page has loaded.
  • If the document is already loaded when you add a load event via onLoad, onReady, or onLoadLazy then Frodo will just execute your function immediately.
function wee.event.add(...)( element/string id,  string type,  function handler )
Start observing a new event on element, document, or window.
  1. {element|string} The id of an element or the actual element, or window/document.
  2. {string} A string of the event type, with or without the "on", such as "click".
  3. {function} Your event handling function.
ReturnsA numeric id you can use to remove the event later.
ImportantThis is a important function/property to know.

var handler = function(event) {
	 alert("stop clicking!");
	return false;

Event.add(document,'click', handler);

Although you can do it this way if you want, you can also add events directly from the element itself, with the observe() functions, for example, document.observe. The functions arguments are the same, except you need not include the element for argument 1.

document.observe( 'click', handler );
function wee.event.remove(...)( string id / number id )
Remove an event
  1. {string|number} The id or name assigned to the event when you created it.

Removing events can be a real pain normally, but Jwee makes it simple. When you create a new event you can optionally provide a unique name to it, like you would give a DOM element an id. You can use this ID to remove the event, without worrying about function references.

var handler = function() { ... };
Event.add( document, "onclick#myClickerEvent", handler );

Jwee recognizes this special syntax, and remembers the id myClickerEvent as long as the event exists. If you ever need to remove this event later on, simply pass the id to remove().


function wee.event.onReady(...)( function )
Run a function the moment the DOM is ready (happens before onLoad).
  1. {function} A function to be run on page ready.
ImportantThis is a important function/property to know.

Add your function to the queue of events to be executed when the page DOM is ready. This event fires before onload. Using onReady instead of onLoad is a good way to prevent an interface "flicker" when you are changing styles or elements immediately on page load.

Event.onReady( function() {
	alert("The page is loaded");
	// I can access elements now by id and do whatever
} );

Naturally, event functions can be a function name too.

function doThisOnLoad() {
	alert( "foo" );

Event.onReady( doThisOnLoad );
function wee.event.onLoad(...)( function f )
This is a the classic onLoad functionality.
  1. A function to be run on page load.
ImportantThis is a important function/property to know.

This is a the classic onLoad functionality. This would be the same as assigning a function to window.onload or putting a onload attribute on <BODY>. These functions will execute after your onReady functions. The significant difference of onLoad is that at this point all images, flash, embeds, backgrounds and everything is dowloaded and the page is completely displayed.

Event.onLoad( function() {
	// This page AND all images and flash and everything
	// is 100% loaded and displayed to user
} );
function wee.event.onLoadLazy(...)( function f )
These functions will execute in a lazy manner a couple seconds after the page has displayed and the browser is no longer cpu hogging.
  1. A function to be run lazily after page load.
ImportantThis is a important function/property to know.

These functions will execute in a lazy manner a couple seconds after the page has displayed and the browser is no longer cpu hogging.

function wee.event.onMouseWheel(...)( element or id,  function handler )
Capture mouse wheel scrolling. Special event.
  1. {element} The element
  2. {function} Your function that will be called on mouse wheel activity.
function wee.event.onRollIn()
Special event that triggers only ONCE when mouse enters element's area
function wee.event.onRollOut()
Special event that triggers only ONCE when mouse leaves element's area
function wee.event.getEvent()
Get current Event object.
function wee.event.getOwner()
Get the current event's owner element. This is the element the event is initially attached to.
function wee.event.getTarget()
Get the current's event's target element, which may or may not be the owning element.
function wee.event.getRelated()
Gets the related element if applicable.
function wee.event.getKeyCode()
Get the current key event's key code.
function wee.event.getKey()
Get the current event's key as a letter if applicable.
function wee.event.getMousePos()
Get the current event's mouse position.
ReturnsAn object containing the x and y properties.
function wee.event.returnFalse()
Returns the event as false, canceling any default browser action and haulting the event chain
Examplereturn Event.returnFalse(); // Inside your event handler
function wee.event.returnTrue()
Returns the event as true, not canceling default action or stopping the event chain
Examplereturn Event.returnTrue(); // Inside your event handler
function wee.event.trace()
Log the event to the console, for debugging
function wee.event.trace_extra()
Log the event to the console, for debugging (more details)

Discussion on /learn/api/events

Zach 11/05/14 :  

That's a good idea. I'll take a stab at it and see if I can figure out how they did things. Thanks.

Xymon 11/05/14 :  

Plus you could always use event.keyCode

Virux's Minion 11/05/14 :  

Lies o.o