Lewati ke konten

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:

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:

JSON
{
  "name": "intro",
  "title": "Intro",
  "markdown": "# Intro\n\nThis page is generated from inline markdown."
}
JSON
{
  "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:

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

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

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

JSON
{
  "name": "docs-reference",
  "title": "Reference",
  "path": "reference",
  "sync": true
}
Markdown
---
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:

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

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

Text
pages/legal-notice/
  page.json
  page.tsx
  data.php
JSON
{
  "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:

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

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

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

Kode
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "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' ).

JSON
{
  "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.json bertingkat tetap memiliki koleksinya sendiri, dan hierarki halamannya tidak disertakan dalam koleksi situs.
  • Nilai bawaan diterapkan per halaman: nilai bawaan render hanya 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
<?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:

PHP
'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
<?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
<?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:

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

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<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:

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

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

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

PHP
$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:

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

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

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

  1. Templat menetapkan <p key="intro">Default intro.</p>
  2. Pengguna mengedit paragraf di editor menjadi "Teks pengantar khusus."
  3. Pengembang memperbarui templat, menambahkan blok baru, dan mengubah tata letak
  4. Saat sinkronisasi: paragraf tetap berisi "Teks pengantar khusus." sementara tata letak baru diterapkan

Atribut dari templat tetap diterapkan:

  1. Templat memiliki blok sampul dengan key="hero" dan atribut url
  2. Pengembang mengubah atribut url milik sampul ke gambar latar baru
  3. 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.

JSON
{
  "name": "terms",
  "title": "Terms of Service",
  "templateLock": "all"
}
HTML
<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.

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<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.

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

JSON
{
  "name": "blog",
  "title": "Blog",
  "sync": false
}
HTML
<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:

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

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

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

PHP
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

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

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