Attributen renderen
In templatebestanden zijn alle attributen toegankelijk via de variabelen $attributes of $a en de bijbehorende ID van het veld.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Attributen programmatisch schrijven
De editor slaat waarden genest op onder blockstudio.attributes. Alles wat buiten de editor een
blok schrijft, zoals de REST API, WP-CLI, een inhoudsmigratie of
een MCP-server, haalt de blokdefinitie op uit de attributen die Blockstudio registreert op
de WP_Block_Type en schrijft ze op het hoogste niveau. Beide structuren worden gerenderd:
// 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"}}} /-->' );
Alleen ID’s die het blok declareert, worden van het hoogste niveau gelezen, dus de
eigen attributen van WordPress, zoals anchor, className, lock, metadata en style, worden
nooit als veldwaarden overgenomen. Als dezelfde ID op beide plaatsen voorkomt, krijgt de
geneste waarde voorrang.
Attributen programmatisch uitlezen
Code die buiten de template wordt uitgevoerd, zoals gestructureerde gegevens op save_post,
exports, zoekindexering of een render_block-filter, heeft vaak de waarden van een opgeslagen
blok nodig zoals de template ze ziet. bs_block_values() retourneert ze
zonder het blok te renderen. Roep deze functie na blokregistratie aan (init of
later) met de volledige array attrs uit 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'] ?? '');
}
Het resultaat is de array $a van de template, gesorteerd op veld-ID:
- Veldstandaardwaarden worden toegepast en een repeater met
minbevat de beginrijen. - Waarden op het hoogste niveau en
blockstudio.attributesworden samengevoegd; de geneste waarde heeft voorrang. Alleen gedefinieerde ID’s worden op het hoogste niveau uitgelezen, en WordPress verwijdert een waarde op het hoogste niveau die niet overeenkomt met het geregistreerde type van het veld, bijvoorbeeld een selectiestring, precies zoals bij het renderen. - De velden van overeenkomende extensies worden opgenomen,
inclusief hun standaardwaarden. Een extensie van een kernblok of blok van derden leest
alleen
blockstudio.attributes, net als bij het renderen. - Retourformaten worden toegepast. Zo geeft een selectie met
returnFormatingesteld oplabelhet label terug en geeft een bestandsveld de bijlagegegevens terug. - Uitgeschakelde en lege velden worden
false, net als in de template.
null betekent dat noch het blok, noch een extensie wordt beheerd door Blockstudio.
Een Blockstudio-blok zonder velden retourneert [].
De functie voert dezelfde transformatie uit als bij het renderen en heeft daardoor dezelfde neveneffecten: bestandsvelden zoeken de bijlagen op, een blokveld dat niet data retourneert, rendert het blok waarnaar wordt verwezen, en het filter blockstudio/blocks/attributes/render wordt voor elke waarde uitgevoerd. De functie rendert de eigen template van het blok niet en lost innerBlocks niet op; loop er zelf doorheen. Een codeveld behoudt een gegenereerde %selector%-ID die per aanroep verschilt.
De resolutie gebruikt de huidige context WordPress. Alleen bij het renderen gemaakte metadata, zoals bloktellers en innerBlocks, wordt niet aangemaakt; attributen-renderfilters ontvangen de bloknaam, niet de metadata van een volledig gerenderd blok.
Er is geen optie om de opgeslagen waarden zonder transformatie op te halen. Lees daarvoor de array attrs rechtstreeks uit, of gebruik bs_validate_block() om ze te controleren.
Lege waarden
Attribuutwaarden retourneren false als het veld leeg is of er geen optie is geselecteerd.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Complexe typen
Bestanden
Standaard (zonder returnFormat of met "returnFormat": "object") retourneert het bestandsveld een array met de gegevens van de bijlage. Met "multiple": true retourneert het een lijst met zulke arrays. Een bestand waarvan de bijlage niet meer bestaat, wordt false.
| Sleutel | Beschrijving |
|---|---|
ID |
De bijlage-ID. |
title |
De titel van de bijlage. |
alt |
De alt-tekst. Is deze leeg, dan wordt de titel van de bijlage gebruikt. |
caption |
Het bijschrift. |
description |
De beschrijving. |
href |
De permalink van de bijlagepagina. |
url |
De URL van het bestand. Met de formaatkeuzelijst ("size": true) de URL van het geselecteerde formaat. |
sizes |
De URL en afmetingen van elk geregistreerd afbeeldingsformaat; zie hieronder. |
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 bevat één item per geregistreerde afbeeldingsgrootte plus full: de URL onder de naam van de grootte en de afmetingen onder <size>-width en <size>-height. Een WordPress waarvoor geen bestand voor een bijlage is gegenereerd, verwijst naar het oorspronkelijke bestand met de bijbehorende afmetingen. Als WordPress een afbeelding of voorbeeld niet kan vinden, ontbreekt de sleutel sizes. Een PDF zonder gegenereerd voorbeeld heeft bijvoorbeeld geen sizes, maar een PDF met voorbeeldmetadata kan wel afbeeldingsgroottes hebben. sizes is null als er geen afbeeldingsgroottes zijn geregistreerd of als het filter files/sizes deze uitschakelt. Dat filter kan de lijst ook inkorten. Controleer daarom of een grootte bestaat voordat u de afmetingen ervan uitleest, zoals in de voorbeelden hierboven.
Het object heeft geen sleutels width, height, mime, type of size. Lees de
afmetingen uit sizes, of gebruik ID met functies zoals
wp_get_attachment_image() en get_post_mime_type().
Retourformaten
returnFormat bepaalt wat het veld retourneert:
returnFormat |
Waarde |
|---|---|
"object" (standaard) |
De hierboven beschreven array. |
"id" |
De opgeslagen bijlage-ID, of een lijst met ID’s met "multiple": true. |
"url" |
De URL als tekenreeks, of een lijst met URL’s met "multiple": true. Voor afbeeldingen wordt het formaat gebruikt dat is ingesteld met returnSize (standaard full); voor andere bestanden wordt hun bestand URL gebruikt. |
Link
Het linkveld retourneert een object met URL en attributen:
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 %}
Pictogram
Het pictogramveld retourneert een object met de sleutels set, subSet en icon. Gebruik de hulpfuncties bs_render_icon() en bs_icon() om de SVG weer te geven:
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() geeft de SVG direct weer. bs_icon() retourneert deze als een tekenreeks.
Attributen
Het veldtype voor attributen retourneert een array met paren {attribute, value} om als HTML-attributen te renderen. Gebruik bs_render_data_attributes() om ze weer te geven:
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() geeft de attributen direct weer. bs_data_attributes() retourneert de tekenreeks.
Groep
Groepsvelden voegen de groepsnaam toe als voorvoegsel aan de ID’s van hun onderliggende attributen. Gebruik bs_get_group() om groepsvelden in een overzichtelijke array uit te pakken:
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>
Hiermee wordt het groepsvoorvoegsel uit attribuutsleutels verwijderd. Bijvoorbeeld, $a['settings_title'] wordt $group['title'].
De helper werkt ook wanneer de groep afkomstig is uit een hergebruikt aangepast veld:
{
"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
Loop door de repeater-items:
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 %}