Toolbox

The toolbox is the side menu from whence the user may create new blocks.
The structure of the toolbox is specified with XML, which may be either a tree
of nodes, or a string representation. This XML is passed to Blockly when it is
injected into the page. If you don't like typing XML manually, we recommend that
you check out Blockly Developer Tools. With it, you can
construct a toolbox and automatically generate its toolbox XML using a visual
interface.

If there are a small number of blocks, then they may be displayed without any
categories (as in the minimal example above). In this simple mode all the
available blocks are shown in the toolbox, there are no scrollbars on the main
workspace, and the trashcan is not needed.

Categories

The blocks in the toolbox may be organized in categories. Here are two
categories ('Control' and 'Logic'), each of which contain three blocks:

Below is the resulting toolbox, with the 'Logic' category clicked so that the
three logic blocks in the flyout may be seen:

The presence of categories changes Blockly's UI to support larger applications.
Scrollbars appear, allowing for an infinitely large workspace. A trashcan
appears. Context menus contain more advanced options such as adding comments or
collapsing blocks. All of these features may be overridden using the
configuration options.

Each category can be assigned a colour using the optional colour attribute.
Note the British spelling. The colour is a number (0-360) defining the hue.

This colour appears as a rectangle to the left of the category, and as
highlighting for the currently selected category:

Dynamic categories

There are two categories that have special behaviours. Variable and function
categories are defined with no contents, but with a 'custom' property of
'VARIABLE' or 'PROCEDURE' respectively. These categories will be populated
automatically with the appropriate blocks.

The XML for these customized blocks or groups is the same as Blockly's XML save
format. Thus, the easiest way to construct the XML for such blocks is to use the
Code application
to build the blocks, then switch to the XML tab and copy the result. The x,
y, and id properties are ignored by the toolbox and may be stripped out.

Shadow blocks

Shadow blocks are placeholder blocks that perform several functions:

They indicate the default values for their parent block.

They allow users to type values directly without needing to fetch a number or string block.

Unlike a regular block, they get replaced if the user drops a block on top of them.

They inform the user of the type of value expected.

Shadow blocks cannot be constructed with the Code application directly. Instead
one can use regular blocks, then change <block ...> and </block> in the XML
to <shadow ...> and </shadow>.

Note: Shadow blocks may not include a variable field or have children that are
not also shadows.

Separators

Adding a <sep></sep> tag between any two categories will create a separator.

By default every block is separated from its lower neighbour by 24 pixels.
This separation may be changed using the 'gap' attribute, which will replace the default gap.

Disabling blocks may be used to restrict the user's choices. Perhaps advanced
blocks might be unlocked after certain achievements.

Changing the Toolbox

The application may change the blocks available in the toolbox at any time with
a single function call:

workspace.updateToolbox(newTree);

As was the case during initial configuration, newTree may either be a tree of
nodes, or a string representation. The only restriction is that the mode cannot
be changed; that is if there were categories in the initially-defined toolbox
then the new toolbox must also have categories (though the categories may change).
Likewise, if the initially-defined toolbox did not have any categories, then the
new toolbox may not have any categories.

Be aware that at this time updating the toolbar causes some minor UI resets:

In a toolbox with categories, the flyout will close if it was open.

In a toolbox without categories, any fields changed by the user (such as a dropdown) will revert to the default.

Any toolbox so long that it extends beyond the page will have its scrollbar jump to the top.