Adicionar blocos personalizados

Embora o Blockly defina vários blocos padrão, a maioria dos aplicativos precisa definir e implementar pelo menos alguns blocos relevantes ao domínio.

Os blocos são compostos por três componentes:

• Objeto de definição de bloco: define a aparência e o comportamento de um bloco, incluindo texto, cor, campos e conexões.
• Referência da caixa de ferramentas: uma referência ao tipo de bloco no XML da caixa de ferramentas para que os usuários possam adicioná-lo ao espaço de trabalho.
• Função de gerador: gera a string de código para este bloco. Ele é sempre escrito em JavaScript, mesmo que a linguagem de destino não seja JavaScript.

Definição do bloco

O Blockly para Web carrega Blocks por arquivos de script. O diretório blocks/ inclui vários exemplos desse tipo para os blocos padrão. Supondo que seus blocos não se encaixem nas categorias atuais, crie um novo arquivo JavaScript. Esse novo arquivo JavaScript precisa ser incluído na lista de tags <script ...> no arquivo HTML do editor.

Observação: a maior parte de um bloco pode ser definida usando as Ferramentas para desenvolvedores do Blockly, em vez de criar manualmente o código abaixo.

Uma definição de bloco típica é semelhante a esta:

JSON

Blockly.Blocks['string_length'] = {
  init: function() {
    this.jsonInit({
      "message0": 'length of %1',
      "args0": [
        {
          "type": "input_value",
          "name": "VALUE",
          "check": "String"
        }
      ],
      "output": "Number",
      "colour": 160,
      "tooltip": "Returns number of letters in the provided text.",
      "helpUrl": "http://www.w3schools.com/jsref/jsref_length_string.asp"
    });
  }
};

JavaScript

Blockly.Blocks['string_length'] = {
  init: function() {
    this.appendValueInput('VALUE')
        .setCheck('String')
        .appendField('length of');
    this.setOutput(true, 'Number');
    this.setColour(160);
    this.setTooltip('Returns number of letters in the provided text.');
    this.setHelpUrl('http://www.w3schools.com/jsref/jsref_length_string.asp');
  }
};

• string_length: é o nome do tipo do bloco. Como todos os blocos compartilham o mesmo namespace, é recomendável usar um nome composto pela sua categoria (neste caso, string) seguido pela função do bloco (neste caso, length).

• init: essa função define a aparência do bloco.

Isso define o seguinte bloco:

Os detalhes das definições de bloco podem ser encontrados em Definir blocos.

Matriz JSON

Vários blocos podem ser definidos de uma vez usando uma matriz de definições de bloco JSON.

JSON

Blockly.defineBlocksWithJsonArray([
  // Block for colour picker.
  {
    "type": "colour_picker",
    "message0": "%1",
    "args0": [
      {
        "type": "field_colour",
        "name": "COLOUR",
        "colour": "#ff0000"
      }
    ],
    "output": "Colour",
    "helpUrl": "%{BKY_COLOUR_PICKER_HELPURL}",
    "style": "colour_blocks",
    "tooltip": "%{BKY_COLOUR_PICKER_TOOLTIP}",
    "extensions": ["parent_tooltip_when_inline"]
  },
  // Block for random colour.
  {
    "type": "colour_random",
    "message0": "%{BKY_COLOUR_RANDOM_TITLE}",
    "output": "Colour",
    "helpUrl": "%{BKY_COLOUR_RANDOM_HELPURL}",
    "style": "colour_blocks",
    "tooltip": "%{BKY_COLOUR_RANDOM_TOOLTIP}"
  }
]);

Adicionar referência de caixa de ferramentas

Depois de definido, use o nome do tipo para fazer referência ao bloco à caixa de ferramentas:

<xml id="toolbox" style="display: none">
  <category name="Text">
    <block type="string_length"></block>
  </category>
  ...
</xml>

Consulte o guia Caixa de ferramentas para mais detalhes.

Adicionar gerador de código de bloco

Por fim, para transformar o bloco em código, faça o pareamento com uma função geradora. Os geradores são específicos para o idioma de saída pretendido, mas os geradores padrão geralmente têm o seguinte formato:

javascriptGenerator.forBlock['text_length'] = function(block, generator) {
  // String or array length.
  var argument0 = generator.valueToCode(block, 'VALUE', Order.FUNCTION_CALL) || '\'\'';
  return [argument0 + '.length', Order.MEMBER];
};

A função do gerador usa uma referência ao bloco para processamento. Ela renderiza as entradas (a entrada VALUE acima) em strings de código e, em seguida, concatena-as em uma expressão maior.

→ Mais informações sobre geradores de código de bloqueio...