authoring interactives

[Daniel Damelin]

Hi Trevor and Rebecca,

Here’s the info you will need to get started on authoring interactives.

The codebases are managed as Git repositories on Github. If you are going to do any significant work on interactives then you will need to understand at least some rudimentary Git commands. You might check out: http://rogerdudler.github.io/git-guide/ or https://help.github.com 

Git can be run from the command line, but I use an application to do most Git operations. The one I like best is  Sourcetree, but there are other simpler ones.

The codebase in which you will do most, if not all, of your work is the lab-interactives-site. This is where all the interactive definitions and model definitions are stored. To do work here, you should fork the repo and follow the directions in the Readme file (shown on the landing page of the repo) to set up a local clone of your fork of the repository, and then create a branch for doing work on a particular interactive. Once you have work you want to share you can submit a pull request for that branch and I can take a look at it to make sure it is running properly and the format is compliant with how we format other interactive files (mainly how things are indented and where line breaks are used). You can look at many other examples at the lab-interactives-site to see what is expected. 

The Lab framework is another repository. This contains the code for the molecular dynamics engine (as well as some other modeling engines) and has the code for rendering the view of the models and the surrounding interactives. If you wanted to create new modeling features, user interface widgets, or outputs, this is where those kinds of changes would be made, but this codebase is more complex than making new interactives using current features. There are a few parts of this repo that will be helpful to be familiar with even if you are not modifying it.

Generally you will look at other interactives for examples of how to do things you want to do in other interactives, but there are some formal definitions of the interactive and model JSON files. These will give you some sense of the parts that are possible to be present, and in some cases what they refer to. See:

Interactive JSON metadata definition: https://github.com/concord-consortium/lab/blob/master/src/lab/common/controllers/interactive-metadata.js 

Model JSON metatdata definition: https://github.com/concord-consortium/lab/blob/master/src/lab/models/md2d/models/metadata.js

In the Interactive you will often have to write JavaScript that talks to the model via an API. The scripting API for the molecular dynamics model is here:

https://github.com/concord-consortium/lab/blob/master/src/lab/models/md2d/controllers/scripting-api.js 

We still generally create models (the initial number, position, and properties of atoms) using the Classic (Java) version of the Molecular Workbench. When you save a page you made using that application, the saved model files all have the .mml extension. This type of file can be converted to the new .json format by using the converter found here: http://lab-framework.concord.org/mml-converter.html  

I recommend you join the lab-models google group. That is the best place to ask questions while working on interactives.

https://groups.google.com/forum/#!forum/lab-models

Hope that is enough to get you started,

-Dan