Get Started

This document is aimed at developers who wish to create their own applications that incorporate Blockly as a code editor. It is assumed that one is generally familiar with Blockly's usage, and one has a basic understanding of HTML and JavaScript.

After reading this document, you may wish to try the Getting Started codelab.

Overview

Blockly is designed to easily install into your web application. Users drag blocks around, Blockly generates code, your application does something with that code. From your application's point of view, Blockly is just a textarea in which the user types syntactically perfect JavaScript, Python, PHP, Lua, Dart, or another language.

Blockly is 100% client side, requiring no support from the server (unless one wants to use the cloud-storage feature). There are no 3rd party dependencies (unless one wants to recompile the core). Everything is open source.

Get the Code

Blockly is published on the npm registry and yarn registry. We recommend accessing Blockly through a package manager because:

  • It is easier to stay up to date with changes in Blockly
  • It encourages using plugins instead of monkeypatching Blockly

If you need more convincing you can watch our 2021 Blockly on npm talk. If you are already using a package manager, you can install Blockly with

npm install --save blockly

You can reference Blockly in your application code with:

import Blockly from 'blockly';

This will import the default packages. For more information, see the package readme, and the examples for using Blockly with Node and webpack.

Unpkg

If you aren't using a package manager for your project, but don't want to have to copy the code yourself, you can use unpkg.

<script src="https://unpkg.com/blockly/blockly.min.js"></script>

Unpkg grabs the latest version of the published code, so there won't be any version control with this method. It is great for demos or quick experiments, and we use it in many codelabs.

GitHub

You can also copy the entire source code from GitHub. However, you will have to manually sync to our repository at regular intervals in order to receive the latest updates and fixes to Blockly.

First, download the source code from GitHub. If you know how to use Git or Subversion, we highly recommend syncing from our repository so that your code stays up to date.

Download ZIP File Download TAR Ball View On GitHub

Once you have the code, point your browser at demos/fixed/index.html and verify that blocks can be dragged around.

In your application code, you can load Blockly with:

<script src="blockly_compressed.js"></script>

You may need to include other files as well, which are explained in the "Injecting Blockly" guides linked in the next section.

Injecting Blockly

With your installation of Blockly verified as working, inject Blockly into a web page using a fixed-size div.

→ More info on injecting fixed-sized Blockly...

More advanced web pages may wish to allow Blockly to resize to fill the page.

→ More info on injecting resizable Blockly...

Configuration

Blockly is highly configurable. For instance, you may set the theme or renderer on a workspace, set a workspace to RTL mode, or select from a variety of zoom and scroll modes.

Configuration is done per-workspace, by passing a configuration struct when injecting a Blockly workspace.

→ More info on configuring a workspace...

Defining Blocks

In addition to the default blocks that come with Blockly, custom blocks need to be built to call your web application's API. An example is this maze game which has custom blocks for movement.

→ More info on creating custom blocks...

Code Generators

Blockly is not a programming language, one cannot 'run' a Blockly program. Instead, Blockly can translate the user's program into JavaScript, Python, PHP, Dart, or some other language.

→ More info on code generators...

Importing and Exporting Blocks

If your application needs to save and store the user's blocks and restore them at a later visit, use this call for export to XML:

var xml = Blockly.Xml.workspaceToDom(workspace);
var xml_text = Blockly.Xml.domToText(xml);

This will produce a minimal (but ugly) string containing the XML for the user's blocks. If one wishes to obtain a more readable (but larger) string, use Blockly.Xml.domToPrettyText instead.

Restoring from an XML string to blocks is just as simple:

var xml = Blockly.Xml.textToDom(xml_text);
Blockly.Xml.domToWorkspace(xml, workspace);

Cloud Storage

Blockly comes with an optional cloud-storage feature. It enables users to save, load, share, and publish their programs. If your project is hosted on App Engine you can take advantage of this service.

→ More info on Cloud Storage...