Membangun Halaman Berbasis File
Pembuatan halaman WordPress tradisional dilakukan di editor blok: menyeret blok, mengatur setelan, lalu mengeklik simpan. Cara ini cocok bagi klien yang membuat halamannya sendiri, tetapi menimbulkan masalah bagi pengembang yang membuat halaman terstruktur dan dikontrol versinya. Tata letak halaman tersimpan di basis data, bukan di kode. Anda tidak dapat meninjaunya dalam pull request, mengembalikannya dengan git, atau membuatnya kembali pada instalasi baru.
Halaman berbasis file milik Blockstudio mengatasi masalah ini. Anda mendefinisikan halaman sebagai file di tema, menulis templat HTML yang dikonversi menjadi blok WordPress, dan mengontrol dengan tepat apa yang boleh dan tidak boleh diedit klien. Perintah eksplisit menyinkronkan file tersebut menjadi postingan WordPress biasa, sementara templat tetap menjadi sumber utama.
Panduan ini menjelaskan cara membangun halaman dari awal, dengan fokus mendalam pada kontrol penguncian dan pengeditan yang membuat halaman berbasis file praktis untuk proyek klien.
Halaman Pertama Anda
Buat folder pages di tema Anda, lalu tambahkan subfolder dengan dua file:
theme/
└── pages/
└── about/
├── page.json
└── index.php
{
"name": "about",
"title": "About Us",
"postStatus": "publish"
}
<h1>About Us</h1>
<p>We build things for the web.</p>
Jalankan perintah sinkronisasi halaman:
wp bs pages sync
Blockstudio mengurai HTML menjadi blok WordPress dan membuat halaman bernama
“Tentang Kami” dengan slug about. Buka halaman itu di editor dan Anda akan melihat
judul serta paragraf, sama persis seperti jika Anda menambahkannya secara manual.
Edit index.php, ubah teksnya, lalu jalankan perintah lagi. Muat ulang editor
untuk melihat perubahannya. Inilah alur kerjanya: tulis HTML, sinkronkan sesuai
kehendak, lalu hasilkan blok.
Bahasa Templat
Parser HTML milik Blockstudio mengonversi elemen HTML standar menjadi blok WordPress. Tulis <p> untuk membuat blok paragraf. Tulis <h2> untuk membuat blok judul. Pemetaan ini intuitif:
| HTML | Blok |
|---|---|
<p> |
Paragraf |
<h1> sampai <h6> |
Judul (tingkat sesuai tag) |
<ul>, <ol> |
Daftar |
<blockquote> |
Kutipan |
<img> |
Gambar |
<div>, <section> |
Grup |
<hr> |
Pemisah |
<details> |
Detail |
<table> |
Tabel |
Untuk blok yang tidak memiliki padanan langsung HTML, gunakan elemen <block> dengan atribut name:
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Hero Title</h2>
<p>Content over the background image.</p>
</block>
<block name="core/spacer" height="80px" />
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
<block name="core/button" url="/work">See Our Work</block>
</block>
Atribut pada elemen <block> diteruskan sebagai atribut blok. Nilainya dikonversi otomatis: "true" menjadi boolean, "3" menjadi bilangan bulat, dan string JSON seperti '{"type":"flex"}' diuraikan menjadi objek.
Layout
Grup mendukung berbagai mode layout melalui atribut layout:
<!-- Default group (stacked) -->
<div>
<p>Stacked by default.</p>
</div>
<!-- Row (horizontal flex) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Side</p>
<p>by side</p>
</block>
<!-- Stack (vertical flex) -->
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked</p>
<p>with flex</p>
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<p>Left column.</p>
</block>
<block name="core/column">
<p>Right column.</p>
</block>
</block>
Blok kustom
Sintaks <block> berlaku untuk blok terdaftar apa pun, termasuk blok Blockstudio buatan Anda sendiri:
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />
Atribut dipetakan otomatis ke nilai field Blockstudio milik blok.
Membangun Halaman Landing
Berikut halaman landing lengkap yang menggunakan blok inti untuk struktur dan tata letak:
{
"name": "landing",
"title": "Landing Page",
"slug": "landing",
"postStatus": "publish",
"templateLock": "all"
}
<block name="core/cover" url="https://images.unsplash.com/photo-1497366216548-37526070297c?w=1600">
<h1>Build faster with Blockstudio</h1>
<p>File-based blocks. Zero build step. Full editor integration.</p>
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
<block name="core/button" url="/docs">Documentation</block>
</block>
</block>
<div>
<h2>Why developers love it</h2>
<block name="core/columns">
<block name="core/column">
<h3>No build step</h3>
<p>Write PHP, CSS, and JavaScript. No webpack, no bundler, no transpiler.</p>
</block>
<block name="core/column">
<h3>File-based</h3>
<p>Every block is a folder. Every page is a template. Version control everything.</p>
</block>
<block name="core/column">
<h3>Full editor support</h3>
<p>Fields, previews, and InnerBlocks work in the block editor out of the box.</p>
</block>
</block>
</div>
<block name="core/media-text" mediaurl="https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=800" mediatype="image">
<h2>Ship entire sites from your IDE</h2>
<p>Define pages, blocks, and patterns as files. Blockstudio handles the rest.</p>
</block>
<div>
<h2>Frequently asked questions</h2>
<details>
<summary>Do I need to learn React?</summary>
<p>No. Templates are PHP. Fields are JSON. Interactivity is optional.</p>
</details>
<details>
<summary>Does it work with my existing theme?</summary>
<p>Yes. Drop a blockstudio folder into any theme and start creating blocks.</p>
</details>
</div>
<div>
<block name="core/buttons">
<block name="core/button" url="/get-started">Start Building</block>
</block>
</div>
Halaman ini memiliki hero sampul, grid fitur tiga kolom, bagian media-teks, akordeon FAQ, dan CTA. Semuanya dari satu file HTML. templateLock: "all" di page.json berarti klien tidak dapat mengubah apa pun. Bagian berikutnya menjelaskan cara melonggarkan pengaturan tersebut.
Mengontrol Editor
Di sinilah halaman berbasis file menjadi benar-benar andal. Blockstudio memberi Anda dua kontrol independen: penguncian templat dan mode pengeditan blok. Keduanya memungkinkan Anda menentukan dengan tepat bagian mana dari halaman yang dapat diubah klien. Kunci strukturnya, tetapi biarkan mereka mengedit teks. Bekukan beberapa bagian sementara bagian lain tetap terbuka sepenuhnya. Buat halaman yang hanya memungkinkan klien mengetik pada tiga judul tertentu.
Penguncian Templat
Properti templateLock di page.json mengontrol pengeditan struktur: apakah blok dapat ditambahkan, dihapus, atau diatur ulang.
"all" (default)
{
"name": "terms",
"templateLock": "all"
}
Penguncian paling ketat. Klien tidak dapat menambah, menghapus, atau memindahkan blok. Mereka juga tidak dapat mengedit konten blok (kecuali jika digabungkan dengan blockEditingMode). Ini adalah default jika Anda tidak menentukan nilai.
Kapan digunakan: Halaman hukum, ketentuan layanan, kebijakan privasi. Halaman apa pun yang kontennya hanya boleh diubah melalui kode.
"insert"
{
"name": "about",
"templateLock": "insert"
}
Klien tidak dapat menambah atau menghapus blok, tetapi dapat memindahkan blok yang sudah ada dan mengedit kontennya. Jumlah blok tetap, tetapi urutannya fleksibel.
Kapan digunakan: Halaman dengan bagian tetap yang ingin Anda izinkan untuk diurutkan ulang oleh klien. Misalnya, halaman portofolio dengan jumlah bagian yang sudah ditentukan, tetapi urutannya dipilih klien.
"contentOnly"
{
"name": "homepage",
"templateLock": "contentOnly"
}
Klien dapat mengedit konten teks, tetapi tidak dapat menambah, menghapus, atau memindahkan blok. Perbedaannya dengan "all" adalah "all" juga mencegah pengeditan konten, sedangkan "contentOnly" secara khusus mengizinkannya.
Kapan digunakan: Pilihan paling umum untuk halaman yang ditujukan kepada klien. Developer mengontrol tata letak. Klien mengisi teksnya.
false
{
"name": "blog",
"templateLock": false
}
Tanpa penguncian. Klien memiliki kendali penuh: dapat menambah, menghapus, memindahkan, dan mengedit blok apa pun. Templat menyediakan struktur awal, lalu klien bebas mengelolanya.
Kapan digunakan: Halaman indeks blog, halaman konten bebas, atau halaman apa pun yang memberi klien kebebasan editorial penuh.
Mode Pengeditan Blok
Sementara templateLock mengontrol struktur (menambah, menghapus, memindahkan), blockEditingMode mengontrol interaksi pada tingkat blok individual: apakah blok dapat dipilih, dikonfigurasi, atau diedit.
Tetapkan default tingkat halaman di page.json:
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
"default"
Pengeditan penuh. Blok dapat dipilih, pengaturannya dapat diubah, dan kontennya dapat diedit. Ini adalah pengalaman editor yang normal.
"contentOnly"
Blok dapat diedit, tetapi hanya konten teksnya. Anda tidak dapat membuka pengaturan blok, mengubah warna, menyesuaikan padding, atau mengubah atribut nonkonten apa pun. Bilah alat blok hanya menampilkan opsi pemformatan teks.
"disabled"
Blok sepenuhnya tidak interaktif. Blok ditampilkan di editor, tetapi tidak dapat diklik, dipilih, atau diubah dengan cara apa pun. Klien dapat melihat konten, tetapi tidak dapat mengutak-atiknya.
Penggantian Per Elemen
Di sinilah hal menarik terjadi. blockEditingMode tingkat halaman menetapkan default untuk setiap blok di halaman, tetapi Anda dapat menggantinya pada elemen individual dalam templat:
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" url="https://example.com/hero.jpg">
<h1 blockEditingMode="contentOnly">Edit This Heading</h1>
<p blockEditingMode="contentOnly">Edit this paragraph too.</p>
</block>
<div>
<h2>Features</h2>
<p>This paragraph cannot be edited (inherits "disabled").</p>
<p blockEditingMode="contentOnly">But this one can.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">This button is frozen</block>
</block>
Default halaman adalah "disabled", jadi setiap blok dimulai dalam keadaan tidak interaktif. Lalu, elemen tertentu memilih "contentOnly" sehingga hanya teksnya yang dapat diedit. Hasilnya: halaman tempat klien dapat mengetik tepat pada dua kolom teks (judul hero dan paragraf) serta satu paragraf fitur. Semua bagian lain terkunci.
Ini berfungsi pada elemen HTML apa pun (<h1>, <p>, <div>, dan seterusnya) serta pada elemen <block>. Anda juga dapat menetapkan blockEditingMode="default" pada elemen tertentu untuk memberikan akses pengeditan penuh:
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
Kini klien dapat mengubah teks tombol, URL, gaya, dan pengaturan lainnya. Semua bagian lain pada halaman tetap terkunci.
Rantai Pewarisan dari Induk
Ada detail penting tentang interaksi penggantian per elemen dengan blok kontainer. Jika default halaman adalah "disabled" dan Anda menetapkan blockEditingMode="contentOnly" pada judul di dalam grup, judul itu harus dapat dijangkau. Namun, grup induknya adalah "disabled", yang berarti grup itu sama sekali tidak dapat dimasuki.
Blockstudio menangani ini secara otomatis. Ketika blok anak memiliki penggantian mode pengeditan, semua blok induknya ditetapkan ke "contentOnly" agar blok anak tetap dapat diakses. Anda tidak perlu menetapkan mode secara manual pada kontainer induk. Cukup tetapkan penggantian pada blok yang ingin Anda jadikan dapat diedit, maka jalur menuju blok itu akan terbuka.
<!-- page default: "disabled" -->
<div>
<!-- this group is auto-set to "contentOnly" because it contains an override -->
<div>
<!-- this group is also auto-set to "contentOnly" -->
<p blockEditingMode="contentOnly">Deeply nested but still editable.</p>
</div>
</div>
Rantai pewarisan dari induk hanya menaikkan tingkat kontainer ke "contentOnly", bukan ke "default". Artinya, grup induk dapat dinavigasi (Anda dapat memasukinya), tetapi tidak dapat diedit sepenuhnya (pengaturannya tidak dapat diubah).
Matriks Keputusan
Menggabungkan templateLock dan blockEditingMode memberi Anda beragam tingkat kendali. Berikut kombinasi yang paling berguna:
Developer mengontrol semuanya
{ "templateLock": "all" }
blockEditingMode tidak diperlukan. Default templateLock: "all" mencegah semua perubahan. Gunakan ini untuk halaman yang dikelola sepenuhnya melalui kode.
Klien mengedit semua teks
{ "templateLock": "contentOnly" }
Klien dapat mengedit teks di blok mana pun, tetapi tidak dapat mengubah struktur halaman. Sederhana dan fleksibel.
Klien hanya mengedit teks tertentu
{
"templateLock": "all",
"blockEditingMode": "disabled"
}
Digabungkan dengan blockEditingMode="contentOnly" pada elemen tertentu di templat. Ini opsi paling presisi: klien hanya dapat mengedit blok yang Anda tandai.
Klien mengurutkan ulang bagian tetap
{ "templateLock": "insert" }
Klien dapat mengatur ulang bagian dan mengedit konten, tetapi tidak dapat menambah atau menghapus blok. Cocok untuk halaman dengan bagian tetap yang urutannya fleksibel.
Klien memiliki kendali penuh
{ "templateLock": false }
Templat hanya menjadi titik awal. Setelah itu klien dapat melakukan apa saja.
Mempertahankan Editan Klien
Secara default, saat Anda memperbarui file templat, Blockstudio mengganti seluruh konten halaman. Jika klien mengedit judul di editor, editan itu akan hilang setelah sinkronisasi berikutnya. Ini tidak masalah untuk halaman yang dikendalikan developer, tetapi untuk halaman yang kontennya turut dibuat klien, Anda perlu cara untuk mempertahankan hasil kerja mereka.
Kunci
Tambahkan atribut key ke elemen mana pun agar elemen tersebut digabungkan, bukan diganti:
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
<h1>Default Hero Title</h1>
<p>Default hero description.</p>
</block>
<div key="features">
<h2>Features</h2>
<p>Feature introduction text.</p>
</div>
<div>
<h2>Unkeyed Section</h2>
<p>This gets replaced on every sync.</p>
</div>
Saat templat berubah dan halaman disinkronkan kembali:
- Blok berkunci mempertahankan konten klien (teks, blok di dalamnya, pemformatan). Atribut struktural templat (seperti
urlpada cover) tetap diperbarui. - Blok tanpa kunci sepenuhnya diganti dengan versi dari templat.
Kunci melindungi seluruh blok beserta semua anaknya. Anda tidak perlu memberi kunci pada paragraf satu per satu di dalam grup berkunci. Kunci grup tersebut melindungi semua yang ada di dalamnya.
Kunci harus unik
Kunci harus unik secara global di seluruh templat. Jika dua elemen memakai kunci yang sama, elemen kedua dianggap tidak berkunci (dan peringatan PHP akan dikeluarkan). Gunakan nama deskriptif: "hero", "features", "cta", "testimonial-section".
Mengembangkan templat
Kunci memungkinkan Anda menambahkan bagian baru ke templat tanpa mengganggu konten klien yang sudah ada:
<h1 key="title">Welcome</h1>
<div key="services">
<h2>Our Services</h2>
<p>We do great work.</p>
</div>
<h1 key="title">Welcome</h1>
<div key="services">
<h2>Our Services</h2>
<p>We do great work.</p>
</div>
<div key="testimonials">
<h2>What Clients Say</h2>
<p>Default testimonial text.</p>
</div>
Saat disinkronkan, judul dan layanan mempertahankan editan klien. Bagian testimoni yang baru muncul dengan konten default dari templat. Jika nanti Anda menghapus blok berkunci dari templat, blok itu juga dihapus dari halaman.
Alur kerja klien lengkap
Berikut penerapannya dalam proyek nyata:
{
"name": "homepage",
"title": "Home",
"slug": "home",
"postStatus": "publish",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
<h1 blockEditingMode="contentOnly">Your Company Name</h1>
<p blockEditingMode="contentOnly">Your tagline goes here.</p>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
</block>
</block>
<div key="features">
<h2 blockEditingMode="contentOnly">What We Do</h2>
<block name="core/columns">
<block name="core/column">
<h3 blockEditingMode="contentOnly">Service One</h3>
<p blockEditingMode="contentOnly">Describe this service.</p>
</block>
<block name="core/column">
<h3 blockEditingMode="contentOnly">Service Two</h3>
<p blockEditingMode="contentOnly">Describe this service.</p>
</block>
<block name="core/column">
<h3 blockEditingMode="contentOnly">Service Three</h3>
<p blockEditingMode="contentOnly">Describe this service.</p>
</block>
</block>
</div>
<block name="core/media-text" key="about" mediaurl="https://example.com/team.jpg" mediatype="image">
<h2 blockEditingMode="contentOnly">About Us</h2>
<p blockEditingMode="contentOnly">Tell your story here.</p>
</block>
<div key="cta">
<h2 blockEditingMode="contentOnly">Ready to get started?</h2>
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
</block>
</div>
Halaman ini memiliki empat bagian berkunci. Klien dapat mengedit judul dan paragraf yang ditandai dengan blockEditingMode="contentOnly", dan editan tersebut tetap ada saat templat diperbarui. Developer mengontrol tata letak, gambar, URL tombol, dan struktur keseluruhan. Jika developer kemudian menambahkan bagian testimoni di antara “about” dan “cta”, bagian itu akan muncul pada sinkronisasi berikutnya tanpa mengganggu teks klien.
Pengikatan Blok: Alternatif untuk Kunci
WordPress 6.5 memperkenalkan Pengikatan Blok API, yang menghubungkan atribut blok ke meta postingan. Alih-alih menyimpan konten yang dapat diedit di markup blok (tempat kunci melindunginya), konten disimpan di wp_postmeta (tempat sinkronisasi templat tidak dapat menyentuhnya).
<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.
</p>
Kunci meta harus didaftarkan di PHP:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Pengikatan blok memiliki dua keunggulan dibandingkan kunci: datanya dapat dikueri dengan WP_Query melalui meta_query, dan tersedia di REST API. Komprominya, Anda perlu mendaftarkan setiap kunci meta di PHP, dan pengikatan hanya berfungsi pada atribut blok individual (bukan konten bertingkat yang kompleks).
Gunakan kunci untuk bagian konten kaya yang struktur bloknya penting (grup berisi judul, paragraf, dan gambar). Gunakan pengikatan untuk nilai teks individual yang juga perlu Anda kueri atau tampilkan di tempat lain.
Templat Jenis Pos
Gunakan templateFor untuk menetapkan struktur blok default bagi semua postingan baru dari jenis tertentu:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
<h1>Product Name</h1>
<block name="core/columns">
<block name="core/column">
<img src="" alt="Product image" />
</block>
<block name="core/column">
<p>Product description goes here.</p>
<block name="core/buttons">
<block name="core/button" url="#">Buy Now</block>
</block>
</block>
</block>
<div>
<h2>Specifications</h2>
<table>
<thead>
<tr><th>Feature</th><th>Value</th></tr>
</thead>
<tbody>
<tr><td>Weight</td><td>1.2 kg</td></tr>
</tbody>
</table>
</div>
Setiap postingan “product” baru dimulai dengan struktur ini. templateLock: "insert" memungkinkan editor mengatur ulang bagian dan mengedit konten, tetapi tidak menambah atau menghapus blok.
Tips
Sinkronkan pada batas deployment yang disengaja. Jalankan wp bs pages sync setelah
mengubah atau men-deploy sumber halaman. Kunjungan frontend dan admin tidak pernah menyinkronkan
halaman. Perangkat deployment PHP dapat memanggil Blockstudio\Pages::reconcile() dan
memeriksa laporannya yang dapat dibaca mesin.
Tetapkan ID postingan yang penting. Gunakan postId di page.json untuk halaman yang dirujuk oleh menu, tautan hardcode, atau sistem eksternal. Tanpa penetapan ID, halaman yang dihapus lalu dibuat kembali akan mendapat ID baru sehingga rujukan tersebut rusak.
Gunakan sync: false untuk kerangka awal. Jika Anda ingin membuat halaman sekali lalu
menyerahkannya sepenuhnya kepada klien, tetapkan "sync": false dan buat halaman itu dengan
Blockstudio\Pages::force_sync(). Rekonsiliasi normal kemudian akan mengabaikannya.
Kunci dan buka kunci melalui PHP. Panggil Blockstudio\Pages::lock('about') untuk mencegah halaman tertentu disinkronkan (berguna selama sesi pengeditan klien). Panggil Blockstudio\Pages::unlock('about') untuk mengaktifkan kembali sinkronisasi.
Mesin templat. Selain PHP, templat dapat ditulis dalam Twig (memerlukan Timber) atau Blade (memerlukan illuminate/view). Ini berguna untuk loop dan filter, tetapi templat halaman dikompilasi saat sinkronisasi eksplisit, bukan saat permintaan frontend. Tetap gunakan PHP jika kompilasi sumber itu sendiri memerlukan helper khusus PHP.
Paksa sinkronisasi mengabaikan kunci. Memanggil Pages::force_sync('about') akan mengganti seluruh konten halaman, dengan mengabaikan kunci dan pemeriksaan waktu modifikasi. Gunakan ini saat Anda memang ingin mengatur ulang halaman ke keadaan templat.
Langkah Berikutnya
- Referensi Pages: semua properti
page.json, PHP API, dan algoritme penggabungan berkunci secara terperinci. - Ikhtisar Pages & Patterns: parser HTML, referensi sintaks blok, renderer khusus, dan pemetaan elemen.
- Patterns: sintaks templat yang sama untuk pola blok yang dapat digunakan kembali, bukan halaman.