overview
Introduction to Blockly
Blockly is library that adds a visual code editor to web and Android apps. The Blockly editor uses interlocking, graphical blocks to represent code concepts like variables, logical expressions, loops, and more. It allows users to apply programming principles without having to worry about syntax or the intimidation of a blinking cursor on the command line.
Blockly is for developers. Blockly apps are for students. Blockly is a complicated library targeted at experienced developers. If you're here to use educational apps rather than build them, check out these Computer Science Learning Opportunities.
Building a Blockly app
From a user's perspective, Blockly is an intuitive, visual way to build code. From a developer's perspective, Blockly is essentially a text box that contains syntactically correct user-generated code. Blockly can export blocks to many languages, including these popular options:
- JavaScript
- Python
- PHP
- Lua
- Dart
Here's a high-level breakdown of what goes into building a Blockly app:
- Integrate the Blockly editor. The Blockly editor at its simplest consists of a toolbox to store block types, and a workspace for arranging blocks. Learn more about integrating Blockly in the Get Started docs for Web or Android.
- Create your app's blocks. Once you've got Blockly in your app, you need to create blocks for your users to code with, then add them to your Blockly toolbox. Learn how in Create Custom Blocks Overview.
- Build the rest of the app. By itself, Blockly is just a way to generate code. The heart of your app is in deciding what to do with that code.
Blockly's strengths and other options
Blockly is one of a growing number of visual programming environments. Deciding which one to use in your app is an important step, so here are a few of Blockly's biggest strengths to help you make the decision:
- Exportable code. Users can extract their block-based programs to common programming languages and smoothly transition to text-based programming.
- Open source. Everything about Blockly is open: you can fork it, hack it, and use it in your own sites and Android apps.
- Extensible. Tweak Blockly to fit your needs by adding custom blocks for your API or removing unneeded blocks and functionality.
- Highly capable. Blockly is not a toy. You can implement complex programming tasks like calculating standard deviation in a single block.
- International. Blockly has been translated to 40+ languages, including right-to-left versions for Arabic and Hebrew.
Even with all those positives, Blockly isn't the solution for every app. Here are a few other visual editors that you might find helpful:
- Scratch Blocks: Designed by the people behind MIT's Scratch and built on the Blockly code base, Scratch Blocks offers a simplified programming model ideal for young learners.
- Droplet: The graphical programming editor that powers Pencil Code, its distinguishing feature is the ability to convert from code to blocks.
- Snap: A Scratch-inspired graphical programming language, it's not a library but is instead a full app with an integrated execution environment.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Get Started ( web )
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.
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 other 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
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.
Once you have the code, point your browser at demos/fixed/index.html and verify that blocks can be dragged around.
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
The Blockly.inject line used in the examples above contains as its second argument a dictionary of name-value pairs. These are used for configuration. The following options are supported:
| Name | Type | Description | |
|---|---|---|---|
| collapse: | boolean | Allows blocks to be collapsed or expanded. Defaults to true if the toolbox has categories, false otherwise. | |
| comments: | boolean | Allows blocks to have comments. Defaults to true if the toolbox has categories, false otherwise. | |
| css: | boolean | If false, don't inject CSS (providing CSS becomes the document's responsibility). Defaults to true. | |
| disable: | boolean | Allows blocks to be disabled. Defaults to true if the toolbox has categories, false otherwise. | |
| grid: | object | Configures a grid which blocks may snap to. See Grid... | |
| horizontalLayout: | boolean | If true toolbox is horizontal, if false toolbox is vertical. Defaults to false. | |
| maxBlocks: | number | Maximum number of blocks that may be created. Useful for student exercises. Defaults to Infinity. | |
| media: | string | Path from page (or frame) to the Blockly media directory. Defaults to "https://blockly-demo.appspot.com/static/media/". | |
| oneBasedIndex: | boolean | If true list and string operations should index from 1, if false index from 0. Defaults to true. | |
| readOnly: | boolean | If true, prevent the user from editing. Supresses the toolbox and trashcan. Defaults to false. | |
| rtl: | boolean | If true, mirror the editor (for Arabic or Hebrew locales). See RTL demo. Defaults to false. | |
| 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. | |
| toolbox: | XML nodes or string | Tree structure of categories and blocks available to the user. See below for more information. | |
| toolboxPosition: | string | If "start" toolbox is on top (if horizontal) or left (if vertical and LTR) or right (if vertical and RTL). If "end" toolbox is on opposite side. Defaults to "start". | |
| trashcan: | boolean | Displays or hides the trashcan. Defaults to true if the toolbox has categories, false otherwise. | |
| zoom: | object | Configures zooming behaviour. See Zoom... | |
The most important option is toolbox. This is an XML tree that specifies which blocks are available in the toolbox (the side menu), how they are grouped, and whether there are categories.
→ More info on defining the toolbox...
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...
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
