Przejdź do treści

Tworzenie szablonów za pomocą znaczników bloków

Gdy projekt zawiera już kilka bloków, szablony zaczynają zależeć od siebie. Blok funkcji chce wyświetlić trzy karty. Strona docelowa potrzebuje sekcji z przyciskiem wewnątrz. Możesz wywołać bs_render_block() dla każdego bloku, ale szablon pełen wywołań PHP z zagnieżdżonymi tablicami trudno czytać i jeszcze trudniej zagnieżdżać.

Znaczniki bloków pozwalają umieścić blok tam, gdzie ma pojawić się jego wynik, jako znacznik HTML:

HTML
<bs:acme-card title="Fast" text="Rendered on the server." />

Ten sam znacznik oznacza dwie różne rzeczy w zależności od miejsca użycia. W szablonie bloku lub treści wpisu zostaje zastąpiony wyrenderowanym HTML bloku. Na stronie, wzorcu lub w źródle szablonu witryny staje się rzeczywistym blokiem WordPress, który pojawia się w edytorze. W tym przewodniku utworzymy kilka bloków, połączymy je na oba sposoby, dodamy prefiks projektu dla krótszych nazw, a następnie pokażemy, jak przywrócić skrótom przenośną postać.

Bloki

Wystarczą trzy niewielkie bloki. Karta z dwoma polami:

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>

Sekcja, która obejmuje dowolną umieszczoną w niej zawartość, z polem heading zadeklarowanym tak samo jak pole karty:

PHP
<section useBlockProps class="acme-section">
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <InnerBlocks />
</section>

Oraz przycisk w drugiej przestrzeni nazw, acme-ui/button, z polami label i href:

PHP
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>

Znaczniki w szablonie bloku

Szablony bloków automatycznie renderują znaczniki. Nie trzeba nic konfigurować. Blok funkcji może bezpośrednio wyświetlić dwie karty i separator rdzenia:

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>

Wyrenderowanie acme/features daje:

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>

Każdy blok Blockstudio w wyniku jest poprzedzony komentarzem <!--blockstudio/namespace/slug-->. Bufor strony usuwa go z odpowiedzi; w przypadku wyniku pomijającego bufor użyj bs_strip_render_markers(). Obie składnie są równoważne. <bs:acme-card> koduje nazwę bloku w znaczniku, a <block name="acme/card"> przekazuje ją jako atrybut. Każdy inny atrybut staje się wartością pola, więc title trafia do szablonu karty jako $a['title']. Działają też bloki podstawowe, renderowane za pomocą WordPress i wbudowanych rendererów bloków.

Znaczniki otwierające i zamykające oraz zawartość wewnętrzna

Znacznik otwierający i zamykający przekazuje elementy potomne do bloku. W bloku Blockstudio wypełniają one <InnerBlocks />, a zagnieżdżone znaczniki są renderowane jako pierwsze:

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>

Jak nazwa znacznika staje się nazwą bloku

Nazwa znacznika <bs:> nie zawiera ukośnika, więc Blockstudio go wyszukuje. Po kolei zastępuje każdy łącznik ukośnikiem, od lewej do prawej, i wybiera pierwszego zarejestrowanego kandydata. <bs:acme-card> zostaje rozpoznane jako acme/card za pierwszym razem. <bs:acme-ui-button> sprawdza acme/ui-button, nie znajduje niczego, a następnie rozpoznaje acme-ui/button. Przestrzenie nazw zawierające łączniki działają więc bez konfiguracji, o ile oba warianty nie są jednocześnie zarejestrowane.

Krótsze nazwy z prefiksami

<bs:acme-ui-button> jest precyzyjne, ale długie. Prefiks projektu przypisuje krótki prefiks znacznika do jednej lub kilku przestrzeni nazw. Skonfiguruj go w blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "blockTags": {
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    }
  }
}

Możesz też zarejestrować tę samą mapę z poziomu PHP:

PHP
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
	$prefixes['acme'] = array( 'acme' );
	$prefixes['ui']   = array( 'acme-ui' );

	return $prefixes;
} );

Teraz <acme-card> zostaje rozpoznane jako acme/card, a <ui-button> jako acme-ui/button. Jeśli prefiks zawiera kilka przestrzeni nazw, są one sprawdzane po kolei, a pierwszeństwo ma pierwszy znaleziony blok. Dzięki temu blok projektu może przesłonić blok biblioteki o tym samym uproszczonym identyfikatorze.

Prefiksy można też łączyć. <acme-ui-button> najpierw sprawdza acme/ui-button. Tego bloku nie ma, a pozostała część znacznika, ui-button, jest sama w sobie zarejestrowanym znacznikiem prefiksu, więc rozpoznawanie przechodzi do acme-ui/button. Dopasowanie bezpośrednie ma zawsze pierwszeństwo przed zagnieżdżonym.

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>

Renderuje dokładnie to samo HTML co przedstawiona wyżej wersja kanoniczna.

Prefiksy podlegają kilku zasadom:

  • Prefiks składa się z małych liter i cyfr, zaczyna się od litery i nie zawiera łączników.
  • Znacznik z prefiksem, który nie wskazuje zarejestrowanego bloku, pozostaje w wyniku bez zmian. <acme-missing title="x" /> zachowuje więc pierwotną postać.
  • Dokładne aliasy z filtra blockstudio/block_tags/tag_aliases mają pierwszeństwo przed prefiksami. Alias przypisuje jeden znacznik z łącznikiem do jednego bloku, na przykład $aliases['acme-cta'] = 'acme-ui/button'; sprawia, że <acme-cta> renderuje przycisk.

Znaczniki z prefiksami i aliasami są renderowane w szablonach bloków razem ze znacznikami <bs:> i <block> z Blockstudio 7.5.

Atrybuty

Atrybuty pasujące do identyfikatora pola stają się jego wartościami. Dwa prefiksy służą do czegoś innego:

  • Atrybuty data-* są kopiowane do elementu głównego wyrenderowanego bloku.
  • Atrybuty html-* są kopiowane do elementu głównego z pominiętym prefiksem, więc html-id="intro" staje się id="intro".
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>

html-class ustawia atrybut, nie dopisuje do niego wartości, więc własne klasy acme-card wp-block-acme-card bloku znikają. Jeśli wywołujący ma dodawać klasy blokowi, zadeklaruj dla nich pole i połącz je w szablonie.

Każdy inny atrybut, który nie jest zadeklarowanym polem, zostaje pominięty. Zwykłe class="wide" na <bs:acme-card> renderuje kartę bez tego atrybutu. Blockstudio 7.7 zgłasza takie atrybuty jako powiadomienie _doing_it_wrong(), gdy włączono WP_DEBUG.

Te same znaczniki w źródłach stron

W stronach opartych na plikach, wzorcach i szablonach witryny znaczniki nie są renderowane. Podczas przetwarzania źródła są zamieniane na bloki, więc pojawiają się w edytorze. Oto źródło strony:

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>

Jest przetwarzane na następujący znacznik bloku (dla czytelności dodano podziały wierszy):

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

Wartości pól trafiają do blockstudio.attributes, gdzie bloki Blockstudio je przechowują, a akapit i oba bloki wewnętrzne stają się blokami wewnętrznymi sekcji. Prefiksy i aliasy są tu rozpoznawane na tych samych zasadach co w szablonach.

Znaczniki w treści wpisu

Zawartość wpisana w edytorze lub zapisana w widżetach nie jest domyślnie skanowana. Włącz renderowanie na poziomie strony w blockstudio.json:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

Znaczniki w the_content i widget_text są wtedy renderowane z priorytetem 5. To samo ustawienie rejestruje filtr renderujący znaczniki w dowolnym ciągu znaków:

PHP
$html = apply_filters( 'blockstudio/block_tags/render', $content );

Ogranicz znaczniki, które mogą być renderowane, za pomocą wzorców allow i deny, obsługujących symbole wieloznaczne fnmatch(). Reguły te obowiązują we wszystkich składniach i obu trybach renderowania:

JSON
{
  "blockTags": {
    "enabled": true,
    "deny": ["acme-ui/*"]
  }
}

Po wprowadzeniu tej reguły <acme-ui-button> i <bs:acme-ui-button> pozostają w wyniku bez renderowania. deny ma pierwszeństwo przed allow. Filtry blockstudio/block_tags/allow i blockstudio/block_tags/deny zmieniają te same listy z poziomu PHP.

Analiza sprawdza zapis kanoniczny

Rozszerzenie PHPStan sprawdza znaczniki bloków w szablonach PHP, Twig i Blade. Błędnie zapisana nazwa pola lub bloku jest zgłaszana wraz z nazwą rozpoznanego bloku:

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

W 7.6 obejmuje to znaczniki <bs:> i <block>. Znacznik z prefiksem, taki jak <acme-card txt="...">, nie jest sprawdzany. Wersja Blockstudio 7.7 rozszerza tę regułę na znaczniki z prefiksami, źródła stron i mapowane elementy HTML. Podpowiedź zawiera atrybuty globalne, które znacznik może przekazywać dalej.

Przywracanie skrótom zapisu kanonicznego

Znaczniki z prefiksami i aliasami ułatwiają pracę w projekcie. Są rozpoznawane tylko wtedy, gdy wczytano filtry i ustawienia projektu, więc szablon skopiowany do innego projektu, biblioteki bloków lub kontekstu agenta programistycznego traci swoje znaczenie. <bs:namespace-slug> zapisuje prawdziwą nazwę bloku i działa wszędzie, dlatego własne przykłady, komunikaty diagnostyczne i generowane dane wyjściowe Blockstudio używają tej postaci.

Samodzielne polecenie zamienia skróty na zapis kanoniczny. Załóżmy, że źródła projektu nadal zawierają krótkie formy, w tym alias, znacznik bloku, który już nie istnieje, oraz przykład w fragmencie kodu:

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>

Polecenie nie wczytuje WordPress, dlatego pobiera konfigurację projektu jako pliki JSON przechowywane poza skanowanym drzewem:

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

Najpierw uruchom próbę bez wprowadzania zmian — jest to też tryb domyślny:

Powłoka
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.

Raport zawiera każde mapowanie, które zostałoby zastosowane, oraz każdy przypadek, którego polecenie nie rozstrzygnie:

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

Raport został tu skrócony. Zawiera też konfigurację i hashe plików przed zmianami i po nich. Znaczniki otwierający i zamykający sekcję są liczone jako dwa wystąpienia. acme-quote pasuje do prefiksu acme, ale nie wskazuje żadnego znanego bloku, więc jest nieznany. acme-card wewnątrz <pre><code> to przykład, a nie znacznik, dlatego wymaga ręcznego sprawdzenia i nigdy nie jest przepisywany; to samo dotyczy komentarzy HTML i kodu w tekście.

Nie można zastosować zmian, dopóki pozostają nieznane, niejednoznaczne lub dynamiczne znaczniki:

Text
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.

Polecenie kończy działanie z kodem 2. Popraw nieznany znacznik — w tym przykładzie usuń go — i uruchom polecenie z --apply zamiast --dry-run:

Text
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.

Zmieniają się tylko nazwy znaczników. Atrybuty pozostają zachowane bajt w bajt:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>

Ponowne uruchomienie próby na wyniku zgłasza 0 changed, 0 replacements. Prefiksy można pozostawić zarejestrowane, więc nic się nie zepsuje, gdy inne gałęzie nadal używają krótkiej formy.

Następne kroki