Migrasi ke v7
Panduan ini membahas perubahan yang perlu Anda lakukan saat meningkatkan dari Blockstudio 6 ke 7.
Impor Modul ES
Prefiks npm: Baru (Disarankan)
Blockstudio 7 memperkenalkan prefiks npm: baru untuk impor modul ES, selaras dengan konvensi Denonpm.
Sebelum (v6):
import { h, render } from "blockstudio/preact@10.15.1";
import htm from "blockstudio/htm@3.1.1";
import confetti from "blockstudio/canvas-confetti@1.6.0";
Sesudah (v7):
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";
Impor CSS
Perubahan yang sama berlaku untuk impor CSS:
Sebelum (v6):
import "blockstudio/swiper@11.0.0/swiper.min.css";
Sesudah (v7):
import "npm:swiper@11.0.0/swiper.min.css";
Kompatibilitas Mundur
Prefiks blockstudio/ tetap didukung demi kompatibilitas mundur. Kode Anda yang sudah ada akan tetap berfungsi tanpa perubahan. Namun, kami menyarankan Anda beralih ke prefiks npm: agar konsisten dengan ekosistem JavaScript yang lebih luas.
Prefiks npm: menawarkan beberapa keunggulan:
- Selaras dengan ekosistem – Mengikuti konvensi Deno yang sudah mapan
- Jelas – Langsung menunjukkan bahwa Anda mengimpor dari npm
- Siap untuk masa depan – Prefiks
blockstudio/mungkin tidak lagi digunakan dalam versi mayor mendatang
Nama Hook
Blockstudio 7 menstandarkan semua nama hook PHP dengan menggunakan snake_case alih-alih camelCase, selaras dengan konvensi inti WordPress.
Nama Hook yang Berubah
| Nama Lama (v6) | Nama Baru (v7) |
|---|---|
blockstudio/blocks/components/useblockprops/render |
blockstudio/blocks/components/use_block_props/render |
blockstudio/blocks/components/innerblocks/render |
blockstudio/blocks/components/inner_blocks/render |
blockstudio/blocks/components/innerblocks/frontend/wrap |
blockstudio/blocks/components/inner_blocks/frontend/wrap |
blockstudio/blocks/components/richtext/render |
blockstudio/blocks/components/rich_text/render |
blockstudio/assets/process/scss/importPaths |
blockstudio/assets/process/scss/import_paths |
blockstudio/settings/assets/process/scssFiles |
blockstudio/settings/assets/process/scss_files |
blockstudio/settings/editor/formatOnSave |
blockstudio/settings/editor/format_on_save |
blockstudio/settings/blockEditor/disableLoading |
blockstudio/settings/block_editor/disable_loading |
blockstudio/settings/blockEditor/cssClasses |
blockstudio/settings/block_editor/css_classes |
blockstudio/settings/blockEditor/cssVariables |
blockstudio/settings/block_editor/css_variables |
blockstudio/settings/ai/enableContextGeneration |
blockstudio/settings/ai/enable_context_generation |
Kompatibilitas Mundur
Nama hook camelCase lama tetap didukung demi kompatibilitas mundur. Kode Anda yang sudah ada akan tetap berfungsi tanpa perubahan. Namun, kami menyarankan Anda beralih ke nama snake_case yang baru agar konsisten.
Contoh migrasi:
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
return ['my-stylesheet'];
});
// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
return ['my-stylesheet'];
});
Tag Blok Kanonis
Blockstudio 7.6 tetap menyediakan prefiks proyek dan alias persis sebagai titik ekstensi saat runtime, tetapi menggunakan <bs:namespace-slug> sebagai ejaan kanonis dalam contoh, keluaran katalog, deklarasi render, dan diagnostik. Tag kanonis memuat nama blok terdaftar yang sebenarnya dan tidak bergantung pada filter khusus host.
Untuk proyek yang menggunakan brand => ["theme-components"] dan ui => ["bsui"]:
<!-- Legacy project shorthand -->
<brand-card>
<ui-input />
</brand-card>
<!-- Canonical output -->
<bs:theme-components-card>
<bs:bsui-input />
</bs:theme-components-card>
Perintah migrasi mandiri menginventarisasi proyek yang sudah ada dan menulis ulang bentuk singkat ke ejaan kanonis. Perintah ini mengutamakan laporan, berhenti jika ada kasus yang belum terselesaikan, dan hanya mengubah nama tag. Lihat Migrasi Tag Blok untuk perintah, masukan, dan perilaku keamanannya.
Penamaan File Aset
Blockstudio 7 memperkenalkan notasi titik untuk akhiran nama file aset, menggantikan notasi tanda hubung lama sebagai konvensi yang disarankan.
Nama File yang Berubah
| Nama Lama (v6) | Nama Baru (v7) |
|---|---|
*-inline.(s)css |
*.inline.(s)css |
*-inline.js |
*.inline.js |
*-editor.(s)css |
*.editor.(s)css |
*-editor.js |
*.editor.js |
*-scoped.(s)css |
*.scoped.(s)css |
*-view.js |
*.view.js |
Kompatibilitas Mundur
Notasi tanda hubung lama tetap didukung demi kompatibilitas mundur. File yang sudah ada akan tetap berfungsi tanpa perlu diubah namanya. Namun, kami menyarankan Anda menggunakan notasi titik untuk blok baru.
Contoh migrasi:
my-block/
├── block.json
├── index.php
├── style.css
├── style-inline.css → style.inline.css
├── style-scoped.css → style.scoped.css
├── style-editor.css → style.editor.css
├── script.js
├── script-inline.js → script.inline.js
├── script-editor.js → script.editor.js
└── script-view.js → script.view.js
Sakelar Field
Properti switch kini secara bawaan bernilai false, bukan true. Di v6, setiap field memiliki sakelar tak terlihat di tepi kiri yang aktif secara bawaan. Di v7, sakelar bersifat opsional dan menggunakan ikon mata yang terlihat pada label field.
Perubahan
- Nilai bawaan kini
false: field tidak lagi memiliki sakelar kecuali Anda menetapkan"switch": truesecara eksplisit - Ikon mata terlihat: tombol ikon mata muncul di area label, menggantikan zona klik tersembunyi di sisi kiri
- Lapisan nonaktif: saat field dinonaktifkan, lapisan buram dengan teks "Field ini dinonaktifkan" ditampilkan, bukan sekadar mengurangi opasitas
Migrasi
Jika Anda mengandalkan perilaku sakelar bawaan di v6, Anda perlu mengaktifkannya secara eksplisit:
{
"id": "title",
"type": "text",
"label": "Title",
"switch": true
}
Jika sebelumnya Anda menetapkan "switch": false untuk menonaktifkan sakelar, Anda dapat menghapusnya karena kini false menjadi nilai bawaan.
Tailwind CSS
Blockstudio 7 sepenuhnya menggantikan pendekatan v6 Tailwind. Di v6, Tailwind CSS dikompilasi di sisi klien melalui CDN di editor dan disimpan ke disk saat kiriman disimpan. Di v7, Tailwind CSS dikompilasi di sisi server pada setiap permintaan frontend melalui TailwindPHP dengan cache berbasis file otomatis.
Lihat dokumentasi Tailwind CSS untuk detail lengkap tentang sistem baru.
Kompilasi Sisi Server yang Selalu Aktif
Saat tailwind.enabled bernilai true, setiap permintaan frontend dikompilasi di sisi server. Alur kompilasinya:
- WordPress merender halaman penuh HTML ke dalam buffer keluaran
- Kandidat kelas CSS diekstrak dari HTML (regex cepat, tanpa kompilasi)
- Kandidat diurutkan dan di-hash dengan konfigurasi CSS untuk membuat kunci cache
- Jika cache cocok: file CSS yang tersimpan dibaca dan disisipkan
- Jika cache tidak cocok: TailwindPHP mengompilasi CSS, menulisnya ke cache runtime bersama milik Blockstudio dalam cakupan
tailwind, lalu menyisipkannya
CSS yang telah dikompilasi disisipkan sebagai tag <style id="blockstudio-tailwind"> sebaris sebelum </head>. Ini mencakup preflight milik Tailwind dan semua kelas utilitas yang cocok.
Skrip CDN tetap aktif di editor hanya untuk pratinjau langsung. Skrip ini tidak pernah disajikan di frontend.
Perubahan Format config
Properti config berubah dari objek JSON (Tailwind v3) menjadi string CSS (sintaks Tailwind v4-first CSS).
Sebelum (v6):
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
Sesudah (v7):
{
"tailwind": {
"config": "@theme { --color-primary: pink; }"
}
}
Pengaturan customClasses Dihapus
Pengaturan larik customClasses telah dihapus. Dengan pendekatan CSS-first dari Tailwind v4, kelas utilitas khusus didefinisikan langsung dalam string config menggunakan @layer utilities.
Sebelum (v6):
{
"tailwind": {
"customClasses": [
{ "className": "btn", "value": "px-4 py-2 rounded-lg font-medium" },
{ "className": "card", "value": "bg-white rounded-xl shadow-lg p-6" }
]
}
}
Sesudah (v7):
{
"tailwind": {
"config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
}
}
Atau melalui filter untuk konfigurasi multiline:
add_filter('blockstudio/settings/tailwind/config', function () {
return <<<CSS
@layer utilities {
.btn { @apply px-4 py-2 rounded-lg font-medium; }
.card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});
Filter blockstudio/settings/tailwind/custom_classes juga telah dihapus. Gunakan filter blockstudio/tailwind/css untuk menambahkan aturan CSS khusus.
Endpoint REST Dihapus
Endpoint POST /blockstudio/v1/editor/tailwind/save telah dihapus. CSS yang dikompilasi tidak lagi disimpan dari editor. Jika kode khusus Anda memanggil endpoint ini, kode tersebut dapat dihapus dengan aman.
Caching
Blockstudio menggunakan strategi caching berbasis kandidat. Alih-alih melakukan hash pada seluruh HTML halaman (yang akan membatalkan cache pada setiap permintaan akibat nonce dan stempel waktu), hanya kandidat kelas CSS yang di-hash. Artinya:
- Dua halaman dengan kelas CSS yang sama berbagi file cache yang sama
- Konten dinamis (nonce, bilah admin, stempel waktu) tidak membatalkan cache
- Cache hanya dibatalkan saat kumpulan kelas CSS berubah atau konfigurasi berubah
File cache menggunakan root runtime Blockstudio yang dikonfigurasi di
sites/{network-blog}/{runtime-identity}/tailwind/. Panggil
Blockstudio\Runtime_Cache::purge('tailwind') untuk memaksa kompilasi ulang.
Perubahan Filter
| Nama Lama (v6) | Nama Baru (v7) |
|---|---|
blockstudio/tailwind/on_demand/css |
blockstudio/tailwind/css |
blockstudio/tailwind/assets/dir |
Dihapus |
blockstudio/settings/tailwind/custom_classes |
Dihapus |
File dan Pemuatan yang Dihapus
Di v6, Tailwind CSS dimuat sebagai stylesheet eksternal (blockstudio-tailwind, blockstudio-tailwind-preflight). Di v7, semua CSS disisipkan sebaris melalui buffer keluaran. Tidak ada tag link atau stylesheet yang dimuat untuk Tailwind di frontend.
Pustaka Blok
Pustaka “Blockstudio Elements” bawaan telah dihapus. Pengaturan library di blockstudio.json dan filter blockstudio/settings/library tidak lagi berpengaruh.
Jika Anda menggunakan blok dari pustaka (Gallery, Slider, Image Comparison, Code, Icon), salin folder blok dari direktori includes/library/blockstudio-element/ pada instalasi v6 ke direktori blockstudio tema Anda, lalu perbarui file block.json dengan nama dan kategori baru.