Island
Island blok memungkinkan blok tetap menggunakan alur rendering normal Blockstudio sambil memindahkan keluaran spesifik permintaan dari respons HTML awal.
Ini berguna ketika halaman perlu di-cache secara agresif, tetapi satu blok masih bergantung pada pengunjung saat ini, sesi, keranjang, izin, atau konteks permintaan langsung lainnya.
Blok Blockstudio tetap merupakan blok WordPress dinamis. Island tidak mengubahnya menjadi HTML statis yang telah dikompilasi sebelumnya. Sebaliknya, Blockstudio mengubah apa yang dirender pada permintaan pertama:
- island terhidrasi merender HTML normalnya yang aman untuk cache dan menerima peristiwa pemasangan
- island dinamis merender placeholder yang aman untuk cache terlebih dahulu, lalu mengambil fragmen sebenarnya dari browser pengunjung
Mode
Island Terhidrasi
Gunakan island terhidrasi ketika keluaran server aman untuk di-cache dan blok hanya memerlukan sinyal pemasangan frontend.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
HTML blok lengkap tersedia dalam respons awal. Runtime island tidak membuat permintaan REST untuknya. Runtime mengirimkan blockstudio:island:hydrate pada penanda agar kode frontend dapat memasang perilaku.
Island Dinamis
Gunakan island dinamis ketika keluaran blok sebenarnya harus dirender dalam konteks permintaan pengunjung.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Respons awal hanya berisi placeholder. Browser menggabungkan semua island dinamis yang siap ke dalam satu permintaan menuju:
POST /wp-json/blockstudio/v1/island/render
Endpoint hanya merender blok Blockstudio terdaftar yang bersifat dinamis dan memiliki blockstudio.island.mode bernilai dynamic.
Konfigurasi
Nilai island dapat berupa singkatan atau objek.
{
"blockstudio": {
"island": true
}
}
true dan "hydrate" sama-sama berarti terhidrasi. "dynamic" berarti dinamis.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Properti | Tipe | Default | Deskripsi |
|---|---|---|---|
mode |
"hydrate" atau "dynamic" |
"hydrate" |
Mode island. |
tag |
string |
"div" |
Tag pembungkus marker. |
attributes |
string[] |
semua atribut blok | Daftar izin atribut yang dikirim ke permintaan fragmen dinamis. |
placeholder |
string |
terdeteksi otomatis | Jalur template placeholder relatif. |
loading |
"eager" atau "visible" |
"eager" |
Kapan runtime harus mengambil island dinamis. |
event |
string |
tidak ditetapkan | Nama peristiwa window yang memperbarui island dinamis. |
context |
boolean |
false |
Tandatangani dan pulihkan ID pos serta tipe pos halaman yang dikueri untuk fragmen dinamis. |
cache |
boolean atau object |
false |
Kebijakan cache fragmen opsional. |
Konteks Halaman
Fragmen dinamis biasanya dirender secara terpisah dari kerangka halaman. Aktifkan identitas halamannya jika blok Anda membaca pengaturan khusus halaman atau konten terkait:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Marker menyertakan postId dan postType halaman yang dikueri di dalam data-bs-island-context. Kedua nilai ditandatangani bersama nama blok dan atribut yang masuk daftar izin menggunakan rahasia situs yang menyajikannya. Nilai tersebut tidak dapat diubah atau ditambahkan ke permintaan tanpa membuat tanda tangan tidak valid. Runtime mengirimkannya bersama permintaan fragmen yang sudah dipaketkan, termasuk pembaruan yang dipicu oleh visibilitas maupun peristiwa. Ini juga berfungsi dengan bs_render_block(), bs_block(), dan tag blok.
Selama perenderan fragmen, $block['postId'], $block['postType'], get_the_ID(), dan get_queried_object_id() merujuk ke halaman tersebut. Kueri WordPress dan variabel global pos dipulihkan setelahnya, termasuk jika terjadi pengecualian saat render. Ini adalah halaman yang dikueri, bukan item di dalam Query Loop. Proses ini tidak memutar ulang parameter URL sembarang atau memulihkan URL permintaan asli. Gunakan get_permalink($block['postId']) jika Anda memerlukan HTML halaman dengan URL kanonis. Arsip dan render tanpa pos yang dikueri tidak mengirimkan identitas halaman.
Endpoint memeriksa apakah halaman masih ada, memiliki tipe pos yang ditandatangani, dan dapat dibaca oleh pengunjung saat ini sebelum memeriksa cache fragmen. Tanda tangan yang valid tidak melewati perlindungan pos privat atau pos dengan kata sandi, kelayakan island, daftar izin atribut, maupun pemeriksaan izin milik blok Anda sendiri. Jika tersedia, identitas halaman selalu menjadi bagian dari kunci cache fragmen, sehingga blok dan atribut yang sama di halaman berbeda tidak pernah berbagi fragmen. Gunakan per: "user" atau jangan gunakan cache fragmen jika keluaran juga bergantung pada pengunjung.
Jika context tidak disertakan atau false, marker yang ada dan perilaku tanpa konteks tetap tidak berubah. Jangan masukkan data rahasia ke dalam marker publik.
Placeholder Dinamis
Island dinamis harus merender placeholder yang aman dalam cache halaman penuh bersama. Jangan sertakan data khusus pengunjung pada cabang placeholder.
Blockstudio mencari placeholder dengan urutan berikut:
- jalur
island.placeholderyang ditentukan secara eksplisit placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- templat normal dengan tanda placeholder
<div class="cart-count-placeholder">
Loading cart...
</div>
Jika tidak ada berkas placeholder, gunakan tanda templat pada templat normal:
<?php if ( $isIslandPlaceholder ) : ?>
<div class="cart-count-placeholder">Loading cart...</div>
<?php else : ?>
<div class="cart-count">
<?php echo esc_html( acme_cart_count() ); ?>
</div>
<?php endif; ?>
Nilai yang sama tersedia di templat PHP, Twig, dan Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase adalah "normal", "hydrate", "placeholder", atau "fragment".
Perilaku Runtime
Blockstudio menyisipkan runtime island hanya jika halaman yang dirender berisi penanda island. Halaman tanpa island tidak memuat JavaScript island tambahan.
Untuk island dinamis, runtime:
- mengumpulkan semua penanda yang siap
- menghapus duplikasi pasangan nama blok, atribut, dan tanda tangan yang identik
- mengirim satu permintaan REST gabungan
- mengganti setiap placeholder dengan fragmen yang dikembalikan
- mengirimkan
blockstudio:island:rendered - mengirimkan
blockstudio:island:hydrate
Island loading: "eager" dirender segera setelah runtime dimulai. Island loading: "visible" menunggu IntersectionObserver. Jika beberapa island yang terlihat masuk ke area pandang secara bersamaan, semuanya digabungkan dalam satu permintaan.
event memperbarui island saat peristiwa window bernama tersebut terjadi:
window.dispatchEvent(new Event('cart:updated'));
Kegagalan membiarkan placeholder tetap di tempatnya dan mengirimkan
blockstudio:island:error.
Endpoint Fragmen
Endpoint island bersifat publik, tetapi bukan API rendering blok umum.
Setiap penanda memuat:
- nama blok
- atribut yang diizinkan
- tanda tangan yang dibuat server
Endpoint hanya merender jika:
- blok terdaftar
- blok merupakan blok WordPress dinamis
- blok ditandai sebagai island Blockstudio dinamis
- atribut yang masuk lolos skema blok dan daftar izin island
- tanda tangan cocok dengan nama blok dan atribut yang dinormalisasi
Tanda tangan dibuat saat rendering di situs WordPress yang melayani permintaan, berdasarkan salt situs tersebut dan payload island. Tanda tangan tidak diekspor atau disertakan dalam tema.
Respons endpoint ditandai agar tidak dapat di-cache. Jika Anda ingin melakukan caching fragmen, gunakan island.cache.
Caching Fragmen
Fragmen dinamis tidak di-cache secara default.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true menggunakan cache global berdurasi singkat. Gunakan bentuk objek untuk kontrol eksplisit:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" menggunakan satu fragmen tersimpan dalam cache untuk blok, atribut, dan konteks halaman yang sama saat ikut serta.
per: "user" memvariasikan cache berdasarkan ID pengguna WordPress saat ini.
Rendering Terprogram
Island berfungsi di mana pun blok Blockstudio dirender:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Island juga berfungsi melalui tag blok:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
Keluaran awal tetap berupa penanda island dan placeholder, dan runtime disisipkan ketika respons yang dirender memuat penanda tersebut.
PHP API
Blockstudio\Islands::is_island('acme/cart-count');
Blockstudio\Islands::mode('acme/cart-count');
Blockstudio\Islands::registered();
Blockstudio\Islands::marker('acme/cart-count', $attributes, $html);
marker() memvalidasi metadata blok. Penanda dinamis hanya dibuat untuk blok Blockstudio dinamis terdaftar yang memiliki island.mode bernilai dynamic.
Hook
Deteksi dan markup:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Endpoint dan rendering:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request mengubah jumlah maksimum island dinamis yang diterima oleh satu permintaan endpoint gabungan. Defaultnya adalah 50.
Konfigurasi runtime:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Tanda tangan:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Tindakan siklus hidup:
blockstudio/islands/registered
blockstudio/islands/rendered
Kapan Tidak Menggunakan Island
Jangan gunakan island dinamis untuk konten penting bagi SEO. Fragmen island dinamis tidak ada dalam HTML awal dan tidak dimaksudkan untuk diindeks.
Gunakan rendering normal atau island terhidrasi jika konten aman untuk di-cache dan harus terlihat oleh crawler. Gunakan island dinamis hanya untuk konten yang dapat dimuat setelah kerangka halaman, seperti UI akun, status keranjang, rekomendasi yang dipersonalisasi, atau kontrol yang dibatasi izin.