Using VDD Core

Installation

• Update your project.clj file with the version specifed in the README as a dependency.
• Add viz to the source path in the development profile.

An excerpt of the :profiles in your project.clj might look like the following:

  :dependencies [[vdd-core "0.1.0"]]

  ;; Add viz as a source path to load visualization drivers
  :profiles {:dev {:source-paths ["viz"]}}

Starting the Server

Execute the following code in your REPL:

(require '[vdd-core.core :as vdd])
(def server (vdd/start-viz))

Go to http://localhost:8080 in your web browser.

Development Mode Only!

Important Note: VDD Core is designed to be used during active development. It should not be used either as a production server or started on an open port. It allows arbitrary execution of server side code from the browser as part of its goal to aid in testing.

Project Layout

Visualizations are defined as folders in a viz folder in your project. vdd-core looks for in a top level viz folder when it starts up. Any subfolders of viz that contain an index.html page will be considered a visualization.

A visualization usually consists of the following files:

• index.html - This will contain the visualization of your code.
• A visualization specific CSS file - Your index file should include this.
• A visualization specific JavaScript file - Your index file should include this. This can be either hand written or generated from ClojureScript.
• driver.clj - Contains code to "drive" the visualization. See the Visualization Driver section below.

Visualization Driver

Visualizing execution of some code usually requires having some helper code that will invoke the code being tested, capture execution data (See Capturing Code Execution below.), and send the captured data to the visualization. Drivers should be put in a driver.clj file in the visualization folder in viz. If your visualization is named "qsort" then your folder structure and driver would look like this

• my-clojure-project/
  • viz/
    • qsort/
      • index.html
      • qsort.css
      • qsort.js
      • driver.clj

driver.clj:

(ns qsort.driver
  (:require [my-clojure-project.my-code :as my-code]
            [vdd-core.core :as vdd]
            [vdd-core.capture-global :as capture]))

(defn test-viz-my-code []
  ; TODO execute your code and capture data

  ; Then send the captured data to the visualization through websockets.
  ; Note: You need to have http://localhost:8080/viz/qsort/index.html open in your browser before executing this.
  (vdd/data->viz data-captured-from-my-code-execution))            

Capturing Code Execution

Representing code execution as data is one the key ways we can visualize it. VDD Core provides a basic set of functions to capture code execution as data. For a more robust solution see the Lamina project's Probes and Instrumentation capabilities.

TODO Link to API documentation after we put it on github pages.

Here's an example of capturing code execution and sending it to the visualization. This is a very trivial example for which we normally create a visualization.

The code in your application:

(ns my-math-lib
  (:require [vdd-core.capture-global :as capture]))

(defn average 
  "Takes a set of numbers and calculates their average."
  [numbers]
  (let [size (count numbers)
        sum (reduce + numbers)]
    (capture/capture! {:numbers numbers :size size :sum sum})
    (float (/ sum size))))

driver.clj:

(ns my-math-lib.driver
  (:require [my-math-lib]
            [vdd-core.core :as vdd]
            [vdd-core.capture-global :as capture]))

(defn viz-average 
  "Executes the average function. Gathers captured data and sends it to the visualization."
  [numbers]
  ; Enable capturing of data.
  (capture/enable)
  ; Reset the global captured state
  (capture/reset-captured!)
  
  (let [result (my-math-lib/average numbers)
        captured (capture/captured)]
    ; Send the data to be visualized
    (vdd/data->viz captured)))

Creating Interactive Visualizations

Visualizations don't have to be completely passive. They can interact with the server. VDD Core allows creation of visualizations that are both testing tools and visualizations. You can create an interactive visualization by following these steps:

• Add a function in your driver that will call the code being tested and send any captured data to the visualization. You probably already have a function like this defined for testing from the REPL.
• Add appropriate HTML controls to enter test data in the visualization.
• Add a submit button with JavaScript handler. In the button handler use the vdd_core.connection.callServerFunction to call the function defined in your driver. See that functions documentation for more details and some example code.