@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.

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.

DebugDrawer.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