Přejít k obsahu

Vykreslování atributů

V souborech šablon lze ke všem atributům přistupovat pomocí proměnných $attributes nebo $a a příslušného ID pole.

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é zapisování atributů

Editor ukládá hodnoty vnořené pod blockstudio.attributes. Nástroje, které zapisují blok mimo editor, například REST API, WP-CLI, migrace obsahu nebo server MCP, zjistí blok z atributů, které Blockstudio registruje v WP_Block_Type, a zapíší je na nejvyšší úrovni. Vykreslí se oba formáty:

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

Načítají se pouze ID deklarovaná blokem, takže vlastní atributy WordPress, jako anchor, className, lock, metadata a style, se nikdy nepřevezmou jako hodnoty polí. Pokud se stejné ID objeví na obou místech, přednost má vnořená hodnota.

Programové čtení atributů

Kód spouštěný mimo šablonu, například strukturovaná data v save_post, exporty, indexování pro vyhledávání nebo filtr render_block, často potřebuje hodnoty uloženého bloku v podobě, v jaké je vidí šablona. bs_block_values() je vrátí bez vykreslení bloku. Zavolejte jej po registraci bloku (init nebo později) s úplným polem 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ýsledkem je pole $a šablony, indexované podle ID polí:

  • Použijí se výchozí hodnoty polí a opakovač s min obsahuje své počáteční řádky.
  • Sloučí se nejvyšší úroveň hodnot a blockstudio.attributes; přednost má vnořená hodnota. Načítají se pouze deklarovaná ID z nejvyšší úrovně a WordPress zahodí nejvyšší hodnotu, která neodpovídá registrovanému typu pole, například řetězec výběru, stejně jako při vykreslování.
  • Zahrnou se pole odpovídajících rozšíření rozšíření včetně jejich výchozích hodnot. Rozšíření bloku jádra nebo bloku třetí strany načítá pouze blockstudio.attributes, stejně jako při vykreslování.
  • Použijí se formáty návratových hodnot, takže výběr s returnFormat typu label vrátí štítek a pole souborů vrátí data příloh.
  • Zakázaná a prázdná pole jsou false, stejně jako v šabloně.

null znamená, že blok ani rozšíření nespravuje Blockstudio. Blok Blockstudio bez polí vrací [].

Funkce spouští stejnou transformaci jako vykreslování, takže má i stejné vedlejší účinky: pole souborů načítají přílohy, pole bloku, které nevrací data, vykreslí odkazovaný blok a filtr blockstudio/blocks/attributes/render se spustí pro každou hodnotu. Vlastní šablonu bloku nevykresluje a neřeší innerBlocks; projděte je sami. Pole kódu zachovává vygenerované ID %selector%, které se mezi voláními liší.

Převod používá aktuální kontext WordPress. Metadata dostupná pouze při vykreslování, jako jsou počítadla bloků a innerBlocks, se nevytvářejí; filtry vykreslování atributů dostávají název bloku, nikoli metadata plně vykresleného bloku.

Pro uložené hodnoty bez transformace není k dispozici žádná možnost. Přečtěte přímo pole attrs nebo je ověřte pomocí bs_validate_block().

Prázdné hodnoty

Hodnoty atributů vracejí false, pokud je pole prázdné nebo není vybrána žádná možnost.

PHP

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

Twig

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

Složené typy

Soubory

Ve výchozím nastavení (bez returnFormat nebo při hodnotě "returnFormat": "object") vrací pole souborů pole s daty přílohy. S "multiple": true vrací seznam těchto polí. Soubor, jehož příloha už neexistuje, je false.

Klíč Popis
ID ID přílohy.
title Název přílohy.
alt Alternativní text. Pokud je prázdný, použije se název přílohy.
caption Popisek.
description Popis.
href Trvalý odkaz na stránku přílohy.
url URL souboru. Při použití rozbalovací nabídky velikostí ("size": true) jde o URL vybrané velikosti.
sizes URL a rozměry každé registrované velikosti obrázku; viz níže.

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 pro každou registrovanou velikost obrázku a také full: URL pod názvem velikosti a rozměry pod <size>-width a <size>-height. Pokud se pro přílohu nevygenerovala velikost WordPress, vrátí se původní soubor s jeho rozměry. Pokud WordPress nedokáže rozpoznat obrázek nebo náhled, klíč sizes chybí. Například PDF bez vygenerovaného náhledu nemá sizes, ale PDF s metadaty náhledu může mít velikosti obrázku. sizes má hodnotu null, když nejsou registrovány žádné velikosti obrázku nebo když filtr files/sizes zakáže jejich použití. Tento filtr může mapu také zkrátit, proto před načtením rozměrů ověřte, že velikost existuje, jako v příkladech výše.

Objekt nemá klíče width, height, mime, type ani size. Rozměry načtěte z sizes nebo použijte ID s funkcemi, jako jsou wp_get_attachment_image() a get_post_mime_type().

Formáty návratových hodnot

returnFormat mění hodnotu, kterou pole vrací:

returnFormat Hodnota
"object" (výchozí) Výše popsané pole.
"id" ID přílohy v uložené podobě, případně seznam ID při použití "multiple": true.
"url" URL jako řetězec, případně seznam URL při použití "multiple": true. Obrázky používají velikost nastavenou pomocí returnSize (výchozí full), ostatní soubory používají svou URL souboru.

Pole odkazu vrací objekt s klíčem URL a atributy:

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 vrací objekt s klíči set, subSet a icon. K vykreslení SVG použijte pomocné funkce 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 přímo. bs_icon() jej vrátí jako řetězec.

Atributy

Typ pole atributů vrací pole dvojic {attribute, value}, které se vykreslí jako atributy HTML. K jejich výpisu použijte 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 atributy přímo. bs_data_attributes() vrátí řetězec.

Skupina

Pole atributů potomků skupiny opatří předponou názvu skupiny. Pomocí bs_get_group() extrahujte pole skupiny do přehledného pole:

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 se z klíčů atributů odstraní předpona skupiny. Například $a['settings_title'] se změní na $group['title'].

Pomocná funkce funguje také v případě, že skupina pochází z opakovaně použitého vlastního pole:

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č

Procházejte položky opakovače:

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

Kuchařka vzorů polí