Skip to content

Developer Guide

Jump to bottom
Kirk Swenson edited this page Jan 13, 2017 · 22 revisions

Developing with the CODAP Open Source Repository

These are instructions for setting up a full CODAP development environment. This is useful for running CODAP locally with the purpose of modifying CODAP software. It is not necessary if all you want to do is create a plugin (Data Interactive) that will run in CODAP. If that is your goal, please see https://github.com/concord-consortium/codap/wiki/CODAP-Data-Interactive-API.

Setting Up the Development Environment

Development Pre-requisites

CODAP utilizes the SproutCore framework which requires Ruby 1.9.2+ for its build tools.

Depending on the version of Ruby installed on your system, you may find it convenient to use RVM which helps manage multiple versions of Ruby.

####Instructions for Macs:####

  1. Install SproutCore 1.11 Follow the instructions for installing SproutCore from SproutCore website. CODAP uses SproutCore version 1.11 which needs to be specified during installation.

    $ gem install sproutcore -v 1.11

  2. Get the CODAP Source

    To clone the CODAP repository itself:

    $ https://github.com/concord-consortium/codap.git
$ cd codap
$ git submodule update --init --recursive

To work with the CODAP repository it is often useful to fork it on Github and then clone the fork.

####Instructions for Windows 8.1:####

  1. Install Ruby 1.9.3 with DevKit 
	c:\Ruby193\DevKit>ruby dk.rb init
	c:\Ruby193\DevKit>ruby dk.rb review
    c:\Ruby193\DevKit>ruby dk.rb install

  1. Install SproutCore

    c:\Ruby193\DevKit>gem install sproutcore

  2. Get the CODAP Source

    To download the CODAP repository to your local directory:

To work with the CODAP repository it is often useful to fork it on Github and then clone the fork.

Install NPM Packages

Assuming you have the NodeJS and the Node Package Manager (npm) installed on your system, change to your CODAP directory in a terminal window and run the following commands:

    % npm install           # or 'yarn'
    % npm run build:bundle

Run the CODAP Application Locally

On the command line, change your working directory to the project directory and run:

    $ sc-server

This runs the SproutCore server, which serves the application code locally. To run the application, enter the following URL into your web browser of choice: http://localhost:4020/dg.

This should run the CODAP application.

Introducing Data into CODAP

Data can be introduced into CODAP in a variety of ways. For example, in modular browsers a CSV or tab-delimited .txt (simple text) file can be dragged and dropped into the CODAP workspace. Third party data sets/activities can also be dropped into the workspace. These are called data interactives. There are examples of data games on the project page.

Modifying the CODAP Source

Most changes to the CODAP application source are automatically reflected by simply reloading the browser page at http://localhost:4020/dg. More extensive changes (e.g. adding/removing source files) may require stopping and restarting sc-server and/or removing the generated tmp folder. For npm users, a set of scripts are defined in the package.json file to assist with many of these development tasks. Some of the more commonly used scripts for local development are listed below. See the package.json file for the full list of available scripts.

  • npm run build:bundle - builds the library bundle required by CODAP. Must be run before running CODAP locally for the first time.
  • npm run clean - deletes the tmp directory and other build products
  • npm run clean-and-serve - runs the clean script and then starts sc-server
  • npm run codap - starts sc-server
  • npm run lint - runs ESLint/JSHint over the sources
  • npm run test - runs CODAP's unit tests

Updating the Cloud File Manager

CODAP uses the Cloud File Manager library (CFM) to handle most of its document storage/retrieval. Currently, the built CFM files are simply included in the CODAP git repository. To update the version of CFM included in CODAP, it is necessary to build the CFM library with some CODAP-specific options and put the appropriate CFM output files into the apps/dg/resources/cloud-file-manager directory in CODAP. There is an npm script named build:codap in the CFM repository which takes care of all the details as long as the codap and cloud-file-manager repositories are in sibling directories, i.e. something like ../projects/codap and ../projects/cloud-file-manager. With this configuration, within the cloud-file-manager repository, simply typing:

$ npm run build:codap

will build the CFM and place the output files in the appropriate place in the codap repository. Under the hood, npm run build:codap executes the following command:

$ gulp clean-and-build --dest ../codap/apps/dg/resources/cloud-file-manager --codap --nojQuery --noReact --noMap

If your codap repository is not a sibling of your cloud-file-manager repository or has a different name, you can execute an analogous command with a different destination path. After updating the CFM, simply reloading the page at http://localhost:4020/dg should make the changes available as long as sc-server is running.

Clone this wiki locally