Ugrás a tartalomhoz

Webhelyszerkesztő-sablonok és -sablonrészek fájlokból

Egy blokktéma az elrendezését templates/*.html és parts/*.html fájlokban írja le: blokkokat szerializált megjegyzések formájában tartalmazó fájlokban, például <!-- wp:template-part {"slug":"header"} /-->. Senki sem szeretné ezeket kézzel írni, ezért általában a Webhelyszerkesztőben készülnek, majd exportálják őket. Ez addig működik, amíg két ember ugyanazt a sablont szerkeszti, vagy egy bírálónak a HTML megjegyzésekbe írt escape-elt JSON kód változásait kell átnéznie.

A Blockstudio segítségével ugyanazokat a sablonokat fájlalapú oldalakhoz hasonlóan írhatja meg: egy mappába kerül egy rövid JSON jegyzék és egy forrásfájl HTML-szerű jelöléssel, egyszerű elemekkel, <block> címkékkel és saját Blockstudio blokkokkal. A Blockstudio natív blokkjelöléssé fordítja a forrást, majd témához tartozó fájlként átadja a WordPress számára. A Webhelyszerkesztő továbbra is pontosan a megszokott módon működik: a felhasználók testreszabhatják a sablont, a visszaállítás pedig ismét a fájlverziót tölti be.

Ez az útmutató létrehoz egy fejléc- és egy lábléc-részt, kezdőlap- és bejegyzés-sablonokat, valamint egy egyéni sablont, amelyet a szerkesztők kiválaszthatnak az oldalakhoz, majd bemutatja, hogyan oldja fel őket a WordPress.

Mappastruktúra

A sablonok helye a templates/, a sablonrészeké pedig a parts/. Mindegyik egy mappa, benne egy jegyzékkel és egy forrásfájllal:

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

Ezek ugyanazok a templates/ és parts/ mappák, amelyeket a blokktémához a WordPress olvas be. A Blockstudio először az aktív, majd a szülőtémát vizsgálja át. A template.json vagy part.json fájllal rendelkező mappák Blockstudio források; a mellettük lévő egyszerű .html fájlok továbbra is natív WordPress sablonok maradnak.

A forrásfájl lehet index.php, index.blade.php, index.twig vagy index.html; az ellenőrzés ebben a sorrendben történik. A Twig használatához Timber szükséges, a Blade használatához pedig a megjelenítőcsomagja, ahogy azt a Sablonmotorok című rész ismerteti.

1. lépés: A fejléc-rész

Minden részhez szükség van egy part.json elemre. A area adja meg, hová tartozik a rész a Webhelyszerkesztőben:

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

A forrás ugyanazt a szintaxist használja, mint az Blockstudio oldalak és minták. Egy <div> csoportblokká válik, az attribútumok blokkattribútumokká, a <block> elemek pedig bármely regisztrált blokkot előállíthatnak:

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

A Blockstudio ezt a blokkjelölést állítja elő:

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

Ezt írta volna meg egyébként kézzel. A saját blokkok ugyanígy működnek: a <block name="acme/announcement" />, egy <bs:acme-announcement /> címke vagy egy beállított címkeelőtag is az adott blokk megjegyzését eredményezi.

Egy rész akár egyetlen bekezdésből is állhat. Ez a index.html használatával mutatja be, hogy a forrás jelölés, nem program:

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

A fordítás eredménye: <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.

3. lépés: Kezdőlap- és bejegyzés-sablonok

A sablonok a template.json elemet használják. A slug értékének pontosan meg kell egyeznie a WordPress sablonhierarchia egyik nevével, például: front-page, single, page, archive, 404 vagy single-product. A Blockstudio soha nem kerül elé.

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

A bejegyzés egyedi sablonja ugyanezt a felépítést követi bejegyzésblokkokkal:

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

A lefordított bejegyzéssablon:

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

A <main> csoportblokkká vált a tagName: "main" értékkel, a sablonrész-blokkok pedig az 1. és 2. lépésben létrehozott részekre hivatkoznak a slugjuk alapján. Amikor a WordPress megjeleníti a sablont, ezek a hivatkozások feloldódnak a fájlalapú részekre: így a kezdőlap kimenete a webhely címét és navigációját tartalmazó <header class="wp-block-template-part"> elemmel kezdődik, és a lábléc bekezdését tartalmazó <footer class="wp-block-template-part"> elemmel zárul.

4. lépés: Egyéni sablon oldalakhoz

A hierarchiába nem tartozó slugú sablonok egyéni sablonok. A postTypes segítségével sorolja fel, mely bejegyzéstípusokra alkalmazhatók, így a szerkesztők kiválaszthatják őket a sablonválasztóban:

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

A get_block_templates( array( 'post_type' => 'page' ), 'wp_template' ) most már tartalmazza a page-landing elemet, a sablonobjektum pedig a post_types: ["page"] értéket hordozza.

A források egyszeri fordítása

A forrás beolvasása és blokkjelöléssé fordítása egyszer történik, nem minden kérésnél. Ilyenkor nincs aktuális bejegyzés és kérési környezet. A index.php jelölésként olvasódik be: a benne lévő PHP kód nem fut le, ezért a <?php echo get_bloginfo( 'name' ); ?> semmit sem eredményez. A kéréstől függő tartalom futásidőben megjelenített blokkba való: például core/site-title a webhely nevének kiírása helyett, core/post-title a the_title() helyett, vagy saját dinamikus Blockstudio blokk.

A lefordított eredmények gyorsítótárazása a fájlfigyelő metaadataival együtt történik. Egy jegyzék- vagy forrásfájl módosítása érvényteleníti az adott elem gyorsítótárazott tartalmát, így a következő kérés már a módosított változatot kapja külön buildlépés nélkül.

Hogyan látja a fájlokat a WordPress

A Blockstudio ugyanazokhoz a keresési folyamatokhoz kapcsolódik, amelyeket a WordPress használ a témasablonokhoz. A get_block_templates() felületen a fájlalapú sablonok a source: "theme" és a origin: "theme" értékkel jelennek meg, akárcsak a natív témához tartozó fájlok; a get_block_template( 'acme//header', 'wp_template_part' ) pedig a fejléc-részt adja vissza a saját area értékével.

A keresés sorrendje:

  1. A Webhelyszerkesztő adatbázisban tárolt testreszabása.
  2. A .html natív fájlja az aktív témában.
  3. A Blockstudio fájlalapú forrás.
  4. A szülőtémából vagy bővítményből származó tartalékok.

Ez a sorrend megőrzi a Webhelyszerkesztő munkafolyamatát. Amikor a felhasználó szerkeszti és menti a láblécet, a WordPress egy wp_template_part bejegyzést tárol, a get_block_template() pedig ezt a testreszabást adja vissza a source: "custom" értékkel. A parts/footer/index.html későbbi módosításai nem jelennek meg, amíg a testreszabás létezik. Amikor a felhasználó visszaállítja a részt, vagy törli a bejegyzést, a keresés visszatér a fájlhoz, és ismét a legújabb lefordított forrást adja vissza.

A Blockstudio nem írja vissza fájlokba a Webhelyszerkesztő módosításait. Ha a felhasználó módosításának kell az új alapértelmezetté válnia, másolja át a forrásfájlba, majd állítsa vissza a testreszabást.

Beágyazott index.html elemek és slugok

A WordPress rekurzívan keresi meg a templates/ és parts/ helyen található .html fájlokat. Ezért egy olyan jegyzékmappa, amely a index.html elemet használja – például a parts/footer/index.html –, szintén natív részként jelenik meg, az útvonalból származó footer/index sluggal. Mivel a Blockstudio 7.6.6, a jegyzékhez tartozó index.html csak a deklarált slug alatt jelenik meg, így a Webhelyszerkesztő egy láblécet sorol fel, nem kettőt. A jegyzék nélküli, beágyazott .html fájlokhoz nem nyúl.

Sablonok ellenőrzése a PHP segítségével

A Blockstudio\Site_Templates osztály beolvassa és lefordítja a forrásokat; ez tesztek és telepítési ellenőrzések során hasznos:

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

Minden elem tartalmazza a slug, title, description és type értéket (wp_template vagy wp_template_part), a status, source_type és postTypes értéket sablonoknál, illetve a area értéket részeknél, továbbá a meta értéket és a lefordított content elemet. Adjon át listát, ha csak a kiválasztott elemeket szeretné lefordítani; a hozzájuk tartozó problémákat a selection_errors() segítségével olvashatja ki:

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

További mappák hozzáadása

Ha a Blockstudio forrásokat el szeretné különíteni a natív sablonoktól, vagy bővítményből szeretné biztosítani őket, szűrőkkel adjon hozzá keresési gyökérmappákat:

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

A blockstudio/site_templates/template_content és part_content szűrők a feldolgozás előtt módosítják a forrást, a blockstudio/site_templates/parser pedig egyetlen elemhez cseréli le a feldolgozót. A szűrők teljes listáját a Webhelysablonok hookjainak táblázata tartalmazza.

Mikor melyiket használja?

Cél Használja
A témához tartozó elrendezés WordPress egy URL számára választ: fejléc, lábléc, egyedi bejegyzés, archívum Webhelysablonok és -részek
Fájlokban tárolt tartalmú, útvonallal elérhető oldal Fájlalapú oldalak
Újra felhasználható, szerkesztők által beszúrható szakasz Minták

A sablonok nem hoznak létre bejegyzéseket; az oldalak igen. Például egy dokumentációs szakasz olyan oldalgyűjtemény, amelynek bejegyzései továbbra is az itt létrehozható sablon segítségével jelennek meg.

Következő lépések