Š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:
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ří:
{
"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:
<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:
<!-- 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.
Krok 2: Část zápatí
Část může obsahovat jen jeden odstavec. Tato používá index.html, aby ukázala,
že zdrojem jsou značky, nikoli program:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<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á.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template"
}
<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ů:
{
"slug": "single",
"title": "Single Post"
}
<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:
<!-- 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:
{
"slug": "page-landing",
"title": "Landing Page",
"description": "Full-width page without a header",
"postTypes": ["page"]
}
<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í:
- Úprava v editoru webu uložená v databázi.
- Nativní soubor
.htmlv aktivním motivu. - Zdroj ze souboru Blockstudio.
- 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í:
$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():
$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ů:
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
- Referenční příručka k šablonám webu: všechny vlastnosti manifestu, PHP API a všechny hooky.
- Přehled stránek a vzorů: parser HTML, značky bloků a mapování prvků používané zdroji šablon.
- Tvorba webu s dokumentací: kolekce stránek s Markdown, načítači a rozvrženími.