Blockly is a web-based, graphical programming editor. Users can drag blocks together to build an application. No typing required. Credit goes to these awesome developers and a small army of translators.
This repository contains the source code for the apps Blockly based 20 hour curriculum and Hour of Code. Information about Blockly can be found in the wiki.
One of the node modules, node-canvas, depends on Cairo being installed.
Instructions for MacOSX using brew (instructions for other platforms can be found here):
- Install XQuartz from here
export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/opt/X11/lib/pkgconfig"
brew update
brew install cairo
- In blockly,
npm install
cd blockly
# Machine setup (OSX with Homebrew)
brew install node
npm install -g grunt-cli
export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/opt/X11/lib/pkgconfig"
npm install -g canvas
# Perform first full build
npm install
MOOC_DEV=1 grunt build
- To make your changes show up in dashboard, run the following after the first time you build blockly:
cd ../dashboard
bundle exec rake 'blockly:dev[../blockly]'
cd ../blockly
- If you find your changes are not showing up within dashboard, you may have accidentally reverted your symlink to point to the pre-built version of blockly (e.g. when switching branches or stashing changes). To check your symlink, run:
git status
and look for something like public/blockly -> blockly-package
in the output. [NEEDS VALIDATION].
- If the symlink is in place, then when you run later builds of blockly, your results should show up in Dashboard.
To run a full build (minus localization):
MOOC_DEV=1 grunt build
MOOC_DEV=1
builds a 'debug' version with more readable javascriptgrunt rebuild
does aclean
before abuild
grunt dev
open http://localhost:8000
This will serve a few sample blockly apps at http://localhost:8000.
Note: this does not update asset files. For that, use a full grunt build
.
To have grunt rebuild only a single app, use the MOOC_APP parameter:
MOOC_APP=studio grunt dev
To have grunt build a single foreign language, use the MOOC_LOCALE parameter. This will build en_us, en_loc, and the specified locale
MOOC_LOCALE=ar_sa grunt build
grunt build # run a build before testing
grunt test
- If you see an error like
ReferenceError: Blockly is not defined
or notes about missing npm packages, double check that you've rungrunt build
beforegrunt test
grunt test
will also be run via Travis CI when you create a pull request
To run an individual test, use the --grep
option to target a file or Mocha describe
identifier:
grunt test --grep myTestName # e.g., 2_11, or requiredBlockUtils
To debug tests using the node-inspector Chrome-like debugger:
npm install -g node-inspector
node-inspector &
# open debugger URL
node --debug-brk $(which grunt) --grep='testname'
# This will breakpoint your inspector at the beginning of that test
- You can add new test files as /test/*Tests.js, see
/test/feedbackTests.js
as an example of adding a mock Blockly instance - Blockly tests typically target built files in the
build/js
folder
- Check out blockly-core as a sibling directory to blockly.
./build_with_core.sh debug
- The
debug
flag builds debug versions of both blockly-core and blockly, suitable for debugging
grunt dev
It's especially important to test your changes with localization when modifying layouts. We support right-to-left languages and have some special layout tweaks embedded in the CSS to support that.
Running a full localization build can take several minutes. Since localization re-builds javascript files for many languages, the default build target locales are en_us
and en_ploc
(pseudolocalized). To build
all available locales, specify MOOC_LOCALIZE=1
in your environment when running a task:
MOOC_LOCALIZE=1 grunt rebuild
Note: if you're running the grunt dev
live-reload server and get the error too many open files
after a localization build, try increasing the OS open file limit by running ulimit -n 1024
(and adding it to your .bashrc
).
To get new strings localized using CrowdIn, we currently run a script in a private repository. Contact a code.org engineer to trigger an update.
To add a new package using npm, e.g., lodash
, run: npm i --save-dev lodash
--save-dev
adds the dependency to node's package.json, freezing the current version- Because the build process is done in dev mode, include dependencies as devDependencies rather than production dependencies
We'd love to have you join our group of contributors!
For notes on our pull process, where to find tasks to work on, etc.—see the Dashboard contribution guide.
- In general follow Google's javascript style guide.
- 80 character line length.
- 2 space indent.
- 4 space indent on long line breaks.
grunt jshint
should report 0 warnings or errors.