@blockly/dev-tools

A library of helpful tools for Blockly development.

Installation

npm install @blockly/dev-tools -D --save

Usage

Playground

The playground is a tremendously useful tool for debugging your Blockly project. As a preview, here is one of the plugin playgrounds. The playground features are:

• All the default blocks
• All the language generators (JavaScript, Python, PHP, Lua, and Dart)
• Switch between different Blockly options (eg: rtl, renderer, readOnly, zoom and scroll)
• Switch between different toolboxes and themes
• Import and export programs, or generate code using one of the built-in generators
• Trigger programmatic actions (eg: Show/hide, Clear, Undo/Redo, Scale)
• A debug renderer
• Stress tests for the renderer
• Log all events in the console

import {createPlayground} from '@blockly/dev-tools';

const defaultOptions = {
  ...
};
createPlayground(document.getElementById('blocklyDiv'), (blocklyDiv, options) => {
  return Blockly.inject(blocklyDiv, options);
}, defaultOptions);

This package also exports pieces of the playground (addGUIControls, addCodeEditor) if you'd rather build your own playground.

Toolboxes

Blockly built-in Simple and Category toolboxes.

import * as Blockly from 'blockly';
import {toolboxSimple, toolboxCategories} from '@blockly/dev-tools';

Blockly.inject('blocklyDiv', {
  toolbox: toolboxCategories,
});

Test Toolbox

The test toolbox is re-exported in this package, but can be imported as a stand-alone through @blockly/block-test. See the README for details.

Helpers

populateRandom

The populateRandom function adds random blocks to a workspace. Blocks are selected from the full set of defined blocks. Pass in a worskpace and how many blocks should be created.

import {populateRandom} from '@blockly/dev-tools';
// Add 10 random blocks to the workspace.
populateRandom(workspace, 10);

spaghetti

The spaghetti function is a renderer stress test that populates the workspace with nested if-statements. Pass in a worskpace and how deep the nesting should be.

import {spaghetti} from '@blockly/dev-tools';
spaghetti(workspace, 8);

generateFieldTestBlocks

The generateFieldTestBlocks function automatically generates a number of field testing blocks for the passed-in field. This is useful for testing field plugins.

import {generateFieldTestBlocks} from '@blockly/dev-tools';

const toolbox = generateFieldTestBlocks('field_template', [
  {
    args: {
      value: 0, // default value
    },
  },
]);

Test Helpers

This package is also used in mocha tests, and exports a suite of useful test helpers. You can find the full list of helpers here.

Debug Renderer

The debug renderer is a renderer plugin that wraps your normal renderer, and visualizes the measurements the render info collects. This is extremely helpful for understanding what your renderer thinks about the block it is trying to render.

What it surfaces

The debug renderer can show you several different things.

Debug info	Image	Description
Rows		The bounds of the individual rows in a block.
Row spacers		The bounds of the row spacers in a block.
Elements		The bounds of the elements in a block.
Element spacers		The bounds of the element spacers in a block.
Connections		The locations of the connection points, with large circles for next and input connections (parent connections) and small circles for output and previous connections (child connections).
Block bounds		The bounds of the block, not including any child blocks.
Connectioned block bounds		The bounds of the block, including child blocks.
Render / paint		Flashes the block red when the renderer rerenders the block, equivalent to paint flashing in Chrome.

How to use it

The debug renderer wraps your existing renderer, and then you can register and use it just like any other renderer.

import {createNewRenderer, DebugDrawer} from '@blockly/dev-tools';

const DebugRenderer = createNewRenderer(YourCustomRenderer);
Blockly.blockRendering.register('debugRenderer', DebugRenderer);

Blockly.inject('blocklyDiv', {renderer: 'debugRenderer'});

To see the different information the debug renderer surfaces, you can modify the config from the browser console.

DebugRenderer.config = {
  rows: true,
  rowSpacers: true,
  elems: true,
  elemSpacers: true,
  connections: true,
  blockBounds: true,
  connectedBlockBounds: true,
  render: true,
};

Logger

A lightweight workspace console logger.

import {logger} from '@blockly/dev-tools';

logger.enableLogger(workspace);
logger.disableLogger(workspace);

The logger is included by default in the playground.

License

Apache 2.0