Home

Getting Started

Scratch Blocks is designed to easily install into any web application. The blocks are 100% client-side, requiring no support from the server. There are no 3rd party dependencies and everything is open source.

Scratch Blocks is based on Google's Blockly project. For a full API reference please see Google's Custom Blocks documentation.

Installation

First, download the source code from GitHub. As this project is quickly being updated we recommend you use git but you are more than welcome to download the code directly as well.

If you are using the library in another project, you can also install it with npm:

npm install --save-dev scratch-blocks

Before testing with the "Playground" or running any demos, you'll need to ensure that you have Google's Closure Library installed. The closure library is included as a dev dependency so you can install it with a symlink:

ln -s $(npm root)/google-closure-library ../closure-library

If you run into any trouble with this step, or see the following dialog please refer to Google's Blockly documentation.

Finally, run npm install, which will install the closure library and build the assets used in the playground.

Once you have the code, point your browser at tests/horizontal_playground.html and verify that blocks can be dragged around. In addition to being the "hello world" test for Scratch Blocks, the playgrounds are also useful for testing more advanced features including event handling, right-to-left (RTL), and stack highlighting.

Configuration

Configuration of the workspace is mostly the same between Blockly and Scratch Blocks but is subject to change as the project continues to develop. Below is a list of configuration options that we are likely to continue to support:

Name	Type	Description
horizontalLayout	boolean	If true, uses the horizontal grammar for displaying blocks. Defaults to false.
rtl	boolean	If true, mirror the editor (for Arabic or Hebrew locales). Defaults to false.
media	string	Path from page (or frame) to the Scratch Blocks media directory.
scrollbars	boolean	Sets whether the workspace is scrollable or not. Defaults to true if the toolbox has categories, false otherwise.
sounds	boolean	If false, don't play sounds (e.g. click and delete). Defaults to true.
zoom	object	Configures zooming behavior. See zoom API details.

---

Building

Before sharing with users, we recommend that you build and compress Scratch Blocks. It's possible to build locally or using Google's online Closure Compiler. If the build system detects that it can build locally it will do so, and otherwise it will try to build remotely.

The requirements for local and remote builds are as follows:

Local Build	Remote Build
NodeJS	NodeJS
Python 2	Python 2
Java JRE or JDK	Internet Connection

A Java runtime may be installed on your system already; you can test by typing java in your console. If not, it can be downloaded here. Depending on your system there may also be alternative JREs or alternative installation methods available.

An Internet connection is also needed the first time you build, even for a local build, so that NPM can download necessary Node.js modules.

Once you are ready, you can build by running the following in your console:

npm install

This will export multiple files including:

blockly_uncompressed_vertical.js
blockly_uncompressed_horizontal.js
blockly_compressed_vertical.js
blockly_compressed_horizontal.js
blocks_compressed.js
msg/js/en.js

These can then be used in your project by updating the HTML of your application:

<script src="blockly_compressed_horizontal.js"></script>
<script src="blocks_compressed.js"></script>
<script src="msg/js/en.js"></script>