Rendera attribut
I mallfiler kan alla attribut nås med variablerna $attributes eller $a och respektive fält-ID.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Skriva attribut programmatiskt
Redigeraren kapslar in sparade värden under blockstudio.attributes. Allt som skriver ett
block utanför redigeraren, till exempel REST API, WP-CLI, en innehållsmigrering eller
en MCP-server, hittar blocket bland attributen som Blockstudio registrerar på
WP_Block_Type och skriver dem på den översta nivån. Båda strukturerna renderas:
// 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"}}} /-->' );
Endast ID:n som blocket deklarerar läses från den översta nivån, så WordPress egna
attribut som anchor, className, lock, metadata och style används
aldrig som fältvärden. Om samma ID finns på båda ställena gäller det
nästlade värdet.
Läsa attribut programmatiskt
Kod som körs utanför mallen, till exempel strukturerade data på save_post,
exporter, sökindexering eller ett render_block-filter, behöver ofta en sparad
blocks värden så som mallen ser dem. bs_block_values() returnerar dem
utan att rendera blocket. Anropa den efter blockregistreringen (init eller
senare) med hela attrs-matrisen från 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'] ?? '');
}
Resultatet är mallens $a-matris, sorterad efter fält-id:
- Fältens standardvärden används, och en repeater med
minfår sina startrader. - Värden på toppnivå slås samman med
blockstudio.attributes, och det nästlade värdet har företräde. Endast deklarerade id:n läses från toppnivån, och WordPress tar bort ett värde på toppnivån som inte matchar fältets registrerade typ, till exempel en sträng för ett selectfält, precis som vid rendering. - Fälten i matchande tillägg ingår, tillsammans med sina standardvärden. Ett tillägg till ett kärnblock eller tredjepartsblock läser endast
blockstudio.attributes, precis som vid rendering. - Returformat tillämpas, så ett selectfält med
returnFormatpålabelger etiketten och ett filfält ger bilagedata. - Inaktiverade och tomma fält är
false, som i mallen.
null betyder att varken blocket eller ett tillägg hanteras av Blockstudio.
Ett Blockstudio-block utan fält returnerar [].
Funktionen kör samma transformering som vid rendering och har därför samma sidoeffekter: filfält hämtar bilagorna, ett blockfält som inte returnerar data renderar det refererade blocket, och filtret blockstudio/blocks/attributes/render körs för varje värde. Den renderar inte blockets egen mall och löser inte upp innerBlocks; gå igenom dem själv. Ett kodfält behåller ett genererat %selector%-id som skiljer sig mellan anrop.
Upplösningen använder den aktuella kontexten WordPress. Renderingsspecifika metadata, som blockräknare och innerBlocks, skapas inte; attributens renderingsfilter får blocknamnet, inte metadata från ett fullt renderat block.
Det finns inget alternativ för lagrade värden utan transformeringen. Läs attrs-matrisen direkt för att komma åt dem, eller använd bs_validate_block() för att kontrollera dem.
Tomma värden
Attributvärden returnerar false om fältet är tomt eller inget alternativ har valts.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Komplexa typer
Filer
Som standard (utan returnFormat eller med "returnFormat": "object") returnerar filfältet en matris med bilagans data. Med "multiple": true returneras en lista med sådana matriser. En fil vars bilaga inte längre finns är false.
| Nyckel | Beskrivning |
|---|---|
ID |
Bilagans id. |
title |
Bilagans titel. |
alt |
Alt-texten. Om den är tom används bilagans titel. |
caption |
Bildtexten. |
description |
Beskrivningen. |
href |
Permalänken till bilagesidan. |
url |
Filens URL. Med storlekslistan ("size": true) visas URL för den valda storleken. |
sizes |
URL och måtten för varje registrerad bildstorlek, se nedan. |
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 har en post per registrerad bildstorlek samt full: URL under
storleksnamnet och måtten under <size>-width och <size>-height. Om en storlek WordPress inte har
skapats för en bilaga används originalfilen med dess mått. Om WordPress inte kan hitta en bild eller
förhandsvisning saknas nyckeln sizes. En PDF utan skapad förhandsvisning har till exempel inget sizes,
men en PDF med metadata för förhandsvisningen kan ha bildstorlekar. sizes är null när
inga bildstorlekar är registrerade eller när filtret
files/sizes inaktiverar dem.
Filtret kan också göra kartan kortare, så kontrollera att en storlek finns innan du läser dess mått,
som i exemplen ovan.
Objektet har inga nycklar för width, height, mime, type eller size. Läs måtten från
sizes eller använd ID med funktioner som
wp_get_attachment_image() och get_post_mime_type().
Returformat
returnFormat ändrar vad fältet returnerar:
returnFormat |
Värde |
|---|---|
"object" (standard) |
Matrisen som beskrivs ovan. |
"id" |
Bilagans id som det lagras, eller en lista med id:n med "multiple": true. |
"url" |
URL som en sträng, eller en lista med URL:er med "multiple": true. Bilder använder storleken som anges med returnSize (standard full), andra filer använder sin fil-URL. |
Länk
Länkfältet returnerar ett objekt med URL och attribut:
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 %}
Ikon
Ikonfältet returnerar ett objekt med nycklarna set, subSet och icon. Använd hjälpfunktionerna bs_render_icon() och bs_icon() för att skriva ut SVG-koden:
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() skriver ut SVG-koden direkt. bs_icon() returnerar den som en sträng.
Attribut
Attributfältstypen returnerar en array med par av {attribute, value} för rendering som HTML-attribut. Använd bs_render_data_attributes() för att skriva ut dem:
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() skriver ut attributen direkt. bs_data_attributes() returnerar strängen.
Grupp
Gruppfält lägger till gruppnamnet som prefix i underordnade attribut-ID:n. Använd bs_get_group() för att extrahera gruppfält till en ren array:
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>
Detta tar bort grupprefixet från attributnycklarna. Till exempel blir $a['settings_title'] $group['title'].
Hjälpfunktionen fungerar även när gruppen kommer från ett återanvänt anpassat fält:
{
"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>
Repeater
Gå igenom repeater-objekten:
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 %}