Custom Blocks

This document is aimed at developers who wish to create new blocks within Blockly. It is assumed that one has a local copy of Blockly which one can edit, one is generally familiar with Blockly's usage, and one has a basic understanding of JavaScript.

Blockly comes with a large number of pre-defined blocks. Everything from mathematical functions to looping structures. However, in order to interface with an external application, one must create custom blocks to form an API. For example, when creating a drawing program, one might need to create a "draw circle of radius R" block.

In most cases the easiest approach is to just find a really similar block which already exists, copy it, and modify it as needed. The following documentation is for those who need more help.

Define a Block

The first step is to create a block; specifying its shape, fields, and connection points. Using Blockly Developer Tools is the easiest way to write this code.

→ More info on the Blockly Developer Tools...

Alternatively, one can write this code by hand after studying the API.

→ More info on Defining Blocks...

Advanced blocks may dynamically change their shape in response to the user or other factors.

→ More info on Mutators...

Code Generation

The second step is to create the generator code to export the new block to a programming language (such as JavaScript, Python, PHP, Lua, or Dart).

→ More info on Generating Code...

To generate code that is both clean and correct, one must be mindful of the order of operations list for the given language.

→ More info on Operator Precedence...

Creating more complicated blocks requires the use of temporary variables and/or utility functions. This is particularly true when an input is used twice and needs to be cached.

→ More info on Caching Arguments...