Ga naar de inhoud

Siteditor-sjablonen en -onderdelen vanuit bestanden

Een blokthema beschrijft de lay-out in templates/*.html en parts/*.html: bestanden vol geserialiseerde blokopmerkingen zoals <!-- wp:template-part {"slug":"header"} /-->. Niemand schrijft die graag met de hand, dus meestal worden ze in de Siteditor gemaakt en geëxporteerd. Dat werkt totdat twee mensen dezelfde template bewerken of een beoordelaar een diff van geëscapete JSON in opmerkingen van HTML moet lezen.

Met Blockstudio schrijf je dezelfde templates zoals je pagina’s op basis van bestanden schrijft: een map met een klein manifest JSON en een bronbestand met markup in de stijl van HTML, met gewone elementen, tags <block> en je eigen blokken van Blockstudio. Blockstudio compileert de bron naar native blokmarkup en geeft deze aan WordPress door als themabestand. De Siteditor werkt nog precies zoals voorheen: gebruikers kunnen een template aanpassen en door deze te herstellen, keert de bestandsversie terug.

In deze handleiding maak je een kop- en voettekstonderdeel, templates voor de voorpagina en enkele berichten, en een aangepaste template die editors voor pagina’s kunnen kiezen. Vervolgens zie je hoe WordPress ze vindt.

Mapstructuur

Templates staan in templates/ en sjabloononderdelen in parts/. Elk is een map met een manifest en één bronbestand:

Code
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

Dit zijn dezelfde mappen templates/ en parts/ die WordPress voor een blokthema inleest. Blockstudio doorzoekt eerst het actieve thema en daarna het bovenliggende thema. Mappen met een template.json of part.json zijn bronnen van Blockstudio; gewone bestanden .html ernaast blijven native templates van WordPress.

Het bronbestand kan index.php, index.blade.php, index.twig of index.html zijn; ze worden in die volgorde gecontroleerd. Voor Twig is Timber vereist en voor Blade het bijbehorende renderpakket, zoals beschreven in Engines voor templates.

Stap 1: het koptekstonderdeel

Elk onderdeel heeft een part.json nodig. De area geeft aan de Siteditor aan waar het onderdeel hoort:

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

De bron gebruikt dezelfde syntaxis als pagina’s en patronen van Blockstudio. Een <div> wordt een groepsblok, kenmerken worden blokkenmerken en elementen van <block> leveren elk geregistreerd blok op:

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

Blockstudio compileert dit naar deze blokmarkup:

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

Dat is wat je anders met de hand zou schrijven. Je eigen blokken werken op dezelfde manier: <block name="acme/announcement" />, een tag <bs:acme-announcement /> of een geconfigureerd tagvoorvoegsel worden allemaal gecompileerd naar de blokopmerking voor dat blok.

Een onderdeel kan zo klein zijn als één alinea. Dit voorbeeld gebruikt index.html om duidelijk te maken dat de bron markup is en geen programma:

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

Dit wordt gecompileerd naar <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.

Stap 3: templates voor de voorpagina en enkele berichten

Templates gebruiken template.json. De slug moet exact de naam van een template in de hiërarchie WordPress zijn, zoals front-page, single, page, archive, 404 of single-product. Blockstudio wordt er nooit voor gezet.

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

De template voor een afzonderlijk bericht volgt dezelfde structuur met berichtblokken:

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

De gecompileerde template voor een afzonderlijk bericht:

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> werd een groepsblok met tagName: "main", en de blokken voor de sjabloononderdelen verwijzen op basis van hun slug naar de onderdelen uit stap 1 en 2. Wanneer WordPress de template weergeeft, verwijzen die naar de onderdelen uit bestanden. De uitvoer van de voorpagina begint dan met <header class="wp-block-template-part">, met de sitetitel en navigatie, en eindigt met <footer class="wp-block-template-part">, met de voettekstparagraaf.

Stap 4: een aangepaste template voor pagina’s

Templates waarvan de slug geen deel uitmaakt van de hiërarchie zijn aangepaste templates. Vermeld de berichttypen waarop ze van toepassing zijn met postTypes. Editors kunnen ze dan kiezen in de templateselector:

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' ) bevat nu ook page-landing en het templateobject bevat post_types: ["page"].

Bronnen worden één keer gecompileerd

De bron wordt ingelezen en één keer naar blokmarkup gecompileerd, niet per verzoek. Er is geen huidig bericht of verzoekcontext. index.php wordt als markup ingelezen: code PHP erin wordt niet uitgevoerd, dus <?php echo get_bloginfo( 'name' ); ?> wordt naar niets gecompileerd. Alles wat afhankelijk is van het verzoek, hoort in een blok dat tijdens runtime wordt weergegeven: core/site-title in plaats van een sitenaam die wordt weergegeven, core/post-title in plaats van the_title(), of een dynamisch blok Blockstudio van jezelf.

Gecompileerde resultaten worden in de cache opgeslagen met metadata voor bestandsbewaking. Als je een manifest of bronbestand bewerkt, wordt de cache voor dat item ongeldig. Bij het volgende verzoek is de wijziging zichtbaar zonder aparte buildstap.

Hoe WordPress de bestanden vindt

Blockstudio haakt in op dezelfde opzoekingen die WordPress gebruikt voor thematemplates. In get_block_templates() verschijnen de templates op basis van bestanden met source: "theme" en origin: "theme", net als native themabestanden. get_block_template( 'acme//header', 'wp_template_part' ) retourneert het koptekstonderdeel met zijn area.

De zoekvolgorde is:

  1. Een aanpassing in de Siteditor die in de database is opgeslagen.
  2. Een native bestand .html in het actieve thema.
  3. De bron op basis van bestanden Blockstudio.
  4. Terugvalopties van het bovenliggende thema of een plugin.

Deze volgorde behoudt de workflow van de Siteditor. Wanneer een gebruiker de voettekst bewerkt en opslaat, slaat WordPress een bericht van het type wp_template_part op en retourneert get_block_template() deze aanpassing met source: "custom". Latere wijzigingen aan parts/footer/index.html zijn niet zichtbaar zolang de aanpassing bestaat. Wanneer de gebruiker het onderdeel herstelt of het bericht wordt verwijderd, valt de zoekactie terug op het bestand en wordt de nieuwste gecompileerde bron opnieuw geretourneerd.

Blockstudio schrijft aanpassingen in de Siteditor niet terug naar bestanden. Als de wijziging van een gebruiker de nieuwe standaard moet worden, kopieer je deze naar het bronbestand en herstel je de aanpassing.

Geneste index.html en slugs

WordPress vindt recursief bestanden .html in templates/ en parts/. Een manifestmap die index.html gebruikt, zoals parts/footer/index.html, verschijnt daarom ook als native onderdeel met de padgebaseerde slug footer/index. Omdat Blockstudio 7.6.6, wordt een index.html dat door een manifest wordt beheerd alleen onder de opgegeven slug aangeboden. De Siteditor toont dus één voettekst, niet twee. Geneste bestanden .html zonder manifest blijven ongemoeid.

Templates controleren vanuit PHP

De klasse Blockstudio\Site_Templates leest de bronnen in en compileert ze. Dit is handig bij tests en implementatiecontroles:

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

Elk item bevat slug, title, description, type (wp_template of wp_template_part), status, source_type, postTypes voor templates of area voor onderdelen, meta en de gecompileerde content. Geef een lijst op om alleen geselecteerde items te compileren en lees de problemen voor die selectie met selection_errors():

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

Andere mappen toevoegen

Voeg met filters ontdekkingslocaties toe om bronnen van Blockstudio gescheiden te houden van native templates of om ze vanuit een plugin mee te leveren:

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

De filters blockstudio/site_templates/template_content en part_content passen een bron aan voordat deze wordt geparseerd; met blockstudio/site_templates/parser kun je de parser voor één item vervangen. De volledige lijst staat in de tabel met Hooks voor Siteditor-sjablonen.

Wanneer gebruik je wat?

Je wilt Gebruik
De themalay-out die WordPress kiest voor een URL: koptekst, voettekst, afzonderlijk bericht, archief Site-sjablonen en -onderdelen
Een routeerbare pagina waarvan de inhoud in bestanden staat Pagina’s op basis van bestanden
Een herbruikbaar gedeelte dat editors kunnen invoegen Patronen

Templates maken geen berichten aan; pagina’s wel. Een documentatiesectie is bijvoorbeeld een verzameling pagina’s waarvan de berichten worden weergegeven met een template die je nog steeds hier kunt maken.

Volgende stappen