Șabloane și părți ale editorului de site din fișiere
O temă cu blocuri își descrie aspectul în templates/*.html și parts/*.html:
fișiere pline cu comentarii de bloc serializate, precum
<!-- wp:template-part {"slug":"header"} /-->. Nimănui nu-i place să le scrie
manual, așa că de obicei sunt create în Editorul de site și exportate. Acest lucru funcționează
până când două persoane editează același șablon sau un evaluator trebuie să citească o diferență între
comentariile HTML care conțin JSON escapate.
Blockstudio vă permite să scrieți aceleași șabloane la fel ca paginile bazate pe fișiere:
un folder cu un mic manifest JSON și un fișier sursă cu marcaj de tip HTML,
folosind elemente simple, etichete <block> și propriile blocuri Blockstudio.
Blockstudio compilează sursa în marcaj nativ cu blocuri și o transmite către WordPress
ca fișier de temă. Editorul de site funcționează în continuare exact ca înainte: utilizatorii pot
personaliza un șablon, iar resetarea lui readuce versiunea din fișier.
Acest ghid creează o parte pentru antet și una pentru subsol, șabloane pentru pagina principală și pentru articole individuale, precum și un șablon personalizat pe care editorii îl pot selecta pentru pagini, apoi arată cum le rezolvă WordPress.
Structura folderelor
Șabloanele se află în templates/, iar părțile de șablon în parts/. Fiecare este un folder
cu un manifest și un fișier sursă:
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
Acestea sunt aceleași foldere templates/ și parts/ pe care le citește WordPress pentru o temă
cu blocuri. Blockstudio scanează mai întâi tema activă, apoi tema părinte.
Folderele cu template.json sau part.json sunt surse Blockstudio; fișierele simple
.html din apropiere rămân șabloane native WordPress.
Fișierul sursă poate fi index.php, index.blade.php, index.twig sau
index.html, verificate în această ordine. Twig necesită Timber, iar Blade necesită pachetul său de randare, după cum se explică în
Motoare de șabloane.
Pasul 1: Partea de antet
Fiecare parte are nevoie de un part.json. area indică Editorului de site unde
aparține partea:
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
Sursa folosește aceeași sintaxă ca paginile și modelele Blockstudio. Un <div>
devine un bloc de grup, atributele devin atribute ale blocului, iar elementele <block>
generează orice bloc înregistrat:
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
Blockstudio compilează sursa în acest marcaj de bloc:
<!-- 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 -->
Acesta este marcajul pe care altfel l-ați fi scris manual. Blocurile proprii funcționează
la fel: <block name="acme/announcement" />, o etichetă <bs:acme-announcement />
sau un prefix de etichetă configurat se compilează toate în comentariul blocului respectiv.
Pasul 2: Partea de subsol
O parte poate fi cât de mică, de exemplu, un singur paragraf. Aceasta folosește index.html pentru a sublinia
că sursa este marcaj, nu un program:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
Se compilează în <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.
Pasul 3: Pagina principală și șabloanele pentru articole individuale
Șabloanele folosesc template.json. slug trebuie să fie exact numele WordPress al ierarhiei șabloanelor,
precum front-page, single, page, archive, 404 sau
single-product. Blockstudio nu îl prefixează niciodată.
{
"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" />
Șablonul pentru un singur articol urmează aceeași structură, cu blocuri pentru articole:
{
"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" />
Șablonul compilat pentru un singur articol:
<!-- 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> a devenit un bloc de grup cu tagName: "main", iar blocurile pentru părțile de șablon fac referire la părțile din pașii 1 și 2 folosind slug-ul. Când WordPress randează șablonul, referințele indică părțile din fișiere, astfel încât rezultatul paginii principale începe cu <header class="wp-block-template-part"> care conține titlul site-ului și navigarea și se încheie cu <footer class="wp-block-template-part"> care conține paragraful din subsol.
Pasul 4: Un șablon personalizat pentru pagini
Șabloanele al căror slug nu face parte din ierarhie sunt șabloane personalizate. Enumerați tipurile de articole cărora li se aplică folosind postTypes, iar editorii le pot alege din selectorul de șabloane:
{
"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' ) include acum page-landing, iar obiectul șablonului conține post_types: ["page"].
Sursele sunt compilate o singură dată
Sursa este citită și compilată o singură dată în marcaj de bloc, nu la fiecare cerere. Nu există niciun articol curent sau context al cererii. index.php este citit ca marcaj: codul PHP din acesta nu se execută, așa că <?php echo get_bloginfo( 'name' ); ?> se compilează în nimic. Orice depinde de cerere trebuie să fie într-un bloc randat în timpul execuției: core/site-title în locul unui nume de site afișat, core/post-title în loc de the_title() sau un bloc dinamic Blockstudio propriu.
Rezultatele compilării sunt memorate în cache împreună cu metadatele de monitorizare a fișierelor. Editarea unui manifest sau a unui fișier sursă invalidează conținutul memorat pentru acel element, astfel încât următoarea cerere să reflecte schimbarea fără o etapă de compilare separată.
Cum vede WordPress fișierele
Blockstudio se integrează în aceleași căutări pe care le folosește WordPress pentru șabloanele temei. În get_block_templates(), șabloanele din fișiere apar cu source: "theme" și origin: "theme", la fel ca fișierele native ale temei, iar get_block_template( 'acme//header', 'wp_template_part' ) returnează partea de antet cu area.
Ordinea de căutare este:
- O personalizare a Editorului de site stocată în baza de date.
- Un fișier nativ
.htmldin tema activă. - Sursa Blockstudio bazată pe fișiere.
- Fallback-uri din tema părinte sau din pluginuri.
Această ordine păstrează intact fluxul de lucru din Editorul de site. Când un utilizator editează subsolul și salvează, WordPress stochează un articol wp_template_part, iar get_block_template() returnează acea personalizare cu source: "custom". Modificările ulterioare din parts/footer/index.html nu se afișează cât timp există personalizarea. Când utilizatorul resetează partea sau articolul este șters, căutarea revine la fișier și returnează din nou cea mai recentă versiune compilată a sursei.
Blockstudio nu scrie în fișiere modificările făcute în Editorul de site. Dacă modificarea unui utilizator trebuie să devină noua valoare implicită, copiați-o în fișierul sursă și resetați personalizarea.
Foldere imbricate index.html și slug-uri
WordPress detectează recursiv fișierele .html din templates/ și parts/. Prin urmare, un folder cu manifest care folosește index.html, precum parts/footer/index.html, ar apărea și ca parte nativă, cu slug-ul derivat din cale footer/index. Deoarece Blockstudio 7.6.6, un index.html deținut de manifest este expus doar sub slug-ul declarat, astfel încât Editorul de site afișează un singur subsol, nu două. Fișierele .html imbricate fără manifest sunt lăsate neschimbate.
Verificarea șabloanelor din PHP
Clasa Blockstudio\Site_Templates citește și compilează sursele, ceea ce este util în teste și verificări de implementare:
$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();
Fiecare element include slug, title, description, type (wp_template sau wp_template_part), status, source_type, postTypes pentru șabloane sau area pentru părți, meta și content compilat. Transmiteți o listă pentru a compila doar elementele selectate și citiți problemele pentru acea selecție cu selection_errors():
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
Adăugarea altor foldere
Pentru a separa sursele Blockstudio de șabloanele native sau pentru a le livra dintr-un plugin, adăugați rădăcini de descoperire cu filtre:
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;
} );
Filtrele blockstudio/site_templates/template_content și part_content ajustează o sursă înainte de analiză, iar blockstudio/site_templates/parser înlocuiește analizatorul pentru un element. Lista completă se află în tabelul de hook-uri Referință pentru șabloanele site-ului.
Când să folosiți fiecare variantă
| Ce doriți | Folosiți |
|---|---|
| Aspectul temei ales de WordPress pentru un URL: antet, subsol, articol individual, arhivă | Șabloane și părți de site |
| O pagină accesibilă printr-o rută, cu conținutul în fișiere | Pagini bazate pe fișiere |
| O secțiune reutilizabilă pe care editorii o inserează | Modele |
Șabloanele nu creează articole. Paginile, da. De exemplu, o secțiune de documentație este o colecție de pagini ale cărei articole sunt randate printr-un șablon pe care îl puteți crea tot aici.
Pașii următori
- Referință pentru șabloanele site-ului: toate proprietățile manifestului, PHP API și toate hook-urile.
- Prezentare generală a paginilor și modelelor: analizatorul HTML, etichetele de bloc și asocierea elementelor folosite de sursele șabloanelor.
- Crearea unui site de documentație: colecții de pagini cu Markdown, încărcătoare și machete.