Preskočiť na obsah

Vykresľovanie atribútov

V súboroch šablón možno pristupovať ku všetkým atribútom pomocou premenných $attributes alebo $a a príslušného ID poľa.

PHP

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

Twig

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

Programový zápis atribútov

Editor ukladá hodnoty do vnoreného poľa blockstudio.attributes. Nástroj, ktorý zapisuje blok mimo editora, napríklad REST API, WP-CLI, migrácia obsahu alebo server MCP, zistí blok podľa atribútov, ktoré Blockstudio registruje v WP_Block_Type, a zapíše ich na najvyššej úrovni. Fungujú oba tvary:

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

Z najvyššej úrovne sa čítajú iba ID deklarované blokom, takže vlastné atribúty WordPress, ako sú anchor, className, lock, metadata a style, sa nikdy nepoužijú ako hodnoty polí. Ak sa rovnaké ID nachádza na oboch miestach, prednosť má vnorená hodnota.

Programové čítanie atribútov

Kód spúšťaný mimo šablóny, napríklad pri štruktúrovaných údajoch v save_post, exportoch, indexovaní vyhľadávania alebo vo filtri render_block, často potrebuje hodnoty uloženého bloku tak, ako ich vidí šablóna. Funkcia bs_block_values() ich vráti bez vykreslenia bloku. Zavolajte ju po registrácii bloku (init alebo neskôr) s úplným poľom attrs z 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'] ?? '');
}

Výsledkom je pole $a zo šablóny, indexované podľa ID poľa:

  • Použijú sa predvolené hodnoty polí a opakovač s min obsahuje počiatočné riadky.
  • Hodnoty najvyššej úrovne a blockstudio.attributes sa zlúčia; vnorená hodnota má prednosť. Z najvyššej úrovne sa čítajú iba deklarované ID a WordPress zahodí hodnotu najvyššej úrovne, ktorá nezodpovedá registrovanému typu poľa, napríklad reťazec pri výbere, rovnako ako pri vykreslení.
  • Zahrnú sa polia zodpovedajúcich rozšírení vrátane ich predvolených hodnôt. Rozšírenie základného bloku alebo bloku tretej strany číta iba blockstudio.attributes, rovnako ako pri vykreslení.
  • Použijú sa formáty návratových hodnôt, takže výber s returnFormat nastaveným na label vráti štítok a pole súborov vráti údaje prílohy.
  • Zakázané a prázdne polia sa false, rovnako ako v šablóne.

null znamená, že blok ani rozšírenie nespravuje Blockstudio. Blok Blockstudio bez polí vracia [].

Funkcia vykonáva rovnakú transformáciu ako pri vykreslení, takže má aj rovnaké vedľajšie účinky: polia súborov vyhľadávajú prílohy, pole bloku, ktoré nevracia data, vykreslí odkazovaný blok a filter blockstudio/blocks/attributes/render sa spustí pre každú hodnotu. Vlastná šablóna bloku sa nevykreslí a innerBlocks sa nerozpoznajú; prejdite ich sami. Pole kódu si pri každom volaní zachová vygenerované ID %selector%, ktoré sa medzi volaniami líši.

Rozpoznávanie používa aktuálny kontext WordPress. Metadáta vytvárané iba pri vykreslení, ako počítadlá blokov a innerBlocks, sa nevytvárajú; filtre vykreslenia atribútov dostanú názov bloku, nie metadáta úplne vykresleného bloku.

Neexistuje možnosť získať uložené hodnoty bez transformácie. Ak ich potrebujete, čítajte priamo pole attrs alebo ich skontrolujte pomocou bs_validate_block().

Prázdne hodnoty

Hodnoty atribútov vracajú false, ak je pole prázdne alebo nie je vybraná žiadna možnosť.

PHP

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

Twig

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

Zložité typy

Súbory

Predvolene (bez returnFormat alebo pri hodnote "returnFormat": "object") vracia pole súborov pole s údajmi prílohy. Pri hodnote "multiple": true vracia zoznam takýchto polí. Súbor, ktorého príloha už neexistuje, je false.

Kľúč Opis
ID ID prílohy.
title Názov prílohy.
alt Alternatívny text. Ak je prázdny, použije sa názov prílohy.
caption Popisok.
description Opis.
href Trvalý odkaz na stránku prílohy.
url URL súboru. Pri rozbaľovacom zozname veľkostí ("size": true) ide o URL vybranej veľkosti.
sizes URL a rozmery každej registrovanej veľkosti obrázka; pozri nižšie.

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 obsahuje jednu položku pre každú registrovanú veľkosť obrázka a navyše full: URL pod názvom veľkosti a rozmery pod <size>-width a <size>-height. Ak sa veľkosť WordPress pre prílohu nevygenerovala, použije sa pôvodný súbor a jeho rozmery. Ak WordPress nedokáže rozpoznať obrázok alebo ukážku, kľúč sizes chýba. Napríklad PDF bez vygenerovanej ukážky nemá sizes, ale PDF s metadátami ukážky môže mať veľkosti obrázka. Hodnota sizes je null, ak nie sú registrované žiadne veľkosti obrázka alebo ak ich filter files/sizes zakáže. Tento filter môže mapu aj skrátiť, preto pred čítaním rozmerov overte, či daná veľkosť existuje, ako je uvedené v príkladoch vyššie.

Objekt neobsahuje kľúče width, height, mime, type ani size. Rozmery získate z sizes alebo použite ID s funkciami, ako sú wp_get_attachment_image() a get_post_mime_type().

Formáty návratových hodnôt

returnFormat mení hodnotu, ktorú pole vracia:

returnFormat Hodnota
"object" (predvolené) Pole opísané vyššie.
"id" ID prílohy v uloženej podobe alebo zoznam ID pri použití "multiple": true.
"url" URL ako reťazec alebo zoznam URL pri použití "multiple": true. Pri obrázkoch sa použije veľkosť nastavená pomocou returnSize (predvolene full), pri ostatných súboroch ich URL súboru.

Pole odkazu vracia objekt s kľúčmi URL a atribútmi:

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

Ikona

Pole ikony vracia objekt s kľúčmi set, subSet a icon. Na výstup SVG použite pomocné funkcie bs_render_icon() a bs_icon():

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() vypíše SVG priamo. bs_icon() ho vráti ako reťazec.

Atribúty

Typ poľa atribútov vracia pole dvojíc {attribute, value} na vykreslenie ako atribúty HTML. Na ich výstup použite bs_render_data_attributes():

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() vypíše atribúty priamo. bs_data_attributes() vráti reťazec.

Skupina

ID atribútov vnorených polí skupiny majú ako predponu názov skupiny. Pomocou bs_get_group() vyberte polia skupiny do prehľadného poľa:

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>

Tým sa z kľúčov atribútov odstráni predpona skupiny. Napríklad $a['settings_title'] sa zmení na $group['title'].

Pomocná funkcia funguje aj vtedy, keď skupina pochádza z opakovane použitého vlastného poľa:

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>

Opakovač

Prechádzajte položky opakovača:

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

Kuchárka vzorov polí