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:
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:
{
"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:
<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ő:
<!-- 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.
2. lépés: A lábléc-rész
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:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<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é.
{
"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" />
A bejegyzés egyedi sablonja ugyanezt a felépítést követi bejegyzésblokkokkal:
{
"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" />
A lefordított bejegyzéssablon:
<!-- 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:
{
"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" />
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:
- A Webhelyszerkesztő adatbázisban tárolt testreszabása.
- A
.htmlnatív fájlja az aktív témában. - A Blockstudio fájlalapú forrás.
- 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:
$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:
$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:
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
- Webhelysablonok referenciája: minden jegyzéktulajdonság, a PHP API és az összes hook.
- Oldalak és minták áttekintése: a HTML feldolgozó, a blokkcímkék és a sablonforrásokban használt elemek megfeleltetése.
- Dokumentációs webhely készítése: oldalgyűjtemények Markdown, betöltőkkel és elrendezésekkel.