Treci la conținut

Șabloane de site

Șabloanele de site permit temelor bazate pe blocuri să definească surse WordPress wp_template și wp_template_part folosind aceeași sintaxă bazată pe fișiere ca paginile și modelele Blockstudio.

Folosiți șabloanele de site când doriți să controlați macheta temei pe care WordPress o selectează prin ierarhia de șabloane a Editorului site-ului: pagina principală, articole individuale, arhive, căutare, pagini 404, antete, subsoluri și alte părți de șablon.

Pagini, modele sau șabloane de site?

Funcționalitate Creează Potrivit pentru
Pagini Articole sau intrări de tip de articol personalizat Pagini cu conținut real, pagini de documentație, pagini de destinație și conținut accesibil prin rute.
Modele Modele de blocuri Secțiuni reutilizabile inserate de editori.
Șabloane de site Surse de fișiere wp_template și wp_template_part Machetă de temă controlată de Editorul site-ului și ierarhia de șabloane WordPress.

Șabloanele de site nu creează pagini obișnuite. Ele furnizează sursa de fișier folosită de WordPress la rezolvarea unui șablon de temă bazată pe blocuri. Dacă un utilizator personalizează șablonul în Editorul site-ului, WordPress stochează personalizarea în baza de date, iar aceasta are prioritate față de sursa din fișier până la resetare.

Structura folderelor

Plasați șabloanele complete în templates/ și părțile de șablon în 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

Fiecare dosar conține un manifest și un fișier sursă.

Fișier Motor
index.php Marcaj de blocuri de tip HTML, citit ca atare (codul PHP nu se execută)
index.blade.php Blade
index.twig Twig
index.html Marcaj de blocuri de tip HTML

Dacă există mai multe fișiere sursă, Blockstudio folosește această ordine:

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

WordPress descoperă recursiv și fișiere .html și expune în mod obișnuit un index.html imbricat sub slugul derivat din calea sa, precum header/index. Când acel fișier aparține unui manifest Blockstudio, Blockstudio elimină duplicatul derivat din cale și expune doar slug declarat în manifest. Șabloanele native .html imbricate fără manifest Blockstudio rămân neschimbate.

Sursa este compilată o singură dată în marcaj de blocuri nativ WordPress. Nu ar trebui să depindă de cererea curentă sau de articolul curent. Plasați comportamentul de execuție în blocuri dinamice.

template.json

template.json definește un șablon complet pentru Editorul site-ului.

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

Proprietăți

Proprietate Tip Valoare implicită Descriere
slug / name string Numele dosarului Slugul șablonului WordPress. Folosiți sluguri exacte din ierarhie, precum front-page, single, archive-product sau 404.
title string Titlul derivat din slug Titlul afișat în Editorul site-ului.
description string "" Descrierea afișată în Editorul site-ului.
postTypes string[] [] Tipuri de articole pentru șabloane personalizate. Șabloanele ierarhiei de bază pot omite acest câmp.
source / template / file string Fișier index detectat automat Calea opțională a fișierului sursă, relativă la dosarul șablonului.
status string "publish" Starea șablonului.
sync boolean false Rezervat pentru materializare viitoare în baza de date. Personalizările utilizatorilor nu sunt suprascrise niciodată în v1.
meta object {} Metadate personalizate pentru API-urile helper. Cheile necunoscute din manifest sunt stocate și aici.

Slugurile șabloanelor nu au prefix. WordPress are nevoie de nume exacte pentru ierarhia de șabloane:

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 definește o parte de șablon pentru Editorul site-ului.

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

Proprietăți

Proprietate Tip Valoare implicită Descriere
slug / name string Numele dosarului Slugul părții de șablon WordPress.
title string Titlul derivat din slug Titlul afișat în Editorul site-ului.
description string "" Descrierea afișată în Editorul site-ului.
area string "uncategorized" Zona părții de șablon. Valorile uzuale sunt header, footer și sidebar.
source / template / file string Fișier index detectat automat Calea opțională a fișierului sursă, relativă la dosarul părții.
status string "publish" Starea părții de șablon.
meta object {} Metadate personalizate pentru API-urile helper. Cheile necunoscute din manifest sunt stocate și aici.

Scrierea marcajului

Sursele Site Template folosesc același parser ca paginile și modelele:

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>

Elementul <main> devine un bloc core/group care se redă ca <main>, iar copiii săi, inclusiv eticheta de bloc core/post-content, devin blocurile sale interne. Puteți folosi:

  • elemente HTML standard, precum <h1>, <p>, <ul>, <div> și elementele de secționare <main>, <header>, <footer>, <article> și <aside>
  • <block name="namespace/block">
  • <bs:namespace-block>
  • prefixe configurate pentru etichetele blocurilor
  • blocuri și componente Blockstudio

Blocurile de părți de șablon primesc atributul temei active atunci când WordPress redă șablonul compilat.

Personalizări în Editorul site-ului

Blockstudio furnizează sursa din fișier. WordPress gestionează personalizările utilizatorilor.

Ordinea de căutare este:

  1. Personalizarea din baza de date a Editorului site-ului
  2. Fișierul nativ .html al temei active
  3. Sursa bazată pe fișiere Blockstudio
  4. Fallback-uri din tema părinte sau plugin

Când un utilizator salvează în Editorul site-ului un șablon bazat pe fișier Blockstudio, WordPress creează o intrare obișnuită de bază de date wp_template sau wp_template_part. Acea intrare salvată are prioritate față de modificările ulterioare ale fișierului. Resetarea sau ștergerea personalizării dezvăluie din nou cea mai recentă sursă bazată pe fișier.

Blockstudio nu scrie modificările din Editorul site-ului înapoi în fișierele din v1.

Performanță

Descoperirea șabloanelor este memorată în cache per cerere și persistentă împreună cu metadatele de monitorizare a fișierelor. Modificarea unui manifest sau a unui fișier sursă invalidează conținutul compilat din cache. Personalizările din baza de date nu sunt memorate în cache: WordPress le verifică în continuare mai întâi.

Integrările de execuție care combină fișiere din mai multe rădăcini pot furniza o sursă logică de descoperire pentru șabloane și părți de șablon. Manifestele și șabloanele sursă selectate se pot afla în rădăcini fizice diferite, păstrând totodată un singur arbore logic al temei.

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

Transmiteți o listă explicită pentru a citi și compila numai sluguri, căi sau căi sursă exacte:

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

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

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

Omiterea argumentului păstrează comportamentul complet al registrului. Transmiterea unei liste goale nu returnează niciun element. Cererile pentru sluguri și căi convenționale restrâng descoperirea la directoarele corespunzătoare; slugurile personalizate din manifest pot necesita o scanare a metadatelor, însă sursele fără legătură tot nu sunt compilate sau returnate.

Sunt disponibile și funcții helper pentru șabloane:

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

Hook-uri

Suprafața completă de extensie Site Template este:

Cârlig Tip Descriere
blockstudio/site_templates/template_paths Filtru Ajustează rădăcinile de descoperire a șabloanelor complete.
blockstudio/site_templates/part_paths Filtru Ajustează rădăcinile de descoperire a părților de șablon.
blockstudio/site_templates/paths Filtru Ajustează ambele liste de căi ca templates și parts.
blockstudio/site_templates/template_candidates Filtru Ajustează fișierele sursă candidate pentru un manifest.
blockstudio/site_templates/templates Filtru Ajustează șabloanele returnate de registrul API.
blockstudio/site_templates/parts Filtru Ajustează părțile de șablon returnate de registrul API.
blockstudio/site_templates/template_content Filtru Ajustează sursa șablonului complet compilat înainte de analizare.
blockstudio/site_templates/part_content Filtru Ajustează sursa părții de șablon compilate înainte de analizare.
blockstudio/site_templates/parser Filtru Înlocuiește instanța Html_Parser pentru un element.
blockstudio/site_templates/source_compiled Acțiune Se execută imediat înainte de compilarea unei surse selectate.
blockstudio/site_templates/discovered Acțiune Se execută după o trecere de descoperire și compilare fără date în cache.
blockstudio/site_templates/registered Acțiune Se execută după ce registrul reconstruit este persistentizat.

Adăugați sau înlocuiți căi de descoperire:

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

Filtrați datele descoperite:

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

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

Filtrați sursa înainte de analizare:

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

Modificați sursele candidate sau parserul:

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 și registered sunt acțiuni din ciclul de reconstrucție a memoriei cache. Ele nu se execută la o accesare din cache a unui registru deja încărcat.