Template dan Bagian Site Editor dari File
Tema blok menjelaskan tata letaknya di templates/*.html dan parts/*.html:
file yang penuh dengan komentar blok terserialisasi seperti
<!-- wp:template-part {"slug":"header"} /-->. Tak ada yang suka menulisnya
secara manual, jadi biasanya file tersebut dibuat di Site Editor lalu diekspor. Cara ini berjalan baik
sampai dua orang mengedit template yang sama, atau peninjau harus membaca diff
JSON yang di-escape di komentar HTML.
Blockstudio memungkinkan Anda menulis template yang sama seperti saat menulis
halaman berbasis file: sebuah folder dengan manifes JSON kecil dan file sumber dengan markup mirip HTML,
menggunakan elemen biasa, tag <block>, dan blok Blockstudio Anda sendiri.
Blockstudio mengompilasi sumber menjadi markup blok native dan menyerahkannya ke WordPress sebagai file tema. Site Editor tetap berfungsi seperti biasa: pengguna dapat
menyesuaikan template, dan saat direset, versi dari file akan dipulihkan.
Panduan ini membuat bagian header dan footer, template halaman depan dan tunggal, serta template khusus yang dapat dipilih editor untuk halaman, lalu menunjukkan cara WordPress menyelesaikannya.
Struktur Folder
Template disimpan di templates/, sedangkan bagian template disimpan di parts/. Masing-masing berupa folder
berisi manifes dan satu file sumber:
theme/
├── templates/
│ ├── front-page/
│ │ ├── template.json
│ │ └── index.php
│ ├── single/
│ │ ├── template.json
│ │ └── index.php
│ └── page-landing/
│ ├── template.json
│ └── index.php
└── parts/
├── header/
│ ├── part.json
│ └── index.php
└── footer/
├── part.json
└── index.html
Folder templates/ dan parts/ ini sama dengan folder yang dibaca WordPress untuk tema
blok. Blockstudio memindai tema aktif terlebih dahulu, lalu tema induk.
Folder dengan template.json atau part.json merupakan sumber Blockstudio; file .html biasa di sebelahnya tetap menjadi template WordPress native.
File sumber dapat berupa index.php, index.blade.php, index.twig, atau
index.html, yang diperiksa sesuai urutan tersebut. Twig memerlukan Timber dan Blade memerlukan paket renderer-nya, seperti dijelaskan di
Mesin Template.
Langkah 1: Bagian Header
Setiap bagian memerlukan part.json. area memberi tahu Site Editor tempat bagian tersebut
diletakkan:
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
Sumbernya menggunakan sintaks yang sama dengan halaman dan pola Blockstudio. Sebuah <div>
menjadi blok grup, atribut menjadi atribut blok, dan elemen <block>
menghasilkan blok apa pun yang terdaftar:
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
Blockstudio mengompilasinya menjadi markup blok berikut:
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} --><div class="wp-block-group is-layout-flex"><!-- wp:site-title /--><!-- wp:navigation {"overlayMenu":"mobile"} /--></div><!-- /wp:group -->
Itulah yang biasanya Anda tulis secara manual. Blok Anda sendiri bekerja dengan
cara yang sama: <block name="acme/announcement" />, tag <bs:acme-announcement />,
atau awalan tag yang dikonfigurasi, semuanya dikompilasi menjadi komentar blok untuk blok tersebut.
Langkah 2: Bagian Footer
Sebuah bagian bisa sesingkat satu paragraf. Contoh ini menggunakan index.html untuk menegaskan
bahwa sumbernya adalah markup, bukan program:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
Hasil kompilasinya adalah <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.
Langkah 3: Template Halaman Depan dan Tunggal
Template menggunakan template.json. slug harus berupa nama hierarki template WordPress yang tepat,
seperti front-page, single, page, archive, 404, atau
single-product. Blockstudio tidak pernah menjadi awalan untuk nama tersebut.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
Template pos tunggal mengikuti struktur yang sama dengan blok pos:
{
"slug": "single",
"title": "Single Post"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-title" level="1" />
<block name="core/post-date" />
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
Template tunggal hasil kompilasi:
<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-title {"level":1} /--><!-- wp:post-date /--><!-- wp:post-content /--></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
<main> menjadi blok grup dengan tagName: "main", dan blok bagian template merujuk bagian dari langkah 1 dan 2 melalui slug. Saat WordPress merender template, referensi tersebut mengarah ke bagian yang berasal dari file. Dengan demikian, keluaran halaman depan dimulai dengan <header class="wp-block-template-part"> yang berisi judul situs dan navigasi, lalu diakhiri dengan <footer class="wp-block-template-part"> yang berisi paragraf footer.
Langkah 4: Template Khusus untuk Halaman
Template dengan slug yang bukan bagian dari hierarki merupakan template khusus. Cantumkan jenis pos yang berlaku dengan postTypes, lalu editor dapat memilihnya di pemilih template:
{
"slug": "page-landing",
"title": "Landing Page",
"description": "Full-width page without a header",
"postTypes": ["page"]
}
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
get_block_templates( array( 'post_type' => 'page' ), 'wp_template' ) kini
mencakup page-landing, dan objek template membawa post_types: ["page"].
Sumber Dikompilasi Satu Kali
Sumber dibaca dan dikompilasi menjadi markup blok satu kali, bukan setiap permintaan. Sumber tidak memiliki pos saat ini maupun konteks permintaan. index.php dibaca sebagai markup: kode PHP di dalamnya tidak dijalankan, sehingga <?php echo get_bloginfo( 'name' ); ?> dikompilasi menjadi kosong. Semua hal yang bergantung pada permintaan harus berada dalam blok yang dirender saat runtime: core/site-title alih-alih nama situs yang dicetak langsung, core/post-title alih-alih the_title(), atau blok Blockstudio dinamis buatan Anda sendiri.
Hasil kompilasi di-cache bersama metadata pemantauan file. Mengedit manifes atau file sumber membatalkan cache konten item tersebut, sehingga permintaan berikutnya melihat perubahan tanpa langkah build terpisah.
Cara WordPress Mengenali File
Blockstudio terhubung ke pencarian yang sama dengan yang digunakan WordPress untuk template tema. Di get_block_templates(), template berbasis file muncul dengan source: "theme" dan origin: "theme", sama seperti file tema native, dan get_block_template( 'acme//header', 'wp_template_part' ) mengembalikan bagian header beserta area-nya.
Urutan pencariannya:
- Kustomisasi Site Editor yang disimpan di basis data.
- File native
.htmldi tema aktif. - Sumber berbasis file Blockstudio.
- Fallback dari tema induk atau plugin.
Urutan ini mempertahankan alur kerja Site Editor. Saat pengguna mengedit footer lalu menyimpannya, WordPress menyimpan pos wp_template_part, dan get_block_template() mengembalikan kustomisasi tersebut dengan source: "custom".
Perubahan berikutnya pada parts/footer/index.html tidak akan terlihat selama kustomisasi masih ada. Saat pengguna mereset bagian tersebut atau posnya dihapus, pencarian kembali menggunakan file dan mengembalikan sumber hasil kompilasi terbaru.
Blockstudio tidak menulis perubahan Site Editor kembali ke file. Jika perubahan pengguna ingin dijadikan nilai default baru, salin ke file sumber lalu reset kustomisasinya.
index.html dan Slug Bertingkat
WordPress menemukan file .html secara rekursif di templates/ dan parts/. Karena itu, folder manifes yang menggunakan index.html, seperti parts/footer/index.html, juga akan muncul sebagai bagian native dengan slug yang diambil dari jalur footer/index. Karena Blockstudio 7.6.6, index.html yang dikelola manifes hanya ditampilkan dengan slug yang dideklarasikannya, sehingga Site Editor menampilkan satu footer, bukan dua. File .html bertingkat tanpa manifes dibiarkan begitu saja.
Memeriksa Template dari PHP
Kelas Blockstudio\Site_Templates membaca dan mengompilasi sumber, yang berguna dalam pengujian dan pemeriksaan deployment:
$templates = Blockstudio\Site_Templates::templates();
$header = Blockstudio\Site_Templates::get_part( 'header' );
echo $header['area']; // header
echo $header['content']; // compiled block markup
$errors = Blockstudio\Site_Templates::errors();
Setiap item mencakup slug, title, description, type (wp_template atau wp_template_part), status, source_type, postTypes untuk template atau area untuk bagian, meta, serta content hasil kompilasi. Berikan daftar untuk hanya mengompilasi item tertentu, dan baca masalah untuk pilihan tersebut dengan selection_errors():
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
Menambahkan Folder Lain
Untuk memisahkan sumber Blockstudio dari template native, atau menyediakannya lewat plugin, tambahkan lokasi penemuan dengan filter:
add_filter( 'blockstudio/site_templates/template_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-templates';
return $paths;
} );
add_filter( 'blockstudio/site_templates/part_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-parts';
return $paths;
} );
Filter blockstudio/site_templates/template_content dan part_content menyesuaikan sumber sebelum diurai, sedangkan blockstudio/site_templates/parser mengganti pengurai untuk satu item. Daftar lengkapnya ada di tabel hook Template Situs.
Kapan Menggunakan yang Mana
| Yang Anda inginkan | Gunakan |
|---|---|
| Tata letak tema yang dipilih WordPress untuk URL: header, footer, tunggal, arsip | Template dan bagian situs |
| Halaman yang dapat diakses lewat rute dengan konten di dalam file | Halaman berbasis file |
| Bagian yang dapat digunakan ulang dan disisipkan editor | Pola |
Template tidak membuat pos. Halamanlah yang membuatnya. Misalnya, bagian dokumentasi adalah koleksi halaman yang pos-posnya dirender melalui template yang tetap dapat Anda buat di sini.
Langkah Berikutnya
- Referensi Template Situs: setiap properti manifes, PHP API, dan semua hook.
- Ikhtisar Halaman & Pola: pengurai HTML, tag blok, dan pemetaan elemen yang digunakan oleh sumber template.
- Membangun Situs Dokumentasi: koleksi halaman dengan Markdown, loader, dan tata letak.