Vai al contenuto

Template e parti dell’editor del sito da file

Un tema a blocchi descrive il layout in templates/*.html e parts/*.html: file che contengono commenti di blocco serializzati come <!-- wp:template-part {"slug":"header"} /-->. A nessuno piace scriverli a mano, quindi di solito vengono creati nell’editor del sito e poi esportati. Funziona fino a quando due persone modificano lo stesso template o un revisore deve leggere un diff di JSON con caratteri di escape nei commenti HTML.

Blockstudio permette di scrivere gli stessi template come si scrivono le pagine basate su file: una cartella con un piccolo manifest JSON e un file sorgente in markup simile a HTML, con elementi semplici, tag <block> e i propri blocchi Blockstudio. Blockstudio compila il sorgente in markup nativo dei blocchi e lo fornisce a WordPress come file del tema. L’editor del sito continua a funzionare esattamente come prima: gli utenti possono personalizzare un template e, ripristinandolo, torna la versione del file.

Questa guida crea una parte per l’intestazione e una per il piè di pagina, i template per la pagina iniziale e per i singoli contenuti, e un template personalizzato che gli editor possono scegliere per le pagine; poi mostra come WordPress li risolve.

Struttura delle cartelle

I template si trovano in templates/, le parti di template in parts/. Ognuno è una cartella con un manifest e un file sorgente:

Codice
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

Sono le stesse cartelle templates/ e parts/ che WordPress legge per un tema a blocchi. Blockstudio esamina prima il tema attivo e poi quello genitore. Le cartelle con un template.json o un part.json sono sorgenti Blockstudio; i file .html semplici accanto a esse restano template nativi WordPress.

Il file sorgente può essere index.php, index.blade.php, index.twig o index.html, controllati in quest’ordine. Twig richiede Timber e Blade richiede il relativo pacchetto renderer, come descritto in Motori di template.

Passaggio 1: la parte dell’intestazione

Ogni parte richiede un part.json. area indica all’editor del sito dove collocare la parte:

JSON
{
  "slug": "header",
  "title": "Header",
  "description": "Site header with logo and navigation",
  "area": "header"
}

Il sorgente usa la stessa sintassi delle pagine e dei pattern Blockstudio. Un <div> diventa un blocco gruppo, gli attributi diventano attributi del blocco e gli elementi <block> producono qualsiasi blocco registrato:

PHP
<div layout='{"type":"flex","justifyContent":"space-between"}'>
  <block name="core/site-title" />
  <block name="core/navigation" overlayMenu="mobile" />
</div>

Blockstudio lo compila in questo markup di blocco:

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

È ciò che altrimenti avreste scritto a mano. Anche i vostri blocchi funzionano allo stesso modo: <block name="acme/announcement" />, un tag <bs:acme-announcement /> o un prefisso di tag configurato vengono tutti compilati nel commento di blocco corrispondente.

Una parte può essere composta anche da un solo paragrafo. Questa usa index.html per sottolineare che il sorgente è markup, non un programma:

JSON
{
  "slug": "footer",
  "title": "Footer",
  "area": "footer"
}
HTML
<p>Built with Acme.</p>

La compilazione produce <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.

Passaggio 3: template per la pagina iniziale e per i singoli contenuti

I template usano template.json. slug deve essere un nome esatto della gerarchia dei template WordPress, ad esempio front-page, single, page, archive, 404 o single-product. Blockstudio non lo antepone mai.

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" />

Il template per il singolo post segue la stessa struttura, usando blocchi per i post:

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" />

Il template per il singolo contenuto compilato:

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> è diventato un blocco gruppo con tagName: "main" e i blocchi delle parti di template fanno riferimento tramite slug alle parti dei passaggi 1 e 2. Quando WordPress visualizza il template, i riferimenti corrispondono alle parti basate su file: l’output della pagina iniziale comincia con <header class="wp-block-template-part">, che contiene il titolo del sito e la navigazione, e termina con <footer class="wp-block-template-part">, che contiene il paragrafo del piè di pagina.

Passaggio 4: un template personalizzato per le pagine

I template il cui slug non fa parte della gerarchia sono template personalizzati. Indicate con postTypes i tipi di post a cui si applicano; gli editor potranno poi sceglierli dal selettore dei 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' ) ora include page-landing e l’oggetto template contiene post_types: ["page"].

I sorgenti vengono compilati una sola volta

Il sorgente viene letto e compilato in markup di blocco una sola volta, non a ogni richiesta. Non ha un post corrente né un contesto di richiesta. index.php viene letto come markup: il codice PHP al suo interno non viene eseguito, quindi <?php echo get_bloginfo( 'name' ); ?> non produce nulla. Tutto ciò che dipende dalla richiesta appartiene a un blocco che viene visualizzato in fase di esecuzione: core/site-title al posto del nome del sito stampato, core/post-title al posto di the_title() o un blocco Blockstudio dinamico creato da voi.

I risultati compilati vengono memorizzati nella cache insieme ai metadati di monitoraggio dei file. La modifica di un manifest o di un file sorgente invalida i contenuti in cache di quell’elemento, così la richiesta successiva rileva la modifica senza bisogno di un passaggio di build separato.

Come WordPress individua i file

Blockstudio si integra nelle stesse ricerche usate da WordPress per i template del tema. In get_block_templates() i template basati su file compaiono con source: "theme" e origin: "theme", proprio come i file nativi del tema, e get_block_template( 'acme//header', 'wp_template_part' ) restituisce la parte dell’intestazione con il relativo area.

L’ordine di ricerca è:

  1. Una personalizzazione dell’editor del sito salvata nel database.
  2. Un file .html nativo nel tema attivo.
  3. Il sorgente basato su file Blockstudio.
  4. Le alternative del tema genitore o dei plugin.

Quest’ordine mantiene intatto il flusso di lavoro dell’editor del sito. Quando un utente modifica il piè di pagina e salva, WordPress memorizza un post wp_template_part e get_block_template() restituisce la personalizzazione con source: "custom". Le modifiche successive a parts/footer/index.html non vengono mostrate finché la personalizzazione esiste. Quando l’utente ripristina la parte o il post viene eliminato, la ricerca torna al file e restituisce nuovamente il sorgente compilato più recente.

Blockstudio non salva nei file le modifiche dell’editor del sito. Se una modifica dell’utente deve diventare il nuovo valore predefinito, copiatela nel file sorgente e ripristinate la personalizzazione.

index.html e slug annidati

WordPress individua ricorsivamente i file .html in templates/ e parts/. Una cartella manifest che usa index.html, come parts/footer/index.html, comparirebbe quindi anche come parte nativa con lo slug ricavato dal percorso footer/index. Poiché Blockstudio 7.6.6, un index.html gestito da manifest viene esposto solo con lo slug dichiarato, quindi l’editor del sito elenca un solo piè di pagina. I file .html annidati senza manifest restano invariati.

Verificare i template da PHP

La classe Blockstudio\Site_Templates legge e compila i sorgenti, una funzione utile nei test e nei controlli di distribuzione:

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

Ogni elemento include slug, title, description, type (wp_template o wp_template_part), status, source_type, postTypes per i template o area per le parti, meta e l’content compilato. Passate un elenco per compilare solo gli elementi selezionati e leggete i problemi relativi alla selezione con selection_errors():

PHP
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors   = Blockstudio\Site_Templates::selection_errors( 'templates' );

Aggiungere altre cartelle

Per mantenere separati i sorgenti Blockstudio dai template nativi o distribuirli da un plugin, aggiungete radici di ricerca con dei filtri:

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

I filtri blockstudio/site_templates/template_content e part_content modificano un sorgente prima che venga analizzato, mentre blockstudio/site_templates/parser sostituisce l’analizzatore per un singolo elemento. L’elenco completo si trova nella tabella Hook dei template del sito.

Quando usare cosa

Esigenza Soluzione
Il layout del tema WordPress scelto per un URL: intestazione, piè di pagina, singolo contenuto, archivio Template e parti del sito
Una pagina raggiungibile tramite URL con contenuti archiviati in file Pagine basate su file
Una sezione riutilizzabile che gli editor possono inserire Pattern

I template non creano post, lo fanno le pagine. Per esempio, una sezione di documentazione è una raccolta di pagine i cui post vengono visualizzati tramite un template che potete comunque creare qui.

Passaggi successivi