For a while now, I’ve been meaning to start a series of articles on JSAV features. The current documentation only works as a reference to the API and does not explain or give enough examples. Also, it does not argue why things are done certain way and writing these things down makes me really think them through. As I recently implemented a support for easy attachment of event handlers to data structures, that seems like as good as any topic to start.

The Way Things Were

In general, attaching event handlers with jQuery is easy. That is, unless the HTML is generated by the library and there is no reason you should need to know the structure of it. Also, getting the JSAV object for the node/index matching the DOM element is tricky. The old way for doing this was something like:

// register a click event handler to all JSAV array indices
$(".jsavindex").click(function() {
    //find the index of the clicked item
    var index = $(this).parent().find(".jsavindex").index(this);
    // do something with the array
});

Events for the Array Indices

To ease this, a recent commit introduced a better way to attach events to arrays and trees. Both structures support following events: click, dblclick, mousedown, mousemove, mouseup, mouseenter, and mouseleave. While the names are reasonably self-explaining, you can check jQuery event documentation for details on the events.

For a JSAV array, there are functions with the same name as the events that can be used to register event handlers for that event type. So, for example, to add a function to be called whenever mouse enters an array index, you can do the following:

arr.mouseenter(function(index) {
    this.highlight(index);
});

The event handler function gets as the first parameter the index of the array element that the user interacted with. The this variable is set to point to the JSAV array. Naturally you don’t need to pass an anonymous function as the event handler, but you can use any function as the parameter. A good example of this are the JSAV array functions, most of which take an index as the first parameter. The API documentation gives the following example that illustrates this well:

arr.mouseenter(arr.highlight).mouseleave(arr.unhighlight);

This also shows that the event binding functions return the structure itself, so you can safely chain the function calls.

Another parameter the event handler gets is the jQuery event object. You can use that in case you need to, for example, stop the propagation of the event.

arr.dblclick(function(index, event) {
    event.stopPropagation();
    // ... do something else..
});

Note: most of the JSAV functions that change some properties of the structures also store the changes to the animation history. For events that are fired often (such as mousemove), the history can get really long quite fast. Thus, make sure you don’t misuse the events.

Events for Trees

For trees, there are functions for binding handlers for the same set of events: click, dblclick, mousedown, mousemove, mouseup, mouseenter, and mouseleave. These functions can be called for the JSAV tree instance. The actual event handlers will be bound to either nodes or edges of the tree.

Let’s begin with a simple example:

var tree = jsav.ds.tree();
// ...
tree.click(function(e) {
    this.highlight();
});

What this would do is bind the anonymous function to be called whenever a node in the tree is clicked. The event handler function gets as a parameter the jQuery event object. Inside the handler, this will refer to the node or edge that the event was triggered for.

Like I mentioned, the event handler will be bound to the nodes by default. My assumption here, based on our experience with TRAKLA2 assignments, is that this is the more common use case. But don’t worry, binding handlers for edges is almost as simple, you just need to add one option. Like this

tree.click(myEdgeClickHandler, { edge: true });

This will bind the function to only edges, and inside the handler, this will refer to the JSAV edge object triggering the event. If you want (although I can’t come up with a good use case), you can bind the handler to both by adding another option node with value true.

Custom Arguments

The above describes the basic usage of the implementation, but there are other ways to deal with even more complex requirements. First of, custom arguments can be passed to the event handler. For example, to change a CSS property of an array index on mouseenter and remove it on mouseleave, the code needed with the above functions is something like:

arr.mouseenter(function(index) {
    this.css(index, {"color": "red"});
}.mouseleave(function(index) {
    this.css(index, {"color": "black"});
});

To ease this, the event binding functions all take a second, optional, parameter to specify custom parameters for the handler. This parameter should be an array with as many items as you want to pass as arguments for the event handler. With custom arguments, the above example can be simplified to:

arr.mouseenter([{"color": "red"}], arr.css)
  .mouseleave([{"color": "black"}], arr.css);

So, it uses the array’s css function and passes the arguments for that function as parameter when registering the event handler. The function calls made by JSAV would be identical to the those made in the version not using custom arguments, except for the jQuery event object being the last argument. Ordering the parameters for the binding function to be event data first is just to be more consistent with jQuery.

Binding Custom Events

While writing this blog post, I realized there should probably be a way to bind custom events as well. While not required at the moment, I can already see a need to bind, for example, touch events. So, a later commit added on function to array and tree that allows binding any events. As the first parameter, the function takes the event name(s). The other required argument is again the event handler. For example

arr.on("touchstart", myEventHandler);

would register the function myEventHandler to be triggered when touchstart event is triggered.

Custom data for the handler can also be specified as the second parameter:

arr.on("touchstart", {myVal: "cat"}, myEventHandler);

And for trees, a last options parameter can be passed.

Summary

As a summary, here are the function signatures for the functions in array and tree:

arr.eventName([data,] handler);
arr.on(eventName, [data,] handler);
tree.eventName([data,] handler [, options]);
tree.on(eventName, [data,] handler [, options]);

What do you think? Any questions or suggestions on how to improve?