Přejít k obsahu

Šablony webu

Šablony webu umožňují blokovým motivům definovat zdroje WordPress wp_template a wp_template_part pomocí stejné syntaxe založené na souborech, jaká se používá u stránek a vzorů Blockstudio.

Šablony webu použijte, když chcete řídit rozvržení motivu, které WordPress vybírá podle hierarchie šablon editoru webu: úvodní stránka, jednotlivé příspěvky, archivy, vyhledávání, stránky 404, záhlaví, zápatí a další části šablon.

Stránky, vzory, nebo šablony webu?

Funkce Vytváří Vhodné pro
Stránky Příspěvky nebo záznamy vlastního typu příspěvku Skutečný obsah stránek, dokumentační stránky, vstupní stránky a obsah s vlastní cestou.
Vzory Vzory bloků Opakovaně použitelné sekce vkládané editory.
Šablony webu Zdroje souborů wp_template a wp_template_part Rozvržení motivu řízené editorem webu a hierarchií šablon WordPress.

Šablony webu nevytvářejí běžné stránky. Poskytují zdrojový soubor, který WordPress používá při hledání šablony blokového motivu. Pokud uživatel upraví šablonu v editoru webu, WordPress uloží tyto úpravy do databáze a mají přednost před zdrojovým souborem, dokud je uživatel neresetuje.

Struktura složek

Úplné šablony umístěte do templates/ a části šablon do 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

Každá složka obsahuje manifest a jeden zdrojový soubor.

Soubor Engine
index.php Značení bloků podobné HTML, čtené beze změn (kód PHP se nespouští)
index.blade.php Blade
index.twig Twig
index.html Značení bloků podobné HTML

Pokud existuje několik zdrojových souborů, Blockstudio použije toto pořadí:

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

WordPress také rekurzivně vyhledává soubory .html a běžně zpřístupňuje vnořenou položku index.html pod slugem odvozeným z její cesty, například header/index. Pokud tento soubor patří k manifestu Blockstudio, Blockstudio odstraní duplicitní položku odvozenou z cesty a zpřístupní pouze položku slug uvedenou v manifestu. Vnořené nativní šablony .html bez manifestu Blockstudio zůstávají beze změny.

Zdroj se jednou zkompiluje do nativního značení bloků WordPress. Neměl by záviset na aktuálním požadavku ani aktuálním příspěvku. Runtime chování umístěte do dynamických bloků.

template.json

template.json definuje úplnou šablonu editoru webu.

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

Vlastnosti

Vlastnost Typ Výchozí hodnota Popis
slug / name string Název složky Slug šablony WordPress. Použijte přesné slugy z hierarchie, například front-page, single, archive-product nebo 404.
title string Název odvozený ze slugu Zobrazovaný název v editoru webu.
description string "" Zobrazovaný popis v editoru webu.
postTypes string[] [] Typy příspěvků pro vlastní šablony. U základních šablon hierarchie lze tuto položku vynechat.
source / template / file string Automaticky zjištěný indexový soubor Volitelná cesta ke zdrojovému souboru relativní ke složce šablony.
status string "publish" Stav šablony.
sync boolean false Vyhrazeno pro budoucí materializaci v databázi. Uživatelské úpravy se nikdy nepřepisují v v1.
meta object {} Vlastní metadata pro pomocná API. Zde se ukládají i neznámé klíče manifestu.

Slugy šablon nemají předponu. WordPress potřebuje pro hierarchii šablon přesné názvy:

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 definuje část šablony editoru webu.

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

Vlastnosti

Vlastnost Typ Výchozí hodnota Popis
slug / name string Název složky Slug části šablony WordPress.
title string Název odvozený ze slugu Zobrazovaný název v editoru webu.
description string "" Zobrazovaný popis v editoru webu.
area string "uncategorized" Oblast části šablony. Běžné hodnoty jsou header, footer a sidebar.
source / template / file string Automaticky zjištěný indexový soubor Volitelná cesta ke zdrojovému souboru relativní ke složce části šablony.
status string "publish" Stav části šablony.
meta object {} Vlastní metadata pro pomocná API. Zde se ukládají i neznámé klíče manifestu.

Zápis značení

Zdroje šablon webu používají stejný parser jako stránky a vzory:

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>

Prvek <main> se změní na blok core/group, který se vykreslí jako <main>, a jeho potomci včetně značky bloku core/post-content se změní na vnitřní bloky. Můžete použít:

  • standardní prvky HTML, například <h1>, <p>, <ul>, <div> a prvky pro členění stránky <main>, <header>, <footer>, <article> a <aside>
  • <block name="namespace/block">
  • <bs:namespace-block>
  • nakonfigurované předpony značek bloků
  • bloky a komponenty Blockstudio

Bloky částí šablon obdrží atribut aktivního motivu, když WordPress vykreslí zkompilovanou šablonu.

Úpravy v editoru webu

Blockstudio poskytuje zdrojový soubor. WordPress spravuje uživatelské úpravy.

Pořadí vyhledávání:

  1. Úprava v databázi editoru webu
  2. Soubor motivu .html aktivního motivu
  3. Zdroj ze souborů Blockstudio
  4. Záložní zdroje nadřazeného motivu nebo pluginu

Když uživatel uloží šablonu založenou na souboru Blockstudio v editoru webu, WordPress vytvoří běžný záznam wp_template nebo wp_template_part v databázi. Tento uložený záznam má přednost před budoucími změnami souboru. Resetováním nebo odstraněním úpravy se znovu zobrazí aktuální zdroj ze souboru.

Blockstudio nezapisuje úpravy z editoru webu zpět do souborů v v1.

Výkon

Vyhledávání šablon se ukládá do mezipaměti pro každý požadavek a přetrvává spolu s metadaty sledování souborů. Změna manifestu nebo zdrojového souboru zneplatní zkompilovaný obsah v mezipaměti. Úpravy v databázi nejsou přebity z mezipaměti: WordPress je stále kontroluje jako první.

Runtime integrace, které skládají soubory z několika kořenových adresářů, mohou poskytnout logický zdroj pro vyhledávání šablon a částí šablon. Manifesty a vybrané zdrojové šablony se mohou nacházet v různých fyzických kořenových adresářích a přitom zachovat jeden logický strom motivu.

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

Předáním explicitního seznamu můžete načíst a zkompilovat pouze přesné slugy, cesty nebo zdrojové cesty:

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

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

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

Vynecháním argumentu se zachová úplné chování registru. Předáním prázdného seznamu se nevrátí žádné položky. Požadavky na běžné slugy a cesty zúží vyhledávání na odpovídající adresáře. Vlastní slugy manifestu mohou vyžadovat prohledání metadat, ale nesouvisející zdroje se přesto nezkompilují ani nevrátí.

K dispozici jsou také pomocné funkce šablon:

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

Hooky

Úplná plocha rozšíření šablon webu:

Hook Typ Popis
blockstudio/site_templates/template_paths Filtr Upraví kořenové adresáře pro vyhledávání úplných šablon.
blockstudio/site_templates/part_paths Filtr Upraví kořenové adresáře pro vyhledávání částí šablon.
blockstudio/site_templates/paths Filtr Upraví oba seznamy cest jako templates a parts.
blockstudio/site_templates/template_candidates Filtr Upraví kandidáty zdrojových souborů pro manifest.
blockstudio/site_templates/templates Filtr Upraví šablony vrácené registrem API.
blockstudio/site_templates/parts Filtr Upraví části šablon vrácené registrem API.
blockstudio/site_templates/template_content Filtr Upraví zdroj úplné šablony po kompilaci a před parsováním.
blockstudio/site_templates/part_content Filtr Upraví zdroj části šablony po kompilaci a před parsováním.
blockstudio/site_templates/parser Filtr Nahradí instanci Html_Parser pro jednu položku.
blockstudio/site_templates/source_compiled Akce Spustí se těsně před kompilací jednoho vybraného zdroje.
blockstudio/site_templates/discovered Akce Spustí se po průchodu studeného vyhledávání a kompilace.
blockstudio/site_templates/registered Akce Spustí se po uložení znovu sestaveného registru.

Přidání nebo nahrazení cest pro vyhledávání:

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

Filtrování nalezených dat:

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

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

Filtrování zdroje před parsováním:

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

Změna zdrojových kandidátů nebo parseru:

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 a registered jsou akce životního cyklu pro opětovné sestavení mezipaměti. Při zásahu do zahřáté mezipaměti registru se nespouštějí.