Skip to content

Developer Guide

Jump to bottom
Jonathan Sandoe edited this page Feb 28, 2017 · 22 revisions

CODAP Developer Guide

These are instructions for setting up a full CODAP development environment. You will need to do this if you wish to modify or debug CODAP itself. For example, you may wish to create an alternate version, a translation of the user interface, or contribute bug fixes to the CODAP project. You do not need to do this if you wish to deploy an instance of CODAP to a web server or if you wish to create a plugin (Data Interactive) that will run in CODAP. If you wish to deploy an instance of CODAP, you can download a zip file from http://codap.concord.org/releases/zips/ and then unzip it in the file space of your web server. If you wish to develop a CODAP plugin please see: https://github.com/concord-consortium/codap/wiki/CODAP-Data-Interactive-API.

Installing the CODAP development environment

The following are instructions that will install CODAP and its dependencies. There are a variety of ways of installing the dependencies and it is likely that any developer is set up for most dependencies.

Development Dependencies

The development environment for CODAP requires the following software:

Notes for installing Git

Notes for installing node.js and npm

  • Mac OS: Here are useful instructions.
  • Windows: Here are useful instructions.
  • Windows users may wish to install cygwin.

Notes for installing ruby

  • Mac OS: Ruby is not installed natively on Mac OS, but, as with git, can be found in the Mac Developer Tools.

  • In addition, you may find it convenient to install the Ruby Version Manager RVM. It is helpful for managing multiple Ruby versions.

  • For Windows: Install Ruby 1.9.3 or later with DevKit

    c:\Ruby193\DevKit>ruby dk.rb init
c:\Ruby193\DevKit>ruby dk.rb review
c:\Ruby193\DevKit>ruby dk.rb install

Notes for installing Sproutcore

  • The basic command is:
  $ gem install sproutcore -v 1.11

Installing CODAP

Get the CODAP Source

  • In a terminal window:

    $ git clone 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.

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. CODAP should run well on the latest release of modern mainstream browsers, including Chrome, Firefox, Safari, Edge, and IE 11.

Troubleshooting

  • If your local version of CODAP fails to load, check the output in the terminal window where you ran 'sc-server' and check your browser's console.

Working with the CODAP development environment

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

Note that some of these commands require unix or unix-like command line programs, and may not work in pure Windows environments. Windows users may wish to install cygwin.

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: bash $ 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