Skip to content

Developer Guide

Jump to bottom
Kirk Swenson edited this page Sep 8, 2017 · 22 revisions

Table of Contents generated with DocToc

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:

The following notes may assist you in getting these packages installed and configured. If you already have these packages installed, whether by the means identified below or by other means, these notes can safely be ignored.

Notes for installing Git

  • If you do not have git installed already, go here.
  • Mac OS does not have git installed natively, but it comes with the Mac Developer Tools. Mac Developers may wish to also install command line tools.
  • Windows:
    • When prompted check the option for "use git from Windows Command Prompt", pick "Git in Windows Console".
    • Accept defaults for all other options

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 (XCode).

  • An alternate technique for Mac OS, for users who have Homebrew installed:

    $ brew install ruby

  • For Windows: Install Ruby 1.9.3 or later with DevKit

    • Go to RubyInstaller
    • Download latest stable version for your windows instance (e.g. ruby-2.2.6)
    • Download DevKit from the same page.
    • Run installer to install Ruby
    • Unzip DevKit
    • Run "Command Prompt as Ruby" (Goto windows start icon. Search for "Command Prompt with Ruby".)
    c:\Users\username\Downloads>ruby dk.rb init
c:\Users\username\Downloads>ruby dk.rb review
c:\Users\username\Downloads>ruby dk.rb install

  • In addition, you may find it convenient to install the Ruby Version Manager RVM. It is helpful if you need to swap between multiple Ruby versions.

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. To fork CODAP, go to the Github Repository and click on "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

At present, Windows users will need to run the above command from an environment that supports standard Unix command line programs, such as Git Bash, installed above, cygwin, or bash in windows. The terminal window mentioned above should be one of these.

Run the CODAP Application Locally

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

    $ sc-server --allow-from-ips='*.*.*.*'

  • 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.

  • To verify your build there are two easy things to do:

    • Open your local CODAP instance in a browser. Open each the example documents. They should appear and behave exactly as they would in the official CODAP release.
    • In the terminal window change to the CODAP directory and execute:

    $ npm run test.

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 or enable bash in windows.

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, from within the codap repository, typing:

$ npm run build:cfm

or from within the cloud-file-manager repository, 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.

Translation/Localization

The master English strings file is lang/en-US.json, which is a standard JSON file except that JavaScript-style comments are allowed. (Comments are stripped before use where appropriate.) Changes to English strings should be made in the master English strings file. All other language files are output files generated by script and are stored in their respective .lproj directories, following SproutCore localization convention. Translations for other languages are managed via the CODAP project (authentication required) on POEditor, which provides free hosting services for open source projects.

Development

After making changes to the master English strings file (lang/en-US.json), run the strings:build script to strip comments and deploy the apps/dg/english.lproj/strings.js file for building:

npm run strings:build

To push changes to the master English strings file to POEditor, run the strings:push script:

npm run strings:push -- -a <poeditor-api-token>

The API token must be provided as an argument to the strings:push script or it can be set as an environment variable:

export POEDITOR_API_TOKEN=<poeditor-api-token>

To update the strings files within the project, run the strings:pull script:

npm run strings:pull -- -a <poeditor-api-token>

As with the strings:push script, the API token must be provided or be set as an environment variable. The strings:pull script builds the English strings as well so all strings files will be up to date.

After pulling updated strings, the modified files can be committed to git, turned into a Github Pull Request, etc. Note that POEditor supports Github integration which could potentially automate part of this, but that requires further investigation.

Unicode escapes are converted to their UTF-8 equivalents when pushed, i.e. strings are viewed/edited in their "user" form in POEditor, and they remain in their UTF-8 form when pulled. For characters that are better left in their Unicode escape form, such as non-printable characters like ZERO-WIDTH-SPACE ("\u200b") and the RIGHT-TO-LEFT-MARK ("\u200f"), the scripts support a custom Unicode escape sequence such that "[u200b]" and "[u200f]" are converted to "\u200b" and "\u200f" respectively when pulled.

The ZERO-WIDTH-SPACE character can be used to indicate that the empty string is the correct translation for a string in a particular language. If the string were simply left untranslated, then POEditor would 1) show it as untranslated in the POEditor UI and 2) replace it with the English string when pulled. The ZERO-WIDTH-SPACE prevents POEditor from treating the string as untranslated, but it is rendered like an empty string.

Adding a language

To add a new language:

  1. Add the language to the POEditor project
  2. Add the language code to the list of languages in bin/strings-pull-project.sh
  3. Create a new {lang}.lproj folder for the language, e.g. es.lproj for Spanish.
  4. Copy the English function_strings.json (at apps/dg/english.lproj/function_strings.json) into the new {lang}.lproj folder. Translation of the function_strings.json is not currently supported.
  5. There may at some point be another step for configuring which builds should contain the new language, but for now all languages are built by default.
Clone this wiki locally