Lewati ke konten

Templat Situs

Templat Situs memungkinkan tema blok mendefinisikan sumber WordPress wp_template dan wp_template_part dengan sintaks file-first yang sama seperti yang digunakan oleh Blockstudio halaman dan pola.

Gunakan Templat Situs jika Anda ingin mengendalikan tata letak tema yang dipilih WordPress melalui hierarki templat Site Editor: halaman depan, pos tunggal, arsip, pencarian, halaman 404, header, footer, dan bagian templat lainnya.

Halaman, Pola, atau Templat Situs?

Fitur Membuat Cocok untuk
Halaman Pos atau entri jenis pos kustom Halaman konten sungguhan, halaman dokumentasi, halaman arahan, dan konten yang dapat dirutekan.
Pola Pola blok Bagian yang dapat digunakan kembali dan disisipkan oleh editor.
Templat Situs Sumber berkas wp_template dan wp_template_part Tata letak tema yang dikendalikan oleh Site Editor dan hierarki templat WordPress.

Templat Situs tidak membuat halaman biasa. Templat ini menyediakan sumber berkas yang digunakan WordPress saat menentukan templat tema blok. Jika pengguna menyesuaikan templat di Site Editor, WordPress menyimpan penyesuaian tersebut di basis data dan mengutamakannya daripada sumber berkas sampai disetel ulang.

Struktur Folder

Tempatkan templat lengkap di templates/ dan bagian templat di parts/:

Text
theme/
  templates/
    front-page/
      template.json
      index.php
    single/
      template.json
      index.twig
  parts/
    header/
      part.json
      index.php
    footer/
      part.json
      index.php

Setiap folder memiliki manifest serta satu berkas sumber.

Berkas Mesin
index.php Markup blok mirip HTML, dibaca apa adanya (kode PHP tidak dijalankan)
index.blade.php Blade
index.twig Twig
index.html Markup blok mirip HTML

Jika ada beberapa berkas sumber, Blockstudio menggunakan urutan berikut:

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.html

WordPress juga menemukan berkas .html secara rekursif dan biasanya menampilkan index.html bersarang dengan slug yang diturunkan dari jalurnya, seperti header/index. Jika berkas tersebut termasuk dalam manifest Blockstudio, Blockstudio menghapus duplikat yang diturunkan dari jalur dan hanya menampilkan slug yang dideklarasikan dalam manifest. Templat .html native bersarang tanpa manifest Blockstudio tidak berubah.

Sumber dikompilasi satu kali menjadi markup blok WordPress native. Sumber tidak seharusnya bergantung pada permintaan saat ini atau pos saat ini. Tempatkan perilaku runtime di dalam blok dinamis.

template.json

template.json mendefinisikan templat Site Editor lengkap.

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template",
  "postTypes": ["page"]
}

Properti

Properti Jenis Default Deskripsi
slug / name string Nama folder Slug templat WordPress. Gunakan slug hierarki yang tepat seperti front-page, single, archive-product, atau 404.
title string Judul dari slug Judul yang ditampilkan di Site Editor.
description string "" Deskripsi yang ditampilkan di Site Editor.
postTypes string[] [] Jenis pos untuk templat kustom. Templat hierarki inti dapat menghilangkan ini.
source / template / file string Berkas indeks terdeteksi otomatis Jalur berkas sumber opsional relatif terhadap folder templat.
status string "publish" Status templat.
sync boolean false Dicadangkan untuk materialisasi basis data di masa mendatang. Penyesuaian pengguna tidak pernah ditimpa di v1.
meta object {} Metadata kustom untuk API helper. Kunci manifest yang tidak dikenal juga disimpan di sini.

Slug templat tidak diberi awalan. WordPress memerlukan nama yang tepat untuk hierarki templat:

Text
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat

part.json

part.json mendefinisikan bagian templat Site Editor.

JSON
{
  "slug": "header",
  "title": "Header",
  "description": "Main site header",
  "area": "header"
}

Properti

Properti Jenis Default Deskripsi
slug / name string Nama folder Slug bagian templat WordPress.
title string Judul dari slug Judul yang ditampilkan di Site Editor.
description string "" Deskripsi yang ditampilkan di Site Editor.
area string "uncategorized" Area bagian templat. Nilai umum meliputi header, footer, dan sidebar.
source / template / file string Berkas indeks terdeteksi otomatis Jalur berkas sumber opsional relatif terhadap folder bagian.
status string "publish" Status bagian templat.
meta object {} Metadata kustom untuk API helper. Kunci manifest yang tidak dikenal juga disimpan di sini.

Menulis Markup

Sumber Templat Situs menggunakan parser yang sama dengan halaman dan pola:

PHP
<div class="site-shell">
  <block name="core/template-part" slug="header" />

  <main>
    <h1>Welcome</h1>
    <p>This template is compiled from Blockstudio files.</p>
    <block name="core/post-content" />
  </main>

  <block name="core/template-part" slug="footer" />
</div>

Elemen <main> menjadi blok core/group yang dirender sebagai <main>, dan anak-anaknya, termasuk tag blok core/post-content, menjadi blok dalamnya. Anda dapat menggunakan:

  • elemen HTML standar seperti <h1>, <p>, <ul>, <div>, serta elemen pembagian bagian <main>, <header>, <footer>, <article>, dan <aside>
  • <block name="namespace/block">
  • <bs:namespace-block>
  • prefiks tag blok yang dikonfigurasi
  • blok dan komponen Blockstudio

Blok bagian templat menerima atribut tema aktif saat WordPress merender templat yang dikompilasi.

Penyesuaian Site Editor

Blockstudio menyediakan sumber berkas. WordPress menyimpan penyesuaian pengguna.

Urutan pencariannya:

  1. Penyesuaian di basis data Site Editor
  2. Berkas .html tema aktif native
  3. Sumber berbasis berkas Blockstudio
  4. Tema induk atau fallback plugin

Saat pengguna menyimpan templat berbasis berkas Blockstudio di Site Editor, WordPress membuat entri basis data wp_template atau wp_template_part biasa. Entri tersimpan tersebut mengutamakan isinya daripada perubahan berkas berikutnya. Menyetel ulang atau menghapus penyesuaian akan menampilkan kembali sumber berbasis berkas terbaru.

Blockstudio tidak menulis perubahan Site Editor kembali ke berkas di v1.

Performa

Penemuan templat di-cache per permintaan dan disimpan dengan metadata pemantauan berkas. Perubahan pada manifest atau berkas sumber membatalkan konten kompilasi yang di-cache. Penyesuaian basis data tidak di-cache: WordPress tetap memeriksanya terlebih dahulu.

Integrasi runtime yang menggabungkan berkas dari beberapa akar dapat menyediakan sumber penemuan logis untuk templat dan bagian templat. Manifest dan templat sumber yang dipilih dapat berada di akar fisik yang berbeda, amun tetap menjadi satu pohon tema logis.

PHP API

PHP
$templates = Blockstudio\Site_Templates::templates();
$parts = Blockstudio\Site_Templates::parts();

$template = Blockstudio\Site_Templates::get_template('front-page');
$header = Blockstudio\Site_Templates::get_part('header');

$paths = Blockstudio\Site_Templates::get_paths();

Teruskan daftar eksplisit untuk membaca dan mengompilasi hanya slug, jalur, atau jalur sumber tertentu:

PHP
$templates = Blockstudio\Site_Templates::templates([
    'front-page',
]);

$parts = Blockstudio\Site_Templates::parts([
    'header',
]);

$errors = Blockstudio\Site_Templates::selection_errors('templates');

Menghilangkan argumen akan mempertahankan perilaku registri lengkap. Meneruskan daftar kosong akan menghasilkan tanpa item. Permintaan slug dan jalur konvensional mempersempit penemuan ke direktori yang cocok; slug manifest kustom mungkin memerlukan pemindaian metadata, tetapi sumber yang tidak terkait tetap tidak dikompilasi atau dikembalikan.

Fungsi helper templat juga tersedia:

PHP
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');

Hook

Daftar lengkap ekstensi Templat Situs:

Hook Jenis Deskripsi
blockstudio/site_templates/template_paths Filter Menyesuaikan akar penemuan templat lengkap.
blockstudio/site_templates/part_paths Filter Menyesuaikan akar penemuan bagian templat.
blockstudio/site_templates/paths Filter Menyesuaikan kedua daftar jalur sebagai templates dan parts.
blockstudio/site_templates/template_candidates Filter Menyesuaikan kandidat berkas sumber untuk manifest.
blockstudio/site_templates/templates Filter Menyesuaikan templat yang dikembalikan oleh registri API.
blockstudio/site_templates/parts Filter Menyesuaikan bagian templat yang dikembalikan oleh registri API.
blockstudio/site_templates/template_content Filter Menyesuaikan sumber templat lengkap yang dikompilasi sebelum parsing.
blockstudio/site_templates/part_content Filter Menyesuaikan sumber bagian templat yang dikompilasi sebelum parsing.
blockstudio/site_templates/parser Filter Mengganti instance Html_Parser untuk satu item.
blockstudio/site_templates/source_compiled Tindakan Berjalan tepat sebelum satu sumber terpilih dikompilasi.
blockstudio/site_templates/discovered Tindakan Berjalan setelah proses penemuan dan kompilasi dingin.
blockstudio/site_templates/registered Tindakan Berjalan setelah registri yang dibangun ulang tersebut disimpan secara persisten.

Menambahkan atau mengganti jalur penemuan:

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;
});

add_filter('blockstudio/site_templates/paths', function ($paths) {
    return $paths;
});

Memfilter data yang ditemukan:

PHP
add_filter('blockstudio/site_templates/templates', function ($templates) {
    return $templates;
});

add_filter('blockstudio/site_templates/parts', function ($parts) {
    return $parts;
});

Memfilter sumber sebelum parsing:

PHP
add_filter('blockstudio/site_templates/template_content', function ($content, $template) {
    return $content;
}, 10, 2);

add_filter('blockstudio/site_templates/part_content', function ($content, $part) {
    return $content;
}, 10, 2);

Mengubah kandidat sumber atau parser:

PHP
add_filter(
    'blockstudio/site_templates/template_candidates',
    function ($candidates, $directory, $manifest) {
        $candidates[] = $directory . '/template.custom.php';
        return $candidates;
    },
    10,
    3
);

add_filter(
    'blockstudio/site_templates/parser',
    function ($parser, $item) {
        return $parser;
    },
    10,
    2
);

discovered dan registered adalah tindakan siklus hidup pembangunan ulang cache. Keduanya tidak berjalan saat cache registri hangat ditemukan.