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 disukai karena menyederhanakan pelokalan dan lebih mudah dibaca dan ditulis. Namun, format ini tidak dapat digunakan untuk menentukan fitur lanjutan secara langsung seperti mutator atau validator. Fitur 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. Objek ini disimpan 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 dicampur ke dalam objek blok, kata kunci this merujuk ke 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.

Mencampur JSON dan JavaScript

Format JSON terutama mendukung penentuan tampilan dan nuansa blok. Format 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 Anda 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'));
    });
  }
};

API definisi blok

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() {/* ... */},
  // ...
}

Kesalahan umum adalah menganggap 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 dari objek tersebut, 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. Objek 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 akan 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.
  }
};