JSON ve JavaScript

Blockly'de blokları tanımlamanın iki yolu vardır: anahtar/değer çiftleri kullanan JSON nesneleri ve Blockly'nin API'sini çağıran JavaScript işlevleri. JSON biçimi, yerelleştirmeyi basitleştirdiği ve okuma ve yazma işlemini kolaylaştırdığı için tercih edilir. Ancak, değiştirici veya doğrulayıcı gibi gelişmiş özellikleri doğrudan tanımlamak için kullanılamaz. Bunlar JavaScript'te yazılmalı ve genellikle uzantı olarak kullanılmalıdır.

JSON veya JavaScript kullanma

Bu blok:

"string_length" bloğu.

JSON veya JavaScript'te aşağıdaki gibi tanımlanabilir.

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, her JSON nesnesini init işleviyle blok tanımı nesnesine dönüştürür. Bu nesneleri Blockly.Blocks içinde depolar.

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

Blok tanımı nesneleri, blok nesnelerine karıştırıldığı için this anahtar kelimesi, oluşturulmakta olan gerçek bloğu ifade eder.

Her iki yöntem de, blok türü adının (string_length) anahtarıyla Blockly.Blocks içinde bir blok tanımı nesnesi depolanmasıyla sonuçlanır. Blok tanımı nesnesi, bloğun şeklini tanımlayan tek bir yönteme (init) sahiptir.

JSON ve JavaScript'i bir arada kullanma

JSON biçimi, temel olarak bir bloğun görünümünü ve tarzını tanımlamayı destekler. Doğrulayıcılar ve değiştiriciler gibi bazı özellikleri doğrudan tanımlayamaz. Bu özellikler için bir işlev tanımlamanız gerekir. Bu sorunu çözmek için bloğunuzun mümkün olduğunca fazlasını JSON ile tanımlayın ve geri kalanı için JavaScript kullanın.

Aşağıdaki örnekte, JSON nesnesi yüklemek için jsonInit'ı ve dinamik bir ipucu tanımlamak için JavaScript API'yi kullanan bir init işlevi içeren bir blok tanımı oluşturulmaktadır.

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

Blok tanımı API'si

Bu bölümde, özel blokları tanımlamak için kullanılan nesneler ve işlevler özetlenmiştir.

Blockly.Blocks

Blockly.Blocks, blok tanımlarını depolayan bir nesnedir. Anahtarları blok türü adları, değerleri ise blok tanımı nesneleridir. JavaScript ile blokları tanımlarken Blockly.Blocks kullanın:

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

Sık yapılan bir hata, Blockly.Blocks'ün blokları depoladığını varsaymak ve aşağıdaki gibi bir şey denemektir. Bu işlem, Blockly.Blocks blokları değil, blok tanımlarını depoladığı için başarısız olur.

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

defineBlocksWithJsonArray

defineBlocksWithJsonArray, bir JSON nesnesi dizisini kabul eder, bunlardan blok tanımları oluşturur ve bunları Blockly.Blocks'a ekler.

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

createBlockDefinitionsFromJsonArray ve defineBlocks

createBlockDefinitionsFromJsonArray, bir JSON nesnesi dizisini kabul eder ve blok türü adlarını blok tanımlarıyla eşleyen bir nesne döndürür. Bu, genellikle blok tanımlarını Blockly.Blocks'a ekleyen defineBlocks ile birlikte kullanılır.

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

Block.jsonInit

jsonInit, bir JSON nesnesini kabul eder ve Block üzerinde ilgili yöntemleri çağırır. Örneğin, colour: 150 anahtar/değer çiftine sahip bir JSON nesnesi, this.setColour(150) çağrısına neden olur. JSON nesnesi yüklemek için init işlevinde jsonInit kullanın.

var myJson = {
  // ...
};

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