Template del sito
I template del sito consentono ai temi a blocchi di definire origini WordPress wp_template e wp_template_part usando la stessa sintassi basata prima sui file usata per le pagine e i pattern Blockstudio.
Usate i template del sito per controllare il layout del tema selezionato da WordPress tramite la gerarchia dei template dell’Editor del sito: pagina iniziale, post singoli, archivi, ricerca, pagine 404, intestazioni, piè di pagina e altre parti dei template.
Pagine, pattern o template del sito?
| Funzionalità | Crea | Ideale per |
|---|---|---|
| Pagine | Post o voci di tipi di post personalizzati | Pagine con contenuti reali, pagine di documentazione, landing page e contenuti accessibili tramite route. |
| Pattern | Pattern di blocchi | Sezioni riutilizzabili inserite dagli editor. |
| Template del sito | Origini di file wp_template e wp_template_part |
Layout del tema controllato dall’Editor del sito e dalla gerarchia dei template WordPress. |
I template del sito non creano pagine normali. Forniscono l’origine da file usata da WordPress per risolvere un template di tema a blocchi. Se un utente personalizza il template nell’Editor del sito, WordPress salva tale personalizzazione nel database, che ha la precedenza sull’origine da file finché non viene ripristinata.
Struttura delle cartelle
Inserite i template completi in templates/ e le parti di template in parts/:
theme/
templates/
front-page/
template.json
index.php
single/
template.json
index.twig
parts/
header/
part.json
index.php
footer/
part.json
index.php
Ogni cartella contiene un manifest e un file sorgente.
| File | Motore |
|---|---|
index.php |
Markup a blocchi simile a HTML, letto così com’è (il codice PHP non viene eseguito) |
index.blade.php |
Blade |
index.twig |
Twig |
index.html |
Markup a blocchi simile a HTML |
Se sono presenti più file sorgente, Blockstudio segue questo ordine:
index.phpindex.blade.phpindex.twigindex.html
WordPress rileva anche ricorsivamente i file .html e normalmente espone un index.html nidificato con uno slug derivato dal percorso, ad esempio header/index.
Quando il file appartiene a un manifest Blockstudio, Blockstudio rimuove il duplicato derivato dal percorso ed espone solo il slug dichiarato nel manifest.
I template nativi nidificati .html senza un manifest Blockstudio non cambiano.
L’origine viene compilata una sola volta in markup nativo di blocchi WordPress. Non dovrebbe dipendere dalla richiesta corrente o dal post corrente. Inserite il comportamento runtime nei blocchi dinamici.
template.json
template.json definisce un template completo dell’Editor del sito.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template",
"postTypes": ["page"]
}
Proprietà
| Proprietà | Tipo | Predefinito | Descrizione |
|---|---|---|---|
slug / name |
string |
Nome della cartella | Slug del template WordPress. Usate slug esatti della gerarchia come front-page, single, archive-product o 404. |
title |
string |
Titolo ricavato dallo slug | Titolo visualizzato nell’Editor del sito. |
description |
string |
"" |
Descrizione visualizzata nell’Editor del sito. |
postTypes |
string[] |
[] |
Tipi di post per i template personalizzati. I template della gerarchia core possono ometterli. |
source / template / file |
string |
File index rilevato automaticamente | Percorso facoltativo del file sorgente relativo alla cartella del template. |
status |
string |
"publish" |
Stato del template. |
sync |
boolean |
false |
Riservato alla futura materializzazione nel database. Le personalizzazioni degli utenti non vengono mai sovrascritte in v1. |
meta |
object |
{} |
Metadati personalizzati per le API helper. Anche le chiavi di manifest sconosciute vengono memorizzate qui. |
Gli slug dei template non hanno prefisso. WordPress richiede nomi esatti per la gerarchia dei template:
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat
part.json
part.json definisce una parte di template dell’Editor del sito.
{
"slug": "header",
"title": "Header",
"description": "Main site header",
"area": "header"
}
Proprietà
| Proprietà | Tipo | Predefinito | Descrizione |
|---|---|---|---|
slug / name |
string |
Nome della cartella | Slug della parte di template WordPress. |
title |
string |
Titolo ricavato dallo slug | Titolo visualizzato nell’Editor del sito. |
description |
string |
"" |
Descrizione visualizzata nell’Editor del sito. |
area |
string |
"uncategorized" |
Area della parte di template. I valori comuni sono header, footer e sidebar. |
source / template / file |
string |
File index rilevato automaticamente | Percorso facoltativo del file sorgente relativo alla cartella della parte. |
status |
string |
"publish" |
Stato della parte di template. |
meta |
object |
{} |
Metadati personalizzati per le API helper. Anche le chiavi di manifest sconosciute vengono memorizzate qui. |
Creazione del markup
Le origini dei template del sito usano lo stesso parser delle pagine e dei pattern:
<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>
L’elemento <main> diventa un blocco core/group che viene visualizzato come <main>, e i suoi elementi figlio, incluso il tag del blocco core/post-content, diventano blocchi interni. Potete usare:
- elementi HTML standard come
<h1>,<p>,<ul>,<div>e gli elementi di sezione<main>,<header>,<footer>,<article>e<aside> <block name="namespace/block"><bs:namespace-block>- prefissi configurati per i tag dei blocchi
- blocchi e componenti Blockstudio
Quando WordPress esegue il rendering del template compilato, i blocchi delle parti di template ricevono l’attributo del tema attivo.
Personalizzazioni nell’Editor del sito
Blockstudio fornisce l’origine da file. WordPress gestisce le personalizzazioni degli utenti.
L’ordine di ricerca è:
- Personalizzazione nel database dell’Editor del sito
- File
.htmldel tema attivo nativo - Origine da file di Blockstudio
- Fallback del tema genitore o del plugin
Quando un utente salva nell’Editor del sito un template da file Blockstudio,
WordPress crea una normale voce di database di tipo wp_template o wp_template_part.
Questa voce salvata ha la precedenza sulle modifiche successive al file. Ripristinando o eliminando la personalizzazione, torna visibile la versione più recente dell’origine da file.
Blockstudio non riscrive nei file di v1 le modifiche apportate nell’Editor del sito.
Prestazioni
Il rilevamento dei template viene memorizzato nella cache per ogni richiesta e persistito con i metadati di monitoraggio dei file. Le modifiche a un manifest o a un file sorgente invalidano i contenuti compilati nella cache. Le personalizzazioni nel database non vengono memorizzate nella cache: WordPress continua a verificarle per prime.
Le integrazioni runtime che compongono file da più radici possono fornire una fonte di rilevamento logico per i template e le parti di template. I manifest e i template sorgente selezionati possono trovarsi in radici fisiche diverse, pur mantenendo un unico albero logico del tema.
PHP API
$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();
Passate un elenco esplicito per leggere e compilare solo slug, percorsi o percorsi sorgente esatti:
$templates = Blockstudio\Site_Templates::templates([
'front-page',
]);
$parts = Blockstudio\Site_Templates::parts([
'header',
]);
$errors = Blockstudio\Site_Templates::selection_errors('templates');
Omettendo l’argomento si mantiene il comportamento completo del registro. Passando un elenco vuoto non viene restituito alcun elemento. Le richieste basate su slug e percorsi convenzionali restringono il rilevamento alle directory corrispondenti; gli slug personalizzati definiti nel manifest possono richiedere una scansione dei metadati, ma le origini non pertinenti non vengono comunque compilate né restituite.
Sono disponibili anche funzioni helper per i template:
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');
Hook
Ecco tutti i punti di estensione dei template del sito:
| Hook | Tipo | Descrizione |
|---|---|---|
blockstudio/site_templates/template_paths |
Filtro | Modifica le radici di rilevamento dei template completi. |
blockstudio/site_templates/part_paths |
Filtro | Modifica le radici di rilevamento delle parti di template. |
blockstudio/site_templates/paths |
Filtro | Modifica entrambi gli elenchi di percorsi come templates e parts. |
blockstudio/site_templates/template_candidates |
Filtro | Modifica i file sorgente candidati per un manifest. |
blockstudio/site_templates/templates |
Filtro | Modifica i template restituiti dal registro API. |
blockstudio/site_templates/parts |
Filtro | Modifica le parti di template restituite dal registro API. |
blockstudio/site_templates/template_content |
Filtro | Modifica l’origine compilata del template completo prima dell’analisi. |
blockstudio/site_templates/part_content |
Filtro | Modifica l’origine compilata della parte di template prima dell’analisi. |
blockstudio/site_templates/parser |
Filtro | Sostituisce l’istanza di Html_Parser per un singolo elemento. |
blockstudio/site_templates/source_compiled |
Azione | Viene eseguita immediatamente prima della compilazione di un’origine selezionata. |
blockstudio/site_templates/discovered |
Azione | Viene eseguita al termine di un ciclo di rilevamento e compilazione a cache fredda. |
blockstudio/site_templates/registered |
Azione | Viene eseguita dopo il salvataggio del registro ricostruito. |
Aggiungere o sostituire i percorsi di rilevamento:
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;
});
Filtrare i dati rilevati:
add_filter('blockstudio/site_templates/templates', function ($templates) {
return $templates;
});
add_filter('blockstudio/site_templates/parts', function ($parts) {
return $parts;
});
Filtrare l’origine prima dell’analisi:
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);
Modificare le origini candidate o il parser:
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 e registered sono azioni del ciclo di ricostruzione della cache. Non vengono eseguite quando si trova una cache calda del registro.