Lewati ke konten

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:

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

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

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

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

Sebuah bagian bisa sesingkat satu paragraf. Contoh ini menggunakan index.html untuk menegaskan bahwa sumbernya adalah markup, bukan program:

JSON
{
  "slug": "footer",
  "title": "Footer",
  "area": "footer"
}
HTML
<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.

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template"
}
PHP
<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:

JSON
{
  "slug": "single",
  "title": "Single Post"
}
PHP
<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:

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

JSON
{
  "slug": "page-landing",
  "title": "Landing Page",
  "description": "Full-width page without a header",
  "postTypes": ["page"]
}
PHP
<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:

  1. Kustomisasi Site Editor yang disimpan di basis data.
  2. File native .html di tema aktif.
  3. Sumber berbasis file Blockstudio.
  4. 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:

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

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

PHP
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