Към съдържанието

Съставяне на шаблони с блокови тагове

Когато проектът вече има няколко блока, шаблоните започват да зависят един от друг. Блок с функции иска да показва три карти. Целева страница иска секция с бутон вътре. Можете да извикате bs_render_block() за всеки блок, но шаблон, пълен с извиквания PHP и вложени масиви, е труден за четене и още по-труден за влагане.

Блоковите тагове ви позволяват да поставите блока там, където трябва да се покаже резултатът му, като таг HTML:

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

Един и същ таг означава различни неща в зависимост от мястото, където е записан. В шаблон на блок или в съдържанието на публикация той се заменя с визуализирания HTML на блока. В изходен файл на страница, шаблонен образец или Site Template той става истински блок WordPress, който се показва в редактора. Това ръководство създава няколко блока, съставя ги и по двата начина, добавя префикс на проекта за по-кратки имена и накрая показва как тези съкратени форми да се преобразуват обратно в преносимия запис.

Блоковете

Достатъчни са три малки блока. Карта с две полета:

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>

Секция, която обгръща поставеното в нея, с поле heading, декларирано по същия начин като това на картата:

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

И бутон в друго пространство от имена, acme-ui/button, с полетата label и href:

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

Тагове в шаблон на блок

Шаблоните на блокове визуализират таговете автоматично. Не е нужна настройка. Блок с функции може направо да покаже две карти и основен разделител:

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>

Визуализирането на acme/features създава:

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>

Всеки Blockstudio блок в изхода е предшестван от коментар <!--blockstudio/namespace/slug-->. Буферът на страницата го премахва от отговора; за изход, който заобикаля буфера, използвайте bs_strip_render_markers(). Двата синтаксиса са еквивалентни. <bs:acme-card> кодира името на блока в тага, а <block name="acme/card"> го задава като атрибут. Всеки друг атрибут става стойност на поле, така че title достига до шаблона на картата като $a['title']. Работят и основните блокове, визуализирани чрез WordPress с вградените визуализатори на блокове.

Тагове с отваряща и затваряща част и вътрешно съдържание

Таг с отваряща и затваряща част подава дъщерното си съдържание към блока. При блок Blockstudio то попълва <InnerBlocks />, а вложените тагове се визуализират първо:

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>

Как името на тага става име на блок

Името на таг <bs:> няма наклонена черта, затова Blockstudio търси такава. То заменя всяка тире с наклонена черта последователно отляво надясно и използва първия регистриран кандидат. <bs:acme-card> се разрешава като acme/card още при първия опит. <bs:acme-ui-button> пробва acme/ui-button, не намира нищо и след това се разрешава като acme-ui/button. Затова пространствата от имена с тирета работят без конфигурация, стига двата кандидата да не съществуват едновременно.

По-кратки имена с префикси

<bs:acme-ui-button> е прецизно, но дълго. Префикс на проекта свързва кратък префикс на таг с едно или повече пространства от имена. Настройте го в blockstudio.json:

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

Или регистрирайте същата карта чрез PHP:

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

	return $prefixes;
} );

Сега <acme-card> се разрешава като acme/card, а <ui-button> — като acme-ui/button. Когато един префикс съдържа няколко пространства от имена, те се проверяват по ред и се използва първият блок, който е регистриран. Така блок на проекта може да измести библиотечен блок със същия slug.

Префиксите могат да се комбинират. <acme-ui-button> първо пробва acme/ui-button. Този блок не съществува, а останалата част от тага, ui-button, сама по себе си е регистриран таг с префикс, затова търсенето продължава с acme-ui/button. Прякото съвпадение винаги има предимство пред вложеното.

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>

Това визуализира точно същия HTML като каноничната версия по-горе.

За префиксите важат няколко правила:

  • Префиксът съдържа малки букви и цифри, започва с буква и няма тирета.
  • Таг с префикс, който не сочи към регистриран блок, остава непроменен в резултата, така че <acme-missing title="x" /> се запазва както е написан.
  • Точните псевдоними от филтъра blockstudio/block_tags/tag_aliases имат предимство пред префиксите. Псевдонимът свързва един таг с тире с един блок. Например $aliases['acme-cta'] = 'acme-ui/button'; кара <acme-cta> да визуализира бутона.

Таговете с префикси и псевдоними се визуализират в шаблоните на блокове заедно с таговете <bs:> и <block> от Blockstudio 7.5.

Атрибути

Атрибутите, които съвпадат с ID на поле, стават стойности на полета. Два префикса имат друго предназначение:

  • Атрибутите data-* се копират в основния елемент на визуализирания блок.
  • Атрибутите html-* се копират в основния елемент без префикса, така че html-id="intro" става 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 задава атрибута, а не добавя стойност към него: собствените класове acme-card wp-block-acme-card на блока се премахват. Ако извикващият код трябва да добави класове към блок, декларирайте поле за тях и ги обединете в шаблона.

Всеки друг атрибут, който не е декларирано поле, се премахва. Обикновен class="wide" в <bs:acme-card> визуализира картата без този атрибут. Blockstudio 7.7 съобщава за такива атрибути с известие _doing_it_wrong(), когато е включен WP_DEBUG.

Същите тагове в изходните файлове на страници

В страници от файлове, шаблонни образци и Site Templates таговете не се визуализират. При анализ на изходния файл те се преобразуват в блокове, така че да се показват в редактора. Ето този изходен файл на страница:

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>

се анализира до тази маркировка на блокове (с добавени нови редове за по-лесно четене):

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

Стойностите на полетата се поставят в blockstudio.attributes, където блоковете Blockstudio ги съхраняват, а абзацът и двата вътрешни блока стават вътрешни блокове на секцията. Префиксите и псевдонимите се разрешават тук точно както в шаблоните.

Тагове в съдържанието на публикация

Съдържанието, написано в редактора или съхранено в уиджети, не се сканира по подразбиране. Включете визуализирането на ниво страница в blockstudio.json:

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

След това таговете в the_content и widget_text се визуализират с приоритет 5. Същият превключвател регистрира филтър за визуализиране на тагове във всеки низ:

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

Ограничете кои тагове могат да се визуализират с шаблони allow и deny, които приемат заместващи знаци fnmatch() и важат за всеки синтаксис и двата режима на визуализиране:

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

С това правило <acme-ui-button> и <bs:acme-ui-button> остават във резултата без визуализиране. deny има предимство пред allow. Филтрите blockstudio/block_tags/allow и blockstudio/block_tags/deny променят същите списъци от PHP.

Анализът проверява каноничния запис

Разширението PHPStan валидира блоковите тагове в шаблоните PHP, Twig и Blade. Ако има грешка в име на поле или блок, съобщението посочва блока, към който е разрешено името:

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

Във версия 7.6 това обхваща таговете <bs:> и <block>. Таг с префикс, например <acme-card txt="...">, остава непроверен. Blockstudio 7.7 разширява правилото и за тагове с префикс, изходни файлове на страници и съпоставени елементи HTML; подсказката му изброява глобалните атрибути, които даден таг може да препраща.

Преобразуване на съкратените форми в каноничния запис

Таговете с префикси и псевдоними са удобство за конкретния проект. Те се разрешават само когато са заредени филтрите и настройките на проекта, така че шаблон, копиран в друг проект, библиотека от блокове или контекст на помощник за програмиране, губи значението си. <bs:namespace-slug> записва истинското име на блока и се разрешава навсякъде. Затова собствените примери, диагностични съобщения и генериран изход на Blockstudio го използват.

Самостоятелна команда преобразува съкратените форми в този запис. Да разгледаме проект, чиито източници все още използват кратките форми, включително псевдоним, таг за несъществуващ вече блок и пример в кодов фрагмент:

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>

Командата не зарежда WordPress, затова приема конфигурацията на проекта като файлове JSON, съхранявани извън сканираното дърво:

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

Първо направете пробно изпълнение, което е и поведението по подразбиране:

Обвивка
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.

Отчетът изброява всяко съпоставяне, което командата би приложила, и всеки случай, за който няма да прави предположения:

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

Тук отчетът е съкратен. В него се записват и хешовете на конфигурацията и на всеки файл преди и след промяната. Отварящият и затварящият таг на секцията се броят като две срещания. acme-quote съвпада с префикса acme, но не посочва познат блок, затова е неизвестен. acme-card в <pre><code> е пример, а не маркировка, затова се отбелязва за ръчна проверка и никога не се пренаписва; същото важи за коментарите HTML и вградения код.

Промените не могат да се приложат, докато има неизвестни, двусмислени или динамични тагове:

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

Командата завършва с код 2. Поправете неизвестния таг, като тук го премахнете, и изпълнете командата с --apply вместо с --dry-run:

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

Променят се само имената на таговете. Атрибутите се запазват байт по байт:

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

Ако повторите пробното изпълнение върху резултата, отчетът ще покаже 0 changed, 0 replacements. Префиксите могат да останат регистрирани след това, така че няма да възникнат проблеми, докато други клонове все още използват кратката форма.

Следващи стъпки