Halaman
Halaman adalah templat berbasis file yang disinkronkan ke basis data WordPress sebagai postingan.
Sinkronisasi dilakukan secara eksplisit: jalankan wp bs pages sync atau panggil API Pages saat Anda ingin menerapkan perubahan sumber. Memuat frontend atau admin WordPress tidak pernah melakukan penemuan halaman secara menyeluruh atau mengubah postingan halaman.
Halaman dapat didefinisikan sebagai satu folder page.json, sebagai file tunggal Markdown, atau sebagai kumpulan dengan manifes pages.json. Kumpulan berguna untuk dokumentasi, basis pengetahuan, pustaka halaman landing, atau rangkaian halaman bertingkat apa pun yang perlu dibuat dari file.
page.json
Untuk halaman yang didefinisikan oleh JSON, tambahkan file konfigurasi page.json:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Properti
| Properti | Tipe | Default | Deskripsi |
|---|---|---|---|
name |
string |
wajib | Pengidentifikasi unik untuk halaman |
title |
string |
Otomatis dari nama | Judul halaman |
slug |
string |
Sama seperti nama | Slug URL untuk halaman |
path |
string |
"." |
Jalur logis di dalam koleksi |
order |
integer |
0 |
Urutan menu untuk pos yang disinkronkan |
postType |
string |
"page" |
Tipe pos WordPress |
postStatus |
string |
"draft" |
Status untuk pos baru (publish, draft, pending, private) |
postId |
integer |
– | Sematkan halaman ke ID pos WordPress tertentu |
blockEditingMode |
string |
– | Mode pengeditan blok: "default", "contentOnly", atau "disabled" |
templateLock |
string|false |
"all" |
Mode kunci: "all", "insert", "contentOnly", atau false |
templateFor |
string|null |
null |
Tetapkan sebagai templat default untuk suatu tipe pos |
sync |
boolean |
true |
Menentukan apakah rekonsiliasi eksplisit biasa dapat membuat atau memperbarui pos |
render |
string|object|false |
– | Render halaman dengan perender halaman terdaftar (lihat Halaman Komponen) |
Di page.json, frontmatter, dan entri loader, kunci yang dikenali mencakup blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock, dan title. Kunci apa pun yang tidak tercantum di atas disimpan dalam larik meta milik halaman.
Sumber Konten
Definisi halaman menentukan postingan WordPress mana yang harus ada. Sumber konten menentukan markup blok yang ditulis ke postingan tersebut.
Jika folder halaman memiliki page.json, Blockstudio mencari file sumber yang sejajar dalam urutan berikut:
| File | Kegunaan |
|---|---|
index.php |
Markup blok seperti HTML, dibaca apa adanya (kode PHP tidak dieksekusi) |
index.blade.php |
Konten templat Blade |
index.twig |
Konten templat Twig |
index.md |
Konten Markdown |
page.json juga dapat menyediakan markdown atau html sebaris sebagai pengganti file sumber yang sejajar:
{
"name": "intro",
"title": "Intro",
"markdown": "# Intro\n\nThis page is generated from inline markdown."
}
{
"name": "notice",
"title": "Notice",
"html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}
Kumpulan menambahkan dua mode sumber lainnya:
- File Markdown yang ditemukan langsung di pohon kumpulan.
- Entri loader yang dikembalikan dari
loader.php.
Entri loader dapat menggunakan markdown, html, atau content bersama contentType. Entri juga dapat menunjuk ke file atau template lokal. Jenis sumber file dan templat disimpulkan dari ekstensi, kecuali jika contentType ditetapkan secara eksplisit.
Nilai contentType yang didukung adalah php, blade, twig, markdown, dan html. Markdown terlebih dahulu dikonversi menjadi HTML, lalu diurai menjadi blok WordPress bawaan. Sumber PHP, Blade, Twig, dan HTML diproses melalui parser halaman Blockstudio biasa.
Kelas pada blok core
class pada elemen HTML yang dipetakan ke blok core menjadi className.
Tag blok core yang eksplisit dapat menggunakan className secara langsung. Kedua bentuk mempertahankan
kelas pada wrapper tersimpan blok tersebut, bersama kelas yang dihasilkan oleh WordPress:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Jika kedua properti tersedia, className akan diutamakan. Konversi ini hanya berlaku untuk blok core: pemetaan blok kustom mempertahankan bidang class-nya tanpa perubahan. Kelas gaya tombol, seperti is-style-outline, termasuk pada wrapper tombol, bukan tautannya.
Jalankan wp bs pages sync untuk menerapkan koreksi parser pada halaman yang sebelumnya telah disinkronkan. Pemutakhiran parser akan dikenali saat sinkronisasi eksplisit berikutnya tanpa perlu mengedit berkas sumber. Halaman terkunci dan halaman dengan sync: false tetap memiliki perlindungan normal; permintaan frontend tidak pernah menjalankan sinkronisasi ini.
Blok WordPress yang diserialisasi
Sumber halaman dan pola juga dapat berisi blok terserialisasi yang disalin dari editor kode WordPress:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
Jika sumber berisi pemisah blok <!-- wp:... -->, Blockstudio menggunakan parser blok bawaan WordPress untuk seluruh sumber. Atribut, blok bersarang, blok dinamis seperti Query Loop, dan blok Blockstudio mempertahankan struktur serialisasinya. HTML di luar komentar blok tetap berupa HTML bebas bawaan; bagian itu tidak dipetakan menjadi blok tambahan. Jangan mencampur tag blok HTML milik Blockstudio dengan format ini dan berharap keduanya dikonversi. Komentar HTML biasa tidak mengaktifkan mode blok serial.
Halaman Markdown
Gunakan Markdown jika prosa perlu disimpan dalam file tetapi tetap menjadi konten blok WordPress yang dapat diedit setelah sinkronisasi. Sumber Markdown dikonversi menjadi markup blok saat sinkronisasi. Postingan yang disinkronkan menyimpan blok, bukan isi mentah Markdown.
Markdown dapat digunakan dengan tiga cara:
| Sumber | Frontmatter wajib? | Catatan |
|---|---|---|
pages/example/index.md mandiri |
Ya | Frontmatter memberikan identitas halaman. |
page.json plus index.md |
Tidak | page.json mendefinisikan halaman dan Markdown menyediakan konten. |
| Markdown di dalam kumpulan | Tidak | Kumpulan menyimpulkan name dan path dari lokasi file. |
index.md mandiri tanpa frontmatter dilewati karena Blockstudio tidak memiliki identitas halaman untuk disinkronkan. Markdown dalam kumpulan tidak memerlukan frontmatter karena manifes kumpulan dan jalur file memberikan identitas tersebut.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
Anda juga dapat memasangkan page.json dengan index.md. Dalam hal ini, page.json mendefinisikan halaman dan index.md menyediakan konten. Frontmatter dalam index.md menggantikan nilai page.json yang cocok.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
Untuk Markdown kumpulan, jalur file menjadi jalur logis halaman kecuali jika frontmatter menggantikannya:
| File | Jalur default |
|---|---|
pages/docs/index.md |
. |
pages/docs/getting-started.md |
getting-started |
pages/docs/guide/install/index.md |
guide/install |
pages/docs/guide/install.md |
guide/install |
Kunci frontmatter yang tidak dikenal tetap disimpan dalam larik meta milik halaman. Dengan demikian, Anda dapat melampirkan data seperti section atau description dan membacanya dari PHP API.
Markdown diurai sebagai GitHub Flavored Markdown. HTML mentah diizinkan, tautan yang tidak aman dihapus, dan judul tanpa ID eksplisit diberi ID yang stabil. Frontmatter YAML bertingkat memerlukan parser YAML yang disertakan.
Markdown Mentah
Sumber file Markdown dapat menyajikan sumber aslinya dalam Markdown untuk alat eksternal dan konsumen dokumentasi. Markdown sebaris tidak memiliki file sumber, sehingga disinkronkan menjadi blok tetapi tidak menghasilkan respons .md mentah.
Minta halaman dengan akhiran .md, seperti https://example.com/docs/reference.md. Atau kirim header Accept: text/markdown ke URL halaman biasa:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
Frontmatter dihapus dari respons. Respons mentah Markdown yang berhasil mengirimkan Content-Type: text/markdown, X-Robots-Tag: noindex, dan header Link kanonis kembali ke halaman HTML. Rute .md yang tidak ditemukan mengembalikan 404 sungguhan.
Negosiasi kompatibel dengan prarender statis: permintaan yang header Accept-nya memuat text/markdown tidak pernah dijawab dari penyimpanan prarender atau drop-in penyajian awal, sehingga permintaan tersebut mencapai WordPress dan penangan Markdown. Respons HTML yang telah diprarender, HTML dari halaman yang juga menegosiasikan Markdown, dan Markdown yang dijawab melalui Accept mengirimkan Vary: Accept, sehingga cache yang mematuhi Vary memisahkan keduanya. CDN yang hanya menggunakan URL sebagai kunci cache memerlukan aturan sendiri untuk melewati cache bagi permintaan semacam itu. Pages::negotiates_markdown( $post_id ) melaporkan apakah suatu halaman menjawab permintaan Markdown.
Markdown kumpulan mempertahankan bentuk URL yang sama untuk Markdown mentah:
| Halaman URL | Markdown URL mentah |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
Nonaktifkan respons Markdown mentah dengan filter blockstudio/pages/serve_markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
.md URL yang tidak mengarah ke halaman berbasis Markdown hanya mengembalikan 404 jika jalurnya berada di dalam koleksi halaman. Di luar semua koleksi, Blockstudio membiarkan permintaan diteruskan agar ditangani oleh WordPress dan plugin lain.
Halaman Komponen
Halaman komponen dirender oleh perender halaman alih-alih disimpan sebagai blok. Blockstudio tidak menyertakan perender. Tema atau plugin mendaftarkan perender untuk file entri yang ditanganinya, seperti perender React untuk page.tsx, dan Blockstudio memanggilnya dengan halaman, pos WordPress, dan konten slot yang telah dirender.
pages/legal-notice/
page.json
page.tsx
data.php
{
"name": "legal-notice",
"title": "Legal Notice",
"slug": "legal-notice",
"postStatus": "publish",
"render": { "entry": "page.tsx", "data": "data.php" }
}
render bersifat eksplisit. Direktori dengan index.php dan page.tsx tetapi tanpa render tetap menjadi halaman biasa, sehingga penambahan perender tidak akan merender halaman yang sudah ada dua kali. Bentuk-bentuknya adalah:
| Nilai | Makna |
|---|---|
"page.tsx" |
Hanya entri, tanpa pemuat data |
{ "entry": "page.tsx", "data": "data.php" } |
Entri dan pemuat data |
{ "entry": "page.tsx", "renderer": "react" } |
Entri dengan ID perender eksplisit |
false |
Tanpa perender, meskipun default koleksi menyebutkannya |
Jalur dipecahkan relatif terhadap direktori halaman, atau terhadap akar koleksi untuk entri loader. Jalur harus tetap berada di dalam sumber penemuan, kecuali jika blockstudio/pages/allow_external_loader_path mengizinkannya. Tanpa renderer, perender yang mengklaim ekstensi entri akan digunakan. render yang menyebut entri atau file data yang tidak ada, perender yang tidak dikenal, atau ekstensi yang tidak diklaim perender mana pun merupakan kesalahan penemuan, yang menggagalkan rekonsiliasi sebelum apa pun dihapus.
Yang disimpan oleh sinkronisasi
Sinkronisasi menyimpan satu blok blockstudio/page. Jika direktori halaman juga memiliki sumber index.*, sumber tersebut diuraikan seperti sumber halaman lainnya dan menjadi blok-blok dalam, yaitu slotnya:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Simpan konten milik WordPress, seperti shortcode, di dalam slot. Sumber yang hanya berisi satu shortcode, seperti [download_checkout], disimpan sebagai blok core/shortcode agar keluarannya tidak diberi paragraf pembungkus. Sumber tersebut tetap berada di post_content, sehingga pemeriksaan has_shortcode() dapat melihatnya, blok slot berkunci akan digabungkan dengan perubahan editor seperti blok berkunci bersarang, dan do_shortcode memperluas shortcode sekali pada prioritas the_content biasanya, setelah perender membingkainya.
Definisi render disimpan bersama pos sebagai jalur theme: yang portabel. Sidik jari halaman mencakup definisi tersebut, bukan byte entri atau pemuat datanya: mengedit page.tsx atau data.php tidak mengubah pos dan perubahan akan diterapkan kepada pengunjung melalui perenderan serta graf prarender statis, yang mencatat entri, pemuat data, dan setiap file yang dilaporkan perender.
Mendaftarkan perender
Daftarkan perender pada tindakan blockstudio/pages/renderers. Tindakan ini berjalan sekali per permintaan, sebelum penemuan atau perenderan pertama, sehingga permintaan wp bs pages sync dan frontend melihat registri yang sama.
add_action(
'blockstudio/pages/renderers',
static function (): void {
Blockstudio\Page_Renderers::register(
'react',
array(
'extensions' => array( 'tsx' ),
'layouts' => array( 'layout.tsx' ),
'render' => 'my_theme_render_page',
)
);
}
);
ID perender menggunakan huruf kecil. Nama ekstensi atau tata letak hanya dapat dimiliki oleh satu perender, dan layout.php tetap menjadi tata letak milik Blockstudio. Fungsi yang dapat dipanggil menerima satu permintaan:
| Kunci | Nilai |
|---|---|
kind |
page, atau layout untuk tata letak perender tata letak perender |
renderer |
ID perender |
entry |
Jalur entri absolut |
data |
Jalur pemuat data absolut, atau null |
page |
Data halaman kanonis, termasuk meta |
post_id |
ID pos WordPress |
slot |
Konten slot yang telah dirender, atau konten halaman untuk tata letak |
context |
frontend, rest, feed, atau cli |
Fungsi tersebut mengembalikan HTML, file yang dibaca render, dan aset opsional:
function my_theme_render_page( array $request ): array {
return array(
'html' => '<main>...</main>',
'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
'assets' => array( array( 'path' => '/abs/path/to/page.js' ) ),
);
}
context berasal dari jenis permintaan, bukan dari pengunjung, sehingga renderer tidak dapat merusak kesamaan byte bagi pengguna yang login dan anonim dengan membacanya. Jika renderer gagal, renderer akan melempar galat: halaman tidak dirender dengan isi kosong. Dalam pratinjau editor REST, blok menampilkan galat sebagai pemberitahuan. Setelah rendering berhasil, tindakan blockstudio/pages/rendered menerima halaman, HTML, dan dependensinya.
assets mencantumkan file skrip dan gaya yang dibutuhkan halaman. File tersebut diproses sebagai aset blok (konvensi *.inline.*, modul ES, minifikasi, dan ?ver), lalu dicetak sekali oleh halaman melalui buffer yang sama dengan buffer untuk mencetak aset blok, sehingga halaman yang dirender sebelumnya tetap memuatnya. Aset dapat menetapkan version untuk menggantikan nilai ?ver-nya. Kode di luar renderer dapat menggunakan kanal yang sama melalui Blockstudio\Assets::register_owner(), yang mengembalikan komentar penanda untuk dicetak.
Editor
Di editor, blockstudio/page menampilkan pratinjau halaman yang dirender di server dengan slot sebagai blok dalam, yang mengikuti templateLock halaman. Blok ini tidak dapat disisipkan, diduplikasi, atau disarangkan di dalam blok lain.
Koleksi Halaman
Koleksi adalah folder dengan manifes pages.json. Koleksi mengelompokkan banyak sumber halaman di bawah satu slug koleksi, menerapkan nilai default, mendukung jalur bertingkat, dan dapat mendaftarkan jenis postingan khusus secara otomatis.
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
loader.php
{
"collection": "docs",
"title": "Documentation",
"postType": "bs_docs",
"postTypeArgs": {
"label": "Docs",
"rewrite": {
"slug": "docs"
},
"supports": ["title", "editor", "page-attributes"]
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
| Properti | Jenis | Deskripsi |
|---|---|---|
collection / slug / name |
string |
Slug koleksi. collection adalah bentuk paling jelas dan menjadi basis publik URL. |
title |
string |
Judul koleksi yang mudah dibaca. |
postType |
string |
Jenis pos untuk halaman yang dibuat. Bawaannya page. Jika belum ada, Blockstudio akan mendaftarkannya. |
postTypeArgs |
object |
Argumen yang diteruskan ke register_post_type() saat Blockstudio mendaftarkan jenis pos koleksi. |
defaults |
object |
Properti halaman bawaan yang diterapkan ke setiap halaman dalam koleksi. Nilai bawaan render hanya diterapkan pada halaman jika entri tersebut ada di direktori halaman. |
scope |
string |
collection (bawaan) atau site. Lihat Koleksi Situs. |
meta |
object |
Metadata koleksi kustom. Kunci manifes yang tidak dikenal juga disimpan di meta. |
Jalur halaman dalam koleksi adalah jalur logis. Halaman dengan path: "guide/install" disinkronkan sebagai anak dari guide, dan guide disinkronkan sebagai anak dari akar koleksi jika halaman induk tersebut tersedia.
Jika koleksi hierarkis memiliki halaman bertingkat tetapi sumber untuk induk perantara tidak tersedia, Blockstudio membuat halaman kontainer kosong untuk jalur tersebut agar hierarki WordPress tetap lengkap. Jenis postingan nonhierarkis (yang tidak mendukung induk page-attributes) tidak membuat kontainer kosong. Jenis ini merutekan berdasarkan jalur koleksi yang tersimpan, sehingga jalur bertingkat seperti guide/install dan setup/install dapat berdampingan meskipun keduanya diakhiri dengan install.
Jenis Postingan dan URL Koleksi
Tetapkan postType pada manifes koleksi untuk menyinkronkan setiap halaman dalam koleksi ke jenis postingan tersebut. Anda tidak perlu mengulangi nilai yang sama di dalam defaults. Halaman individual tetap dapat mengganti postType di frontmatter atau page.json.
Jika jenis postingan belum ada, Blockstudio mendaftarkannya dengan show_in_rest: true, konfigurasi editor seperti halaman, dan slug koleksi sebagai basis URL publik. postTypeArgs dapat mengganti argumen pendaftaran. Aturan penulisan ulang untuk jenis postingan koleksi diperbarui otomatis ketika jenis postingan koleksi terdaftar atau argumen penulisan ulang berubah, sehingga Anda tidak perlu menyimpan ulang permalink WordPress.
URL koleksi menggunakan slug koleksi ditambah path logis setiap halaman:
| Jalur sumber | Publik URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Model URL ini berfungsi untuk jenis pos koleksi hierarkis maupun nonhierarkis. Blockstudio juga mengalihkan URL ganda seperti /docs/docs/ atau /docs/docs/getting-started/ ke URL kanonis.
Halaman koleksi menampilkan Markdown mentah di URL yang sama (lihat Markdown Mentah).
Jika Anda mengubah koleksi dari postType: "page" menjadi jenis pos kustom, Blockstudio memigrasikan pos koleksi yang sudah disinkronkan langsung jika identitas halaman yang tersimpan cocok. Ini mempertahankan ID pos, metadata, dan konten yang ada sekaligus menghindari pos lama dengan jenis berbeda yang duplikat. Pos koleksi usang dibersihkan di semua status pos sesuai filter blockstudio/pages/orphan_action.
Koleksi Situs
Manifes dengan "scope": "site" mengelompokkan semua halaman di bawahnya tanpa mengubahnya menjadi halaman koleksi. Gunakan di akar hierarki halaman situs untuk menerapkan nilai bawaan bersama dan mencantumkan halaman situs dengan blockstudio_page_tree( 'my-site' ).
{
"collection": "my-site",
"title": "My Site",
"scope": "site",
"defaults": {
"postStatus": "publish",
"templateLock": "all",
"render": { "entry": "page.tsx", "data": "data.php" }
}
}
Halaman dalam koleksi situs mempertahankan identitas persis seperti sebelum ada manifes, sehingga menambahkan manifes ke hierarki yang sudah ada tidak memperbarui baris pos dan tidak membuat atau membuang apa pun:
- Kunci tetap global:
Pages::get_page( 'home' )dan kunci halaman yang tersimpan tetap cocok. - URL tetap menjadi URL halaman WordPress. Tidak ada aturan penulisan ulang koleksi, filter permalink, atau pengalihan URL ganda, dan tidak ada halaman wadah kosong yang dibuat.
- Jalur logis, slug, induk, dan identitas sumber tetap seperti halaman mandiri, dan tata letak ditentukan oleh leluhur terdekat.
- Manifes
pages.jsonbertingkat tetap memiliki koleksinya sendiri, dan hierarki halamannya tidak disertakan dalam koleksi situs. - Nilai bawaan diterapkan per halaman: nilai bawaan
renderhanya berlaku pada halaman yang direktori halamannya memiliki entri tersebut, sehingga halaman shortcode dan Markdown tetap menggunakan sumbernya.
Pemuat Koleksi
Koleksi dapat menyertakan loader.php lokal tepercaya. Gunakan ini saat halaman koleksi berasal dari sumber lokal lain, seperti folder dokumentasi eksternal, paket, atau manifes yang dibuat.
Pemuat berjalan selama penemuan halaman dan sinkronisasi eksplisit. Prosesnya harus deterministik dan lokal. Hindari mengambil konten jarak jauh dari loader.php, karena hal itu akan membuat sinkronisasi deployment bergantung pada layanan tersebut.
<?php
return array(
'meta' => array(
'source' => 'loader',
),
'paths' => array(
__DIR__ . '/external-docs',
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
'pages' => array(
array(
'name' => 'docs-api',
'title' => 'API',
'path' => 'api',
'content' => "# API\n\nGenerated markdown content.",
'contentType' => 'markdown',
),
array(
'name' => 'docs-template',
'title' => 'Template',
'path' => 'template',
'file' => __DIR__ . '/template.md',
),
),
);
Pemuat dapat mengembalikan array dengan kunci pages, meta, dan paths:
| Kunci | Deskripsi |
|---|---|
pages |
Daftar array halaman. Setiap halaman mendukung kunci yang dikenali sama seperti frontmatter page.json dan Markdown. |
meta |
Metadata yang digabungkan ke dalam array meta milik setiap halaman yang dibuat loader. |
paths |
Direktori lokal tambahan untuk ditemukan sebagai bagian dari koleksi ini. Entri dapat berupa string atau objek jalur. |
render |
Definisi render untuk setiap halaman Markdown yang ditemukan dari paths. |
Sebagai bentuk singkat, pemuat dapat mengembalikan daftar array halaman langsung.
Entri halaman pemuat dapat menyediakan konten dengan cara berikut:
| Bentuk | Deskripsi |
|---|---|
markdown |
Konten Markdown sebaris. |
html |
Konten HTML sebaris. |
content + contentType |
Konten sebaris generik. contentType harus mengarah ke markdown atau html. |
file |
Sumber berkas lokal. Jenisnya ditentukan dari ekstensi, kecuali jika contentType ditetapkan. |
template |
Alias untuk file. |
Referensi berkas pemuat dapat menunjuk ke sumber PHP, Blade, Twig, Markdown, atau HTML. Jalur relatif ditetapkan dari akar koleksi. Jalur absolut dan jalur di luar akar koleksi hanya diizinkan jika filter blockstudio/pages/allow_external_loader_path mengizinkannya.
Halaman pemuat secara default menggunakan generated: true. Jika halaman pemuat yang dibuat tidak lagi muncul dalam keluaran pemuat, Blockstudio menganggap pos yang disinkronkan sebagai yatim pada sinkronisasi berikutnya, lalu membersihkannya sesuai filter blockstudio/pages/orphan_action.
Direktori yang tercantum dalam paths ditemukan seperti folder koleksi biasa. Direktori tersebut dapat berisi berkas Markdown atau folder page.json. Jika jalur tersebut berada di luar akar koleksi, filter jalur eksternal yang sama berlaku.
Gunakan entri string jika direktori eksternal harus mempertahankan jalur logisnya sendiri. Gunakan entri objek jika direktori harus dipasang di bawah prefiks jalur koleksi:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
Dengan konfigurasi tersebut, cli-docs/index.md menjadi path: "cli" dan cli-docs/getting-started.md menjadi path: "cli/getting-started" dalam koleksi. Prefiks juga mencegah benturan nama halaman yang dibuat, sehingga beberapa direktori yang dipasang dapat masing-masing memiliki index.md atau getting-started.md. Tetapkan preserveNames ke true pada objek jalur jika nilai name eksplisit dari frontmatter page.json atau Markdown harus dipertahankan.
Properti objek jalur:
| Properti | Jenis | Deskripsi |
|---|---|---|
path |
string |
Direktori lokal untuk ditemukan. Jalur relatif dihitung dari akar koleksi. |
prefix |
string |
Awalan jalur logis opsional di dalam koleksi. |
preserveNames |
boolean |
Pertahankan nama halaman eksplisit alih-alih membuat nama dari jalur berawalan. Bawaannya false jika prefix ditetapkan. |
meta |
object |
Metadata yang digabungkan ke setiap halaman yang ditemukan dari jalur ini. Metadata tingkat halaman diutamakan jika ada kunci duplikat. |
render |
string|object |
Definisi rendering untuk halaman Markdown dari jalur ini, yang menggantikan render milik loader. |
Merender Markdown melalui komponen
Dengan render, halaman Markdown yang ditemukan loader dirender melalui renderer halaman, bukan disimpan sebagai blok:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Halaman tersebut tetap merupakan halaman Markdown: jenis konten, jalur konten, respons .md, dan frontmatter tidak berubah. Sinkronisasi menyimpan satu blok blockstudio/page yang HTML dalamnya adalah Markdown yang telah dikonversi dan disanitasi jika koleksi menyanitasi kontennya, alih-alih blok hasil parsing, sehingga post_content mempertahankan teks dokumen. Renderer menerima HTML tersebut sebagai slot dan dapat membaca sumber dari page.content_path. Jalur relatif dihitung dari akar koleksi; filter jalur eksternal berlaku seperti pada jalur-jalur tersebut. Halaman yang frontmatter-nya menetapkan render sendiri, atau render: false, tidak disertakan.
Tata Letak
Berkas layout.php membungkus perenderan frontend halaman berbasis berkas. Berkas ini tidak menggantikan post_content tersinkronisasi yang disimpan di WordPress, dan tidak membungkus kanvas editor. Tata letak hanya berjalan pada permintaan frontend tunggal.
Untuk koleksi, letakkan layout.php di samping pages.json agar setiap halaman frontend dalam koleksi tersebut dibungkus:
<?php $current = blockstudio_current_page(); ?>
<main class="docs-layout">
<aside>
<?php foreach (blockstudio_page_tree('docs') as $item) : ?>
<?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
<a
href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
<?php echo $is_current ? 'aria-current="page"' : ''; ?>
>
<?php echo esc_html($item['title']); ?>
</a>
<?php endforeach; ?>
</aside>
<article>
<?php echo blockstudio_page_content(); ?>
</article>
</main>
blockstudio_page_content() mencetak isi halaman yang biasanya dirender oleh WordPress melalui the_content. Jika tata letak tidak mengeluarkan blockstudio_page_content(), konten halaman sengaja disembunyikan.
Tata letak dapat menggunakan fungsi pembantu halaman:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Halaman nonkoleksi yang bertingkat juga dapat mewarisi layout.php leluhur terdekat di dalam pohon pages. Untuk halaman koleksi, tata letak akar koleksi disimpan pada setiap pos tersinkronisasi dan dipantau sebagai bagian dari sidik jari halaman, sehingga perubahan tata letak diterapkan pada sinkronisasi berikutnya.
Tata Letak Renderer
Tata letak juga dapat berupa entri renderer, misalnya layout.tsx untuk renderer yang mendaftarkan layouts: ["layout.tsx"]. Entri ini ditemukan di lokasi yang sama dengan layout.php, dan file layout.data.php opsional di sebelahnya berfungsi sebagai pemuat datanya. Saat rendering, renderer menerima kind: "layout" dan konten halaman yang sudah dirender sebagai slot, dengan prioritas the_content yang sama seperti layout.php. Sebuah direktori dapat berisi layout.php atau satu tata letak renderer, tetapi tidak keduanya; jika berisi keduanya, akan terjadi galat penemuan. Kegagalan tata letak memicu blockstudio/pages/layout_error dan membiarkan konten halaman tanpa pembungkus, seperti yang terjadi pada layout.php.
Mode Penyuntingan Blok
Properti blockEditingMode mengatur cara blok dapat diedit di editor. Tetapkan nilai default tingkat halaman di page.json dan ganti per elemen di templat:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
| Nilai | Deskripsi |
|---|---|
"default" |
Penyuntingan penuh. Blok dapat dipilih, dipindahkan, dan diedit |
"contentOnly" |
Hanya penyuntingan teks. Teks blok dapat diedit, tetapi pengaturan dan strukturnya dikunci |
"disabled" |
Tanpa penyuntingan. Blok sepenuhnya noninteraktif |
Penggantian per elemen ditetapkan sebagai atribut HTML pada elemen apa pun (<h1>, <p>, <div>, dan sebagainya) atau pada elemen <block>. Blok kontainer leluhur dari elemen yang diganti otomatis ditetapkan ke contentOnly agar turunannya tetap dapat diakses. Perambatan ini berjalan dari elemen yang diganti ke akar halaman, jadi Anda hanya perlu menetapkan blockEditingMode pada elemen yang ingin Anda buat dapat diedit.
Penguncian Templat
Properti templateLock mengatur cara pengguna dapat mengedit halaman di editor:
| Nilai | Tambah/Hapus | Pindahkan | Edit Konten |
|---|---|---|---|
"all" |
Tidak | Tidak | Tidak |
"insert" |
Tidak | Ya | Ya |
"contentOnly" |
Tidak | Tidak | Ya |
false |
Ya | Ya | Ya |
Saat templateLock ditetapkan, Blockstudio menonaktifkan kemampuan membuka kunci blok melalui UI editor.
Rute Virtual
Beberapa dokumen tidak memiliki pos di belakangnya: referensi komponen yang dibuat dari data, katalog, atau area akun. Daftarkan dokumen tersebut sebagai rute virtual alih-alih mengaitkan template_redirect sendiri:
add_action( 'init', function () {
Blockstudio\Virtual_Routes::register(
'components',
function ( $component, string $rest ) {
get_header();
echo my_component_page( $component );
get_footer();
},
[
'prefix' => true,
'match' => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
'title' => fn ( $component ) => my_component_title( $component ),
'urls' => fn () => my_component_paths(),
]
);
} );
Jalurnya relatif terhadap beranda situs. Dengan prefix, rute ini juga melayani setiap jalur di bawahnya, dan match menerima sisa jalur tersebut (string kosong untuk rute itu sendiri) lalu mengembalikan nilai yang diterima callback render, atau null agar URL diserahkan ke WordPress, yang kemudian menjawab 404 seperti biasa. Callback render mengeluarkan dokumen atau mengembalikannya sebagai string; title berupa string atau closure yang menerima nilai kecocokan.
Untuk permintaan yang cocok, Blockstudio mencegah WordPress menandai 404 dan redirect_canonical mengalihkannya, menghapus status tunggal yang dilaporkan kueri utama, mengirim status (status, secara default 200), dan merender pada prioritas template_redirect Virtual_Routes::PRIORITY. Ini terjadi tepat setelah buffer keluaran Blockstudio dibuka pada Assets::BUFFER_PRIORITY, sehingga dokumen akhir memperoleh aset blok, aset UI yang dibundel, dan Tailwind yang dikompilasi seperti halaman lain, serta sebelum redirect_canonical pada prioritas 10. Penangan yang merender seluruh dokumen sendiri juga harus berjalan setelah Assets::BUFFER_PRIORITY, atau pemrosesan tersebut dilewati. Jalur dalam urls (secara default jalur rute itu sendiri, jika bukan rute prefiks) ditambahkan ke build prarender statis, dan Virtual_Routes::urls() mengembalikannya sebagai URL absolut untuk peta situs. Virtual_Routes::match( $path ) menyelesaikan jalur seperti permintaan biasa.
Perilaku Sinkronisasi
Pos halaman hanya berubah melalui operasi sinkronisasi eksplisit:
wp bs pages sync
Perintah ini menemukan seluruh inventaris sumber, membuat atau memperbarui pos yang berubah, menghapus pos yatim yang terkonfirmasi, menyegarkan perutean koleksi dan konfigurasi templateFor yang dikompilasi, serta melaporkan perubahan. Tambahkan --authoritative untuk mengganti konten terkelola alih-alih mempertahankan konten editor berkunci, dan --full untuk melaporkan proses sebagai rekonsiliasi penuh tanpa memedulikan identitas sumber yang tersimpan:
wp bs pages sync --authoritative --full
Permintaan bootstrap frontend, admin, AJAX, REST, cron, dan WP-CLI generik tidak menjalankan penemuan halaman lengkap, tidak meminta inventaris rekonsiliasi terkelola, dan tidak menulis pos halaman. Permintaan tersebut menggunakan pos WordPress yang sudah disinkronkan beserta konfigurasi ringkas koleksi dan templat jenis pos yang disimpan oleh operasi eksplisit terakhir. Instalasi atau pemutakhiran dingin mungkin memindai manifes koleksi sekali untuk memulihkan metadata perutean; bootstrap hanya-baca ini tidak pernah menyinkronkan konten. Endpoint penyegaran Canvas yang diautentikasi dan bersifat opsional adalah API eksplisit untuk penulisan: Canvas memanggilnya sekali saat ruang kerja dibuka agar sumber yang baru ditambahkan atau diubah muncul dalam inventaris awal. Mode Live memanggil batas yang sama saat mendeteksi perubahan sumber halaman.
Blockstudio\Pages::init() kini hanya mendaftarkan hook saat permintaan berlangsung. Integrasi yang sebelumnya meneruskan argumen force ke metode tersebut harus memanggil Blockstudio\Pages::reconcile() atau menjalankan wp bs pages sync sebagai gantinya.
Untuk mencegah halaman ditimpa setelah diedit secara manual, tetapkan "sync": false di page.json.
Lokasi Sumber Portabel
File tema yang disinkronkan disimpan sebagai lokasi relatif terhadap tema, bukan sebagai jalur instalasi absolut. File tema anak dan tema induk mempertahankan identitas terpisah, meskipun memiliki nama file relatif yang sama. Helper halaman tetap mengembalikan nilai template_path, content_path, layout_path, dan directory absolut yang sudah diresolusikan untuk permintaan saat ini.
Ini memungkinkan CLI sinkronisasi dan permintaan web menggunakan root sistem berkas yang berbeda, seperti pada hosting terisolasi, tanpa merusak respons Markdown, tata letak, pemindaian Tailwind, atau pelacakan sumber prapembuatan. Path tema absolut yang sudah ada akan disesuaikan saat dibaca jika nama direktori tema tidak berubah. Tidak diperlukan sinkronisasi, migrasi basis data, atau penulisan metadata saat permintaan berlangsung untuk membacanya; sinkronisasi eksplisit berikutnya akan menyimpan lokasi portabel.
Direktori tema yang merupakan symlink, misalnya ke checkout pengembangan, menyimpan lokasi theme: yang sama baik sumber dibaca melalui symlink maupun targetnya, dan menyelesaikannya ke direktori tema yang dikonfigurasi.
File di luar tema anak dan induk yang aktif tetap didukung pada path absolut yang dikonfigurasi, dengan tunduk pada batasan open_basedir milik PHP. File tersebut tidak dapat dipindahkan secara otomatis: setelah memindahkan sumber eksternal, perbarui path yang dikonfigurasi dan jalankan sinkronisasi eksplisit.
Kepemilikan Field Post
postStatus menetapkan status awal. Sinkronisasi berikutnya mempertahankan status draft, pending, privat, terbit, dan terjadwal, termasuk dengan --authoritative. Draft tidak diterbitkan ulang hanya karena file-nya menyatakan postStatus: "publish". Perilaku pemulihan orphan yang ada tidak berubah: sinkronisasi eksplisit memulihkan post terkelola yang dipindahkan ke sampah jika sumbernya tersedia. Kunci halaman atau nonaktifkan sinkronisasi untuk mencegah pemulihan tersebut.
File tetap menjadi acuan untuk judul, slug, jenis post, induk, dan urutan menu yang dikonfigurasi. Mengeditnya di WordPress tidak mengubah definisi sumber. Sinkronisasi eksplisit berikutnya menerapkan kembali nilai dari file dan menyebutkan field yang terdampak di pages.<name>.overwritten, dengan peringatan pada keluaran tabel CLI. Izin bawaan WordPress tetap berlaku, termasuk slug kosong untuk post pending saat pengguna yang melakukan sinkronisasi tidak memiliki izin untuk menerbitkannya.
Gunakan blockstudio/pages/update_post_data untuk integrasi yang secara eksplisit memiliki kebijakan status berbeda. Blok berkunci mempertahankan konten blok yang dimiliki editor; kunci tidak mengubah kepemilikan judul atau slug post.
Untuk halaman koleksi, sidik jari mencakup manifes, pemuat, sumber halaman, berkas tata letak, metadata, dan jalur sumber terkait. Sinkronisasi eksplisit berikutnya menerapkan perubahan pada masukan tersebut.
Saat sumber koleksi dihapus, Blockstudio menghapus halaman yang dibuat agar halaman koleksi lama tidak tertinggal setelah berkas sumber hilang. Secara default, halaman koleksi yatim dipindahkan ke sampah. Gunakan blockstudio/pages/orphan_action untuk mengembalikan trash, delete, atau keep.
Pada permintaan frontend, Blockstudio mengisi registri halaman dari pos terbit yang sudah disinkronkan. Halaman draf dan privat tersedia dalam konteks admin dan sinkronisasi, tetapi pembantu frontend hanya memuat halaman terbit.
Rekonsiliasi Deployment
Blockstudio\Pages::reconcile() adalah titik masuk deployment PHP. Ini menemukan seluruh inventaris yang diinginkan, membandingkan sidik jari sumber dan mesin sinkronisasi, lalu mengembalikan laporan yang dapat dibaca mesin:
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
'renames' => [
[
'from' => 'pages/old/index.php',
'to' => 'pages/new/index.php',
],
],
]);
Laporan mencakup discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, hasil per halaman, error penemuan, dan sourceIdentity yang deterministik.
Halaman terkunci memiliki status: "locked" dan dihitung terpisah dari halaman yang tidak berubah. removedPages mencantumkan name, key, postId, dan action aktual untuk setiap halaman yang dihapus (trash atau delete); post yang dipertahankan atau sudah dipindahkan ke sampah tidak dihitung sebagai baru dihapus. Keluaran tabel CLI juga menyebutkan halaman yang dibuat, diperbarui, dikunci, dihapus, dan dipertahankan kontennya beserta ID post-nya.
Setelah parsing dan penggabungan berkunci, post akhir yang identik tidak memanggil wp_update_post(), mengubah post_modified, membuat revisi, atau menjalankan hook pembaruan post. Hasilnya adalah unchanged. Jika konten sumber berbeda dari konten berkunci yang dimiliki editor, preserved: true menandai keputusan tersebut dan jumlah preserved tingkat atas mencakupnya. Sidik jari sumber baru dan metadata terkelola tetap dicatat agar sinkronisasi berikutnya yang tidak berubah menjadi tanpa operasi. preserved adalah flag tambahan, bukan status eksklusif: halaman dapat mempertahankan konten berkunci sekaligus memperbarui judul yang dimiliki file atau menambahkan blok lain.
authoritative: true dapat menghapus kunci Page Sync dan mengganti konten dengan definisi berkas alih-alih mempertahankan konten editor berkunci. Biarkan dalam keadaan false untuk sinkronisasi eksplisit biasa. plan_valid: false, full: true, broad: true, identitas sumber sebelumnya yang hilang, atau sidik jari mesin sinkronisasi yang berubah menandai proses sebagai rekonsiliasi penuh (fullReconciliation dalam laporan). Proses mana pun tetap membandingkan seluruh inventaris. Catatan penggantian nama Git hanya menjadi petunjuk identitas. Catatan itu tidak pernah menggantikan perbandingan inventaris lengkap.
Sidik jari yang sama dengan jalur runtime yang tidak berubah tidak menghasilkan penulisan pos atau postmeta dan tidak memicu hook pembaruan. Saat sumber yang tidak berubah berpindah ke direktori rilis baru, rekonsiliasi hanya menyegarkan jalur templat, konten, tata letak, dan direktori yang tersimpan; proses ini tidak memperbarui post_content atau stempel waktu modifikasi pos. Halaman terkelola yang hilang hanya dihapus setelah proses rekonsiliasi lengkap selesai tanpa kesalahan penemuan atau penulisan halaman.
Rekonsiliasi API langsung tidak menandai deployment sebagai berhasil. Setelah mengaktifkan dan memverifikasi artefak statis serta rute yang sesuai, simpan identitas yang dikembalikan secara eksplisit:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync menyimpan identitas yang dikembalikan setelah proses berhasil. Bootstrap WP-CLI biasa hanya mendaftarkan ulang jenis pos koleksi dan aturan penulisan ulang yang tersimpan. Bootstrap ini tidak menemukan atau menyinkronkan halaman.
Penetapan ID Pos
Secara default, WordPress menetapkan ID pos secara otomatis. Jika halaman dihapus lalu dibuat ulang, ID-nya berubah sehingga referensi eksternal seperti menu atau tautan hardcoded rusak.
Gunakan postId untuk menetapkan ID tertentu pada halaman:
{
"name": "about",
"title": "About Us",
"postId": 42
}
Saat membuat halaman, Blockstudio meneruskan ID ke WordPress melalui import_id. Jika ID tersedia, WordPress menggunakannya persis. Jika ID sudah dipakai pos yang tidak terkait, WordPress secara diam-diam menetapkan ID baru secara otomatis.
Saat mencari halaman yang sudah ada, Blockstudio memeriksa ID yang ditetapkan terlebih dahulu, sebelum memeriksa meta atau slug. Artinya, jika halaman dihapus lalu disinkronkan kembali, halaman tersebut memperoleh ID yang sama.
Penggabungan Blok Berkunci
Secara default, saat berkas templat berubah, Blockstudio mengganti seluruh konten pos dengan templat baru. Artinya, semua suntingan yang dibuat di editor WordPress akan hilang.
Tambahkan atribut key ke blok untuk mempertahankan suntingan pengguna saat sinkronisasi templat. Jika templat memiliki blok berkunci, Blockstudio menggabungkan perubahan templat dengan konten pos yang ada alih-alih menggantinya.
Menambahkan Kunci
Gunakan atribut key pada elemen HTML atau elemen <block> apa pun:
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>
<div key="features">
<p>First feature.</p>
<p>Second feature.</p>
</div>
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h2>Hero Title</h2>
<p>Hero description.</p>
</block>
<block
name="acme/testimonial"
key="featured-quote"
quote="Default quote"
/>
Kunci harus unik secara global di seluruh templat. Kunci melindungi seluruh blok dan semua kontennya. Anda tidak perlu memberi kunci pada anak satu per satu di dalam induk yang sudah berkunci. Blok berkunci dapat dipindahkan ke posisi atau tingkat penyarangan mana pun di antara pembaruan templat, dan konten penggunanya akan tetap dipertahankan.
Kunci berfungsi sama untuk blok kustom Blockstudio. key adalah metadata struktural Page Sync; nilai bidang kustom tetap menjadi atribut Blockstudio biasa. Saat editor mengubah bidang tersebut, sinkronisasi templat berikutnya mempertahankan nilai editor sambil tetap menerapkan perubahan templat yang terpisah. Halaman yang dibuat oleh versi lama dengan kunci di dalam data bidang kustom dimigrasikan secara otomatis pada sinkronisasi berikutnya.
Cara Kerja Penggabungan
Saat berkas templat berubah dan halaman disinkronkan ulang:
| Blok | Perilaku |
|---|---|
| Blok berkunci | Konten pengguna dan nilai bidang Blockstudio dipertahankan. Atribut dan struktur milik templat diterapkan. |
| Blok tanpa kunci | Sepenuhnya diganti dengan versi templat (sama seperti tanpa kunci) |
Contoh
Suntingan pengguna dipertahankan dalam blok berkunci:
- Templat menetapkan
<p key="intro">Default intro.</p> - Pengguna mengedit paragraf di editor menjadi "Teks pengantar khusus."
- Pengembang memperbarui templat, menambahkan blok baru, dan mengubah tata letak
- Saat sinkronisasi: paragraf tetap berisi "Teks pengantar khusus." sementara tata letak baru diterapkan
Atribut dari templat tetap diterapkan:
- Templat memiliki blok sampul dengan
key="hero"dan atributurl - Pengembang mengubah atribut
urlmilik sampul ke gambar latar baru - Saat sinkronisasi: gambar latar baru diterapkan, tetapi suntingan konten pengguna di dalam sampul tetap dipertahankan
Kasus Khusus
| Skenario | Perilaku |
|---|---|
| Blok berkunci baru ditambahkan ke templat | Muncul dengan konten default templat |
| Blok berkunci dihapus dari templat | Dihapus dari pos |
| Jenis blok berubah (kunci sama) | Templat sepenuhnya menjadi acuan, tanpa penggabungan konten |
| Kunci duplikat | Kemunculan kedua dianggap tanpa kunci |
| Tidak ada kunci dalam templat | Penggantian penuh (sama seperti perilaku tanpa kunci) |
| Sinkronisasi paksa | Penggantian penuh, kunci diabaikan |
| Pos terkunci | Tidak ada sinkronisasi sama sekali |
Menggabungkan dengan Kontrol Penyuntingan
Kunci, templateLock, dan blockEditingMode dapat digabungkan untuk mengatur dengan cermat hal-hal yang boleh dan tidak boleh dilakukan klien. Berikut pola alur kerja yang umum.
Halaman terkunci sepenuhnya
Pengembang mengendalikan semuanya. Halaman ini adalah tata letak statis yang sama sekali tidak dapat disentuh klien. Cocok untuk halaman hukum, ketentuan layanan, atau halaman apa pun yang hanya boleh diubah melalui kode.
{
"name": "terms",
"title": "Terms of Service",
"templateLock": "all"
}
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>
Tidak perlu kunci. Templat menjadi satu-satunya sumber kebenaran. Setiap sinkronisasi menimpa seluruh halaman.
Tata letak terkunci dengan konten yang dapat diedit
Ini pola yang paling umum. Kunci struktur halaman agar klien tidak dapat menambah, menghapus, atau mengatur ulang blok, tetapi izinkan mereka mengedit teks di bagian tertentu. Kunci memastikan suntingan mereka tetap ada saat templat diperbarui.
{
"name": "landing",
"title": "Landing Page",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h1 blockEditingMode="contentOnly">Edit This Title</h1>
<p blockEditingMode="contentOnly">Edit this description.</p>
</block>
<div key="features">
<h2>Features</h2>
<p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
</block>
Klien dapat mengedit judul hero, deskripsi, dan pengantar fitur. Tidak ada yang lain. Teks tombol, URL, dan gambar latar sampul dikendalikan oleh pengembang. Saat pengembang memperbarui templat (e.g., menambahkan tombol kedua), bagian yang diberi kunci mempertahankan teks klien.
Templat yang berkembang dengan konten yang dipertahankan
Untuk halaman yang berkembang seiring waktu. Pengembang menambahkan bagian baru ke templat, dan setiap sinkronisasi menambahkan konten baru tanpa menyentuh hal yang sudah disesuaikan klien.
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<div key="testimonials">
<h2>Testimonials</h2>
<p>What our clients say.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
</block>
Bagian testimoni dan tombol baru muncul saat sinkronisasi. Perubahan klien pada judul, pengantar, dan layanan tetap utuh.
Kerangka awal satu kali
Buat halaman dengan struktur awal, lalu serahkan sepenuhnya. Atur sync ke false agar sinkronisasi normal tidak pernah membuat atau memperbarui halaman, lalu buat sekali dengan Blockstudio\Pages::force_sync('blog'). Setelah itu, klien memiliki kendali penuh atas halaman tersebut.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync melewati halaman ini, sehingga force_sync() membuatnya satu kali. Setelah itu, klien bebas menambahkan, menghapus, dan menyusun ulang blok. Perubahan templat diabaikan.
Pengikatan Blok
Alternatif untuk penggabungan berdasarkan kunci adalah menggunakan WordPress core API Block Bindings untuk menghubungkan blok ke meta pos. Ini bukan fitur Blockstudio, melainkan WordPress API bawaan. Blockstudio hanya meneruskan atribut metadata ke markup blok yang dihasilkan. Konten disimpan dalam meta pos, bukan markup blok, sehingga sinkronisasi templat dapat menimpa markup dengan leluasa karena editor membaca dari meta, bukan dari innerHTML.
Teruskan atribut metadata pada elemen HTML atau elemen <block> mana pun:
<h1
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
Default Title
</h1>
<p
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
Default description text.
</p>
<img
metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>
Kunci meta harus didaftarkan dengan show_in_rest diaktifkan:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Kunci vs. pengikatan
| Aspek | Kunci | Pengikatan |
|---|---|---|
| Konten disimpan di | Markup blok (post_content) |
Meta pos (wp_postmeta) |
| Dipertahankan saat sinkronisasi templat | Ya (digabung berdasarkan kunci) | Ya (data tersimpan di meta) |
Dapat dikueri melalui WP_Query |
Tidak | Ya (meta_query) |
| Tersedia di REST API | Tidak | Ya |
| Memerlukan pendaftaran | Tidak | Ya (register_post_meta) |
| Pengguna dapat memindahkan blok | Tidak (templat memberlakukan ulang struktur) | Tidak (templat memberlakukan ulang struktur) |
Kedua pendekatan dapat digunakan dalam templat yang sama. Gunakan kunci untuk bagian yang struktur bloknya penting (e.g., grup dengan beberapa anak). Gunakan pengikatan untuk bidang individual jika Anda juga ingin datanya dapat diakses di luar editor blok.
Templat Jenis Pos
Gunakan templateFor untuk menetapkan halaman sebagai templat default untuk jenis pos:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Setiap pos baru dari jenis tersebut akan dimulai dengan struktur blok yang ditentukan.
Jalur Kustom
Secara default, Blockstudio memindai get_template_directory() . '/pages'. Tambahkan jalur lain dengan filter:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Integrasi runtime yang menggabungkan berkas dari beberapa akar dapat mengganti pemindaian sistem berkas dengan sumber penemuan logis. Manifest halaman, tata letak, pemuat, dan templat sumber kemudian ditentukan melalui jalur logis, meskipun berkas yang dipilih berada di akar yang berbeda.
Filter dan Tindakan
Penemuan halaman, sinkronisasi, dan perutean koleksi menyediakan titik ekstensi berikut:
| Hook | Jenis | Deskripsi |
|---|---|---|
blockstudio/pages/paths |
Filter | Tambahkan direktori yang dipindai Blockstudio untuk mencari sumber halaman. |
blockstudio/pages/collection_post_type_args |
Filter | Sesuaikan argumen register_post_type() untuk CPT koleksi. |
blockstudio/pages/template_candidates |
Filter | Sesuaikan nama file template yang dipertimbangkan untuk sumber halaman. |
blockstudio/pages/serve_markdown |
Filter | Aktifkan atau nonaktifkan respons Markdown mentah. |
blockstudio/pages/orphan_action |
Filter | Kembalikan trash, delete, atau keep untuk pembersihan orphan. |
blockstudio/pages/docs_allowed_html |
Filter | Sesuaikan HTML yang diizinkan untuk konten dokumen Markdown yang dihasilkan. |
blockstudio/pages/allow_external_loader_path |
Filter | Izinkan paths loader di luar root koleksi. |
blockstudio/pages/manifest_scan_interval |
Filter | Tetapkan usia maksimum cache manifes lama sebelum 7.6.2 yang dapat digunakan untuk mengisi konfigurasi runtime tersimpan selama peningkatan versi. |
blockstudio/pages/create_post_data |
Filter | Ubah data post sebelum halaman tersinkronisasi dibuat. |
blockstudio/pages/update_post_data |
Filter | Ubah data post sebelum halaman tersinkronisasi diperbarui. |
blockstudio/pages/sync_engine_inputs |
Filter | Tambahkan versi parser, pemetaan, atau migrasi yang sengaja akan memperluas rekonsiliasi satu kali. |
blockstudio/pages/post_created |
Action | Berjalan setelah post halaman tersinkronisasi dibuat. |
blockstudio/pages/post_updated |
Action | Berjalan setelah post halaman tersinkronisasi diperbarui. |
blockstudio/pages/synced |
Action | Berjalan setelah registri halaman selesai disinkronkan. |
blockstudio/pages/reconciled |
Action | Berjalan setelah rekonsiliasi eksplisit, dengan laporan yang dapat dibaca mesin. |
blockstudio/pages/renderers |
Action | Daftarkan renderer halaman dengan Blockstudio\Page_Renderers::register(). Berjalan sekali per permintaan. |
blockstudio/pages/rendered |
Action | Berjalan setelah halaman komponen dirender, dengan halaman, HTML-nya, dan dependensinya. |
blockstudio/pages/layout_error |
Action | Berjalan saat tata letak tidak dapat dirender, dengan error, path tata letak, dan halaman. |
PHP API
// Get all registered pages.
$pages = Blockstudio\Pages::pages();
// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');
// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');
// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');
// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');
// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');
// Get a specific page.
$page = Blockstudio\Pages::get_page('about');
// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');
// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');
// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();
// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
]);
// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);
// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');
// Unlock a page.
Blockstudio\Pages::unlock('about');
// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
'extensions' => ['tsx'],
'layouts' => ['layout.tsx'],
'render' => 'my_theme_render_page',
]);
// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');
// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);
Lihat Rekonsiliasi Deployment untuk semantik argumen, kolom laporan, dan batas identitas sumber yang terverifikasi.
Fungsi helper global tersedia untuk templat dan tata letak:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Array halaman yang dikembalikan oleh Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children(), dan helper global mencakup identitas pos yang disinkronkan, jalur sumber dan templat, metadata koleksi/jalur, jenis konten, kebijakan sinkronisasi, jenis/status pos, kebijakan pengeditan, metadata kustom, serta kunci permalink. Metadata koleksi dimuat dari rekonsiliasi eksplisit terakhir yang berhasil. Permintaan normal menyusun ulang data runtime ini dari konfigurasi tersimpan dan meta pos yang disinkronkan tanpa membaca pohon sumber halaman. Kelas Pages tidak menyediakan metode permalink terpisah.
Membangun Halaman Berbasis Berkas
Penguncian templat, mode pengeditan blok, penggabungan berdasarkan kunci, dan pengaturan hal yang dapat diedit klien.