Hoppa till innehåll

Webbplatsmallar

Med webbplatsmallar kan blockteman definiera källor för WordPress wp_template och wp_template_part med samma filbaserade syntax som används för Blockstudio- sidor och mönster.

Använd webbplatsmallar när du vill styra temalayouten som WordPress väljer genom webbplatsredigerarens mallhierarki: startsida, enskilda inlägg, arkiv, sökresultat, 404-sidor, sidhuvuden, sidfötter och andra malldelar.

Sidor, mönster eller webbplatsmallar?

Funktion Skapar Bäst för
Sidor Inlägg eller poster av anpassad inläggstyp Sidor med faktiskt innehåll, dokumentationssidor, landningssidor och innehåll som kan nås via en rutt.
Mönster Blockmönster Återanvändbara sektioner som redigerare infogar.
Webbplatsmallar wp_template– och wp_template_part-filkällor Temalayout som styrs av webbplatsredigeraren och mallhierarkin i WordPress.

Webbplatsmallar skapar inte vanliga sidor. De tillhandahåller filkällan som WordPress använder när en blocktemamall väljs. Om en användare anpassar mallen i webbplatsredigeraren lagrar WordPress anpassningen i databasen, och den har företräde framför filkällan tills den återställs.

Mappstruktur

Lägg fullständiga mallar i templates/ och malldelar i 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

Varje mapp har ett manifest samt en källfil.

Fil Motor
index.php Blockuppmärkning som liknar HTML, läses som den är (PHP-kod körs inte)
index.blade.php Blade
index.twig Twig
index.html Blockuppmärkning som liknar HTML

Om det finns flera källfiler använder Blockstudio följande ordning:

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

WordPress identifierar även .html-filer rekursivt och visar normalt en nästlad index.html under dess sökvägsbaserade slug, till exempel header/index. När filen tillhör ett Blockstudio-manifest tar Blockstudio bort den sökvägsbaserade dubbletten och visar bara manifestets angivna slug. Näslade inbyggda .html-mallar utan ett Blockstudio-manifest påverkas inte.

Källan kompileras en gång till inbyggd blockuppmärkning i WordPress. Den ska inte vara beroende av den aktuella förfrågan eller det aktuella inlägget. Placera körningsbeteende i dynamiska block.

template.json

template.json definierar en fullständig mall för webbplatsredigeraren.

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

Egenskaper

Egenskap Typ Standard Beskrivning
slug / name string Mappnamn Slug för WordPress-mallen. Använd exakta hierarkisluggar som front-page, single, archive-product eller 404.
title string Titel från slug Visningstitel i webbplatsredigeraren.
description string "" Visningsbeskrivning i webbplatsredigeraren.
postTypes string[] [] Inläggstyper för anpassade mallar. Hierarkimallar från kärnan kan utelämna detta.
source / template / file string Indexfil identifieras automatiskt Valfri källfilsökväg relativt till mappmallen.
status string "publish" Mallstatus.
sync boolean false Reserverat för framtida materialisering i databasen. Användaranpassningar skrivs aldrig över i v1.
meta object {} Anpassade metadata för hjälpar-API:er. Okända manifestnycklar lagras också här.

Mallsluggar har inget prefix. WordPress behöver exakta namn för mallhierarkin:

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 definierar en malldel för webbplatsredigeraren.

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

Egenskaper

Egenskap Typ Standard Beskrivning
slug / name string Mappnamn Slug för WordPress-malldelen.
title string Titel från slug Visningstitel i webbplatsredigeraren.
description string "" Visningsbeskrivning i webbplatsredigeraren.
area string "uncategorized" Malldelens område. Vanliga värden är header, footer och sidebar.
source / template / file string Indexfil identifieras automatiskt Valfri källfilsökväg relativt till mappdelen.
status string "publish" Malldelens status.
meta object {} Anpassade metadata för hjälpar-API:er. Okända manifestnycklar lagras också här.

Skriva uppmärkning

Webbplatsmallarnas källor använder samma parser som sidor och mönster:

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>

Elementet <main> blir ett core/group-block som återges som <main>, och dess underordnade element, inklusive blocktaggen core/post-content, blir dess inre block. Du kan använda:

  • vanliga HTML-element som <h1>, <p>, <ul>, <div> och sektionsindelande element som <main>, <header>, <footer>, <article> och <aside>
  • <block name="namespace/block">
  • <bs:namespace-block>
  • konfigurerade prefix för blocktaggar
  • Blockstudio-block och komponenter

Malldelsblock får det aktiva temaattributet när WordPress återger den kompilerade mallen.

Anpassningar i webbplatsredigeraren

Blockstudio tillhandahåller filkällan. WordPress hanterar användaranpassningar.

Sökordningen är:

  1. Anpassning i webbplatsredigerarens databas
  2. Fil för det aktiva inbyggda temat .html
  3. Filbaserad källa från Blockstudio
  4. Reservlösningar från överordnat tema eller tillägg

När en användare sparar en filbaserad Blockstudio-mall i webbplatsredigeraren skapar WordPress en vanlig databaspost av typen wp_template eller wp_template_part. Den sparade posten har företräde framför framtida filändringar. Om anpassningen återställs eller tas bort visas den senaste filbaserade källan igen.

Blockstudio skriver inte tillbaka redigeringar i webbplatsredigeraren till filer i v1.

Prestanda

Mallidentifiering cachelagras per förfrågan och sparas tillsammans med metadata för filbevakning. Om ett manifest eller en källfil ändras blir det cachelagrade, kompilerade innehållet ogiltigt. Databasanpassningar cachelagras inte bort: WordPress kontrollerar dem fortfarande först.

Körningsintegreringar som sammanfogar filer från flera rötter kan ange en logisk upptäcktskälla för mallar och malldelar. Manifest och valda källmallar kan finnas i olika fysiska rötter men ändå tillhöra samma logiska tematräd.

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

Ange en uttrycklig lista för att läsa och kompilera endast exakta sluggar, sökvägar eller källsökvägar:

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

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

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

Om argumentet utelämnas behålls hela registrets beteende. En tom lista ger inga objekt. Förfrågningar med konventionell slug eller sökväg begränsar identifieringen till motsvarande kataloger. Anpassade manifestsluggar kan kräva en metadatasökning, men orelaterade källor kompileras eller returneras ändå inte.

Hjälpfunktioner för mallar är också tillgängliga:

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

Hooks

Hela utökningsytan för webbplatsmallar omfattar:

Hook Typ Beskrivning
blockstudio/site_templates/template_paths Filter Justera identifieringssökvägar för fullständiga mallar.
blockstudio/site_templates/part_paths Filter Justera identifieringssökvägar för malldelar.
blockstudio/site_templates/paths Filter Justera båda sökvägslistorna som templates och parts.
blockstudio/site_templates/template_candidates Filter Justera kandidater för källfiler i ett manifest.
blockstudio/site_templates/templates Filter Justera mallar som registret returnerar via API.
blockstudio/site_templates/parts Filter Justera malldelar som registret returnerar via API.
blockstudio/site_templates/template_content Filter Justera källan för en kompilerad fullständig mall före parsning.
blockstudio/site_templates/part_content Filter Justera källan för en kompilerad malldel före parsning.
blockstudio/site_templates/parser Filter Ersätt instansen Html_Parser för ett objekt.
blockstudio/site_templates/source_compiled Åtgärd Körs omedelbart innan en vald källa kompileras.
blockstudio/site_templates/discovered Åtgärd Körs efter en kall identifierings- och kompileringsomgång.
blockstudio/site_templates/registered Åtgärd Körs efter att det återskapade registret har sparats.

Lägg till eller ersätt identifieringssökvägar:

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

Filtrera identifierade data:

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

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

Filtrera källa före parsning:

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

Ändra källkandidater eller parsern:

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 och registered är åtgärder i cacheombyggnadens livscykel. De körs inte när ett varmt registercacheträff inträffar.