javascript

Event Handling for JSAV Data Structures

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?

OEmbed Endpoint for TRAKLA2 Algorithm Visualizations

This summer in the Program Visualization Workshop 2011, I had a paper with a colleague about the use of web services to help algorithm visualization (AV) systems. One potential service we identified and implemented was an OEmbed endpoint for embedding AVs into hypertext learning materials such as ebooks. OEmbed is "a format for allowing an embedded representation of a URL on third party sites". To make it more understandable, let's go through an example of the OEmbed endpoint for TRAKLA2 AVs.

Example Request

Let's say we want to embed the TRAKLA2 Binary Search Tree search AV on our own HTML page. The BST search AV is located at http://www.cse.hut.fi/en/research/SVG/TRAKLA2/exercises/BST_search-28.html. The OEmbed endpoint where we can query for information to embed the TRAKLA2 AVs is running at http://trakla.cs.hut.fi/oembed/. To request the embedding information for the BST search AV, we simply make a request to the oembed endpoint with a HTTP GET parameter url specifying the URL of the resource we want to embed. So, we make a request to URL http://trakla.cs.hut.fi/oembed/?url=http://www.cse.hut.fi/en/research/SVG/TRAKLA2/exercises/BST_search-28.html

Example Response

A request to the URL above will give the following JSON response.

{"version": "1.0", 
 "type": "rich", 
 "html": "<applet code=\"applications.exerciseapplet.ExerciseApplet.class\" archive=\"http://www.cse.hut.fi/en/research/SVG/TRAKLA2/exercises/matrix.jar\" width=\"610\" height=\"600\"<<param name=\"swap\" value=\"on\" /><param name=\"ex\" value=\"content.exercises.BST_search\" /></applet>"}

The response indicates that it is using version 1.0 of the OEmbed specification and the type of he object to be embedded is rich. That tells us that we should look for the html property for the HTML to embed the object. Adding that HTML to a page, we can embed the AV.

How to Actually Embed

The request and the actual embedding of the HTML in the response can be done on a server or on a client. Here, I'll concentrate on the client side as it brings with it a new problem: same origin policy permitting JavaScript in browser to only access resources from the same origin as the page was loaded. This is obviously done for security reasons, but it also inhibits a script to load the JSON data from the trakla.cs.hut.fi domain. But not to worry, there is a simple workaround known as JSONP or "JSON with padding". JSONP requires the service to support it, and the OEmbed endpoint we have implemented does.

With JSONP, a callback function is specified in the request. This callback function is than called with the returned data as parameter. The callback can be appended to the URL as callback GET parameter, for example, a request to URL http://trakla.cs.hut.fi/oembed/?callback=foo&url=http://www.cse.hut.fi/en/research/SVG/TRAKLA2/exercises/BST_search-28.html In the response, the data will then call the function foo: foo({"version": "1.0", ...});

Now, we only need to implement a function foo to handle the data. Or, we can use jQuery to simplify things.

A Complete HTML + JavaScript Example

Let's assume we have an HTML page where we load the jQuery JavaScript library and have an element where we want to embed the BST search AV.

<div id="embedHere"></div>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>

Now, we can make the request and embed the AV with the following piece of JavaScript.

$(function() {
  $.getJSON("http://trakla.cs.hut.fi/oembed/?url=http://www.cse.hut.fi/en/research/SVG/TRAKLA2/exercises/BST_search-28.html&callback=?", 
    function(data) {
      $("#embedHere").html(data.html);
    })
});

What is happening here is the code using the jQuery function getJSON to load the JSON from the specified URL. The callback parameter is specified using callback=? GET parameter. jQuery will generate a unique ID for the callback function, which is given as the second parameter for the getJSON function. The function gets the response JSON as a parameter, data, and sets the HTML content of the element with id embedHere to be the html in the data. The end result is the AV to be embedded on the page.

Benefits of the approach

So, why would anyone want to do it this complicated when one could just copy and paste the HTML into a page? Well, with a single AV that is possible. The real benefits come when we embed multiple AVs and do not want to keep the HTML up to date. Embedding the content using OEmbed, the responsibility of the up-to-date embedding information is on the creator of the AV (system). Furthermore, this gives the AV creator the possibility to update the embedding information or even the content of the AV. Hopefully, one day we'll be able to replace the TRAKLA2 AV applets with JavaScript versions using the JSAV library. Those embedding the AVs through OEmbed would benefit from our update immediately without any manual updates.

Status of the Service

The service is up and running online, and can be used to embed resources available on the TRAKLA2 exercise site. So go give it a try and let me know what you think and how it could be improved!

The code for the service is available on GitHub. At the moment, it is a bit TRAKLA2 specific, but with reasonable effort it could be improved to be a more generic AV embedding service.

JavaScript Algorithm Visualization (JSAV) Library v0.2 Released

JSAV and OpenDSA

For a while now, I've been working with Cliff Shaffer on the JavaScript Algorithm Visualization (or, JSAV) library. The goal of the library is to provide a modern JavaScript framework for building interactive algorithm visualizations.

This is still early work, but the version 0.2 of the library has just been released. At the moment, the library supports only array data structure and animation effects on that. Building the library is part of my research project on mobile algorithm visualization as well as the larger OpenDSA project. OpenDSA project aims at collaboratively create an active electronic book covering the whole data structures and algorithms course.

The OpenDSA work has been started by creating a somewhat complete chapter on shellsort.

What's next?

For the next version, we have planned to add support for creating interactive exercises. The exercises will support visualizations of algorithms with stop-and-think questions about the content. Another exercise type will be exercises similar to those in TRAKLA2 where user interacts with the visualization to mimic the behavior of an algorithm. Feedback of correctness as well as model answer as algorithm visualization will also be supported.

Want to contribute?

If you're interested in contributing to JSAV (and we sure could use the help) or just want to follow the development, head over to the JSAV GitHub repository. Alternatively, you can join the discussions on AlgoViz.org forums.

New Publication List with bib-publication-list

I finally got tired of updating my old HTML publication list by hand. I wanted something that would be automatically generated from my BibTeX file, without me having to remember to run any scripts or copy files. So, I wrote bib-publication-list. With it, I can just include the BibTeX into my HTML page and tell the script to turn it into a sortable and searchable table. Besides loading the required JavaScript files, all that is needed is to add a table where the data should be added and include the BibTeX:

    @article{Karavirta:JVLCTaxonomy,
        title = {A comprehensive taxonomy of algorithm animation languages},
        journal = {Journal of Visual Languages \& Computing},
        volume = {20},
        number = {1},
        pages = {1--22},
        year = {2010},
        issn = {1045-926X},
        doi = {DOI: 10.1016/j.jvlc.2009.09.001},
        author = {Ville Karavirta and Ari Korhonen and Lauri Malmi and Thomas Naps}
    }

Alternatively, the bibtex can be loaded from a file. I prefer including it in the HTML, though. This way, browsers without JavaScript enabled get at least to see the bibtex instead of a blank page.

Finally, the bib-publication-list needs to know the input data element and the output table. So, one line of JavaScript:

bibtexify("#bibtex", "pubTable");

The result looks like the figure below (or my new publication list).

The source code for the library is available on GitHub. The code uses some great libraries: jQuery, DataTables, Protovis, and JavaScript BibTeX Parser.

Let me know what you think. Especially comment if you have problems with it, I haven't tested it on all browsers (yet).

Interactive Questions in JSXaal

Update (March 2012): The JSXaal project is not actively worked on anymore. See JSAV for a JavaScript algorithm visualization framework.

Interactive Questions

Interactive questions in algorithm animations are questions shown to the student. Typically, the questions require students to predict what is going to happen in the following steps of the animation based on the current state and the algorithm in question. The main motivation behind the questions is the belief that the more engaging the animations are, the better the learning results (see Engagement Taxonomy, especially level Responding). For this reason, interactive questions have been used in many visualization systems, such as Animal, JHAVÉ, Jeliot, and ViLLE.

Interactive Questions in JHAVÉ..

Interactive Questions in JHAVÉ..

Since the usage of interactive questions has become more and more popular in AV systems, several studies of their effectiveness in learning has been carried out. Here I'll introduce only some of them

  • In 2000, an experiment comparing levels viewing and responding was conducted by Jarc et al. The results of the survey found no statistically significant differences. However, the data indicated that the students working on level responding scored better on difficult topics, but poorly overall. The study used the Interactive Data Structure Visualizations system to visualize the data structures.
  • Grissom et al. experimented in 2003 to compare levels no viewing, viewing, and responding using JHAVÉ system. The results show that learning improves as the level of student engagement increases. The difference between no viewing and responding was statistically significant.
  • A recent study in 2009 by Taylor et al. compared students using passive and predictive animations of graph algorithms. They conclude that students working on the responding level learned better than students viewing passive animations. It is unclear, though, whether or not their results were statistically significant.

Interactive Questions in XAAL

The roots of XAAL come from the ITiCSE 2005 working group "Development of XML-based Tools to Support User Interaction with Algorithm Visualizations" (see also the Working Group report). The working group specified and gave examples for different parts of an XML-based algorithm animation language. One of the parts that was specified in detail were the interactive questions. Thus. those specifications have been adopted in XAAL. Below are examples and explanations of the different question types supported by XAAL (the working group report specifies more), see the documentation for the XAAL XML schema for interaction for details.

  • select: for multiple-choice questions where multiple answers can be selected by student
    <select id="selectQuestion">
      <contents type="label">Which do you want to select?</contents>
      <item id="sit1" grade="2">
        <contents type="answer">Select me!</contents>
      </item>
      <item id="sit2" grade="1">
        <contents type="answer">Select me also!</contents>
      </item>
      <item id="sit3" grade="-2">
        <contents type="answer">I hope you won't select me..</contents>
      </item>
    </select>
    
  • select-one:for multiple-choice questions where only one answer can be selected by student
    <select-one id="selectOneQuestion" solutionId="it3">
      <contents type="label">How many <i>children</i> does 
                 the rootnode of the tree have?</contents>
      <item id="it1">
        <contents type="answer">1</contents>
      </item>
      <item id="it2">
        <contents type="answer">3</contents>
      </item>
      <item id="it3">
        <contents type="answer">4</contents>
      </item>
    </select-one>
    
  • fill: for fill-in-the-blanks questions that can contain several blanks where the student should enter her aswers

..and in JSXaal

When an animation with interactive questions is viewed in JSXaal, the questions are shown to the user. The user will also get feedback on whether or not her answers were correct. The figure below shows an example question in JSXaal. You can also view an example online. Currently, JSXaal supports questions of type select-one and select.

Example question in JSXaal
Example question in JSXaal

When integrating with online material and some learning environment, it's often necessary to communicate the student answers back to the server. In JSXaal, this can be done by implementing a simple JavaScript class. The class has to have two functions:

  • questionAnswered(question): This function is called whenever a student answers a question. It gets as a parameter the question as an instance of JSXaal.Question.
  • annotationAdded(annotation): This function is called whenever a students adds an annotation to the animation.

So, a simple example of doing this is:

Event.observe(window, 'load', function() {
  viewer = new JSXaalViewer("animation", {}, {fileUrl: "xaal-interaction-demo.xml"});
  MyServerInterface = Class.create({
    annotationAdded: function(annotation){
      // handle the annotation
    },
    questionAnswered: function(question){
      // handle the question
    }
  });
  viewer.setServerInterface(new MyServerInterface());
});

What you do with the annotation and question is completely up to you. One possible way is to store the complete XAAL animation on the server, as the question response and the annotation are added to the current animation.

JSXaal Goes Open Source

Update (March 2012): The JSXaal project is not actively worked on anymore. See JSAV for a JavaScript algorithm visualization framework.

JSXaal viewer, the JavaScript viewer for XAAL animations is now an open source project at Google Code. You can find the project here.

Getting Started

First of all, make sure to check the brief introduction to XAAL. Then follow the three simple steps below.

Step 1: Check out the source

To checkout the source code, you will need Subversion installed. Then you can checkout the code by typing: svn checkout http://jsxaal.googlecode.com/svn/trunk/ jsxaal-read-only

Step 2: Play with the Example

The directory that you just checked out includes an example in doc/example.html (imaginative naming, don't you think?). You can also view the example online. What you should see when opening that file is something like the image below. The controls for the animation should be quite self-evident: forward moves you forward and backward one step backward.

JSXaal Viewer Example

JSXaal Viewer Example

Step 3: Modify the XAAL document

The example loads the XAAL file doc/example.xml. Try modifying it by, for example, changing the positions or colors of the objects. You can also add new objects or animation effects according to the XAAL specification. Note, that the viewer does not support the whole specification yet.

My article "Seamless Merging of Hypertext and Algorithm Animation" in TOCE

My article "Seamless Merging of Hypertext and Algorithm Animation" was finally published in ACM Transactions on Computing Education (TOCE) in volume 9, issue 2 (in ACM digital library). The abstract of the article:

Online learning material that students use by themselves is one of the typical usages of algorithm animation (AA). Thus, the integration of algorithm animations into hypertext is seen as an important topic today to promote the usage of algorithm animation in teaching. This article presents an algorithm animation viewer implemented purely using HTML and JavaScript. The viewer is capable of viewing animations in Xaal (eXtensible Algorithm Animation Language), a language designed to allow easy transformation of AAs between various formats. This solution is extremely suited for use in hypertext learning material due to the advanced interaction possibilities between learning material (HTML) and the animation.

I'll try to post some demos of the viewer soon. Below is a picture explaining the main parts of the viewer.

JSXaal viewer
JSXaal viewer