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 theBlock
(orBlockSvg
) 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.