Извеждане на атрибути
В шаблонните файлове достъпвате всички атрибути чрез променливите $attributes или $a и съответния ID на полето.
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"}}} /-->' );
От най-горното ниво се четат само ID-тата, декларирани от блока, затова собствените атрибути на WordPress, като anchor, className, lock, metadata и style, никога не се приемат за стойности на полета. Когато един и същ ID се среща и на двете места, предимство има вложената стойност.
Програмно четене на атрибути
Кодът, който се изпълнява извън шаблона, например за структурирани данни в 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() връща низа.
Група
Полетата от група добавят името на групата като префикс към ID-тата на дъщерните атрибути. Използвайте 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 %}