Events in Javascript are often seen as a bit of an enigma. This is odd given that Javascript is very much an event driven language, but it is typically down to their complex nature and difficulty to debug. To this end I've created Visual Event to help track events which are subscribed to DOM nodes.

Introduction

Visual Event is an open source Javascript bookmarklet which provides debugging information about events that have been attached to DOM elements. Visual Event shows:

  • Which elements have events attached to them
  • The type of events attached to an element
  • The code that will be run with the event is triggered
  • The source file and line number for where the attached function was defined (Webkit browsers and Opera only)

In addition to being useful for debugging your own code, Visual Event can be used as an educational tool, showing how many web-sites have been authored.

Visual Event is open source software (GPLv2) and a Git repo is hosted on GitHub for you to fork and modify as you wish!

Install

As Visual Event is a bookmarklet, installing and running it on any web-page is extremely simple:

  • Drag the "Visual Event" link on the right to your bookmark bar: Visual Event
  • Load a web-page which uses one of the supported Javascript libraries
  • Click "Visual Event" in your bookmark bar
  • View the event handlers which are attached to the document elements.

A demo of Visual Event that is automatically loaded is available. This demo uses DataTables to create a test page with a number of events attached to different elements.

How it works

It turns out that there is no standard method provided by the W3C recommended DOM interface to find out what event listeners are attached to a particular element. While this may appear to be an oversight, there was a proposal to include a property called eventListenerList to the level 3 DOM specification, but was unfortunately been removed in later drafts. As such we are forced to looked at the individual Javascript libraries, which typically maintain a cache of attached events (so they can later be removed and perform other useful abstractions).

As such, in order for Visual Event to show events, it must be able to parse the event information out of a Javascript library. Currently the following libraries are supported by Visual Event:

  • DOM 0 events
  • jQuery 1.2+
  • YUI 2
  • MooTools 1.2+
  • Prototype 1.6+
  • Glow
  • ExtJS 4.0.x

How to get involved

Visual Event is open source software and available under the GPL v2 license. Source control is done with Git, and the project has a page on GitHub. Any help with improvements and suggestions for Visual Event are very welcome indeed! If you hit a specific problem, then please open an issue on GitHub for the problem you are encountering, including a link to the page where the problem occurs. Forks and pull requests are also very much encouraged!

One area which may be of interest to you is how to add support for additional Javascript libraries. The key thing that is needed is access to the event cache that the library uses, since without that it is impossible to determine what nodes have events and the attached code.

The VisualEvent class has a static array called `VisualEvent.parsers` which is an array of functions - to add a new parser, just push your function onto this array. The function must return a Javascript array of objects with the following parameters:

[
	{
		"node": {element},            // The DOM element that has attached events
		"listeners": [                // Array of attached events
			{
				"type": {string},     // The event type - click, change, keyup etc
				"func": {string},     // The code that will handle the event, from Function.toString()
				"removed": {boolean}, // If the event has been removed or not (typically will be false, but used if the library doesn't remove the event from its cache)
				"source": {string}    // Library name and version that attached the event (e.g. "jQuery 1.7")
			},
			...
		]
	},
	...
]

Building Visual Event

In order to run a local copy of Visual Event you must build it, since this process does file concatenation, which brings in the library parsers to the main file. The build process will also build the JSDoc documentation and compress the Javascript files (unless made with debug).

To build Visual Event, all you need is a system which will run bash scripts and enter the command `./build.sh debug` in your terminal. This will create a new directory in the "builds" directory with the correct loader and the build Visual Event directory (note the timestamp is used to help prevent caching issues for the bookmarklet, both during development and when deployed). The following is the usage for the build script:

Visual Event build script - usage:
  ./build.sh [loader-dir] [debug]
    loader-dir - The web-address of the build files. Note that the build
      directory name is automatically appended. For example:
        localhost/VisualEvent/builds - default if no option is provided
        sprymedia.co.uk/VisualEvent/builds
    debug - Debug indicator. Will not compress the Javascript

  Example deploy build:
    ./build.sh sprymedia.co.uk/VisualEvent/builds

  Example debug build:
    ./build.sh localhost/VisualEvent/builds debug

The file `bookmarklet.html` is provided to build your own bookmarklet loader nice and easily. Typically you'll only need to modify the path for the bookmarklet. The link is updated on each keypress and you install it just as you would with any other bookmarklet :-).

Version history

  • 15th April 2013
    • Fix to support file: protocol.
  • 27th February 2013
    • Support for SSL loading. Note: this requires that you update your Visual Event bookmarklet (i.e. delete and reinstall it)
    • Support for host pages using jQuery 1.9
  • 28th May 2012
    • ExtJS 4.0.x event parser

Elsewhere on the web