Vai al contenuto

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

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

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:

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.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.

JSON
{
  "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:

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 definisce una parte di template dell’Editor del sito.

JSON
{
  "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:

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>

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

  1. Personalizzazione nel database dell’Editor del sito
  2. File .html del tema attivo nativo
  3. Origine da file di Blockstudio
  4. 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

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

Passate un elenco esplicito per leggere e compilare solo slug, percorsi o percorsi sorgente esatti:

PHP
$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:

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

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

Filtrare i dati rilevati:

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

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

Modificare le origini candidate o il 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 e registered sono azioni del ciclo di ricostruzione della cache. Non vengono eseguite quando si trova una cache calda del registro.