What's a block definition?

A block definition is an object that defines a custom block. For example, it defines the block's look and feel, (text, fields, connections, colour, etc.), as well as its behavior (block-level event handler, etc.).

For example, this block:

can be defined in JSON or JavaScript as follows:

JSON

Blockly.common.defineBlocksWithJsonArray([{
  "type": "string_length",
  "message0": 'length of %1',
  "args0": [
    {
      "type": "input_value",
      "name": "VALUE",
      "check": "String"
    }
  ],
  "output": "Number",
  "colour": 160,
  "tooltip": "Returns number of letters in the provided text.",
  "helpUrl": "http://www.w3schools.com/jsref/jsref_length_string.asp"
}]);

defineBlocksWithJsonArray creates a block definition from a JSON object.

JavaScript

Blockly.Blocks['string_length'] = {
   init: function() {
     this.appendValueInput('VALUE')
         .setCheck('String')
         .appendField('length of');
     this.setOutput(true, 'Number');
     this.setColour(160);
     this.setTooltip('Returns number of letters in the provided text.');
     this.setHelpUrl('http://www.w3schools.com/jsref/jsref_length_string.asp');
   }
};

When you use JavaScript, you create the block definition directly.

How block definitions work

A block definition is a mixin containing function-valued properties. When a new block is instantiated, these properties are copied to the newly created block object. Blockly calls these functions to invoke custom behavior.

Because the definition functions are mixed in to the block object:

• The this keyword in definition functions refers to the block object. That is, it can be used to access the public methods and properties in the Block (or BlockSvg) class.

Blockly defines a small number of functions you can use to customize blocks. The most common of these is init, which Blockly calls to initialize a block and which is used to define the block's look and feel. For a complete list, see the function-valued properties in the Block and BlockSvg classes. These properties effectively form an interface for block definitions to implement; all of them are optional.

Block definitions can also have custom functions, although Blockly will not call these directly. Instead, they can be used to implement other functions. For example, a block-level event handler (the Block.onchange property) could delegate different events to different custom functions.

How to create block definitions

There are several different ways to create block definitions:

• Use the Blockly Developer Tools to define the look and feel of your block. Copy the generated JSON or JavaScript to your code and add custom code as needed. For more information, see Blockly Developer Tools.
• Find a similar block, copy its definition, and modify it as needed. For more information, see Modify existing definitions.
• Write a block definition by hand. For more information, see JSON and JavaScript.