Mengupgrade kolom kustom

Pada Juli 2019 (rilis 2.20190722), API kolom yang lebih terstruktur ditambahkan. Tujuannya adalah agar kompatibel dengan versi sebelumnya sebisa mungkin. Artinya, jika Anda telah membuat kolom kustom sebelum Juli 2019, kolom tersebut kemungkinan besar akan terus berfungsi. Sebelum memutuskan apakah kolom kustom Anda perlu diupgrade, Anda harus membaca bagian Area berbahaya dan menguji kolom Anda secara menyeluruh.

Karena kurangnya standarisasi antar-kolom sebelum Juli 2019, sulit untuk mencakup semua perubahan yang mungkin perlu dilakukan developer. Dokumen ini mencoba mencakup semua kemungkinan perubahan, tetapi jika dokumen ini tidak mencakup sesuatu yang Anda minati, baca bagian tentang mendapatkan bantuan upgrade.

Catatan: Jika Anda memiliki sejumlah kecil kolom kustom, mungkin lebih mudah untuk menulis ulang kolom tersebut menggunakan petunjuk pembuatan kolom kustom, daripada mencoba mengupgradenya secara bertahap.

Area berbahaya

Area berbahaya adalah tempat yang diketahui di mana API telah berubah, dan kolom Anda mungkin rusak.

Blockly.Field.register

Kolom tidak lagi didaftarkan melalui Blockly.Field.register();. Sekarang ada namespace fieldRegistry yang menangani pendaftaran.

Blockly.Field.register('my_field_name', myFieldClass);

Menjadi:

Blockly.fieldRegistry.register('my_field_name', myFieldClass);

setText

Fungsi setText tidak lagi dipanggil oleh inti Blockly, jadi jika fungsi setText Anda berisi logika, fungsi tersebut harus dipindahkan ke rangkaian fungsi penanganan nilai, fungsi getText, dan fungsi rendering (bergantung pada apa yang dilakukan fungsi setText Anda).

CustomFields.UpgradeField.prototype.setText = function(newText) {
  // Do validation.
  if (typeof newText != 'string' || newText === this.text_) {
    return;
  }

  // Fire event.
  if (this.sourceBlock_ && Blockly.Events.isEnabled()) {
    Blockly.events.fire(new Blockly.Events.BlockChange(
        this.sourceBlock_, 'field', this.name, this.text_, newText
    ));
  }

  // Update text value.
  this.text_ = 'prefix' + newText;

  // Rerender.
  this.size_.width = 0;
};

Menjadi:

CustomFields.UpgradeField.prototype.doClassValidation_ = function(newValue) {
  if (typeof newValue != 'string') {
    return null;
  }
  return newValue;
};

CustomFields.UpgradeField.prototype.getText = function() {
  return  'prefix' + this.value_;
}

Blockly secara otomatis menangani:

• Memeriksa apakah nilai baru berbeda dengan nilai lama.
• Memperbarui nilai.
• Memicu peristiwa perubahan.
• Merender ulang kolom.

Anda harus menangani:

• Validasi nilai (doClassValidation_).
• Teks kolom (getText).
• UI kolom

Catatan: Sebaiknya ubah semua panggilan setText menjadi panggilan setValue, karena setValue mendukung validasi dan setText tidak.

Upgrade yang direkomendasikan

Upgrade yang direkomendasikan adalah tempat di mana API kolom telah diubah, tetapi jika Anda memilih untuk tidak melakukan perubahan, kolom Anda kemungkinan besar akan tetap berfungsi.

SERIALIZABLE

Untuk mengetahui informasi selengkapnya tentang properti EDITABLE dan SERIALIZABLE, lihat Properti yang dapat diedit dan diserialisasi.

CustomFields.UpgradeField.prototype.SERIALIZABLE = true;

Peringatan di bawah dapat diabaikan, tetapi Anda dapat menyelesaikannya dengan menentukan properti SERIALIZABLE:

Detected an editable field that was not serializable. Please define
SERIALIZABLE property as true on all editable custom fields. Proceeding
with serialization.

Peringatan di atas berarti Blockly yakin bahwa Anda ingin kolom diserialisasi (karena properti EDITABLE bernilai benar), tetapi tidak dapat memastikannya hingga Anda menentukan properti SERIALIZABLE. Jika Anda memilih untuk membiarkannya, semuanya akan berfungsi dengan baik, dan kolom Anda akan diserialisasi, tetapi Anda akan menerima peringatan konsol.

size_.width

this.size_.width = 0;

Menjadi:

this.isDirty_ = true;

Peringatan di bawah dapat diabaikan, tetapi Anda dapat menyelesaikannya dengan menetapkan properti isDirty_ alih-alih properti size_.width:

Deprecated use of setting size_.width to 0 to rerender a field. Set
field.isDirty_ to true instead.

Peringatan di atas berarti Blockly telah mendeteksi bahwa Anda menggunakan metode lama untuk merender ulang kolom, dan ingin Anda menggunakan metode baru.

Untuk mengetahui informasi selengkapnya tentang properti isDirty_, lihat isDirty_.

init

Fungsi init telah dibuat menjadi fungsi template untuk mengurangi kode duplikat dalam subkelas.

CustomFields.UpgradeField.prototype.init = function() {
  if (this.fieldGroup_) {
    // Already initialized once.
    return;
  }

  // Call superclass.
  CustomFields.UpgradeField.superClass_.init.call(this);

  // Create DOM elements.
  this.extraDom_ = Blockly.utils.dom.createSvgElement('image',
      {
        'height': '10px',
        'width': '10px'
      });
  this.extraDom_.setAttributeNS('http://www.w3.org/1999/xlink',
      'xlink:href', 'image.svg');
  this.extraDom_.style.cursor = 'pointer';
  this.fieldGroup_.appendChild(this.extraDom_);

  // Bind events.
  this.mouseOverWrapper_ =
    Blockly.browserEvents.bind(
        this.getClickTarget_(), 'mouseover', this, this.onMouseOver_);
  this.mouseOutWrapper_ =
    Blockly.browserEvents.bind(
        this.getClickTarget_(), 'mouseout', this, this.onMouseOut_);

  // Render.
  this.setValue(this.getValue());
};

Menjadi:

CustomFields.UpgradeField.prototype.initView = function() {
  CustomFields.UpgradeField.superClass_.initView.call(this);

  this.extraDom_ = Blockly.utils.dom.createSvgElement('image',
      {
        'height': '10px',
        'width': '10px'
      });
  this.extraDom_.setAttributeNS('http://www.w3.org/1999/xlink',
      'xlink:href', 'image.svg');
  this.extraDom_.style.cursor = 'pointer';
  this.fieldGroup_.appendChild(this.extraDom_);
};

CustomFields.UpgradeField.prototype.bindEvents_ = function() {
  CustomFields.UpgradeField.superClass_.bindEvents_.call(this);

  this.mouseOverWrapper_ =
    Blockly.bindEvent_(
        this.getClickTarget_(), 'mouseover', this, this.onMouseOver_);
  this.mouseOutWrapper_ =
    Blockly.bindEvent_(
        this.getClickTarget_(), 'mouseout', this, this.onMouseOut_);
};

Artinya, blockly kini otomatis menangani:

• Memeriksa apakah kolom sudah diinisialisasi.
• Membuat fieldGroup_.
• Merender kolom.
• Mengikat tooltip dan menampilkan peristiwa editor.

Anda harus menangani:

• Menambahkan elemen DOM tambahan (initView).
• Menambahkan binding peristiwa tambahan (bindEvents_).
• Menghapus pengikatan peristiwa (dispose).

Penting: Semua pembuatan DOM harus dilakukan di dalam initView karena hal itu paling efisien. Pertimbangkan untuk memfaktorkan ulang jika Anda memiliki pembuatan DOM di dalam konstruktor, setText, setValue, atau render_.

onMouseDown_

CustomFields.UpgradeField.prototype.onMouseDown_ = function(e) {
  // ...
};

Menjadi:

CustomFields.UpgradeField.prototype.showEditor_ = function() {
  // ...
}

Sebaiknya ganti fungsi showEditor_ untuk menangani klik mouse, bukan fungsi onMouseDown_ karena hal itu memungkinkan input diteruskan melalui sistem gestur.

Untuk mengetahui informasi selengkapnya tentang editor, lihat Editor.

setValue

Fungsi setValue kini menjadi fungsi template untuk mengurangi kode duplikat di subkelas. Jika fungsi setValue Anda berisi logika, pertimbangkan untuk memfaktorkannya ulang agar sesuai dengan jalur penanganan nilai yang dijelaskan dalam Penanganan nilai.

text_

Sebaiknya Anda tidak pernah mengakses atau memperbarui properti text_ kolom Anda secara langsung. Sebagai gantinya, gunakan fungsi getText untuk mengakses teks kolom yang dapat dibaca pengguna dan fungsi setValue untuk memperbarui nilai kolom yang disimpan.

Untuk mengetahui informasi selengkapnya tentang nilai kolom vs. teksnya, lihat Anatomi kolom.

Mendapatkan bantuan upgrade

Catatan: Sebelum meminta bantuan upgrade, lakukan yang terbaik untuk mengupgrade kolom Anda secara mandiri menggunakan informasi yang diberikan.

Yang harus diberikan

Saat meminta bantuan, sebaiknya ajukan pertanyaan spesifik:

Tidak direkomendasikan: "Apa yang salah dengan kolom ini?"

Juga tidak direkomendasikan: "Bantu saya mengupgrade kolom ini".

Direkomendasikan: "Teks kolom tidak diperbarui dengan benar."

Anda juga perlu menyediakan sumber daya bagi orang yang membantu Anda. File ini harus mudah digunakan oleh orang lain.

Tidak direkomendasikan:

• Gambar kode.
• Kode tidak lengkap.

Direkomendasikan:

• Kode kolom lengkap dalam format teks.
• Gambar GIF perilaku kolom yang buruk.
• Langkah-langkah untuk mereproduksi perilaku kolom yang buruk.
• Versi blockly yang Anda upgrade.

Tempat memposting

Posting pertanyaan upgrade di forum developer Blockly.

Jika Anda yakin bahwa masalahnya adalah masalah pada blockly core, Anda juga dapat memposting masalah di GitHub blockly. Jika Anda memutuskan untuk memposting masalah, harap isi semua informasi yang diminta.