Відтворення атрибутів
У файлах шаблонів доступ до всіх атрибутів можна отримати за допомогою змінних $attributes або $a та відповідного ідентифікатора поля.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Програмний запис атрибутів
Редактор вкладає збережені значення в blockstudio.attributes. Будь-який спосіб запису блока поза редактором, як-от REST API, WP-CLI, перенесення вмісту або MCP-сервер, визначає блок за атрибутами, які Blockstudio реєструє в WP_Block_Type, і записує їх на верхньому рівні. Обидві структури відтворюються:
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );
// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );
З верхнього рівня зчитуються лише ідентифікатори, оголошені блоком, тому власні атрибути WordPress, як-от anchor, className, lock, metadata і style, ніколи не використовуються як значення полів. Якщо той самий ідентифікатор є в обох місцях, пріоритет має вкладене значення.
Програмне читання атрибутів
Коду, який виконується поза шаблоном, наприклад для структурованих даних у save_post, експорту, індексування пошуку або фільтра render_block, часто потрібні значення збереженого блока в тому вигляді, у якому їх бачить шаблон. bs_block_values() повертає їх без рендерингу блока. Викликайте цю функцію після реєстрації блока (init або пізніше), передавши повний масив attrs із parse_blocks():
foreach (parse_blocks($post->post_content) as $block) {
if ($block['blockName'] === null) {
continue;
}
$a = bs_block_values($block['blockName'], $block['attrs']);
if ($a === null) {
// Not a Blockstudio block, and no extension applies.
continue;
}
echo esc_html($a['title'] ?? '');
}
Результат — масив $a шаблону з ключами за ідентифікаторами полів:
- Застосовуються значення полів за замовчуванням, а повторювач із
minмістить початкові рядки. - Значення верхнього рівня та
blockstudio.attributesоб’єднуються, і вкладене значення має пріоритет. Із верхнього рівня зчитуються лише оголошені ідентифікатори, а WordPress відкидає значення верхнього рівня, яке не відповідає зареєстрованому типу поля, наприклад рядок для вибору, так само як під час рендерингу. - Додаються поля відповідних розширень разом зі значеннями за замовчуванням. Розширення основного або стороннього блоку зчитує лише
blockstudio.attributes, як і під час рендерингу. - Застосовуються формати повернення, тож список із
returnFormatтипуlabelповертає мітку, а поле файлів — дані вкладень. - Вимкнені й порожні поля
false, як і в шаблоні.
null означає, що блоком або розширенням не керує Blockstudio. Блок Blockstudio без полів повертає [].
Функція виконує те саме перетворення, що й під час рендерингу, тому має ті самі побічні ефекти: поля файлів запитують вкладення, поле блока, яке не повертає data, рендерить блок, на який посилається, а фільтр blockstudio/blocks/attributes/render запускається для кожного значення. Функція не рендерить власний шаблон блока й не розгортає innerBlocks; обходьте їх самостійно. Поле коду зберігає згенерований ідентифікатор %selector%, який відрізняється під час кожного виклику.
Розгортання відбувається в поточному контексті WordPress. Метадані, доступні лише під час рендерингу, як-от лічильники блоків і innerBlocks, не створюються; фільтри рендерингу атрибутів отримують назву блока, а не метадані повністю відрендереного блока.
Для збережених значень без перетворення немає відповідного параметра. Для них безпосередньо прочитайте масив attrs або скористайтеся bs_validate_block(), щоб перевірити їх.
Порожні значення
Значення атрибутів повертають false, якщо поле порожнє або не вибрано жодного параметра.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Складні типи
Файли
За замовчуванням (без returnFormat або з "returnFormat": "object") поле файлів повертає масив із даними вкладення. З "multiple": true воно повертає список таких масивів. Для файлу, вкладення якого більше не існує, повертається false.
| Ключ | Опис |
|---|---|
ID |
Ідентифікатор вкладення. |
title |
Назва вкладення. |
alt |
Альтернативний текст. Якщо він порожній, використовується назва вкладення. |
caption |
Підпис. |
description |
Опис. |
href |
Постійне посилання на сторінку вкладення. |
url |
URL файлу. У спадному списку розмірів ("size": true) — URL вибраного розміру. |
sizes |
URL і розміри кожного зареєстрованого розміру зображення; див. нижче. |
PHP
<?php if ($a['image']) :
$image = $a['image'];
$sizes = $image['sizes'] ?? [];
?>
<img
src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
alt="<?php echo esc_attr($image['alt']); ?>"
<?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
width="<?php echo esc_attr($sizes['large-width']); ?>"
height="<?php echo esc_attr($sizes['large-height']); ?>"
<?php endif; ?>
/>
<?php endif; ?>
Twig
{% if a.image %}
<img
src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
alt="{{ a.image.alt|e('html_attr') }}"
{% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
width="{{ a.image.sizes['large-width']|e('html_attr') }}"
height="{{ a.image.sizes['large-height']|e('html_attr') }}"
{% endif %}
/>
{% endif %}
sizes містить один запис для кожного зареєстрованого розміру зображення, а також full: URL під назвою розміру та розміри під <size>-width і <size>-height. Якщо розмір WordPress не було створено для вкладення, повертається оригінальний файл із його розмірами. Якщо WordPress не може отримати зображення або попередній перегляд, ключ sizes відсутній. Наприклад, PDF без створеного попереднього перегляду не має sizes, але PDF із метаданими попереднього перегляду може містити розміри зображень. sizes дорівнює null, якщо розміри зображень не зареєстровані або якщо фільтр files/sizes вимикає їх.
Цей фільтр також може скоротити мапу, тому перед зчитуванням розмірів переконайтеся, що потрібний розмір існує, як у прикладах вище.
Об’єкт не має ключів width, height, mime, type або size. Зчитайте розміри з sizes або використайте ID із такими функціями, як wp_get_attachment_image() і get_post_mime_type().
Формати повернення
returnFormat змінює значення, яке повертає поле:
returnFormat |
Значення |
|---|---|
"object" (за замовчуванням) |
Масив, описаний вище. |
"id" |
Ідентифікатор вкладення у збереженому вигляді або список ідентифікаторів із "multiple": true. |
"url" |
URL у вигляді рядка або список URL-адрес із "multiple": true. Для зображень використовується розмір, заданий у returnSize (за замовчуванням full), а для інших файлів — їхній URL. |
Посилання
Поле посилання повертає об’єкт із ключами URL та атрибутами:
PHP
<?php if ($a['link']) : ?>
<a
href="<?php echo $a['link']['url']; ?>"
target="<?php echo $a['link']['target']; ?>"
>
<?php echo $a['link']['title']; ?>
</a>
<?php endif; ?>
Twig
{% if a.link %}
<a href="{{ a.link.url }}" target="{{ a.link.target }}">
{{ a.link.title }}
</a>
{% endif %}
Піктограма
Поле піктограми повертає об’єкт із ключами set, subSet і icon. Використовуйте допоміжні функції bs_render_icon() і bs_icon(), щоб вивести SVG:
PHP
<?php if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
Twig
{% if a.icon %}
<div class="icon">
{{ bs_icon(a.icon) }}
</div>
{% endif %}
bs_render_icon() безпосередньо виводить SVG. bs_icon() повертає його як рядок.
Атрибути
Тип поля атрибутів повертає масив пар {attribute, value} для виведення як атрибутів HTML. Використовуйте bs_render_data_attributes(), щоб вивести їх:
PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
Content
</div>
bs_render_data_attributes() безпосередньо виводить атрибути. bs_data_attributes() повертає рядок.
Група
Поля групи додають назву групи як префікс до ідентифікаторів дочірніх атрибутів. Використовуйте bs_get_group(), щоб отримати поля групи у вигляді чистого масиву:
PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
Це прибирає префікс групи з ключів атрибутів. Наприклад, $a['settings_title'] перетворюється на $group['title'].
Допоміжна функція також працює, коли група походить із повторно використаного власного поля:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
Повторюване поле
Перебирайте елементи повторюваного поля:
PHP
<?php foreach ($a['items'] as $item) : ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['description']; ?></p>
</div>
<?php endforeach; ?>
Twig
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}