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. 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. This XML asset path is passed to the BlocklyController when it is constructed. If your activity extends AbstractBlocklyActivity, this is done automatically using the asset path returned by getToolboxContentsXmlPath():

@Override
protected String getToolboxContentsXmlPath() {
    return "default/toolbox.xml";
}

Here is a minimal example, using a tree of nodes:

<toolbox>
  <block type="controls_if"></block>
  <block type="controls_whileUntil"></block>
</toolbox>

This toolbox loads these blocks:

Example of a toolbox without categories.

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.

Categories

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

<toolbox>
  <category name="Control">
    <block type="controls_if"></block>
    <block type="controls_whileUntil"></block>
    <block type="controls_for"></block>
  </category>
  <category name="Logic">
    <block type="logic_compare"></block>
    <block type="logic_operation"></block>
    <block type="logic_boolean"></block>
  </category>
</toolbox>

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

Example of toolbox categories with one tab open.

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.

<toolbox>
  <category name="Logic" colour="210">...</category>
  <category name="Loops" colour="120">...</category>
  <category name="Math" colour="230">...</category>
  <category name="Colour" colour="20">...</category>
</toolbox>

This colour appears as a tint on the background behind the blocks.

Examples of the category colors in various tabs.

Tab coloration is pending (issue #296).

Block Groups

The XML may contain customized blocks, or groups of blocks. Here are four blocks:

  1. A simple logic_boolean block:
    A block for klzzwxh:0021.
  2. A math_number block that has been modified to display the number 42 instead of the default of 0:
    A block for the number klzzwxh:0025.
  3. A controls_for block that has three math_number blocks connected to it:
    A for loop block with three inline numbers.
  4. A math_arithmetic block that has two math_number shadow blocks connected to it:
    An addition block using shadow number blocks.

Here is the code to generate these four blocks in a toolbox:

<toolbox>
  <block type="logic_boolean"></block>

  <block type="math_number">
    <field name="NUM">42</field>
  </block>

  <block type="controls_for">
    <value name="FROM">
      <block type="math_number">
        <field name="NUM">1</field>
      </block>
    </value>
    <value name="TO">
      <block type="math_number">
        <field name="NUM">10</field>
      </block>
    </value>
    <value name="BY">
      <block type="math_number">
        <field name="NUM">1</field>
      </block>
    </value>
  </block>

  <block type="math_arithmetic">
    <field name="OP">ADD</field>
    <value name="A">
      <shadow type="math_number">
        <field name="NUM">1</field>
      </shadow>
    </value>
    <value name="B">
      <shadow type="math_number">
        <field name="NUM">1</field>
      </shadow>
    </value>
  </block>
</toolbox>

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 are placeholder blocks that perform several functions:

  • They indicate the default values for thier 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>.

Changing the Toolbox

The applications based on AbstractBlocklyActivity may change the blocks available in the toolbox at any time by calling this.reloadToolbox(). This will trigger a new call to getToolboxContentsXmlPath(), where the application can return a new value.