Porting an exercise to Blockly - BuggleInc/PLM GitHub Wiki

The webPLM supports Blockly, the visual programming language. Programs are built through the assembly of blocks, which makes syntax errors impossible.

Currently, the environment supports that programming language, but only very few exercises were ported to that mechanism. Any pull requests to port more exercises to Blocky would be very welcome.

Three steps are needed to get Blockly to work:

Add the Blockly entity

As for other languages, we need first to add a new entity for the Blockly language.

  • In the PLM sources, find the folder containing the exercise you are working on. Here for example
  • Then copy /path/to/exercise/<yourexercise>Entity.py to /path/to/exercise/<yourexercise>Entity.blockly
  • You will then need to add a toolbox for this exercise.

Create an exercise's toolbox

For each exercise, a toolbox is used to specify the set of blocks the user can use to solve it.

A toolbox's template

A toolbox defined a list of categories, each categories being named and including a list of blocks. The file is formatted in JSON. Here is an example:

[
    {
        "name": "Buggle",
        "blocks": [
            {
                "type": "buggle_facingWall"
            }
        ]
    },
    {
        "name": "Logic",
        "blocks": [
            {
                "type": "controls_if"
            },
            {
                "type": "newlogic_operation"
            },
            {
                "type": "logic_negate"
            }
        ]
    },
    {
        "name": "Loops",
        "blocks": [
            {
                "type": "controls_whileUntil"
            }
        ]
    },
    {
        "name": "Move",
        "blocks": [
            {
                "type": "move_forward"
            },
            {
                "type": "move_backward"
            },
            {
                "type": "turn_right"
            },
            {
                "type": "turn_left"
            },
            {
                "type": "turn_back"
            }
        ]
    },
    {
        "name": "World",
        "blocks": [
            {
                "type": "world_baggle_ground"
            },
            {
                "type": "world_baggle_pickup"
            },
            {
                "type": "world_baggle_drop"
            }
        ]
    }
]

Where to place the toolbox file?

Once you write the toolbox file, you have to place it in the PLM sources, in exercise's Blockly entity's folder.

Create a new block

A block is composed from two parts:

  • Its looks: its color, shape and how it can be linked to others blocks.
  • The code it will generate when used.

When adding a new block, these two parts need to be specified.

Generate the code

First you need to generate the block's code. For example, here is the block forward's code:

  • Its looks:
Blockly.Blocks['move_forward'] = {
    init: function () {
        this.setColour(30);
        this.appendDummyInput()
            .appendField(Blockly.Msg.MOVE_FORWARD_TITLE);
        this.setPreviousStatement(true);
        this.setNextStatement(true);
        this.setTooltip(Blockly.Msg.MOVE_FORWARD_TOOLTIP);
    }
};
  • The code it generates:
Blockly.Python['move_forward'] = function (block) {
    var code = 'forward()\n';
    return code;
};

In order to generate these chunks of code, you can first use the block factory provided by Blockly. If you have grasped Blockly's structure, you can also try to write it manually.

Where to place the block's code

Once you got the code corresponding to the block you want to add to the webPLM, you need to add it.

  • First, add the code corresponding to the block's looks into a existing file in the /public/javascripts/blockly/blocks folder or into a new one.
  • Then add the code generator into the according file in the /public/javascripts/blockly/generators/python folder.
  • If you have created new files for your block, you need to add them both in /app/views/index.scala.html here.