README

@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 helpful tool to debug blocks when building a custom renderer.

import {DebugRenderer} from '@blockly/dev-tools';
// Initialize the debug renderer.
DebugRenderer.init();

The debug renderer is included by default in the playground.

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

Usage no npm install needed!