Перейти до вмісту

Компонування шаблонів із тегами блоків

Коли в проєкті з’являється кілька блоків, шаблони починають залежати один від одного. Блок функцій має вивести три картки. Для цільової сторінки потрібен розділ із кнопкою всередині. Для кожного можна викликати 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>

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

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

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.

Атрибути

Атрибути, що відповідають ідентифікатору поля, стають значеннями поля. Два префікси працюють інакше:

  • Атрибути 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.

Ті самі теги у вихідному коді сторінок

У сторінках на основі файлів, патернах і шаблонах сайту теги не рендеряться. Під час розбору вихідного коду вони перетворюються на блоки, тож з’являються в редакторі. Ось вихідний код сторінки:

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

Наступні кроки