Перейти к содержимому

Создание шаблонов с помощью тегов блоков

Когда в проекте появляется несколько блоков, шаблоны начинают зависеть друг от друга. Блоку возможностей нужно вывести три карточки. Для целевой страницы нужна секция с кнопкой внутри. Для каждого блока можно вызвать bs_render_block(), но в шаблоне, заполненном вызовами PHP с вложенными массивами, трудно разобраться и еще труднее создавать вложенные структуры.

Теги блоков позволяют размещать блок прямо там, где должен появиться его вывод, в виде тега HTML:

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

Один и тот же тег означает разное в зависимости от того, где он написан. В шаблоне блока или в содержимом записи он заменяется результатом отображения блока HTML. В исходном коде страницы, паттерна или шаблона сайта он становится настоящим блоком 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>

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

Теги в шаблонах блоков выводятся автоматически. Настраивать ничего не нужно. В блоке features можно сразу вывести две карточки и разделитель core:

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. Если для префикса указано несколько пространств имен, они проверяются по порядку, и выбирается первый зарегистрированный блок. Так блок проекта может иметь приоритет над библиотечным блоком с тем же ярлыком.

Можно комбинировать и префиксы. Сначала <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 при включенном WP_DEBUG о таких атрибутах сообщается уведомлением _doing_it_wrong().

Те же теги в исходниках страниц

В шаблонах паттернов и шаблонах сайта страницы на основе файлов теги не выводятся. При разборе исходного кода они преобразуются в блоки, поэтому отображаются в редакторе. Исходный код этой страницы:

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. После этого префиксы можно оставить зарегистрированными: ничего не сломается, пока в других ветках используется сокращенная форма.

Следующие шаги