JSON dan JavaScript

Blockly memiliki dua cara untuk menentukan blok: objek JSON, yang menggunakan key-value pair, dan fungsi JavaScript, yang memanggil API Blockly. Format JSON lebih direkomendasikan karena menyederhanakan lokalisasi dan lebih mudah dibaca serta ditulis. Namun, mutator tidak dapat digunakan untuk menentukan fitur lanjutan seperti pengubah atau validator secara langsung. Fungsi ini harus ditulis dalam JavaScript, biasanya sebagai ekstensi.

Menggunakan JSON atau JavaScript

Blok ini:

Blok `string_length`.

dapat ditentukan dalam JSON atau JavaScript sebagai berikut.

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 mengonversi setiap objek JSON menjadi objek definisi blok dengan fungsi init. Kode ini menyimpan objek ini di 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');
  }
};

Karena objek definisi blok dicampurkan ke dalam objek blok, kata kunci this merujuk pada blok sebenarnya yang sedang dibuat.

Kedua metode tersebut menghasilkan objek definisi blok yang disimpan di Blockly.Blocks dengan kunci nama jenis blok (string_length). Objek definisi blok memiliki satu metode (init), yang menentukan bentuk blok.

Menggabungkan JSON dan JavaScript

Format JSON terutama mendukung penentuan tampilan dan nuansa blok. Fungsi ini tidak dapat menentukan beberapa fitur secara langsung, seperti validator dan mutator, yang mengharuskan Anda menentukan fungsi. Untuk mengatasi masalah ini, tentukan sebanyak mungkin blok dengan JSON, dan gunakan JavaScript untuk sisanya.

Contoh berikut membuat definisi blok dengan fungsi init, yang menggunakan jsonInit untuk memuat objek JSON dan JavaScript API untuk menentukan tooltip dinamis.

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

Block definition API

Bagian ini merangkum objek dan fungsi yang digunakan untuk menentukan blok kustom.

Blockly.Blocks

Blockly.Blocks adalah objek yang menyimpan definisi blok. Kuncinya adalah nama jenis blok dan nilainya adalah objek definisi blok. Gunakan Blockly.Blocks saat menentukan blok dengan JavaScript:

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

Error umum adalah mengasumsikan Blockly.Blocks menyimpan blok dan mencoba sesuatu seperti berikut. Hal ini gagal karena Blockly.Blocks menyimpan definisi blok, bukan blok.

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

defineBlocksWithJsonArray

defineBlocksWithJsonArray menerima array objek JSON, membuat definisi blok darinya, dan menambahkannya ke Blockly.Blocks.

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

createBlockDefinitionsFromJsonArray dan defineBlocks

createBlockDefinitionsFromJsonArray menerima array objek JSON dan menampilkan objek yang memetakan nama jenis blok ke definisi blok. Ini umumnya digunakan dengan defineBlocks, yang menambahkan definisi blok ke Blockly.Blocks.

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

Block.jsonInit

jsonInit menerima objek JSON dan memanggil metode yang sesuai di Block. Misalnya, objek JSON dengan key-value pair colour: 150 menghasilkan panggilan ke this.setColour(150). Gunakan jsonInit dalam fungsi init untuk memuat objek JSON.

var myJson = {
  // ...
};

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