Přejít k obsahu

Šablony a části editoru webu ze souborů

Blokový motiv popisuje rozvržení pomocí templates/*.html a parts/*.html: souborů plných serializovaných komentářů bloků, například <!-- wp:template-part {"slug":"header"} /-->. Nikdo je nechce psát ručně, proto se obvykle vytvoří v editoru webu a exportují. To funguje, dokud stejnou šablonu neupravují dva lidé nebo dokud recenzent nemusí číst rozdíly v escapovaných JSON uvnitř komentářů HTML.

Blockstudio umožňuje vytvářet stejné šablony podobně jako stránky ze souborů: složka s malým manifestem JSON a zdrojovým souborem ve značkách podobných HTML, který používá běžné prvky, značky <block> a vlastní bloky Blockstudio. Blockstudio zkompiluje zdroj do nativních značek bloků a předá jej WordPress jako soubor motivu. Editor webu dál funguje stejně jako předtím: uživatelé mohou šablonu upravovat a po obnovení původní verze se vrátí obsah ze souboru.

V tomto průvodci vytvoříme část záhlaví a zápatí, šablony úvodní a jednotlivé stránky a vlastní šablonu, kterou mohou editoři vybrat pro stránky. Poté ukážeme, jak je WordPress vyhledává.

Struktura složek

Šablony patří do templates/ a části šablon do parts/. Každá je ve vlastní složce s manifestem a jedním zdrojovým souborem:

Kód
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

Jde o stejné složky templates/ a parts/, které WordPress načítá pro blokový motiv. Blockstudio nejprve prohledá aktivní motiv a poté nadřazený motiv. Složky obsahující template.json nebo part.json jsou zdroje Blockstudio; běžné soubory .html vedle nich zůstávají nativními šablonami WordPress.

Zdrojovým souborem může být index.php, index.blade.php, index.twig nebo index.html, v tomto pořadí. Twig vyžaduje Timber a Blade vyžaduje svůj vykreslovací balíček, jak je popsáno v Šablonové enginy.

Krok 1: Část záhlaví

Každá část potřebuje part.json. Položka area určuje editoru webu, kam část patří:

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

Zdroj používá stejnou syntaxi jako stránky a vzory Blockstudio. Značka <div> se změní na blok skupiny, atributy na atributy bloku a prvky <block> vytvoří libovolný registrovaný blok:

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

Blockstudio jej zkompiluje do těchto značek bloku:

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

To je výsledek, který byste jinak museli napsat ručně. Vlastní bloky fungují stejně: <block name="acme/announcement" />, značka <bs:acme-announcement /> nebo nakonfigurovaná předpona značky se kompilují na komentář bloku pro daný blok.

Část může obsahovat jen jeden odstavec. Tato používá index.html, aby ukázala, že zdrojem jsou značky, nikoli program:

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

Zkompiluje se na <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.

Krok 3: Šablony úvodní a jednotlivé stránky

Šablony používají template.json. Položka slug musí přesně odpovídat názvu šablony v hierarchii WordPress, například front-page, single, page, archive, 404 nebo single-product. Blockstudio se před něj nikdy nepřidává.

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

Šablona jednotlivého příspěvku má stejnou strukturu, jen používá bloky příspěvků:

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

Zkompilovaná šablona jednotlivého příspěvku:

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> se změnil na blok skupiny s tagName: "main" a bloky částí šablony odkazují podle slugů na části z kroků 1 a 2. Když WordPress vykreslí šablonu, odkazy se vyřeší na části ze souborů. Výstup úvodní stránky tak začíná <header class="wp-block-template-part"> obsahujícím název webu a navigaci a končí <footer class="wp-block-template-part"> obsahujícím odstavec zápatí.

Krok 4: Vlastní šablona pro stránky

Šablony, jejichž slug není součástí hierarchie, jsou vlastní šablony. Pomocí postTypes určete typy příspěvků, pro které platí; editoři si je pak mohou vybrat ve výběru šablon:

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' ) nyní obsahuje page-landing a objekt šablony nese post_types: ["page"].

Zdroje se kompilují jednou

Zdroj se načte a zkompiluje do značek bloků jednou, nikoli při každém požadavku. Nemá aktuální příspěvek ani kontext požadavku. index.php se načítá jako značky: kód PHP uvnitř se nespustí, takže <?php echo get_bloginfo( 'name' ); ?> se zkompiluje naprázdno. Vše, co závisí na požadavku, patří do bloku vykreslovaného za běhu: core/site-title místo vypsaného názvu webu, core/post-title místo the_title() nebo vlastní dynamický blok Blockstudio.

Výsledky kompilace se ukládají do mezipaměti spolu s metadaty sledovaných souborů. Úpravou manifestu nebo zdrojového souboru se zneplatní obsah příslušné položky v mezipaměti, takže se změna projeví při dalším požadavku bez samostatného kroku sestavení.

Jak WordPress načítá soubory

Blockstudio se napojuje na stejná vyhledávání, která WordPress používá pro šablony motivu. V get_block_templates() se šablony ze souborů zobrazují pomocí source: "theme" a origin: "theme", stejně jako nativní soubory motivu, a get_block_template( 'acme//header', 'wp_template_part' ) vrací část záhlaví s jejím area.

Pořadí vyhledávání:

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

Toto pořadí zachovává pracovní postup v editoru webu. Když uživatel upraví zápatí a uloží ho, WordPress uloží příspěvek wp_template_part a get_block_template() vrátí tuto úpravu pomocí source: "custom". Pozdější změny v parts/footer/index.html se neprojeví, dokud úprava existuje. Když uživatel část obnoví do původní podoby nebo příspěvek odstraní, vyhledávání přejde k souboru a znovu vrátí nejnovější zkompilovaný zdroj.

Blockstudio nezapisuje úpravy z editoru webu zpět do souborů. Pokud se má změna uživatele stát novou výchozí verzí, zkopírujte ji do zdrojového souboru a obnovte původní podobu úpravy.

Vnořené index.html a slugy

WordPress vyhledává soubory .html v templates/ a parts/ rekurzivně. Složka manifestu používající index.html, například parts/footer/index.html, se proto také zobrazí jako nativní část se slugem odvozeným z cesty footer/index. Protože Blockstudio 7.6.6, manifestem spravovaný index.html se zpřístupní pouze pod deklarovaným slugem, takže Editor webu zobrazí jednu patičku, ne dvě. Vnořené soubory .html bez manifestu zůstanou beze změny.

Kontrola šablon z PHP

Třída Blockstudio\Site_Templates čte a kompiluje zdroje, což se hodí při testování a kontrolách nasazení:

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

Každá položka obsahuje slug, title, description, type (wp_template nebo wp_template_part), status, source_type, postTypes pro šablony nebo area pro části, meta a zkompilovaný content. Předáním seznamu zkompilujete pouze vybrané položky a problémy pro tento výběr načtete pomocí selection_errors():

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

Přidání dalších složek

Chcete-li oddělit zdroje Blockstudio od nativních šablon nebo je dodávat prostřednictvím pluginu, přidejte kořenové adresáře pro vyhledávání pomocí filtrů:

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

Filtry blockstudio/site_templates/template_content a part_content upravují zdroj před parsováním a blockstudio/site_templates/parser nahrazuje parser pro jednu položku. Úplný seznam najdete v tabulce hooků šablon webu.

Kdy co použít

Co potřebujete Použijte
Rozvržení motivu WordPress pro URL: záhlaví, zápatí, jednotlivý příspěvek, archiv Šablony a části webu
Směrovatelnou stránku s obsahem uloženým v souborech Stránky ze souborů
Opakovaně použitelnou sekci, kterou mohou editoři vložit Vzory

Šablony nevytvářejí příspěvky, to dělají stránky. Například sekce dokumentace je kolekce stránek, jejichž příspěvky se vykreslují pomocí šablony, kterou stále můžete vytvářet zde.

Další kroky