JSON e JavaScript

Blockly ha due modi per definire i blocchi: oggetti JSON, che utilizzano coppie chiave-valore, e funzioni JavaScript, che chiamano l'API di Blockly. Il formato JSON è preferibile perché semplifica la localizzazione ed è più facile da leggere e scrivere. Tuttavia, non può essere utilizzato per definire direttamente funzionalità avanzate come mutatori o validatori. Questi devono essere scritti in JavaScript, di solito come estensioni.

Utilizzare JSON o JavaScript

Questo blocco:

Un blocco `string_length`.

può essere definito in JSON o JavaScript come segue.

JSON

Blockly.common.defineBlocksWithJsonArray([{
  "type": "string_length",
  "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"
}]);

defineBlocksWithJsonArray converte ogni oggetto JSON in un oggetto di definizione del blocco con una funzione init. Questi oggetti vengono memorizzati in Blockly.Blocks.

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');
  }
};

Poiché gli oggetti di definizione dei blocchi vengono combinati con gli oggetti dei blocchi, la parola chiave this si riferisce al blocco effettivo in fase di creazione.

Entrambi i metodi comportano la memorizzazione di un oggetto di definizione del blocco in Blockly.Blocks con una chiave del nome del tipo di blocco (string_length). L'oggetto di definizione del blocco ha un singolo metodo (init), che definisce la forma del blocco.

Combinare JSON e JavaScript

Il formato JSON supporta principalmente la definizione dell'aspetto di un blocco. Non può definire direttamente alcune funzionalità, come i validatori e i mutatori, che richiedono la definizione di una funzione. Per risolvere questo problema, definisci il maggior numero possibile di blocchi con JSON e utilizza JavaScript per il resto.

L'esempio seguente crea una definizione di blocco con una funzione init, che utilizza jsonInit per caricare un oggetto JSON e l'API JavaScript per definire un suggerimento dinamico.

JavaScript

// Define the block structure in JSON.
var mathChangeJson = {
  "message0": "change %1 by %2",
  "args0": [
    {"type": "field_variable", "name": "VAR", "variable": "item", "variableTypes": [""]},
    {"type": "input_value", "name": "DELTA", "check": "Number"}
  ],
  "previousStatement": null,
  "nextStatement": null,
  "colour": 230
};

Blockly.Blocks['math_change'] = {
  init: function() {
    // Use jsonInit to load the JSON block structure.
    this.jsonInit(mathChangeJson);

    // Use JavaScript to define a tooltip function.
    // Assign 'this' to a variable for use in the tooltip closure below.
    var thisBlock = this;
    this.setTooltip(function() {
      return 'Add a number to variable "%1".'.replace('%1',
          thisBlock.getFieldValue('VAR'));
    });
  }
};

API di definizione dei blocchi

Questa sezione riassume gli oggetti e le funzioni utilizzati per definire i blocchi personalizzati.

Blockly.Blocks

Blockly.Blocks è un oggetto che memorizza le definizioni dei blocchi. Le chiavi sono i nomi dei tipi di blocchi e i valori sono gli oggetti di definizione dei blocchi. Utilizza Blockly.Blocks quando definisci i blocchi con JavaScript:

Blockly.Blocks['my_block'] = {
  init: function() {/* ... */},
  onchange: function() {/* ... */},
  // ...
}

Un errore comune è presupporre che Blockly.Blocks memorizzi i blocchi e provare a eseguire un'operazione simile alla seguente. Questa operazione non riesce perché Blockly.Blocks memorizza le definizioni dei blocchi, non i blocchi.

// Fails with "Blockly.Blocks.my_block.setColour is not a function".
Blockly.Blocks['my_block'].setColour(150);

defineBlocksWithJsonArray

defineBlocksWithJsonArray accetta un array di oggetti JSON, crea definizioni di blocchi da questi e le aggiunge a Blockly.Blocks.

Blockly.common.defineBlocksWithJsonArray([
  {
    type: 'my_block1',
    // ...
  }
  {
    type: 'my_block3',
    // ...
  }
  {
    type: 'my_block2',
    // ...
  }
]);

createBlockDefinitionsFromJsonArray e defineBlocks

createBlockDefinitionsFromJsonArray accetta un array di oggetti JSON e restituisce un oggetto che mappa i nomi dei tipi di blocchi alle definizioni dei blocchi. In genere viene utilizzato con defineBlocks, che aggiunge le definizioni dei blocchi a Blockly.Blocks.

const myBlockDefinitions = Blockly.common.createBlockDefinitionsFromJsonArray([
  {
    type: 'my_block1',
    // ...
  }
  {
    type: 'my_block3',
    // ...
  }
  {
    type: 'my_block2',
    // ...
  }
]);
Blockly.common.defineBlocks(myBlockDefinitions);

Block.jsonInit

jsonInit accetta un oggetto JSON e chiama i metodi corrispondenti su Block. Ad esempio, un oggetto JSON con la coppia chiave-valore colour: 150 genera una chiamata a this.setColour(150). Utilizza jsonInit in una funzione init per caricare un oggetto JSON.

var myJson = {
  // ...
};

Blockly.Blocks['my_block'] = {
  init: function() {
    this.jsonInit(myJson);
    // The rest of the init function.
  }
};