Sablonok összeállítása blokkcímkékkel
Ha egy projektben már néhány blokk is van, a sablonoknak szükségük lesz egymásra. Egy funkcióblokk három kártyát szeretne megjeleníteni. Egy céloldal pedig egy gombot tartalmazó szakaszt. Mindegyikhez meghívhatod a bs_render_block() függvényt, de egy sablon, amely tele van PHP hívásokkal és egymásba ágyazott tömbökkel, nehezen olvasható és nehezen bővíthető.
A blokkcímkékkel közvetlenül oda írhatod a blokkot, ahol a kimenetének meg kell jelennie, egy HTML címkeként:
<bs:acme-card title="Fast" text="Rendered on the server." />
Ugyanaz a címke mást jelent attól függően, hogy hol szerepel. Blokksablonban vagy bejegyzéstartalomban a blokk renderelt HTML kimenete kerül a helyére. Oldal-, mintázat- vagy webhelysablon-forrásban valódi WordPress blokk lesz belőle, amely megjelenik a szerkesztőben. Ez az útmutató néhány blokk létrehozásán és mindkét módon történő összeállításán keresztül bemutatja a rövidebb neveket biztosító projektelőtagokat, majd azt is, hogyan alakíthatók vissza ezek a rövidítések hordozható írásmódra.
A blokkok
Három egyszerű blokk elég. Egy kétmezős kártya:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/card",
"title": "Card",
"blockstudio": {
"attributes": [
{ "id": "title", "type": "text", "label": "Title", "default": "" },
{ "id": "text", "type": "textarea", "label": "Text", "default": "" }
]
}
}
<article useBlockProps class="acme-card">
<h3><?php echo esc_html( $a['title'] ); ?></h3>
<p><?php echo esc_html( $a['text'] ); ?></p>
</article>
Egy szakasz, amely körbeveszi a benne elhelyezett tartalmat, egy heading mezővel, amelyet a kártyáéhoz hasonlóan deklarálunk:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
És egy gomb a második névtérben, a acme-ui/button-ban, a következő mezőkkel: label és href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Címkék blokksablonban
A blokksablonok automatikusan renderelik a címkéket. Nincs szükség beállításra. Egy funkcióblokk közvetlenül megjeleníthet két kártyát és egy core elválasztót:
<div useBlockProps class="acme-features">
<bs:acme-card title="Fast" text="Rendered on the server." />
<block name="acme/card" title="Typed" text="Fields come from block.json." />
<block name="core/separator" />
</div>
A acme/features renderelése ezt eredményezi:
<!--blockstudio/acme/features--><div class="acme-features wp-block-acme-features">
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Fast</h3>
<p>Rendered on the server.</p>
</article>
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Typed</h3>
<p>Fields come from block.json.</p>
</article>
<hr class="wp-block-separator has-alpha-channel-opacity">
</div>
A kimenetben minden Blockstudio blokkot egy <!--blockstudio/namespace/slug--> megjegyzés előz meg. Az oldal puffere eltávolítja ezt a válaszból; ha a kimenet kihagyja a puffert, használja ezt: bs_strip_render_markers().
A két szintaxis egyenértékű. A <bs:acme-card> a címkében kódolja a blokk nevét, a <block name="acme/card"> pedig attribútumként adja át. Minden más attribútum mezőértékké válik, így a title a kártyasablonhoz $a['title'] formában jut el. Az alapblokkok is működnek, a beépített blokkrenderelőkön keresztül, a WordPress használatával.
Páros címkék és belső tartalom
A páros címke átadja a gyermekelemeit a blokknak. Egy Blockstudio blokk esetében ezek töltik ki a <InnerBlocks /> mezőt, a beléjük ágyazott címkék pedig először renderelődnek:
<bs:acme-section heading="Why Acme">
<bs:acme-card title="Fast" text="Rendered on the server." />
<bs:acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
<!--blockstudio/acme/section--><section class="acme-section wp-block-acme-section">
<h2>Why Acme</h2>
<div>
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Fast</h3>
<p>Rendered on the server.</p>
</article>
<!--blockstudio/acme-ui/button--><a class="acme-button wp-block-acme-ui-button" href="/start">Get started</a>
</div>
</section>
Hogyan lesz a címkenévből blokk neve
A <bs:> címkenévben nincs perjel, ezért a Blockstudio megkeres egyet. Balról jobbra haladva minden kötőjelet perjelre cserél, majd az első bejegyzett jelöltet használja. A <bs:acme-card> első próbálkozásra a acme/card névre oldódik fel. A <bs:acme-ui-button> a acme/ui-button értékkel próbálkozik, nem talál semmit, majd a acme-ui/button névre oldódik fel. A kötőjelet tartalmazó névterek ezért külön konfiguráció nélkül is működnek, ha a két jelölt közül csak az egyik létezik.
Rövidebb nevek előtagokkal
A <bs:acme-ui-button> pontos, de hosszú. Egy projektelőtag a rövid címkeelőtagot egy vagy több névtérhez rendeli. A blockstudio.json fájlban konfigurálhatod:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Vagy regisztráld ugyanezt a leképezést a PHP használatával:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Most a <acme-card> a acme/card névre oldódik fel, a <ui-button> pedig a acme-ui/button névre. Ha egy előtag több névteret sorol fel, a rendszer sorrendben próbálkozik, és az első bejegyzett blokk nyer. Így egy projekt blokkja felülírhatja ugyanazon slug könyvtári blokkját.
Az előtagok egymásba is ágyazhatók. A <acme-ui-button> először a acme/ui-button értékkel próbálkozik. Ez a blokk nem létezik, a címke többi része, a ui-button pedig önállóan bejegyzett előtagcímke, ezért a feloldás a acme-ui/button értékre folytatódik. A közvetlen egyezés mindig elsőbbséget élvez a beágyazottal szemben.
<bs:acme-section heading="Why Acme">
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
Ez pontosan ugyanazt a HTML rendereli, mint a fenti kanonikus változat.
Az előtagokra néhány szabály vonatkozik:
- Az előtag kisbetűkből és számjegyekből áll, betűvel kezdődik, és nem tartalmaz kötőjelet.
- Ha az előtaggal ellátott címke nem oldható fel bejegyzett blokkra, változatlanul marad a kimenetben, tehát a
<acme-missing title="x" />úgy marad, ahogy leírtad. - A
blockstudio/block_tags/tag_aliasesszűrőben megadott pontos aliasok elsőbbséget élveznek az előtagokkal szemben. Egy alias egy kötőjeles címkét rendel egy blokkhoz; például a$aliases['acme-cta'] = 'acme-ui/button';hatására a<acme-cta>a gombot rendereli.
Az előtag- és aliascímkék a blokksablonokban a Blockstudio 7.5-ös verziójából származó <bs:> és <block> címkékkel együtt renderelődnek.
Attribútumok
A mezőazonosítóval egyező attribútumok mezőértékké válnak. Két előtag másként működik:
- A
data-*attribútumok a renderelt blokk gyökérelemére kerülnek. - A
html-*attribútumok szintén a gyökérelemre kerülnek, de az előtag nélkül, így ahtml-id="intro"értékébőlid="intro"lesz.
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
<article data-track="card" id="intro" class="featured">
<h3>Hi</h3>
<p>There</p>
</article>
A html-class beállítja az attribútum értékét, nem hozzáfűz: a blokk saját acme-card wp-block-acme-card osztályai eltűnnek. Ha a hívó fél osztályokat szeretne hozzáadni a blokkhoz, deklarálj egy erre szolgáló mezőt, és fűzd hozzá a sablonban.
A deklarált mezőként meg nem adott összes többi attribútum törlődik. Ha a <bs:acme-card> elemen egyszerűen csak class="wide" szerepel, a kártya nélküle renderelődik. A WP_DEBUG bekapcsolásakor a Blockstudio 7.7 egy _doing_it_wrong() jelzésben jelenti az ilyen attribútumokat.
Ugyanezek a címkék oldalforrásokban
A fájlalapú oldalakon, mintázatokban és webhelysablonokban a címkék nem renderelődnek. A forrás feldolgozásakor blokkokká alakulnak, ezért megjelennek a szerkesztőben. Ez az oldalforrás:
<bs:acme-section heading="Why Acme">
<p>Everything below is a real block.</p>
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
Ebből a blokkjelölésből áll elő (a könnyebb olvashatóság kedvéért sortörésekkel):
<!-- wp:acme/section {"blockstudio":{"attributes":{"heading":"Why Acme"}}} -->
<!-- wp:paragraph --><p>Everything below is a real block.</p><!-- /wp:paragraph -->
<!-- wp:acme/card {"blockstudio":{"attributes":{"title":"Fast","text":"Rendered on the server."}}} /-->
<!-- wp:acme-ui/button {"blockstudio":{"attributes":{"label":"Get started","href":"/start"}}} /-->
<!-- /wp:acme/section -->
A mezőértékek a blockstudio.attributes alatt jelennek meg, ahol a Blockstudio blokkok tárolják őket, a bekezdés és mindkét belső blokk pedig a szakasz belső blokkjává válik. Az előtagok és aliasok itt ugyanúgy oldódnak fel, mint a sablonokban.
Címkék a bejegyzések tartalmában
A szerkesztőben írt vagy widgetekben tárolt tartalmat a rendszer alapértelmezés szerint nem vizsgálja át. Engedélyezd az oldalszintű renderelést itt: blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Ezután a the_content és widget_text címkék a 5 prioritással renderelődnek. Ugyanez a kapcsoló egy szűrőt is regisztrál, amely tetszőleges karakterláncban rendereli a címkéket:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
A renderelhető címkék korlátozásához használd a allow és deny mintákat, amelyek fnmatch() helyettesítő karaktereket fogadnak el, és minden szintaxisra, valamint mindkét renderelési módra érvényesek:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Ezzel a szabállyal a <acme-ui-button> és a <bs:acme-ui-button> renderelés nélkül marad a kimenetben. A deny elsőbbséget élvez a allow értékkel szemben. A blockstudio/block_tags/allow és blockstudio/block_tags/deny szűrők a PHP helyről módosítják ugyanezeket a listákat.
Az elemzés a kanonikus írásmódot ellenőrzi
A PHPStan bővítmény ellenőrzi a blokkcímkéket a PHP, a Twig és a Blade sablonokban. Az elírt mező- vagy blokknév mellett azt a blokkot is megadja, amelyre feloldódott:
3 Block tag "acme/card" has unknown attribute "txt" in index.php
🪪 blockstudio.blockTag.attribute
4 Block tag references unknown block "acme/cards" in index.php
🪪 blockstudio.blockTag.unknown
A 7.6-os verzióban ez a <bs:> és a <block> címkéket fedi le. Egy előtagos címke, például a <acme-card txt="..."> ellenőrzés nélkül marad. A Blockstudio 7.7 kiterjeszti a szabályt az előtagos címkékre, az oldalforrásokra és a leképezett HTML elemekre, a tipp pedig felsorolja azokat a globális attribútumokat, amelyeket egy címke továbbadhat.
A rövidítések átalakítása kanonikus írásmódra
Az előtagos és aliascímkék a projekt kényelmét szolgálják. Csak ott oldódnak fel, ahol betöltődnek a projekt szűrői és beállításai, ezért egy másik projektbe átmásolt sablonban, egy blokkkönyvtárban vagy egy kódolóügynök környezetében elveszítik a jelentésüket. A <bs:namespace-slug> rögzíti a valódi blokknevet, és mindenhol feloldható, ezért a Blockstudio saját példái, diagnosztikai üzenetei és generált kimenete is ezt használja.
Egy önálló parancs a rövidítéseket erre az írásmódra alakítja át. Tegyük fel, hogy egy projekt forrásai még mindig a rövid formákat használják, köztük egy aliast, egy már nem létező blokk címkéjét, valamint egy kódmintában szereplő példát:
<div useBlockProps class="acme-features">
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</div>
<acme-section heading="Why Acme">
<acme-cta label="Talk to us" href="/contact" />
<acme-quote text="Missing block" />
</acme-section>
<pre><code><acme-card /> <acme-card title="Example" /></code></pre>
A parancs nem tölti be a WordPress értéket, ezért a projekt konfigurációját JSON fájlként kell megadni, a vizsgált könyvtárfán kívül tárolva:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Először futtass próbaüzemet; ez az alapértelmezett mód:
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
--root="$PWD" \
--prefix-map=/tmp/acme-tags/prefixes.json \
--known-blocks=/tmp/acme-tags/blocks.json \
--aliases=/tmp/acme-tags/aliases.json \
--report=/tmp/acme-tags/report.json \
--dry-run
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.
A jelentés felsorolja az összes alkalmazandó megfeleltetést és azokat az eseteket, amelyeknél a parancs nem találgat:
{
"mappings": [
{ "legacy": "acme-card", "canonical": "bs:acme-card", "block": "acme/card", "occurrences": 1 },
{ "legacy": "acme-cta", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 },
{ "legacy": "acme-section", "canonical": "bs:acme-section", "block": "acme/section", "occurrences": 2 },
{ "legacy": "acme-ui-button", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 }
],
"unknown": [
{ "path": "pages/home/index.php", "line": 3, "column": 4, "tag": "acme-quote", "reason": "no-known-block" }
],
"manual": [
{ "path": "pages/home/index.php", "line": 5, "column": 33, "tag": "acme-card", "reason": "code-sample" }
]
}
A jelentés itt rövidített. A konfigurációhoz és minden fájlhoz rögzíti a módosítás előtti és utáni hashértéket is. A szakasz nyitó- és zárócímkéje két előfordulásnak számít. A acme-quote illeszkedik a acme előtagra, de nem nevez meg ismert blokkot, ezért ismeretlen. A <pre><code> belsejében lévő acme-card példa, nem jelölés, ezért kézi ellenőrzésre kerül, és soha nem íródik át; ugyanez vonatkozik a HTML megjegyzésekre és a soron belüli kódra.
Az alkalmazást a parancs megtagadja, amíg ismeretlen, kétértelmű vagy dinamikus címkék maradnak:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
A parancs 2 kilépési kódot ad. Javítsd ki az ismeretlen címkét – itt például távolítsd el –, majd futtasd a --dry-run helyett a --apply kapcsolóval:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Csak a címkenevek változnak. Az attribútumok bájtról bájtra változatlanok maradnak:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Ha újra lefuttatod a próbaüzemet az eredményen, a jelentés ezt adja: 0 changed, 0 replacements. Az előtagok ezután is regisztrálva maradhatnak, így nem romlik el semmi, amíg más ágak a rövid formát használják.
Következő lépések
- Renderelés: a teljes címkeszintaxis, az egyéni renderelők és az elemző.
- Beállítások: minden
blockTagslehetőség. - Fájlalapú oldalak készítése: oldalforrások, amelyekben a címkék szerkeszthető blokkokká válnak.
- Blokkcímkék áttelepítése: az áttelepítési parancs összes lehetősége.
- Ellenőrzött sablonok a PHPStan használatával: címkéket ellenőrző elemzés futtatása.