See the application running here: http://sage.concord.org/branch/master
Other useful links:
- Codap – The Data Analysis Platform we are using.
- Codap Sage Icons – A shared icon font for Building Models (ivy) and CODAP.
- MySystem – a simple concept mapping with node/edge graphs.
- Model Survey – Assessing available node/edge graphing tools.
- jsPlumb – The graphing toolkit we are currently using.
- React – Javscript component development toolkit.
- MIT License – The license we are using.
Install the global dependencies:
brew install nodeon OS X `
Check out the project and install the local dependencies:
git checkout https://github.com/concord-consortium/building-models.git
npm start— watches the project sources in
./src/and builds artifacts into
devand starts webserver.
- Edit code in
./src/, watch live changes in browser. (Webpack will build your changes automatically to
./dev/and will automatically refresh your browser when it sees changes there.)
- Place static files you want to be copied to
If you get an node error about "too many files open," try running
ulimit -n 2560
webpackhas run, or while it is running):
./node_modules/mocha/bin/mocha -wto run mocha tests (located in
-wflag should keep the tests running everytime you make a code change (if
webpackis still running), but occasionally a hard-error of a test will force you to start them up again.
Test Sage running in CODAP:
Production releases to S3 are based on the contents of the /dist folder and are built automatically by GitHub Actions for each branch pushed to GitHub and each merge into production.
Merges into production are deployed to http://sage.concord.org.
Other branches are deployed to http://sage.concord.org/branch/BRANCH-NAME.
To deploy a production release:
- Update the version number in package.json and run
npm installto update package-lock.json
v<version>branch and commit changes, push to GitHub, create PR and merge
- Checkout master and pull
- Checkout production
git merge master --no-ff
- Push production to GitHub
- Use https://github.com/concord-consortium/building-models/releases to create a new release tag
NOTE: This repo and the sage-modeler-site repo should be released at the same time, with the same version numbers, even if one of the two repos has no changes, in order to keep their version numbers in sync so that the splashscreen and top nav bar show the same version numbers. Refer to the readme in that repo for release steps.
The master English strings file is
src/code/utils/lang/*.json are output files generated by script. Translations for other languages are managed via the Building Models project (authentication required) on POEditor, which provides free hosting services for open source projects.
After making changes to the master English strings file (
src/code/utils/lang/en-US-master.json), run the
strings:build script to strip comments and deploy the
src/code/utils/lang/en-US.json file for building:
npm run strings:build
To push changes to the master English strings file to POEditor, run the
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:
To update the strings files within the project, run the
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:
- Add the language to the POEditor project
- Add the language code to the list of languages in
- Load the new language file in
Note that there is probably a way to eliminate the need for step 3 above by requiring all JSON files in the
src/code/utils/lang directory (except for
en-US-master.json), but that has not been implemented yet.
Updating the shared fonts.
To update the icon fonts used in this project:
- Checkout and modify the shared icon-font project Codap Sage Icons
- Follow the directions there to deploy to github pages.
curlfonts.shto download a local copy of the CSS and fonts to this project.
Disabling Rollbar integration
If you want to disable Rollbar integration on your development machine just add a
disableRollbar local storage option with the value
true (as a string, all local storage values are strings). This value is checked in the index.html file prior to defining
How to generate CSV researcher graph topology reports:
Tool for education researchers to report on Sage Modeler diagram topology. For more information see: https://www.pivotaltracker.com/story/show/177674195
From web interface:
- Simply browse over to /report.html and follow the instructions
Local development mode:
- Run a local webserver
npm run start
- upload files using http://localhost:8080/report.html
Command line (deprecated):
- Make sure you have npm & node installed.
- Install node dependencies
- Place your reporting sources (
*/.xlsx) into the
npm run convert
- Output CSV files will appear in the