Lewati ke konten

Migrasi ke v7

Panduan ini membahas perubahan yang perlu Anda lakukan saat meningkatkan dari Blockstudio 6 ke 7.

Impor Modul ES

Blockstudio 7 memperkenalkan prefiks npm: baru untuk impor modul ES, selaras dengan konvensi Denonpm.

Sebelum (v6):

JavaScript
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):

JavaScript
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):

JavaScript
import "blockstudio/swiper@11.0.0/swiper.min.css";

Sesudah (v7):

JavaScript
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:

PHP
// 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"]:

HTML
<!-- 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:

Kode
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": true secara 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:

JSON
{
  "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:

  1. WordPress merender halaman penuh HTML ke dalam buffer keluaran
  2. Kandidat kelas CSS diekstrak dari HTML (regex cepat, tanpa kompilasi)
  3. Kandidat diurutkan dan di-hash dengan konfigurasi CSS untuk membuat kunci cache
  4. Jika cache cocok: file CSS yang tersimpan dibaca dan disisipkan
  5. 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):

JSON
{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "primary": "pink"
          }
        }
      }
    }
  }
}

Sesudah (v7):

JSON
{
  "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):

JSON
{
  "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):

JSON
{
  "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:

PHP
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.