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": ""}

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.