Preskočiť na obsah

Šablóny a časti editora webu zo súborov

Bloková téma opisuje svoje rozloženie v templates/*.html a parts/*.html: priečinky plné serializovaných komentárov blokov, napríklad <!-- wp:template-part {"slug":"header"} /-->. Nikto ich nepíše rád ručne, preto sa zvyčajne vytvárajú v Editore webu a exportujú. Funguje to, kým tú istú šablónu neupravujú dvaja ľudia alebo kým recenzent nemusí čítať rozdiely v escapovaných JSON v komentároch HTML.

Blockstudio umožňuje písať rovnaké šablóny podobne ako stránky založené na súboroch: priečinok s malým manifestom JSON a zdrojovým súborom v značkovacom jazyku podobnom HTML, ktorý používa bežné prvky, značky <block> a vlastné bloky Blockstudio. Blockstudio skompiluje zdroj do natívnych značiek blokov a odovzdá ho WordPress ako súbor témy. Editor webu funguje rovnako ako predtým: používatelia môžu šablónu upraviť a jej obnovením sa vráti verzia zo súboru.

Táto príručka vytvorí časť hlavičky a päty, šablóny úvodnej stránky a jednotlivého príspevku a vlastnú šablónu, ktorú si redaktori môžu vybrať pre stránky, a potom ukáže, ako ich WordPress rozpoznáva.

Štruktúra priečinkov

Šablóny patria do templates/, časti šablón do parts/. Každá z nich je priečinok s manifestom a jedným zdrojovým súborom:

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

Ide o tie isté priečinky templates/ a parts/, ktoré WordPress načítava pre blokovú tému. Blockstudio najprv prehľadá aktívnu tému a potom nadradenú tému. Priečinky s template.json alebo part.json sú zdrojmi Blockstudio; obyčajné súbory .html vedľa nich zostávajú natívnymi šablónami WordPress.

Zdrojovým súborom môže byť index.php, index.blade.php, index.twig alebo index.html, v tomto poradí. Twig vyžaduje Timber a Blade vyžaduje svoj vykresľovací balík, ako sa uvádza v Šablónové nástroje.

Krok 1: Časť hlavičky

Každá časť potrebuje part.json. area určuje, kam časť patrí v Editore webu:

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

Zdroj používa rovnakú syntax ako stránky a vzory Blockstudio. Prvok <div> sa zmení na blok skupiny, atribúty sa stanú atribútmi bloku a prvky <block> vytvoria ľubovoľný zaregistrovaný blok:

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

Blockstudio to skompiluje do týchto značiek blokov:

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 presne to, čo by ste inak napísali ručne. Vlastné bloky fungujú rovnako: <block name="acme/announcement" />, značka <bs:acme-announcement /> alebo nakonfigurovaná predpona značky sa skompilujú do komentára bloku pre daný blok.

Časť môže obsahovať len jeden odsek. Táto používa index.html, aby ukázala, že zdroj je značkovací jazyk, nie program:

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

Skompiluje sa na <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.

Krok 3: Šablóny úvodnej stránky a jednotlivého príspevku

Šablóny používajú template.json. slug musí byť presný názov šablóny WordPress v hierarchii, napríklad front-page, single, page, archive, 404 alebo single-product. Blockstudio pred ním nikdy nepridáva predponu.

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

Šablóna jednotlivého príspevku má rovnakú štruktúru, ale používa bloky príspevku:

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

Skompilovaná šablóna jednotlivého príspevku:

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> sa zmenil na blok skupiny s tagName: "main" a bloky častí šablóny odkazujú podľa slugov na časti z krokov 1 a 2. Keď WordPress vykreslí šablónu, tieto odkazy sa vyriešia na časti zo súborov, takže výstup úvodnej stránky sa začína značkou <header class="wp-block-template-part">, ktorá obsahuje názov webu a navigáciu, a končí značkou <footer class="wp-block-template-part">, ktorá obsahuje odsek päty.

Krok 4: Vlastná šablóna pre stránky

Šablóny, ktorých slug nie je súčasťou hierarchie, sú vlastné šablóny. Pomocou postTypes zadajte typy príspevkov, pre ktoré sa používajú; redaktori si ich potom môžu vybrať v selektore šablón:

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' ) teraz obsahuje page-landing a objekt šablóny nesie post_types: ["page"].

Zdroje sa kompilujú len raz

Zdroj sa načíta a skompiluje do značiek blokov iba raz, nie pri každej požiadavke. Nie je k dispozícii aktuálny príspevok ani kontext požiadavky. index.php sa načíta ako značkovací jazyk: kód PHP v ňom sa nevykonáva, takže <?php echo get_bloginfo( 'name' ); ?> sa skompiluje na nič. Všetko, čo závisí od požiadavky, patrí do bloku, ktorý sa vykresľuje za behu: core/site-title namiesto vypísaného názvu webu, core/post-title namiesto the_title() alebo váš vlastný dynamický blok Blockstudio.

Výsledky kompilácie sa ukladajú do vyrovnávacej pamäte spolu s metadátami na sledovanie súborov. Úpravou manifestu alebo zdrojového súboru sa obsah daného prvku v pamäti zneplatní, takže pri ďalšej požiadavke sa prejaví zmena bez samostatného kroku zostavenia.

Ako WordPress načítava súbory

Blockstudio sa pripája k rovnakému vyhľadávaniu, aké WordPress používa pre šablóny tém. V get_block_templates() sa šablóny zo súborov zobrazujú s source: "theme" a origin: "theme", rovnako ako natívne súbory témy, a get_block_template( 'acme//header', 'wp_template_part' ) vráti časť hlavičky s jej area.

Poradie vyhľadávania:

  1. Úprava v Editore webu uložená v databáze.
  2. Natívny súbor .html v aktívnej téme.
  3. Zdroj zo súborov Blockstudio.
  4. Záložné možnosti nadradenej témy alebo doplnku.

Toto poradie zachováva pracovný postup v Editore webu. Keď používateľ upraví pätu a uloží ju, WordPress uloží príspevok wp_template_part a get_block_template() vráti túto úpravu s source: "custom". Neskoršie zmeny v parts/footer/index.html sa neprejavia, kým úprava existuje. Keď používateľ obnoví pôvodnú časť alebo sa príspevok odstráni, vyhľadávanie sa vráti k súboru a znova načíta najnovší skompilovaný zdroj.

Blockstudio nezapisuje úpravy z Editora webu späť do súborov. Ak sa má zmena používateľa stať novým predvoleným nastavením, skopírujte ju do zdrojového súboru a obnovte pôvodnú verziu.

Vnorené index.html a slugy

WordPress rekurzívne vyhľadáva súbory .html v templates/ a parts/. Priečinok s manifestom, ktorý používa index.html, napríklad parts/footer/index.html, sa preto zobrazí aj ako natívna časť so slugom odvodeným od cesty footer/index. Keďže Blockstudio 7.6.6, časť index.html spravovaná manifestom sa sprístupní iba pod deklarovaným slugom, takže Editor webu zobrazí jednu pätu, nie dve. Vnorené súbory .html bez manifestu zostanú nedotknuté.

Kontrola šablón z PHP

Trieda Blockstudio\Site_Templates načítava a kompiluje zdroje, čo je užitočné pri testovaní a kontrolách nasadenia:

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 alebo wp_template_part), status, source_type, postTypes pre šablóny alebo area pre časti, meta a skompilované content. Zoznamom určíte, ktoré položky sa majú skompilovať, a problémy pre daný výber zobrazíte pomocou selection_errors():

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

Pridanie ďalších priečinkov

Ak chcete oddeliť zdroje Blockstudio od natívnych šablón alebo ich distribuovať prostredníctvom doplnku, pridajte ďalšie koreňové priečinky na vyhľadávanie pomocou filtrov:

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

Filtre blockstudio/site_templates/template_content a part_content upravia zdroj pred jeho parsovaním, zatiaľ čo blockstudio/site_templates/parser vymení parser pre jednu položku. Úplný zoznam nájdete v tabuľke Háčiky šablón webu.

Kedy čo použiť

Čo potrebujete Použite
Rozloženie témy, ktoré WordPress vyberie pre URL: hlavičku, pätu, jednotlivý príspevok, archív Šablóny a časti webu
Stránku s vlastnou adresou, ktorej obsah sa nachádza v súboroch Stránky založené na súboroch
Opakovane použiteľnú sekciu, ktorú redaktori vkladajú Vzory

Šablóny nevytvárajú príspevky. Vytvárajú ich stránky. Napríklad sekcia dokumentácie je kolekcia stránok, ktorých príspevky sa vykresľujú pomocou šablóny, ktorú stále môžete vytvoriť tu.

Ďalšie kroky