Hoppa till innehåll

Rendera attribut

I mallfiler kan alla attribut nås med variablerna $attributes eller $a och respektive fält-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>

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:

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

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

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 är mallens $a-matris, sorterad efter fält-id:

  • Fältens standardvärden används, och en repeater med min få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 returnFormat på label ger 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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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
<?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 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änkfältet returnerar ett objekt med URL och attribut:

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

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

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

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:

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

Gå igenom repeater-objekten:

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

Kokbok med fältmönster