Organization and Modularity

A goal for the OpenDSA project is to develop under a creative commons environment that makes it easy for instructors to pick and choose portions of the material to combine into a textbook, along with making changes as desired. To that end, content (text and images) could be developed at a third-party site with established infrastructure for such efforts, such as Connexions, and then the actual AVs and exercises might be linked in.

Thus, there are organizational issues related to the AVs and other dynamic activities (which I will refer to collectively as "AVs" below), and also the assessment infrastructure. For example, Connexions currently does not wish to house JavaScript due to security liability concerns. Even if that were not an issue, it would still be desirable to separate the AVs from the text. Doing so makes it much easier for others to reuse a given AV (which typical instructors are not going to be as willing to modify as they would standard text.

There are various possible approaches to organizing the AVs to be separate from and included into content pages. An easy way is to write the content pages using PHP, and then just include other PHP pages that contain the actual DOM elements and JavaScript for the AV. For example, a PHP page can include a line such as:

<?php include("myAV.php"); ?>

While simple and powerful, this is not likely to be a good approach. One issue is that many developers don't run PHP on their development machine (i.e., their laptop or local desktop PC), and so will find it a nuisance to debug PHP pages. Another issue is that when multiple AVs are included on one page, there is a great opportunity for namespace collision between the different AVs.

A better approach is to use an <iframe> tag to include another HTML page into the current page. This foreign HTML page can be anywhere accessible (meaning another server), and the various included entities are kept separate. The syntax is not too complex. For example, the Shellsort Tutorial originally contained the following to embed the Shellsort Slideshow:

<iframe src="http://algoviz.org/OpenDSA/AV/shellsort-av.html"
   width="824" height="459" frameborder="0" marginwidth="0"
   marginheight="0" scrolling="no">
</iframe>

The "shellsort-av.html" file contains the complete AV, including both DOM elements and JavaScript. It can be placed anywhere the author desires. Multiple AVs can be included on the page using multiple <iframe> tags.

There are a couple of problems with this approach. First, how does someone who wants to embed an AV know the proper size? Second, if you do find that out, what happens if the AV developers make changes? This is what the OEmbed standard is meant to solve. One can "ask" the provider of the objects to be embedded for a JSON or XML record that defines things like the type and size of the object. Then the author (ideally by using a PHP or JavaScript script to automate setting the size, or just by hardcoding from the html code returned in the result if necessary) can know how big to make the embedded element.

For a lot of practical advice on how to do an implementation, see Ville Karavirta's blog post on how TRAKLA supports OEmbed.

We have now added OEmbed support for the AVs in the OpenDSA distribution, in the AV/xml directory. For example, the URL http://algoviz.org/OpenDSA/AV/xml/shellsort-av.xml will return an XML entry that provides the appropriate access and size information. To embed one of our AVs in your own web pages, you could look at the information returned yourself, and then hard-code an iframe as described above. But better is to use either PHP or JavaScript to decode the information that is returned and then create the appropriate iframe code automatically. Here are examples. Just change the URL to embed the desired AV.

JavaScript approach:

<div id="embedHere"></div>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
<script>
$(function() {
  $.getJSON("http://algoviz.org/oembed/?url=http://algoviz.org/OpenDSA/AV/shellsort-av.html&callback=?",
    function(data) {
      $("#embedHere").html(data.html);
    })
});
</script>

Some things to note about this: (1) It uses the JavaScript jQuery library to simplify implementation. (2) The "callback=?" parameter is using the JSONP protocol to get around a security limitation on third-party JavaScript code. This issue is explained in Ville's blog entry referenced above. While not necessary if one is only embedding one's own local AVs, it is necessary if one wants to embed third-party resources. In this example, since the page is rendered from algoviz.org and the AVs are coming from algoviz.org, the callback parameter is not needed. But if we wanted to host the eTextbook at a separate site from the AVs, then the eTextbook page that embeds the AVs would require the callback parameter to make it all work.

PHP approach:

<?php
$data = file_get_contents('http://algoviz.org/oembed/?url=http://algoviz.org/OpenDSA/AV/shellsort-av.html');
$data_a = json_decode($data);
echo $data_a->html;
?>

Presently, the SourceForge distribution for OpenDSA includes a directory containing the JSAV development library, and a separate directory that contains the various AVs that have been developed for the project. All of this is available from http://algoviz.org/OpenDSA. The "textbook" portion of the project will reside elsewhere (to be determined), with the intention being to use iframes (through HTML code provided by OEmbed) to access the AVs.