2. Getting Started

2.1. Overview and Developer’s First Steps

To the end user, OpenDSA consists of content delivered by servers. Content is delivered in the form of “book instances”, which are created through the configuration process. Book instances come in two forms: plain HTML pages (that you can create locally for testing) and those accessed through a Learning Management System (at the moment, we support Canvas, and we have some limited access from other LMS through the LTI protocol). As a new developer, you typically don’t worry about anything other than creating plain HTML book instances.

If you want to develop content, create a book instance, and view it, then you will need to set up the necessary infrastructure. See “Setting up a Local Development Environment” below for details on how to do this.

The overall project structure and developer workflow goes like this. You need to create a configuration file in the OpenDSA/config directory. You will probably start by copying an existing one (Test.json is a good place to start). With that file in place, the main Makefile for OpenDSA (OpenDSA/Makefile) will recognize it as a valid target to compile. If you want a specialized build process, append a rule to the Makefile that overrides the target, and put in the steps for the new build process. Once your config file is set up, then you will execute your Makefile target (a command like make Test called from a commandline window from the OpenDSA repository top level will do this).

The basic unit of an OpenDSA book instance is a Module, and each Module corresponds to a file written in ReStructuredText (RST). The existing modules are in OpenDSA/RST/en, with the files divided among various content subdirectories. You will typically get started by creating your own subdirectory in OpenDSA/RST/en, copying any starting RST files that you want to use, adding these to your config file, and then compiling them to see that you have what you want. Then you can start modifying your copy of the RST file to create content. Actual visualizations and exercises generally live in the OpenDSA/AV and OpenDSA/Exercises directories. See the self-documenting demonstration at OpenDSA/RST/en/SimpleDemo/DemoIntro.rst for getting started (see the end of this page for details on compiling the SimpleDemo book).

2.2. Project Communications

The primary discussion forum for topics related to OpenDSA and JSAV is our Piazza forum at https://piazza.com/class/i1v25wdagpr6sn.

Issues (bug reports and suggestions) related to any of the repositories should be posted to their respective GitHub issue trackers.

2.3. Repositories and Official Mirrors

Main development is done out of repositories hosted at GitHub. We use a GitHub “organization” at https://github.com/OpenDSA. Here is a list of the individual repositories that we use:

An up-to-date development version of the OpenDSA repository is mirrored at http://lti.cs.vt.edu/OpenDSA. The built version of the stable standard book configurations (available either as they appear in Canvas or stand-alone web pages) is available at: https://opendsa-server.cs.vt.edu/home/books.

2.4. JSAV

Visualizations are developed using the JSAV (JavaScript Algorithm Visualization) library. Documentation for the JSAV API can be found at: http://jsav.io/ If you have installed the main OpenDSA repository, then the JSAV library will be in OpenDSA’s lib directory.

2.5. File Structure and File Naming Conventions

The following refers to the OpenDSA content or “client side” repository (“OpenDSA”).

Content materials come in the form of modules (in RST), exercises, AVs, etc. There are various top-level directories, as explained below and in more detail in the project README file (https://github.com/OpenDSA/OpenDSA/blob/master/README.md). Within the RST, AV, SourceCode and Exercises directories, the materials are subdivided into subdirectories based on topical content (such as Sorting). These content subdirectories are mirrored across all of the materials subtypes. That is, if there is a Sorting subdirectory in the AVs directory, there should also be one in the RST directory, Exercises directory and the SourceCode directory to match. In addition, each of the major top-level directories contains a subdirectory named Development. All content starts life in the Development subdirectory. Once it is completed, polished, validated, and had a thorough code review, Dr. Shaffer will move code out of the Development subdirectory to an appropriate content subdirectory.

Algorithm visualizations, proficiency exercises, and related code live in the AV directory.

Exercises built using the Khan Academy exercise infrastructure lives in the Exercises directory.

Tutorial modules live in the RST directory, with the actual source in RST/source.

Code examples that will be presented within the modules (such as Processing or Python code) lives in the SourceCode directory.

Individual files are further labeled by functional type. Files related to AVs have their filename end in AV (such as insertionsortAV.js). Files related to proficiency exercises end in PRO. Files related to mini-slideshows or similar content that is included within a module end in CON. Khan Academy exercises that are multiple choice questions end in MC, and T/F questions end in TF. KA-based questions that are interactive (for example, where a user clicks on JSAV array elements to give an answer) end in PRO. The practice is to put individual KA questions in separate files, and often these are then aggregated to present to students as a battery of “summary” questions. Such aggregations end in Summ.

2.6. OpenDSA Coding Standards

Coding standards for OpenDSA are largely driven by validation tools. The requirements for CSS and JavaScript files are embedded in the validation tools and settings built into the OpenDSA Makefile. No code gets out of the “Development” stage and into public use until it follows our rules for splitting into separate HTML/CSS/JavaScript files and passes the validation tools with zero warnings and errors.

HTML Pages Ideally, HTML pages that are part of OpenDSA should pass the W3 validation suite. An easy way to run this on your page is to install the Web Developer plugin (from http://chrispederick.com) for your browser. This is available for both Chrome and Firefox, and gives you icons on your toolbar that lets you run the validator on the current page. Unfortunately, we so far have not adopted a command-line tool for validation of HTML pages similar to what we are using for CSS and JavaScript.

We try to avoid JavaScript and CSS in the HTML pages (though we often tolerate a couple of lines of CSS for an AV that needs only minimal customization away from the standard [OpenDSA]/lib/odsaStyle.css template). Our standard practice is to use <script> and <link> tags to call separate .js and .css files, respectively.

CSS Files We use csslint to validate css files. [OpenDSA]/Makefile contains our required csslint flags.

JavaScript We use eslint for validating JavaScript. OpenDSA/.eslintrc contains our official configuration file that defines the expected style. It is relatively strict. Developers should strive to eliminate all warnings (and of course, all errors).

JSON Files We use jsonlint to validate json files.

2.7. Web Programming Resources

Since we do so much webpage development and programming in JavaScript, newcomers will need good resources. One well-respected site is https://developer.mozilla.org/en/JavaScript. Beware of doing a search engine query and ending up at w3schools, which is not so well respected these days. If you are at Virginia Tech (or if your school supports this), a wonderful source of documentation is the Safari database (http://proquest.safaribooksonline.com/?uicode=viva), which contains a huge collection of technical books including the entire O’Reilly catalog.

2.8. Disabling the Browser Cache and Debugging

When you right-click a web page in Chrome or Firefox, you get a popup menu whose bottom item is “Inspect” or “Inspect Element”. This brings up the Developer Tools panel. The first thing that you will want to do is to turn off your browser cache when you have the developer panel open, so that reloading your page will show updates to your JavaScript and CSS files that you have been working so hard on. In Chrome or Firefox click on Network tab in the Developer Tools panel. Find and check the box that says “Disable cache (while DevTools is open)”.

The Developer panel can do a lot, but two key things are the console (which lists various error and debug messages), and the inspection panel for inspecting the various DOM elements on your web page. The inspection panel lets you see the CSS styles in effect for any specified DOM element. For details on how to view and even edit on-the-fly your CSS settings in force (for example, to see what you should change), see https://developers.google.com/web/tools/chrome-devtools/css/reference.

The following are highlights for some debugger features and how they can be used.

  • Console - an interactive JavaScript console which allows:

    • Print statments for debugging and error logging.

    • Testing JavaScript statements (including access to variables and functions defined on the current page).

    • Viewing network requests - GET and POST messages appear in the console allowing the user to see what data was sent and the server’s response.

  • Inspect - allows the user to select an element on a page, view the HTML for it and modify the element’s CSS in real time (helpful for rapid GUI prototyping).

  • Debugger - a full featured JavaScript debugger (useful for debugging or simply following code execution).

    For more details on browser developer tools see the Chrome Developer Tools documentation, or the Firefox developer tools documentation.

2.9. Setting up a Local Development Environment

The local development environment for OpenDSA content is provided using Docker. Docker is a containerization solution to provide all of the dependencies required to run OpenDSA.

2.9.1. Installing Docker

On Windows: First, download Docker Desktop for Windows at https://docs.docker.com/docker-for-windows/install/. NOTE: If you have Windows Home Edition, use the following link instead https://docs.docker.com/docker-for-windows/install-windows-home/ and make sure you use the WSL2 with these instructions https://docs.docker.com/docker-for-windows/wsl/.

On Mac: First, download Docker Desktop for Mac https://docs.docker.com/docker-for-mac/install/

On Linux: First, install the Docker Engine for your Linux distribution https://docs.docker.com/engine/install/. Next, follow the post-installation steps here to finish your setup https://docs.docker.com/engine/install/linux-postinstall/. Finally, you should install docker-compose using these steps https://docs.docker.com/compose/install/.

2.9.2. Installing OpenDSA

Here are instructions for installing the toolchain using Docker, which should then allow you to compile OpenDSA books.

These instructions are geared toward Windows, since that is the hardest to install. For Linux or Mac, you can do pretty much the same thing (using sudo for root permissions, and getting the tools from your package manager), but can skip some of the steps.

First, install Git. On Windows, a good choice is “Git for Windows” at https://git-scm.com/download/win. Use the third option for the path environment: “Use Git and optional Unix tools from the Windows Command Prompt”. Choose “checkout as-is, commit Unix-style line endings”, and then use “MinTTY”. You can then check if git is installed with the git --version command from a fresh terminal.

Finally pop open a new Git Bash window, and you are ready to get started. The first thing that you will do is to clone the OpenDSA repository from https://github.com/OpenDSA/OpenDSA. If you are not already familiar with how to do this, then you will need to read some documentation on using Git since there are different ways to do the cloning operation.

Once the repository is cloned (we assume here into a directory named OpenDSA) then do the following:

cd OpenDSA
docker-compose up

This command will first pull and build the OpenDSA images before instantiating the OpenDSA container. This command runs several setup commands in the background to initialize the container and install the python packages requirements of OpenDSA. This will probably take a long time to run the first time.

In order to interact with OpenDSA, you must open a bash shell within the container to run commands using the following command:

docker-compose exec opendsa bash

This command automatically starts the virtual environment and places you in the OpenDSA directory of the container. After activation, you are ready to build a book. For a small test book (within the container), you can try:

make Test

This should put a test book into [OpenDSA]/Books/Test.

When you want to bring the container down, you can stop the server with CTRL+C and run docker-compose up again to restart OpenDSA.

2.9.3. Running a Local Web Server

To see most OpenDSA content properly, it must be viewed through a web server. It won’t work just to point your browser at the local HTML files. But you probably don’t want to install a real web server like Apache on your local machine. So we have made a simple solution:

make Webserver

This command is run automatically when docker-compose up runs and starts a basic server where you can view your OpenDSA content. Once the container starts, you can go to your web browser, and point it to one of the URLs where the web server is responding (http://localhost:8080/ is usually one). This will be the top level of the OpenDSA directory, and you can browse through it in the normal way. Any books that you have made will be in the Books directory.

You can stop the container with CTRL + C (sending an interrupt signal). If you want the sever running continuously, we advise you to either run this command in a second terminal window and leave it open or run docker in detached mode using:

docker-compose up -d

In order to stop the server, you can always run:

docker-compose down

2.10. Writing Visualizations and Exercises

The OpenDSA system has been developed over many years to help people write simple or complex visualizations and interactive exercises. Depending on what you want to do, there might be a lot to learn. To get you productive quickly, we created the SimpleDemo materials. Once you have your development environment with Docker installed, you should compile the SimpleDemo book instance. This is done by typing make SimpleDemo from within the docker container using docker-compose exec opendsa bash. At that point, you can find the book by accessing the simple web server started by Docker, and navigating to Books/SimpleDemo. Read the module, but also look at the sourcecode for both the module and the various examples. These will show you a lot of what you will need to implement your own visualizations and exercises.

This Docker development environment is structured to allow you to edit files on your host machine and have them mirrored to the container.