JSON ve JavaScript

Blockly'da blokları tanımlamanın iki yolu vardır: anahtar/değer çiftlerini kullanan JSON nesneleri ve Blockly'nin API'sini çağıran JavaScript işlevleri. JSON biçimi, yerelleştirmeyi basitleştirdiği ve okunup yazılması daha kolay olduğu için tercih edilir. Ancak, değiştiriciler veya doğrulayıcılar gibi ileri seviye özellikleri doğrudan tanımlamak için kullanılamaz. Bunlar JavaScript'te yazılmalıdır ve genellikle uzantı olarak kullanılır.

JSON veya JavaScript kullanma

Bu blok:

Bir `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şlevine sahip bir 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 nesneleriyle karıştırıldığından this anahtar kelimesi, oluşturulan gerçek bloğu ifade eder.

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

JSON ve JavaScript'i karıştırma

JSON biçimi, öncelikle bir bloğun görünümünü ve tarzını tanımlamayı destekler. Bir işlev tanımlamanızı gerektiren doğrulayıcılar ve değiştiriciler gibi bazı özellikleri doğrudan tanımlayamaz. Bu sorunu çözmek için bloğunuzun mümkün olduğunca büyük bir kısmını JSON ile tanımlayın ve geri kalanını JavaScript ile tanımlayın.

Aşağıdaki örnekte, init işleviyle bir blok tanımı oluşturulur. Bu işlev, jsonInit kullanarak bir JSON nesnesi yükler ve JavaScript API'si kullanarak dinamik bir ipucu tanımlar.

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 özetlenmektedir.

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 blok tanımlarken Blockly.Blocks kullanın:

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

Sık yapılan bir hata, Blockly.Blocks mağazalarının engellediğini varsaymak ve aşağıdakine benzer bir şey denemektir. Blockly.Blocks depoları blokları değil, blok tanımlarını depoladığından bu işlem başarısız olur.

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

defineBlocksWithJsonArray

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

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

createBlockDefinitionsFromJsonArray ve defineBlocks

createBlockDefinitionsFromJsonArray JSON nesneleri dizisini kabul eder ve blok türü adlarını blok tanımlarına eşleyen bir nesne döndürür. Bu işlev genellikle defineBlocks ile birlikte kullanılır. defineBlocks, blok tanımlarını Blockly.Blocks öğesine ekler.

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, anahtar/değer çiftine sahip bir JSON nesnesi colour: 150, this.setColour(150) çağrısına neden olur. JSON nesnesi yüklemek için jsonInit işlevinde init kullanın.

var myJson = {
  // ...
};

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