A library of common utilities for Blockly extension development.
npm install @blockly/dev-toolsA library of helpful tools for Blockly development.
```
npm install @blockly/dev-tools -D --save
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
`js
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.
Blockly built-in Simple and Category toolboxes.
`js
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.
#### 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.
`js`
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.
`js`
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.
`js
import {generateFieldTestBlocks} from '@blockly/dev-tools';
const toolbox = generateFieldTestBlocks('field_template', [
{
args: {
value: 0, // default value
},
},
]);
`
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.
The [debug renderer][dev-tools] is a renderer plugin that wraps your normal
renderer, and visualizes the measurements the [render info][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.
`js
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.
`js`
DebugDrawer.config = {
rows: true,
rowSpacers: true,
elems: true,
elemSpacers: true,
connections: true,
blockBounds: true,
connectedBlockBounds: true,
render: true,
};
[render-info]: https://developers.google.com/blocklyguides/create-custom-blocks/appearance/renderers/concepts/info
[dev-tools]: https://www.npmjs.com/package/@blockly/dev-tools
A lightweight workspace console logger.
`js
import {logger} from '@blockly/dev-tools';
logger.enableLogger(workspace);
logger.disableLogger(workspace);
``
The logger is included by default in the playground.
Apache 2.0