Gå til indhold

Rendering af attributter

I skabelonfiler kan du få adgang til alle attributter ved hjælp af variablerne $attributes eller $a og feltets tilsvarende id.

PHP

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

Twig

Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>

Programmatisk skrivning af attributter

Editoren indlejrer gemte værdier under blockstudio.attributes. Alt, der skriver en blok uden for editoren, såsom REST API, WP-CLI, en indholdsmigrering eller en MCP-server, finder blokken ud fra de attributter, som Blockstudio registrerer på WP_Block_Type, og skriver dem på øverste niveau. Begge strukturer kan renderes:

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"}}} /-->' );

Kun id’er, som blokken erklærer, læses fra øverste niveau, så WordPress’s egne attributter som anchor, className, lock, metadata og style overtages aldrig som feltværdier. Hvis det samme id findes begge steder, vinder den indlejrede værdi.

Læsning af attributter programmatisk

Kode, der kører uden for skabelonen, såsom strukturerede data på save_post, eksporter, søgeindeksering eller et render_block-filter, har ofte brug for værdierne fra en lagret blok, sådan som skabelonen ser dem. bs_block_values() returnerer dem uden at gengive blokken. Kald den efter blokregistreringen (init eller senere) med det komplette array af attrs fra 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'] ?? '');
}

Resultatet er skabelonens array af $a, sorteret efter felt-id:

  • Feltstandardværdier anvendes, og en gentager med min har sine startrækker.
  • Værdier på øverste niveau og blockstudio.attributes flettes sammen, og den indlejrede værdi vinder. Kun definerede id’er læses fra øverste niveau, og WordPress fjerner en værdi på øverste niveau, der ikke matcher feltets registrerede type, for eksempel en selectstreng, præcis som ved gengivelse.
  • Felterne i matchende udvidelser medtages sammen med deres standardværdier. En udvidelse af en kerneblok eller tredjepartsblok læser kun blockstudio.attributes, præcis som ved gengivelse.
  • Returformater anvendes, så et selectfelt med returnFormat på label giver etiketten, og et filfelt giver vedhæftningsdataene.
  • Deaktiverede og tomme felter er false, som i skabelonen.

null betyder, at hverken blokken eller en udvidelse administreres af Blockstudio. En Blockstudio-blok uden felter returnerer [].

Funktionen kører samme transformation som ved gengivelse og har derfor de samme sideeffekter: Filfelter forespørger efter vedhæftningerne, et blokfelt, der ikke returnerer data, gengiver den refererede blok, og blockstudio/blocks/attributes/render-filteret køres for hver værdi. Funktionens egen skabelon for blokken gengives ikke, og innerBlocks opløses ikke; gennemgå dem selv. Et kodefelt beholder et genereret %selector%-id, der er forskelligt fra kald til kald.

Opløsningen bruger den aktuelle WordPress-kontekst. Metadata, der kun oprettes ved gengivelse, såsom bloktællere og innerBlocks, oprettes ikke; attributfiltre ved gengivelse modtager bloknavnet, ikke metadata fra en fuldt gengivet blok.

Der er ingen mulighed for at hente de lagrede værdier uden transformationen. Læs attrs-arrayet direkte for at få dem, eller brug bs_validate_block() til at kontrollere dem.

Tomme værdier

Attributværdier returnerer false, hvis feltet er tomt, eller ingen indstilling er valgt.

PHP

PHP
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

Twig
{% if a.message %}
  <h1>{{ a.message }}</h1>
{% endif %}

Komplekse typer

Filer

Som standard (uden returnFormat eller med "returnFormat": "object") returnerer filfeltet et array med vedhæftningens data. Med "multiple": true returnerer det en liste med disse arrays. En fil, hvis vedhæftning ikke længere findes, er false.

Nøgle Beskrivelse
ID Vedhæftningens ID.
title Vedhæftningens titel.
alt Alternativteksten. Hvis den er tom, bruges vedhæftningens titel.
caption Billedteksten.
description Beskrivelsen.
href Det permanente link til vedhæftningssiden.
url Filens URL. Med rullemenuen til størrelser ("size": true) returneres den valgte størrelses URL.
sizes URL og dimensionerne for alle registrerede billedstørrelser, se nedenfor.

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 har én post pr. registreret billedstørrelse samt full: URL under størrelsens navn og dimensionerne under <size>-width og <size>-height. En størrelse, WordPress, der ikke er blevet genereret for en vedhæftning, henviser til den oprindelige fil med dens dimensioner. Hvis WordPress ikke kan finde et billede eller en forhåndsvisning, mangler nøglen sizes. For eksempel har en PDF uden en genereret forhåndsvisning ingen sizes, men en PDF med metadata for forhåndsvisning kan have billedstørrelser. sizes er null, når der ikke er registreret nogen billedstørrelser, eller når filteret files/sizes deaktiverer dem. Dette filter kan også forkorte oversigten, så kontrollér, at en størrelse findes, før du læser dens dimensioner, som i eksemplerne ovenfor.

Objektet har ingen nøgler for width, height, mime, type eller size. Hent dimensionerne fra sizes, eller brug ID sammen med funktioner som wp_get_attachment_image() og get_post_mime_type().

Returformater

returnFormat ændrer, hvad feltet returnerer:

returnFormat Værdi
"object" (standard) Det array, der er beskrevet ovenfor.
"id" Vedhæftningens ID, som det er gemt, eller en liste over ID’er med "multiple": true.
"url" URL som en streng eller en liste over URL’er med "multiple": true. Billeder bruger den størrelse, der er angivet med returnSize (standard full); andre filer bruger deres fil-URL.

Felttypen link returnerer et objekt med URL og attributter:

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 %}

Ikon

Felttypen icon returnerer et objekt med nøglerne set, subSet og icon. Brug hjælpefunktionerne bs_render_icon() og bs_icon() til at vise SVG’en:

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() skriver SVG’en direkte ud. bs_icon() returnerer den som en streng.

Attributter

Felttypen attributes returnerer et array med {attribute, value}-par, der kan renderes som HTML-attributter. Brug bs_render_data_attributes() til at vise dem:

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() skriver attributterne direkte ud. bs_data_attributes() returnerer strengen.

Gruppe

Gruppefelter sætter gruppenavnet foran deres underordnede attribut-id’er. Brug bs_get_group() til at udtrække gruppefelter til et ryddeligt array:

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>

Dette fjerner gruppepræfikset fra attributnøglerne. Eksempelvis bliver $a['settings_title'] til $group['title'].

Hjælpefunktionen virker også, når gruppen kommer fra et genbrugt brugerdefineret felt:

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>

Gentager

Gå gennem gentagerelementerne:

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 %}

Field Patterns Cookbook