Serialisasi

Serialisasi menyimpan status ruang kerja Anda sehingga dapat dimuat kembali ke ruang kerja nanti. Hal ini mencakup serialisasi status blok, variabel, atau plugin yang ingin Anda simpan. Anda dapat mengonversi semua data yang perlu disimpan ke dalam format berbasis teks untuk memudahkan penyimpanan, lalu memuat data tersebut kembali ke ruang kerja yang berfungsi penuh nanti.

Blockly menyediakan dua format untuk data ini: JSON dan XML. Sebaiknya gunakan sistem JSON untuk project baru, dan dorong project lama yang menggunakan XML untuk mengupgrade. Sistem XML adalah format penyimpanan lama. ID tersebut tidak akan dihapus, tetapi tidak akan menerima fitur baru.

Sistem JSON

Catatan: Untuk informasi tentang cara bermigrasi ke JSON dari XML, lihat panduan migrasi.

Sistem serialisasi JSON terdiri dari beberapa serialisasi. Ada serialisasi bawaan untuk blok dan variabel, dan Anda juga dapat mendaftarkan serialisasi tambahan. Setiap serializer bertanggung jawab untuk melakukan serialisasi dan deserialisasi status plugin atau sistem tertentu.

Menyimpan dan Memuat

Ruang kerja

Anda dapat melakukan serialisasi atau deserialisasi status seluruh ruang kerja dengan memanggil metode save dan load di namespace workspaces.

const state = Blockly.serialization.workspaces.save(myWorkspace);
Blockly.serialization.workspaces.load(state, myWorkspace);

Panggilan ini melakukan serialisasi atau deserialisasi semua sistem individual (diwakili oleh serializer) yang terdaftar dengan ruang kerja.

Blok individual

Anda dapat melakukan serialisasi atau deserialisasi setiap blok dengan memanggil metode save dan append di namespace blocks.

const blockJson = Blockly.serialization.blocks.save(myBlock);
const duplicateBlock =
    Blockly.serialization.blocks.append(blockJson, myWorkspace);

Sistem individual

Anda dapat melakukan serialisasi atau deserialisasi setiap sistem (misalnya, blok, variabel, plugin, dll.) dengan membuat serializer terkait, dan memanggil metode save dan load-nya.

// Saves only the variables information for the workspace.
const serializer = new Blockly.serialization.variables.VariableSerializer();
const state = serializer.save(myWorkspace);
serializer.load(state, myWorkspace);

Urutan deserialisasi

Sistem JSON memiliki urutan deserialisasi eksplisit, yang mempermudah pencegahan duplikasi status dalam penyimpanan.

Saat Blockly.serialization.workspaces.load dipanggil, serializer diberi status untuk melakukan deserialisasi dalam urutan prioritas. Hal ini dijelaskan lebih lanjut di bagian Serializer, dan tujuannya adalah memungkinkan serialisasi bergantung pada status dari sistem lain.

Urutan untuk deserialisasi serializer bawaan adalah:

1. Model variabel dideserialisasi.
2. Model prosedur dideserialisasi.
3. Pemblokiran dideserialisasi. Setiap blok tingkat teratas di-deserialisasi dalam urutan arbitrer.
   1. Jenis dideserialisasi. Tindakan ini akan membuat blok, memicu metode init-nya, dan menggabungkan ekstensi.
   2. Atribut dideserialisasi. Hal ini mencakup properti yang dapat diterapkan ke blok mana pun. Misalnya: x, y, diciutkan, dinonaktifkan, dan data.
   3. Status tambahan dideserialisasi. Lihat dokumentasi Ekstensi dan Mutator untuk mengetahui info selengkapnya.
   4. Blok terhubung ke induknya (jika ada).
   5. Ikon dideserialisasi. Setiap ikon dideserialisasi dalam urutan arbitrer.
   6. Kolom dideserialisasi. Setiap kolom dideserialisasi dalam urutan arbitrer.
   7. Blok input dideserialisasi. Ini mencakup blok yang terhubung ke input nilai dan input pernyataan. Masing-masing input dideserialisasi dalam urutan arbitrer.
   8. Blok berikutnya akan dideserialisasi.

Kapan harus menyimpan status tambahan

Untuk blok, jika Anda memiliki sesuatu yang lebih rendah dalam urutan yang bergantung pada sesuatu yang lebih tinggi dalam urutan, Anda harus menduplikasi data tersebut dan menambahkannya ke status tambahan.

Misalnya, jika Anda memiliki kolom yang hanya ada jika blok berikutnya terhubung, Anda harus menambahkan info tentang blok berikutnya ke status tambahan, sehingga kolom dapat ditambahkan ke blok sebelum status kolom dideserialisasi.

Namun, jika Anda memiliki input yang hanya ada jika kolom memiliki nilai tertentu, Anda tidak perlu menambahkan info tentang kolom ke status tambahan. Hal ini karena status kolom Anda akan dideserialisasi terlebih dahulu, dan jika demikian, Anda dapat menambahkan input ke blok. Biasanya penambahan input akan dipicu oleh validator.

Perhatikan bahwa aturan tentang status duplikat juga harus memperhitungkan bahwa stack blok, ikon, kolom, dan blok input dideserialisasi dalam urutan arbitrer. Misalnya, jika Anda memiliki satu kolom B yang hanya ada jika kolom lain A memiliki nilai tertentu, Anda harus menambahkan info tentang A ke status tambahan jika B di-deserialisasi sebelum A.

Hook blok

Untuk informasi tentang cara menambahkan serialisasi tambahan ke blok, lihat dokumentasi Ekstensi dan Mutator.

Hook kolom

Untuk mengetahui informasi tentang cara melakukan serialisasi kolom, lihat dokumentasi Kolom kustom.

Hook serialisasi

Sistem JSON memungkinkan Anda mendaftarkan serializer yang melakukan serialisasi dan deserialisasi beberapa status. Serializer bawaan Blockly menangani serialisasi informasi tentang blok dan variabel, tetapi jika Anda ingin melakukan serialisasi informasi lain, Anda harus menambahkan serializer Anda sendiri. Misalnya, komentar tingkat workspace tidak diserialisasi secara default oleh sistem JSON. Jika ingin melakukan serialisasi, Anda harus mendaftarkan serializer tambahan.

Penserialisasi tambahan sering kali digunakan untuk membuat serialisasi dan melakukan deserialisasi status plugin.

Blockly.serialization.registry.register(
    'workspace-comments',  // Name
    {
      save: saveFn,      // Save function
      load: loadFn,      // Load function
      clear: clearFn,    // Clear function
      priority: 10,      // Priority
    });

Saat mendaftarkan serialisasi, Anda harus memberikan beberapa hal:

• Nama untuk serializer, yang juga menyimpan data.
• Fungsi untuk save status plugin/sistem yang terkait dengan serializer.
• Fungsi untuk clear status.
• Fungsi untuk load status.

• priority, yang digunakan untuk menentukan urutan deserialisasi.

  Anda dapat mendasarkan prioritas serialisasi pada prioritas bawaan

Saat Blockly.serialization.workspaces.save dipanggil, fungsi save setiap serialisasi akan dipanggil, dan datanya akan ditambahkan ke output JSON akhir:

{
  "blocks": { ... },
  "workspaceComments": [ // Provided by workspace-comments serializer
    {
      "x": 239,
      "y": 31,
      "text": "Add 2 + 2"
    },
    // etc...
  ]
}

Saat Blockly.serialization.workspaces.load dipanggil, setiap serializer akan dipicu sesuai urutan prioritas. Serializer dengan nilai prioritas yang lebih positif akan dipicu sebelum serializer dengan nilai prioritas yang kurang positif.

Saat serializer dipicu, dua hal akan terjadi:

1. Fungsi clear yang disediakan dipanggil. Hal ini memastikan bahwa status plugin/sistem Anda bersih sebelum status lainnya dimuat. Misalnya, serialisasi komentar ruang kerja akan menghapus semua komentar yang ada dari ruang kerja.
2. Fungsi load yang disediakan dipanggil.

Sistem XML

Sistem XML memungkinkan Anda melakukan serialisasi ruang kerja ke node XML. Ini adalah sistem serialisasi asli Blockly. Aplikasi sekarang telah di-icebox, yang berarti tidak akan menerima fitur baru. Oleh karena itu, sebaiknya gunakan sistem JSON jika memungkinkan.

Catatan: Untuk informasi tentang cara bermigrasi ke JSON, lihat panduan migrasi.

API

Untuk informasi tentang API sistem XML, lihat dokumentasi referensi.

Hook blok

Untuk informasi tentang cara menambahkan serialisasi tambahan ke blok, lihat dokumentasi Ekstensi dan Mutator.

Hook field

Untuk mengetahui informasi tentang cara melakukan serialisasi kolom, lihat dokumentasi Kolom kustom.

Memilih antara JSON dan XML

Sebaiknya gunakan serialisasi JSON, bukan XML. Sistem JSON memungkinkan Anda melakukan serialisasi status ruang kerja Anda ke objek JavaScript. Hal ini beruntung karena:

1. JSON mudah dikompresi atau dikonversi ke format lain.
2. JSON mudah digunakan secara terprogram.
3. JSON mudah diperluas dan ditambahkan data.

Selain itu, sistem XML tidak akan lagi menerima update, dan sudah tidak memiliki fitur dibandingkan dengan serialisasi JSON. Misalnya, Anda dapat mendaftarkan serialisasi JSON Anda sendiri untuk menyimpan dan memuat data tambahan dengan mudah, seperti data untuk plugin atau penyesuaian yang telah Anda tambahkan. Hal ini tidak dapat dilakukan di sistem XML.

Jika sebelumnya Anda telah menggunakan serialisasi XML, lihat panduan migrasi untuk mengetahui informasi tentang cara melakukan upgrade.