Ga naar de inhoud

Sitetemplates

Met sitetemplates kunnen blokthema’s WordPress wp_template– en wp_template_part-bronnen definiëren met dezelfde bestandsgerichte syntaxis als voor Blockstudio pagina’s en patronen.

Gebruik sitetemplates om de themalayout te bepalen die WordPress selecteert via de templatehiërarchie van de Site Editor: de voorpagina, afzonderlijke berichten, archieven, zoekresultaten, 404-pagina’s, kopteksten, voetteksten en andere templateonderdelen.

Pagina’s, patronen of sitetemplates?

Functie Maakt aan Ideaal voor
Pagina’s Berichten of aangepaste berichttypen Echte inhoudspagina’s, documentatiepagina’s, landingspagina’s en inhoud met een eigen route.
Patronen Blokpatronen Herbruikbare secties die redacteuren invoegen.
Sitetemplates wp_template– en wp_template_part-bestandsbronnen Themalayout die wordt beheerd door de Site Editor en de templatehiërarchie van WordPress.

Sitetemplates maken geen gewone pagina’s aan. Ze bieden de bestandsbron die WordPress gebruikt bij het bepalen van een template voor een blokthema. Als een gebruiker de template aanpast in de Site Editor, slaat WordPress die aanpassing op in de database; deze heeft dan voorrang op de bestandsbron totdat de aanpassing wordt teruggezet.

Mapstructuur

Plaats volledige templates in templates/ en templateonderdelen 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

Elke map bevat een manifest en één bronbestand.

Bestand Engine
index.php Blokmarkup, vergelijkbaar met HTML, wordt ongewijzigd ingelezen (PHP-code wordt niet uitgevoerd)
index.blade.php Blade
index.twig Twig
index.html Blokmarkup, vergelijkbaar met HTML

Als er meerdere bronbestanden bestaan, gebruikt Blockstudio deze volgorde:

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.html

WordPress detecteert ook recursief .html-bestanden en toont doorgaans een genest index.html onder de op het pad gebaseerde slug, zoals header/index. Als dat bestand bij een manifest van Blockstudio hoort, verwijdert Blockstudio het dubbele item op basis van het pad en toont alleen het door het manifest opgegeven slug. Geneste native templates van .html zonder manifest van Blockstudio blijven ongewijzigd.

De bron wordt eenmalig gecompileerd tot native blokmarkup van WordPress. Deze mag niet afhankelijk zijn van het huidige verzoek of bericht. Plaats runtimegedrag in dynamische blokken.

template.json

template.json definieert een volledige template voor de Site Editor.

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template",
  "postTypes": ["page"]
}

Eigenschappen

Eigenschap Type Standaard Beschrijving
slug / name string Mapnaam Slug voor de template van WordPress. Gebruik exacte hiërarchieslugs zoals front-page, single, archive-product of 404.
title string Titel afgeleid van slug Weergavetitel in de Site Editor.
description string "" Weergavebeschrijving in de Site Editor.
postTypes string[] [] Berichttypen voor aangepaste templates. Dit veld kan ontbreken bij templates voor de core-hiërarchie.
source / template / file string Automatisch gedetecteerd indexbestand Optioneel bronbestandspad relatief aan de templatemap.
status string "publish" Templatestatus.
sync boolean false Gereserveerd voor toekomstige materialisatie in de database. Gebruikersaanpassingen worden nooit overschreven in v1.
meta object {} Aangepaste metadata voor hulpfuncties van API’s. Onbekende manifestkeys worden hier ook opgeslagen.

Template-slugs krijgen geen voorvoegsel. WordPress heeft exacte namen nodig voor de templatehiërarchie:

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 definieert een templateonderdeel voor de Site Editor.

JSON
{
  "slug": "header",
  "title": "Header",
  "description": "Main site header",
  "area": "header"
}

Eigenschappen

Eigenschap Type Standaard Beschrijving
slug / name string Mapnaam Slug voor het templateonderdeel van WordPress.
title string Titel afgeleid van slug Weergavetitel in de Site Editor.
description string "" Weergavebeschrijving in de Site Editor.
area string "uncategorized" Gebied van het templateonderdeel. Veelgebruikte waarden zijn header, footer en sidebar.
source / template / file string Automatisch gedetecteerd indexbestand Optioneel bronbestandspad relatief aan de map van het onderdeel.
status string "publish" Status van het templateonderdeel.
meta object {} Aangepaste metadata voor hulpfuncties van API’s. Onbekende manifestkeys worden hier ook opgeslagen.

Markup schrijven

Bronbestanden voor sitetemplates gebruiken dezelfde parser als pagina’s en patronen:

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>

Het element <main> wordt een core/group-blok dat wordt weergegeven als <main>; het onderliggende blok en de onderliggende blokken, inclusief het bloktag core/post-content, worden de binnenste blokken. U kunt het volgende gebruiken:

  • standaard-HTML-elementen zoals <h1>, <p>, <ul>, <div> en de sectie-elementen <main>, <header>, <footer>, <article> en <aside>
  • <block name="namespace/block">
  • <bs:namespace-block>
  • geconfigureerde voorvoegsels voor bloktags
  • Blockstudio-blokken en componenten

Templateonderdeelblokken ontvangen het actieve thema-attribuut wanneer WordPress de gecompileerde template weergeeft.

Aanpassingen in de Site Editor

Blockstudio levert de bestandsbron. Aanpassingen van gebruikers worden beheerd door WordPress.

De zoekvolgorde is:

  1. Databaseaanpassing in de Site Editor
  2. Templatebestand .html uit het actieve thema
  3. Bestandsbron van Blockstudio
  4. Terugvalopties van het bovenliggende thema of een plugin

Wanneer een gebruiker in de Site Editor een template op basis van een bestand van Blockstudio opslaat, maakt WordPress een normaal database-item van het type wp_template of wp_template_part aan. Dit opgeslagen item heeft voorrang op toekomstige bestandswijzigingen. Als u de aanpassing terugzet of verwijdert, wordt de nieuwste bestandsbron weer gebruikt.

Blockstudio schrijft wijzigingen in de Site Editor niet terug naar bestanden in v1.

Prestaties

De template wordt per verzoek gedetecteerd en in de cache opgeslagen, met blijvende metadata voor bestandsbewaking. Als een manifest of bronbestand wordt gewijzigd, wordt de gecachete, gecompileerde inhoud ongeldig gemaakt. Databaseaanpassingen worden niet gecachet: WordPress controleert ze nog steeds als eerste.

Runtime-integraties die bestanden uit meerdere hoofdmappen samenstellen, kunnen voor templates en templateonderdelen een logische ontdekkingsbron aanbieden. Manifesten en geselecteerde templatebronbestanden kunnen in verschillende fysieke hoofdmappen staan en toch één logische themaboom vormen.

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

Geef een expliciete lijst mee om alleen exacte slugs, paden of bronpaden te lezen en te compileren:

PHP
$templates = Blockstudio\Site_Templates::templates([
    'front-page',
]);

$parts = Blockstudio\Site_Templates::parts([
    'header',
]);

$errors = Blockstudio\Site_Templates::selection_errors('templates');

Als u het argument weglaat, blijft het volledige registergedrag behouden. Een lege lijst meegeven levert geen items op. Verzoeken met gebruikelijke slugs en paden beperken de detectie tot de bijbehorende mappen; voor aangepaste manifest-slugs is mogelijk een metadatascan nodig, maar niet-gerelateerde bronnen worden nog steeds niet gecompileerd of geretourneerd.

Er zijn ook hulpfuncties voor templates beschikbaar:

PHP
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');

Hooks

De volledige uitbreidingsinterface voor sitetemplates is:

Hook Type Beschrijving
blockstudio/site_templates/template_paths Filter Past de detectierootmappen voor volledige templates aan.
blockstudio/site_templates/part_paths Filter Past de detectierootmappen voor templateonderdelen aan.
blockstudio/site_templates/paths Filter Past beide padlijsten aan als templates en parts.
blockstudio/site_templates/template_candidates Filter Past de kandidaten voor bronbestanden van een manifest aan.
blockstudio/site_templates/templates Filter Past de templates aan die door het register-API worden geretourneerd.
blockstudio/site_templates/parts Filter Past de templateonderdelen aan die door het register-API worden geretourneerd.
blockstudio/site_templates/template_content Filter Past de volledige gecompileerde templatebron aan voordat deze wordt geparseerd.
blockstudio/site_templates/part_content Filter Past de gecompileerde bron van templateonderdelen aan voordat deze wordt geparseerd.
blockstudio/site_templates/parser Filter Vervangt de instantie Html_Parser voor één item.
blockstudio/site_templates/source_compiled Actie Wordt uitgevoerd vlak voordat één geselecteerde bron wordt gecompileerd.
blockstudio/site_templates/discovered Actie Wordt uitgevoerd na een koude detectie- en compilatieronde.
blockstudio/site_templates/registered Actie Wordt uitgevoerd nadat het opnieuw opgebouwde register is opgeslagen.

Detectiepaden toevoegen of vervangen:

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

Gedetecteerde gegevens filteren:

PHP
add_filter('blockstudio/site_templates/templates', function ($templates) {
    return $templates;
});

add_filter('blockstudio/site_templates/parts', function ($parts) {
    return $parts;
});

Bron filteren voordat deze wordt geparseerd:

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

Bronkandidaten of de parser wijzigen:

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 en registered zijn acties in de levenscyclus van de cachevernieuwing. Ze worden niet uitgevoerd wanneer een warme registercachetreffer wordt gevonden.