Ugrás a tartalomhoz

Attribútumok renderelése

A sablonfájlokban minden attribútum a(z) $attributes vagy $a változóval és a mező megfelelő azonosítójával érhető el.

PHP

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

Twig

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

Attribútumok programozott írása

A szerkesztő a mentett értékeket a(z) blockstudio.attributes alatt tárolja. Ha a blokkon kívül ír adatot, például a(z) REST API, a(z) WP-CLI, egy tartalommigráció vagy egy MCP-kiszolgáló, az attribútumok alapján deríti fel a blokkot, amelyeket a(z) Blockstudio regisztrál a(z) WP_Block_Type elemen, majd legfelső szinten írja be az értékeket. Mindkét adatforma renderelhető:

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

A legfelső szintről csak a blokk által deklarált azonosítókat olvassa be, ezért a(z) WordPress saját attribútumait, például a(z) anchor, className, lock, metadata és style értékeit soha nem veszi át mezőértékként. Ha ugyanaz az azonosító mindkét helyen szerepel, a beágyazott érték élvez elsőbbséget.

Attribútumok programozott beolvasása

A sablonon kívül futó kódnak, például a save_post strukturált adatainak, exportálásnak, keresőindexelésnek vagy egy render_block szűrőnek gyakran a mentett blokk értékeire van szüksége úgy, ahogyan azokat a sablon látja. A bs_block_values() renderelés nélkül adja vissza ezeket. A blokk regisztrálása után (init vagy később) hívd meg a parse_blocks() teljes attrs tömbjével:

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'] ?? '');
}

Az eredmény a sablon $a tömbje, mezőazonosító szerint rendezve:

  • A mezők alapértelmezett értékei érvényesülnek, a min értékkel rendelkező ismétlőmező pedig a kezdeti soraival tér vissza.
  • A legfelső szintű értékek és a blockstudio.attributes összeolvadnak, a beágyazott érték élvez elsőbbséget. A legfelső szintről csak a deklarált azonosítók kerülnek beolvasásra, és a WordPress elhagyja azt a legfelső szintű értéket, amely nem felel meg a mező regisztrált típusának – például egy választómező szövegét –, pontosan úgy, mint rendereléskor.
  • A megfelelő bővítmények mezői, alapértelmezett értékeikkel együtt, szintén bekerülnek. Egy alapblokk vagy külső fejlesztésű blokk bővítménye rendereléskor is csak a blockstudio.attributes értéket olvassa be.
  • A visszatérési formátumok érvényesülnek, ezért ha egy választómezőnél a returnFormat értéke label, akkor a címke érkezik vissza; a fájlmező pedig a melléklet adatait adja vissza.
  • A letiltott és üres mezők false, ahogyan a sablonban is.

A null azt jelenti, hogy sem a blokkot, sem a bővítményt nem a Blockstudio kezeli. Egy mezők nélküli Blockstudio blokk esetén az eredmény [].

A függvény ugyanazt az átalakítást hajtja végre, mint rendereléskor, ezért ugyanazokkal a mellékhatásokkal jár: a fájlmezők lekérdezik a mellékleteket, az a blokkmező pedig, amely nem a data értéket adja vissza, rendereli a hivatkozott blokkot, és a blockstudio/blocks/attributes/render szűrő minden értéknél lefut. A blokk saját sablonját nem rendereli, és a innerBlocks értékeket sem oldja fel; járd be őket magad. A kódmező minden híváskor eltérő, generált %selector% azonosítót őriz meg.

A feloldás az aktuális WordPress kontextust használja. A kizárólag rendereléskor létrejövő metaadatok, például a blokkszámlálók és a innerBlocks, nem jönnek létre; az attribútumok renderelési szűrői a blokk nevét kapják meg, nem egy teljesen renderelt blokk metaadatait.

A tárolt értékeket átalakítás nélkül lekérő lehetőség nincs. Olvasd be közvetlenül a attrs tömböt, vagy használd a bs_validate_block() lehetőséget az ellenőrzésükhöz.

Üres értékek

Ha a mező üres, vagy nincs kiválasztva egyetlen beállítás sem, az attribútum értéke false lesz.

PHP

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

Twig

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

Összetett típusok

Fájlok

Alapértelmezés szerint (returnFormat vagy "returnFormat": "object" esetén) a fájlmező a melléklet adatait tartalmazó tömböt ad vissza. A "multiple": true használatakor ilyen tömbök listáját adja vissza. Ha a fájl melléklete már nem létezik, az false.

Kulcs Leírás
ID A melléklet azonosítója.
title A melléklet címe.
alt Az alternatív szöveg. Ha üres, a melléklet címe jelenik meg helyette.
caption A képaláírás.
description A leírás.
href A mellékletoldal permalinkje.
url A fájl URL értéke. A méretválasztóval ("size": true) a kiválasztott méret URL értéke jelenik meg.
sizes Minden regisztrált képméret URL értéke és méretei; lásd alább.

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

A sizes minden regisztrált képmérethez és a full értékhez tartalmaz egy bejegyzést: a URL az adott méret neve alatt szerepel, a méretek pedig a <size>-width és <size>-height alatt. Ha egy melléklethez még nem készült el valamelyik WordPress méret, az eredeti fájl és annak méretei jelennek meg. Ha a WordPress nem tud feloldani egy képet vagy előnézetet, a sizes kulcs hiányzik. Például egy előnézet nélkül lévő PDF-nek nincs sizes értéke, de az előnézeti metaadatokkal rendelkező PDF-nek lehetnek képméretei. A sizes értéke null, ha nincs regisztrált képméret, vagy ha a files/sizesszűrő letiltja őket. Ez a szűrő a leképezést is lerövidítheti, ezért olvasás előtt ellenőrizd, hogy a méret létezik-e, ahogyan a fenti példákban.

Az objektumnak nincs width, height, mime, type vagy size kulcsa. A méreteket a sizes mezőből olvasd ki, vagy használd a ID függvényt olyan függvényekkel együtt, mint a wp_get_attachment_image() és a get_post_mime_type().

Visszatérési formátumok

A returnFormat módosítja, hogy mit ad vissza a mező:

returnFormat Érték
"object" (alapértelmezett) A fent leírt tömb.
"id" A melléklet tárolt azonosítója, vagy az azonosítók listája a "multiple": true használatakor.
"url" A URL karakterláncként, vagy az URL-ek listája a "multiple": true használatakor. A képeknél a returnSize értékkel megadott méretet használja (alapértelmezés: full), más fájloknál pedig a fájl URL értékét.

A hivatkozásmező objektumot ad vissza a következőkkel: URL és attribútumok:

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

Az ikonmező objektumként adja vissza a(z) set, subSet és icon kulcsokat. Az SVG kimenetéhez használja a(z) bs_render_icon() és bs_icon() segédfüggvényeket:

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

A(z) bs_render_icon() közvetlenül kiírja az SVG-t. A(z) bs_icon() karakterláncként adja vissza.

Attribútumok

Az attribútumok mezőtípusa renderelhető HTML attribútumokhoz használható, {attribute, value} párokból álló tömböt ad vissza. A kimenethez használja a(z) bs_render_data_attributes() elemet:

PHP

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

Twig

Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
  Content
</div>

A(z) bs_render_data_attributes() közvetlenül kiírja az attribútumokat. A(z) bs_data_attributes() karakterláncot ad vissza.

Csoport

A csoportmezők a csoport nevével egészítik ki a gyermekattribútumok azonosítóit. A csoportmezők tiszta tömbbe rendezéséhez használja a(z) bs_get_group() elemet:

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>

Ez eltávolítja a csoport előtagját az attribútumkulcsokból. Például a(z) $a['settings_title'] helyett ez lesz: $group['title'].

A segédfüggvény akkor is működik, ha a csoport egy újra felhasznált egyéni mezőből származik:

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>

Ismétlő

Végiglépkedés az ismétlő elemein:

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

Mezőminták szakácskönyve