Ugrás a tartalomhoz

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:

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

JSON
{
  "$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": "" }
    ]
  }
}
PHP
<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:

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

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

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

HTML
<!--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:

HTML
<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>
HTML
<!--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:

JSON
{
  "$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:

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

HTML
<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_aliases szű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 a html-id="intro" értékéből id="intro" lesz.
HTML
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
HTML
<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:

HTML
<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):

HTML
<!-- 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:

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:

PHP
$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:

JSON
{
  "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:

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

PHP
<div useBlockProps class="acme-features">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</div>
PHP
<acme-section heading="Why Acme">
  <acme-cta label="Talk to us" href="/contact" />
  <acme-quote text="Missing block" />
</acme-section>
<pre><code>&lt;acme-card /&gt; <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:

JSON
{ "acme": ["acme"], "ui": ["acme-ui"] }
JSON
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
JSON
{ "acme-cta": "acme-ui/button" }

Először futtass próbaüzemet; ez az alapértelmezett mód:

Shell
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
Text
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:

JSON
{
  "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:

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

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

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