Menambahkan kolom plugin ke Block Factory

Blockly Developer Tools memungkinkan Anda membuat blok kustom menggunakan blok. Alat ini mendukung kolom yang dipublikasikan sebagai plugin selain kolom yang disertakan dengan Core Blockly. Jika telah membuat kolom kustom, Anda dapat menambahkan dukungannya ke Block Factory dengan mengikuti panduan ini. Kolom kustom harus dipublikasikan di npm sebelum Anda dapat menambahkan dukungan untuknya. Anda juga harus berkomitmen untuk memperbarui kolom agar tetap dapat mengikuti perubahan di Blockly. Jika tidak, kami mungkin harus menghapusnya dari Block Factory pada masa mendatang.

Pengembangan di Block Factory

Kode sumber untuk Block Factory terletak di repositori blockly-samples dalam direktori examples/developer-tools.

Untuk mengirimkan perubahan ke Developer Tools dalam contoh blockly, Anda harus mengikuti langkah-langkah umum untuk melakukan pengembangan dalam contoh blockly. Namun, tidak seperti bekerja dengan plugin, Anda harus menjalankan npm install dari direktori examples/developer-tools secara langsung, bukan di level root blockly-samples.

Menginstal plugin

Agar Block Factory menampilkan kolom kustom dalam pratinjau, kolom kustom tersebut harus diinstal. Tambahkan kolom Anda sebagai dependensi npm dari alat developer. Kemudian, daftarkan atau lakukan penyiapan lain yang diperlukan di developer-tools/src/blocks/index.ts.

Membuat blok untuk kolom

Karena Block Factory menggunakan blok untuk membuat blok kustom, Anda memerlukan blok yang mewakili kolom kustom.

Membuat definisi blok

Anda harus mendesain blok untuk kolom Anda; jika ingin mendapatkan meta, Anda bahkan dapat mendesainnya menggunakan Block Factory. Blok tersebut harus memungkinkan pengguna mengonfigurasi penyiapan yang diperlukan oleh kolom Anda, seperti nilai default dan nama. Tambahkan definisi blok ini ke developer-tools/src/blocks/fields.ts, lalu impor di developer-tools/src/blocks/index.ts.

Tambahkan blok ke toolbox

Selanjutnya, Anda perlu menambahkan blok ini ke definisi toolbox agar dapat diakses oleh pengguna. Definisi toolbox terletak di developer-tools/src/toolbox.ts. Blok Anda harus ditambahkan ke kategori "Kolom".

Generator Kode

Block Factory bekerja menggunakan sistem Generator Kode yang sudah Anda pahami dari Blockly. Setiap blok memiliki generator kode blok untuk setiap jenis output yang dihasilkan oleh Block Factory, dan blok induk menyusun kode untuk blok turunan menjadi output yang benar. Untuk menambahkan dukungan kolom kustom, Anda harus menambahkan fungsi generator kode blok untuk setiap class Generator Kode.

Buat file untuk blok kolom Anda di direktori output-generators/fields. Anda akan menambahkan generator kode blok untuk setiap Generator berikut ke file ini. Impor file ini dalam file blocks/index.ts sehingga fungsi generator kode blok dimuat ke dalam aplikasi.

Definisi JavaScript

javascriptDefinitionGenerator membuat kode yang akan disertakan dalam definisi JavaScript untuk blok yang menyertakan kolom kustom Anda. Biasanya, ini berarti generator kode blok harus menampilkan baris kode yang terlihat seperti .appendField(new YourFieldConstructor(arg1, arg2), 'userSpecifiedName'). Perhatikan bahwa baris kode ini tidak menyertakan titik koma, karena input yang berisi beberapa kolom akan memiliki beberapa panggilan ke appendField yang dirantai bersama. Argumen dalam konstruktor diambil dari nilai yang ditetapkan pengguna pada blok kolom. Berikut adalah contoh generator kode blok untuk FieldAngle:

javascriptDefinitionGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: JavascriptDefinitionGenerator,
): string {
  const name = generator.quote_(block.getFieldValue('FIELDNAME'));
  const angle = block.getFieldValue('ANGLE');
  return `.appendField(new FieldAngle(${angle}), ${name})`;
};

Blok sudut yang ditarik pengguna dari kategori "Kolom" pada kotak alat Block Factory memiliki dua kolom:

• FIELDNAME: pengguna dapat menetapkan nama kolom pada elemen penyusun kustomnya
• ANGLE: pengguna dapat menetapkan nilai sudut default

Pada generator kode blok ini, kita mendapatkan nilai sudut default dan meneruskannya sebagai satu-satunya argumen ke konstruktor FieldAngle. Nama kolom selalu diteruskan sebagai argumen kedua ke appendField.

Catatan: Untuk tempat yang memerlukan tanda kutip pada nilai kolom, seperti saat meneruskan nama kolom ke appendField, Anda harus menggunakan generator.quote_, bukan menggabungkan tanda kutip secara manual.

Definisi JSON

jsonDefinitionGenerator serupa, tetapi menghasilkan bagian dari definisi blok JSON yang sesuai dengan kolom Anda. Biasanya, kode ini berupa objek JSON yang mencakup:

• type: sesuai dengan nama kolom Anda di registry lapangan Blockly
• name: pengguna dapat menetapkan nama kolom pada elemen penyusun kustomnya
• properti kustom lainnya yang diperlukan oleh metode inisialisasi json kolom Anda.

Berikut contoh dari FieldAngle lagi:

jsonDefinitionGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: JsonDefinitionGenerator,
): string {
  const code = {
    type: 'field_angle',
    name: block.getFieldValue('FIELDNAME'),
    angle: block.getFieldValue('ANGLE'),
  };
  return JSON.stringify(code);
};

Catatan: Generator kode blok selalu menampilkan string, jadi buat string objek sebelum menampilkannya.

Header kode

Generator Header Kode membuat output Header Kode yang ditampilkan di Block Factory. Output ini dapat dialihkan antara impor esmodule dan tag skrip, bergantung pada cara pengguna ingin memuat kode, sehingga sebenarnya ada dua instance generator yang berbeda: satu untuk setiap kasus. Anda perlu menambahkan generator kode blok untuk setiap kode tersebut. Berikut adalah contoh untuk FieldAngle:

importHeaderGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: CodeHeaderGenerator,
): string {
  generator.addHeaderLine(
    `import {registerFieldAngle, FieldAngle} from '@blockly/field-angle';`,
  );
  generator.addHeaderLine(`registerFieldAngle();`);
  return '';
};

scriptHeaderGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: CodeHeaderGenerator,
): string {
  generator.addHeaderLine(
    `<script src="https://unpkg.com/@blockly/field-angle"></script>`,
  );
  generator.addHeaderLine(`registerFieldAngle();`);
  return '';
};

Generator ini memiliki metode yang disebut addHeaderLine yang memungkinkan Anda menentukan baris kode yang harus dipanggil sebelum kolom Anda digunakan dalam kode. Umumnya, hal ini mencakup pekerjaan seperti mengimpor kolom atau memuatnya melalui tag skrip, dan mungkin memanggil fungsi yang akan mendaftarkan kolom tersebut ke registry kolom Blockly.

Tips: Jika paket Anda dipublikasikan di npm, paket tersebut akan otomatis tersedia di unpkg, yang merupakan tempat praktis untuk memuat tag skrip.

Untuk dua generator kode blok ini, semua kode harus ditambahkan melalui panggilan ke addHeaderLine. Fungsi ini akan memastikan setiap baris header hanya ditampilkan satu kali, meskipun blok kolom kustom Anda digunakan beberapa kali dalam satu blok kustom. Generator kode blok harus menampilkan string kosong.

Potongan generator

Terakhir, kita memiliki generator yang membuat stub generator untuk kolom tersebut. Dalam generator kode blok ini, Anda akan menulis kode yang menghasilkan kode yang membantu pengguna menulis kode yang menghasilkan kode. Apakah Anda merasa bingung? Ini lebih mudah dari kedengarannya!

Potongan generator untuk blok kustom mencakup variabel siap pakai yang mewakili setiap kolom di blok. Lalu, ada TODO yang harus diselesaikan pengguna untuk menyusun semua variabel ini ke dalam string kode akhir yang akan ditampilkan oleh blok kustom mereka. Artinya, biasanya semua yang perlu dilakukan generator kode blok Anda adalah menampilkan baris yang membuat variabel kustom ini. Misalnya, pengguna membuat blok kustom yang akan menambahkan sinar matahari ke kanvasnya. Dia menambahkan kolom sudut ke blok dan menamainya "SUN_DIRECTION". Stub generator untuk blok ini akan menyertakan baris const angle_sun_direction = block.getFieldValue("SUN_DIRECTION");. Itulah baris kode generator kode blok kita untuk kolom sudut yang harus ditampilkan:

generatorStubGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: GeneratorStubGenerator,
): string {
  const name = block.getFieldValue('FIELDNAME');
  const fieldVar = generator.createVariableName('angle', name);
  return `const ${fieldVar} = block.getFieldValue(${generator.quote_(
    name,
  )});\n`;
};

Untuk mendapatkan nama variabel yang distandardisasi, Anda dapat memanggil generator.createVariableName dan meneruskan jenis kolom Anda (seperti angle, number, dll.) beserta nama pengguna untuk kolomnya.

Melakukan pengujian

Setelah menulis semua bagian ini, Anda akan dapat memulai Block Factory dengan menjalankan npm start di direktori blockly-samples/examples/developer-tools. Anda harus dapat menarik blok dari kategori kolom, menambahkannya ke input pada blok, dan melihat perubahan outputnya. Pastikan pratinjau blok sudah benar, dan kode untuk setiap bagian output sudah benar.