Ga naar de inhoud

Attributen renderen

In templatebestanden zijn alle attributen toegankelijk via de variabelen $attributes of $a en de bijbehorende ID van het veld.

PHP

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

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:

PHP
// 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():

PHP
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 min bevat de beginrijen.
  • Waarden op het hoogste niveau en blockstudio.attributes worden 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 returnFormat ingesteld op label het 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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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
<?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

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.

Het linkveld retourneert een object met URL en attributen:

PHP

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

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
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

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

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

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
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

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:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% 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
<?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

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

Kookboek met veldpatronen