Програмне виведення
Оскільки Gutenberg стає основним інструментом для створення сайтів, які клієнти можуть легко редагувати, доцільно створити всі потрібні розділи сайту як блоки. Такий підхід підійде більшості, але досвідченим користувачам і для окремих випадків може знадобитися використовувати наявні блоки поза редактором.
Blockstudio пропонує два способи програмного виведення блоків:
- Функції PHP:
bs_render_blockтаbs_blockдля виведення з коду PHP - Теги HTML: теги
<bs:block-name>, які замінюються виводом блока в будь-якому місці сторінки
Підтримуються всі функції, специфічні для Blockstudio, як-от вбудовані стилі, скрипти та обмежені стилі.
Острови також працюють із цими способами виведення. Динамічний острів, виведений за допомогою bs_render_block(), bs_block() або тега блока, повертає той самий маркер-заповнювач, що й блок із вмісту запису. Якщо цей маркер є у відповіді, середовище виконання фронтенду додається автоматично.
Структуровані композиції та повні документи
Для довготривалих інструментів, попереднього перегляду, експорту та галерей компонентів використовуйте версіонований Blockstudio\Render API. Він приймає одне оголошення або впорядкований список і виводить результат без echo:
use Blockstudio\Render;
$composition = [
'root' => 'theme/card',
'example' => [
'data' => [
'heading' => 'Example card',
],
'layers' => [
[
'name' => 'theme/button',
'data' => [
'label' => 'Continue',
],
],
],
],
];
$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
'title' => 'Component preview',
'contentElement' => 'main',
'contentClasses' => ['component-preview'],
]);
Канонічне нормалізоване оголошення має чотири ключі:
[
'name' => 'theme/card',
'attributes' => [],
'content' => '',
'children' => [],
]
data, inner, innerBlocks, root, layers і example — це спрощені параметри вводу, які після нормалізації видаляються. Вкладені оголошення рекурсивно виводяться через той самий конвеєр Blockstudio.
Render::document() повертає schemaVersion, html, body, blocks,
assets, warnings та errors. Значення assets відокремлює head,
footer, styles, scripts, modules, interactivity, ui і tailwind.
Список блоків і ресурсів містить залежності, на які посилаються вибрані шаблони,
але не містить сторонніх ресурсів і ресурсів лише для редактора.
Повні документи можуть задавати bodyClasses/bodyAttributes і за потреби обгортати
відображене тіло елементами contentElement, contentClasses та
contentAttributes. Для обгортки дозволено лише безпечну назву елемента; повернуте
значення body залишається вмістом відображеного документа без обгортки.
Параметри head та footer додають довірену розмітку документа у відповідні
позиції та входять до набору пов’язаних ресурсів у результаті.
Щоб зібрати документ навколо вже відображеного HTML, укажіть відомі назви кореневих блоків:
$document = Render::document_from_html(
$rendered_html,
['theme/hero', 'theme/button'],
['title' => 'Homepage preview']
);
Використовуйте Render::content() для серіалізованого вмісту блоків WordPress. Якщо в одному запиті потрібно відобразити кілька незалежних документів, викликайте Blockstudio\Batch_Render::reset() між ними; Canvas::documents() робить це автоматично.
Рендеринг поза сторінкою
Blockstudio додає коментар <!--blockstudio/namespace/slug--> перед кожним блоком, який рендерить. На зовнішній сторінці буфер зчитує ці коментарі, визначає наявні блоки, завантажує їхні ресурси та видаляє коментарі перед надсиланням відповіді.
Вивід, що не проходить через цей буфер, зберігає коментарі. Це стосується відповідей REST, стрічок, обробників AJAX, а також HTML, які ви зберігаєте або надсилаєте деінде після do_blocks(), Render::content() чи bs_render_block(). Скористайтеся bs_strip_render_markers(), щоб видалити їх:
$html = bs_strip_render_markers(do_blocks($post->post_content));
Функція видаляє коментарі зареєстрованих блоків Blockstudio, залишаючи все інше без змін, зокрема інші коментарі HTML. Вона знаходить ті самі маркери, що й буфер сторінки. Викликайте її після реєстрації блоків (init або пізніше).
Не видаляйте розмітку, яка ще виводиться на зовнішній сторінці через буфер. Сторінці потрібні коментарі, щоб визначити, які ресурси блоків завантажити, а Blockstudio видаляє їх самостійно наприкінці.
Видалення коментарів не додає ресурси. Файли блоків CSS та JavaScript додає лише буфер сторінки. Скористайтеся парами функційbs_block_assets() або Render::document(), якщо вони потрібні споживачу.
Перевірка блоків
Скористайтеся bs_block_fields() після реєстрації блоків (на init або пізніше), щоб отримати розв’язані визначення полів без читання внутрішніх реєстрів:
$fields = bs_block_fields('theme/card');
if ($fields === null) {
// Unknown block, or not a Blockstudio block.
}
Повертається масив зареєстрованих визначень полів, зокрема фільтри атрибутів, розгорнуті користувацькі поля, перевизначення та вкладені групи, вкладки й повторювачі. Для блоку Blockstudio без полів повертається []. Результат є копією: його зміна не змінює зареєстрований блок.
Це визначення, а не збережені значення. Щоб перевірити збережену розмітку, використовуйте bs_validate_block() замість підтримки окремого обходу полів. Щоб описати значення, які приймає блок, використовуйте bs_block_schema(). Атрибути, що належать WordPress, залишаються окремими.
Поля, додані розширеннями, не входять до bs_block_fields(). Скористайтеся bs_block_extension_fields(), щоб отримати їх. Функція знаходить розширення за назвою блоку, тому працює також із вбудованими блоками та блоками сторонніх розробників:
$fields = array_merge(
bs_block_fields('core/paragraph') ?? [],
bs_block_extension_fields('core/paragraph')
);
Повертається список визначень полів усіх відповідних розширень у порядку їх реєстрації, зі структурою, як у bs_block_fields(). Якщо жодне розширення не відповідає блоку, повертається []. Значення розширень зберігаються в тому самому об’єкті attrs.blockstudio.attributes, що й власні значення полів блоку, тож усі ідентифікатори мають спільний простір імен. Якщо два розширення визначають той самий ідентифікатор, повертаються обидва визначення, і вони редагують одне й те саме значення; під час рендерингу застосовується визначення розширення, зареєстрованого пізніше.
Щоб прочитати значення збереженого блоку так, як їх отримує його шаблон, скористайтеся читанням значеньbs_block_values().
Скористайтеся переглядом блокуbs_block_assets(), щоб перевірити виявлені в блоці CSS та JavaScript. Щоб отримати повний документ попереднього перегляду, зокрема з вкладеними блоками та спільними залежностями середовища виконання, скористайтеся Render::document(), як описано вище.
Перевірка збережених значень
Скористайтеся bs_validate_block() після реєстрації блоків (на init або пізніше), щоб програмно перевірити атрибути блоків, згенеровані чи імпортовані перед збереженням:
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);
if ($findings === null) {
// No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
// No stored-value problems were found.
} else {
// Review the findings before saving.
}
Передавайте повний масив attrs, а не лише blockstudio.attributes. Під час рендерингу Blockstudio приймає також оголошені поля на верхньому рівні, а якщо передано обидва варіанти, пріоритет мають вкладені значення. Розширення вбудованих блоків і блоків сторонніх розробників читають лише blockstudio.attributes. Порожній блок Blockstudio є керованим і повертає [], а не null.
Перевірка виконується явно й лише для читання. Вона не рендерить шаблони, не змінює значення, не зберігає дописи, не запитує медіафайли й не запускає зворотні виклики заповнення. Вона не запускається автоматично під час збереження, синхронізації сторінок або рендерингу. Це не засіб санітизації, не перевірка авторизації й не перевірка наявності вкладення.
Кожен результат перевірки містить такі стабільні ключі:
[
'code' => 'unknown_option',
'path' => 'steps/1/style',
'source' => 'block',
'message' => 'This value is not among the field options.',
'value' => 'c',
'expected' => ['a', 'b'],
]
Використовуйте code, а не перекладене message, у засобах розробки. source — це block або
extension. У шляхах використовуються ключі сховища та індекси рядків або вибраних елементів повторювача, що починаються з нуля, без початкової скісної риски. Літеральні ~ і / у ключі екрануються як ~0 і
~1. Група верхнього рівня додає префікс до дочірніх елементів (cta_title); анонімні групи й вкладки не додають рівня. Конструктор не підтримує групи з ID усередині іншої групи або повторювача, тому їхні ключі не приймаються. Поля повідомлень не мають збереженого значення. Для поля файлів дозволено супутній елемент <id>__size.
У корені блоку Blockstudio службові ключі та глобальні атрибути HTML, передані відображуваному елементу, не вважаються невідомими полями. Це не дозволяє довільні ключі в рядках повторювача або розширення основних блоків.
| Код | Значення | expected |
|---|---|---|
unknown_field |
Жодне збережене поле не оголошує цей ключ сховища. | Відомі ключі сховища. |
unknown_option |
Вибраного значення немає серед відомих параметрів. | Дозволені значення параметрів. |
wrong_type |
Збережена структура не підтримується полем. | Очікуване сімейство або тип сховища. |
too_few_rows, too_many_rows |
Наявний повторювач виходить за межі min або max. |
Межа кількості рядків. |
definition_conflict |
Застосовні визначення одного ключа вимагають різних структур сховища. | Джерело й тип поля кожного визначення. |
shadowed_value |
Вкладене значення перевизначає інше значення поля верхнього рівня. | Переможне вкладене значення. |
extension_top_level |
Шаблон може читати значення верхнього рівня, але прив’язки розширення — ні. | Обов’язковий шлях під blockstudio/attributes. |
unknown_attribute |
Ключ верхнього рівня блоку Blockstudio не читається шляхом відображення й відкидається. | Зареєстровані назви атрибутів, поля розширень і blockstudio. |
missing_container |
attributes, disabled, name або editor збережено на верхньому рівні, а blockstudio відсутній. |
Обов’язковий шлях під blockstudio. |
invalid_container |
blockstudio або blockstudio.attributes не є об’єктом. |
object. |
У повідомленні про знахідку unknown_field вказується найближчий ключ сховища на тому самому рівні, якщо відстань до нього не перевищує трьох змін; саме це правило застосовується до невідомих параметрів: This storage key is not declared by the block or its extensions. Did you mean "title"?
expected і далі містить усі відомі ключі.
Під час зіставлення регістр не враховується, а розглядаються лише ключі сховища цього контейнера. Повідомлення перекладено; інтеграціям слід використовувати code, path та expected, а не аналізувати текст повідомлення.
Ключ верхнього рівня блоку Blockstudio, який не є зареєстрованим атрибутом
(його полями, атрибутами, які WordPress додає для supports, lock і
metadata), полем відповідного розширення, blockstudio, службовим ключем або переданим атрибутом HTML, відкидається до запуску шаблону. Такий ключ, наприклад помилково вказаний ID поля або об’єкт значень без обгортки blockstudio, спричиняє повідомлення, оскільки блок відображається без цього значення. Блоки, що містять лише поля розширень, не перевіряються на ключі верхнього рівня.
Допустимі структури відповідають відображенню: множинні вибори й прапорці можуть містити список, об’єкт одного параметра або імпортоване скалярне значення, зокрема числовий нуль. Для чисел допускаються числові рядки. Поля файлів можуть містити ID вкладень, об’єкти ID, списки або рядкові посилання. Значення посилань і піктограм мають бути об’єктами; для користувацьких типів полів використовується зареєстрований тип атрибута.
Поле attributes містить список пар із непорожньою назвою attribute і скалярним значенням value; необов’язкові метадані, як-от data.media, зберігаються.
WordPress перевіряє зареєстровані атрибути верхнього рівня перед відображенням, тож може відхилити структуру, прийнятну всередині blockstudio.attributes. Наприклад, значення радіокнопки "a" працює у вкладеному об’єкті, але на верхньому рівні відкидається, де його зареєстрований тип — object. Таке значення спричиняє wrong_type.
Для тієї самої структури сховища, яку записує редактор, використовуйте вкладений об’єкт.
Обов’язкові поля не вимагаються. Порожні вкладені значення (null, false, '',
[]) і вимкнені поля не спричиняють помилок значень. Явно порожній
повторювач усе одно перевіряється на відповідність min; відсутній або вимкнений повторювач — ні.
Про порожнє значення верхнього рівня повідомляється, якщо WordPress відкидає його й натомість відновлює непорожнє типове значення. Те саме значення у вкладеному об’єкті може його очистити.
Про конфлікти визначень повідомляється, навіть якщо для ключа немає збереженого значення.
Статичні параметри й параметри заповнення, визначені під час реєстрації, перевіряються без повторного виклику функції заповнення. Віддалені параметри fetch і аргументи заповнення, що містять {attributes.*}, пропускаються. Значення кольору й градієнта можуть бути довільними, якщо не задано disableCustomColors або disableCustomGradients.
Перевіряються збережені значення, а не default, fallback чи правила перевірки в редакторі.
Відповідні поля розширень додаються для кожного блока, на який вони націлені. Як і під час відображення, пізніші визначення мають перевагу в блоці або його розширеннях у корені. Власне поле блока й поле розширення залишаються окремими визначеннями одного ключа, і застосовуються обидва. У рядках повторювача засіб відображення читає перше поле з відповідним ID у кожному джерелі, тож застосовуються його параметри й межі. Дублікати визначень зберігаються для діагностики конфліктів: несумісні структури сховища спричиняють definition_conflict, навіть якщо пізніший дублікат не читається під час відображення.
Функція перевіряє один блок. Для перевірки документа обходьте innerBlocks; синхронізовані зразки та інші посилання автоматично не розгортаються. Команда wp bs blocks validate обходить блоки одного або кількох записів і повідомляє шляхи до їхніх блоків.
Сайти з користувацьким обробником під час відображення можуть адаптувати результати без зміни збережених даних:
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
if ($name !== 'my-theme/card') {
return $findings;
}
return array_values(array_filter($findings, function($finding) {
return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
}));
}, 10, 3);
Завжди повертайте список результатів; повернення [] означає, що блок прийнято. Цей фільтр запускається лише для керованих блоків, ніколи — для результату null.
Опис збережених значень
Використовуйте bs_block_schema() після реєстрації блоку (init або пізніше), щоб описати значення, які зберігає блок, наприклад, для створення розмітки блоку в інструменті чи інтеграції зі штучним інтелектом або для перевірки введених даних у маршруті REST:
$schema = bs_block_schema('theme/card');
if ($schema === null) {
// No Blockstudio fields or matching extensions apply.
}
Результатом є схема JSON об’єкта, збереженого в attrs.blockstudio.attributes. Вона охоплює поля блоку й відповідних розширень, а також ключі сховища, які використовує перевірка: група верхнього рівня додає префікс до своїх дочірніх полів, анонімні групи й вкладки не додають рівня, а поле файлу додає свого супутника <id>__size. Повторювачі — це списки об’єктів рядків із minItems та maxItems з min і max. additionalProperties — це false у корені сховища полів і в рядках повторювача. Поля зі значеннями-об’єктами, як-от посилання й власні об’єкти, можуть містити власні метадані. Блок без полів не має properties, тож йому відповідає лише порожній об’єкт.
Кожне поле описується в канонічній формі, яку приймає bs_validate_block():
| Поле | Схема |
|---|---|
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block |
Рядок. |
number, range |
Число з minimum та maximum з min і max. |
toggle |
Логічне значення. |
select, radio, checkbox |
Значення параметра або список значень параметрів для checkbox і multiple, із enum. |
color, gradient |
Рядок із enum, якщо встановлено disableCustomColors або disableCustomGradients. |
token |
Список рядків. |
files |
Невід’ємний цілий ідентифікатор вкладення або список ідентифікаторів із multiple. |
link |
Об’єкт із url, title та opensInNewTab; url обов’язковий. |
icon |
Об’єкт із set, subSet та icon; set і icon обов’язкові. |
attributes |
Список об’єктів із непорожнім attribute і скалярним value. |
repeater |
Список об’єктів рядків. |
| Власні типи полів | Зареєстрований тип атрибута. |
enum перелічує варіанти, які перевіряє валідація: статичні варіанти та варіанти populate, уже розв’язані під час реєстрації. Віддалені варіанти fetch і аргументи populate, що містять {attributes.*}, не мають enum. Ключ із визначеннями різної форми зберігання пропускається, оскільки валідація повідомляє про кожне збережене під ним значення. Якщо поле блоку й поле розширення мають спільний ключ, enum перелічує значення, які приймають обидва поля. Спільні повторювачі поєднують дочірні поля та застосовують суворіші межі рядків із обох визначень. У рядках повторювача застосовується перше поле з відповідним ідентифікатором у кожному джерелі, як і під час рендерингу. Явно задане поле з назвою <id>__size має пріоритет над автоматично доданим супутником розміру файлу.
Якщо закрите поле не має доступних варіантів або два застосовні набори варіантів не перетинаються, його канонічне значення — null для одиничного вибору або порожній список для множинного вибору. Порожній список варіантів не перетворює поле на необмежене. Віддалені варіанти й варіанти, залежні від атрибутів, залишаються відкритими.
label поля стає title, його help стає description, а default зберігається як анотація. Власний title схеми — це назва блоку. Поля ніколи не є обов’язковими, а умовна логіка не входить до схеми.
Обмеження використовують лише ключові слова, які перевіряє rest_validate_value_from_schema(), тому схему можна без змін використовувати як вхідну схему маршруту REST або можливості:
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
$result = rest_validate_value_from_schema($values, $schema);
}
Схема описує одне поле для кожного поля; під час перевірки також приймаються імпортовані форми, як-от об’єкти параметрів, числові рядки та об’єкти ID. Вона не замінює bs_validate_block(): конфлікти визначень є проблемами конфігурації й усе одно можуть виявлятися, навіть якщо конфліктний ключ пропущено. Фільтри перевірки також можуть накладати правила для конкретного сайту. Використовуйте bs_validate_block(), щоб перевірити збережений вміст. Сайти з власним обробником під час рендерингу можуть адаптувати схему за допомогою фільтра blockstudio/blocks/attributes/schema.
Функції PHP
Без даних
У найпростішому вигляді функція приймає одне значення — ID блоку, який потрібно відобразити на сторінці.
bs_render_block('blockstudio/cta');
З даними
Щоб відобразити блок із власними даними, замість одного значення для першого параметра потрібно передати масив. Значення з ключа data буде передано змінній $attributes і $a у шаблоні вашого блоку.
bs_render_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
]);
Вкладені блоки
Блоки можна вкладати один в одного за допомогою функції bs_block у поєднанні з потужною змінною $content у шаблонах блоків.
<div>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => bs_block([
'id' => 'blockstudio/button',
'data' => [
'text' => 'Button Text',
]
])
]);
Блок кнопки буде відображено замість змінної $content у шаблоні блоку.
Вбудовані блоки, відображені за допомогою bs_render_block() або bs_block(), завжди виводять HTML, оброблений для фронтенду, навіть коли батьківський блок зараз відображається в попередньому перегляді редактора. Псевдокомпоненти шаблону, як-от <RichText /> і <InnerBlocks />, обробляються до повернення вбудованого блоку.
Кілька слотів
Також можна створити кілька слотів вмісту, перетворивши змінну $content на асоціативний масив і викликавши відповідні ключі у функції bs_block.
<div>
<?php echo $content['beforeContent']; ?>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content['afterContent']; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => [
'beforeContent' => bs_block([
'id' => 'blockstudio/badge',
'data' => ['text' => 'Before Content']
]),
'afterContent' => bs_block([
'id' => 'blockstudio/button',
'data' => ['text' => 'Button Text']
])
]
]);
Теги блоків
Вбудовуйте будь-який блок за допомогою синтаксису тегів HTML. Підтримуються два формати:
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
Обидва варіанти відображають той самий блок. У синтаксисі <bs:> дефіс стає роздільником простору імен (acme-hero перетворюється на acme/hero). Дефіси перевіряються зліва направо, і перший зареєстрований кандидат перемагає, тому розв’язуються також простори імен із дефісами: <bs:acme-ui-button> перевіряє acme/ui-button, а потім acme-ui/button. Синтаксис <block> приймає повну назву блоку як атрибут name.
Працюють як блоки Blockstudio, так і основні блоки WordPress. Блоки Blockstudio проходять повний конвеєр (шаблони, Tailwind, ресурси). Основні блоки відображаються системою рендерингу блоків WordPress за допомогою вбудованих рендерерів блоків.
Як це працює
Теги блоків поводяться по-різному залежно від місця розташування:
У шаблонах блоків і вмісті записів теги під час виконання замінюються відображеними HTML. Результат — остаточна розмітка відповідного блоку, безпосередньо вбудована в сторінку. У редакторі для них немає блоку WordPress. Це лише механізм рендерингу.
У сторінках, патернах і шаблонах сайту теги перетворюються на власні блоки WordPress до синхронізації джерела файлу або реєстрації в WordPress. Це означає, що блоки з’являються в редакторі, їх можна редагувати там, де цільова система підтримує редагування, і вони проходять повний життєвий цикл блоків у WordPress. Синтаксис тегів — це скорочений спосіб визначення вмісту блоків у файлах шаблонів.
Ця різниця має значення: теги блоків у шаблонах генерують вивід, а теги блоків на сторінках, у патернах і шаблонах сайту створюють власні блоки.
У шаблонах блоків
Теги блоків автоматично відображаються в шаблонах Twig і PHP. Налаштування не потрібні. Це стосується синтаксису <bs:> і <block>, а також будь-яких зареєстрованих тегів із префіксом і псевдонімів, тому шаблон може безпосередньо виводити їх замість виклику bs_render_block(). Результат відображається HTML і безпосередньо вбудовується у вивід шаблону блоку:
<div class="my-page">
<bs:mytheme-card title="Featured" />
<block name="core/separator" />
<bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
<block name="core/heading" level="2">Also WordPress</block>
<theme-card title="Prefix shorthand" />
</div>
У вмісті записів
Рендеринг на рівні сторінки (вміст записів, області віджетів) потрібно ввімкнути окремо:
{
"blockTags": {
"enabled": true
}
}
Або через фільтр:
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
Синтаксис
Теги без закривального елемента:
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
Парні теги з внутрішнім вмістом:
<bs:mytheme-section layout="wide">
<p>Content inside the block.</p>
</bs:mytheme-section>
<block name="core/group">
<block name="core/paragraph">Inside a group.</block>
</block>
Вільно поєднуйте варіанти. Обидва синтаксиси можна вкладати один в одного:
<bs:mytheme-section>
<block name="core/heading" level="2">Title</block>
<bs:mytheme-card title="Features" />
<block name="core/paragraph">Description text.</block>
</bs:mytheme-section>
Скорочення префіксів
Теги блоків також можуть використовувати скорочення префіксів, специфічні для проєкту. Зареєструйте префікс з одним або кількома просторами імен, і Blockstudio зіставить <prefix-slug> з першим зареєстрованим блоком у порядку цих просторів імен:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components', 'bsui'];
return $prefixes;
});
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />
У наведеному вище прикладі <theme-card> зіставляється з theme-components/card, <theme-button> переходить до bsui/button, якщо theme-components/button не зареєстровано, а <theme-ui-feature-matrix> зіставляється з theme-components/ui-feature-matrix.
Префікси також можна поєднувати. Якщо тег із префіксом не зіставляється безпосередньо, а його частина після префікса сама є зареєстрованим тегом із префіксом, зіставлення рекурсивно продовжується. Так префікс бренду може накладатися на префікс простору імен:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components'];
$prefixes['ui'] = ['bsui'];
return $prefixes;
});
<theme-ui-input />
Для <theme-ui-input> немає блоку theme-components/ui-input, тому пошук переходить до префікса ui і зіставляється з bsui/input. Прямі збіги завжди мають перевагу над вкладеним зіставленням, а правила дозволу й заборони застосовуються до остаточно визначеного блоку.
Префікси також можна налаштувати в blockstudio.json:
{
"blockTags": {
"prefixes": {
"theme": ["theme-components", "bsui"]
}
}
}
Префікси мають складатися з малих літер або цифр, починатися з літери й не містити дефісів. Явні псевдоніми з blockstudio/block_tags/tag_aliases мають перевагу над зіставленням префіксів. Теги з невідомими префіксами залишаються без змін.
Теги з префіксами й псевдонімами залишаються зручними способами написання. Канонічний переносний варіант завжди — <bs:namespace-slug>, оскільки він містить справжню назву блоку й не залежить від фільтрів проєкту:
<bs:theme-components-card />
<bs:bsui-input />
У прикладах Blockstudio, згенерованих діагностичних повідомленнях і програмному виводі використовується цей канонічний варіант написання. Щоб прибрати старі скорочені варіанти, проєкти можуть скористатися окремою міграцією канонічних тегів із попереднім пробним запуском, не завантажуючи WordPress.
Основні блоки
Можна використовувати будь-який блок із зареєстрованим рендерером:
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
<bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>
Або із синтаксисом <block>:
<block name="core/group">
<block name="core/columns">
<block name="core/column">
<block name="core/paragraph">Left column</block>
</block>
<block name="core/column">
<block name="core/paragraph">Right column</block>
</block>
</block>
</block>
Списки дозволених і заборонених блоків
Керуйте тим, які блоки можна відображати за допомогою тегів:
{
"blockTags": {
"enabled": true,
"allow": ["mytheme/*", "core/*"],
"deny": ["mytheme/internal-*"]
}
}
allow обмежує вибір лише блоками, що відповідають шаблонам. deny виключає блоки, що відповідають шаблонам, і має перевагу. Обидва параметри підтримують маски * за допомогою fnmatch(). Вони застосовуються до обох синтаксисів, а також до рендерингу на рівні шаблонів і сторінок.
Фільтри: blockstudio/block_tags/allow і blockstudio/block_tags/deny.
Передавання HTML без змін
Атрибути з префіксом data- передаються кореневому елементу відображеного блоку. Атрибути з префіксом html- також передаються, але префікс видаляється. Працює з обома синтаксисами. Атрибут, переданий без змін, замінює наявне значення кореневого елемента, а не об’єднується з ним, тому html-class замінює власні класи блоку.
Блок Blockstudio також додає до свого кореневого елемента глобальні атрибути, які він не оголошує як поля: id, style, role, title, lang, dir, hidden, tabindex і кожен атрибут aria-*. Оголошене поле завжди має перевагу, тому блок із полем title отримує натомість значення з $a['title']. Передані стилі проходять через safecss_filter_attr(); до атрибутів style у вмісті записів застосовується фільтр WordPress, а їх додають до стилю, уже заданого шаблоном.
Значення атрибутів HTML, тому сутності декодуються один раз під час розбору тегу: title="Tom & Jerry" потрапляє до шаблону як Tom & Jerry і під час виводу екранується знову. Значення в лапках можуть містити >, як це потрібно для варіантів Tailwind і селекторів анімації, як в одиночних, так і в парних тегах.
Будь-який інший атрибут, не оголошений блоком, зокрема class, не потрапляє до HTML. Якщо ввімкнено WP_DEBUG, Blockstudio повідомляє про кожен такий атрибут один раз за запит через _doing_it_wrong(). Оголосіть для нього поле або вкажіть його як атрибут data-, aria- чи html-.
<bs:mytheme-card
title="My Card"
html-class="featured-card"
html-id="main-card"
data-analytics="card-click"
/>
<block name="core/paragraph" html-class="highlight" data-section="intro">
Highlighted paragraph.
</block>
Власні рендерери
Зареєструйте власні рендерери блоків для додаткових типів блоків. Рендерери приймають масив атрибутів і рядок внутрішнього вмісту та повертають масив блоку WordPress:
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
$builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
$html = '<div class="my-block">' . $inner_content . '</div>';
return [
'blockName' => 'myplugin/custom-block',
'attrs' => $attrs,
'innerBlocks' => [],
'innerHTML' => $html,
'innerContent' => [$html],
];
};
return $builders;
}, 10, 2);
Для блоків-контейнерів, яким потрібно розібрати внутрішній вміст на дочірні блоки, додайте другий запис у той самий фільтр:
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
$content = ['<div class="my-wrapper">'];
foreach ($inner_blocks as $block) {
$content[] = null;
}
$content[] = '</div>';
return [
'blockName' => 'myplugin/wrapper',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '<div class="my-wrapper"></div>',
'innerContent' => $content,
];
};
blockstudio/block_tags/builders застосовується як до тегів блоків, так і до власних блоків, вибраних через blockstudio/parser/element_mapping. Цей хук доречний, коли потрібно перенести внутрішній текст блоку проєкту зі зіставленням елементів у поле Blockstudio або створити власний масив блоку.
blockstudio/block_tags/renderers і blockstudio/parser/renderers отримують той самий реєстр і структуру зворотного виклику. Вони залишаються доступними для сумісності та остаточних перевизначень на рівні парсера. Фільтри виконуються в такому порядку:
blockstudio/block_tags/buildersblockstudio/block_tags/renderersblockstudio/parser/renderers
Пізніший фільтр може замінити рендерер, зареєстрований раніше.
Програмне використання
Застосуйте рендеринг тегів до будь-якого рядка з PHP:
$html = apply_filters('blockstudio/block_tags/render', $content);
Компоненти
Теги блоків добре поєднуються з компонентами. Компоненти — це блоки, які відображаються лише програмно й ніколи не з’являються в редакторі.
<bs:mytheme-card title="My Card" description="Card content." />
Парсер
Для обробки тегів блоків використовується легкий сканер рядків замість DOMDocument. Парсер обробляє синтаксис <bs:> і <block>, вкладені теги з однаковими назвами з відстеженням глибини, значення атрибутів у лапках і рекурсивні блоки-контейнери. Його створено спеціально для цього випадку; за результатами тестів він швидший за DOMDocument і WordPress WP_HTML_Tag_Processor та уникає відомих проблем DOMDocument із видаленням префіксів просторів імен і перетворенням назв атрибутів на малі літери.
Для сторінок, патернів і шаблонів сайту той самий парсер також обробляє звичайні елементи HTML (<p>, <div>, <h1> тощо), зіставляючи їх із відповідними основними блоками WordPress.
Якщо зіставлення елемента спрямовує <p> на зареєстрований неосновний блок Blockstudio з атрибутом форматованого тексту content, внутрішній вміст HTML автоматично передається цьому атрибуту content, зокрема вбудовані теги, як-от code і img, зіставлені на рівні блоків. Якщо єдиним дочірнім елементом абзацу є зображення, абзац стає блоком, на який зіставляється <img>. Вкладені теги блоків або HTML на рівні блоків і далі обробляються звичайним способом розбору внутрішніх блоків. <block name="core/shortcode"> зберігає текст шорткоду як вміст блоку.