Siirry sisältöön

Attribuuttien renderöinti

Mallipohjatiedostoissa kaikkiin attribuutteihin pääsee käsiksi muuttujien $attributes tai $a sekä kentän tunnisteen avulla.

PHP

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

Twig

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

Attribuuttien kirjoittaminen ohjelmallisesti

Editorissa tallennetut arvot sijoitetaan blockstudio.attributes-avaimen alle. Editorin ulkopuolella lohkoon tietoja kirjoittava toiminto, kuten REST API, WP-CLI, sisällön siirto tai MCP-palvelin, selvittää lohkon Blockstudio-arvoista, jotka WP_Block_Type rekisteröi, ja kirjoittaa ne ylimmälle tasolle. Molemmat rakenteet renderöityvät:

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

Vain lohkon määrittämät tunnisteet luetaan ylimmältä tasolta, joten lohkon WordPress omia attribuutteja, kuten anchor, className, lock, metadata ja style, ei koskaan tulkita kenttäarvoiksi. Jos sama tunniste esiintyy molemmissa paikoissa, sisäkkäinen arvo voittaa.

Attribuuttien lukeminen ohjelmallisesti

Mallin ulkopuolella suoritettava koodi, kuten kohteen save_post rakenteinen data, viennit, hakemistoindeksointi tai render_block-suodatin, tarvitsee usein tallennetun lohkon arvot sellaisina kuin malli ne näkee. bs_block_values() palauttaa arvot renderöimättä lohkoa. Kutsu sitä lohkon rekisteröinnin jälkeen (init tai myöhemmin) käyttäen koko attrs-taulukkoa kohteesta 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'] ?? '');
}

Tuloksena on mallin $a-taulukko, jonka avaimina ovat kenttätunnukset:

  • Kenttien oletusarvot otetaan käyttöön, ja toistimella, jolla on min, on alkuperäiset rivinsä.
  • Ylätason arvot yhdistetään arvoihin blockstudio.attributes, ja sisäkkäinen arvo voittaa. Vain määritettyjen tunnusten arvot luetaan ylätasolta, ja WordPress poistaa ylätason arvon, joka ei vastaa kentän rekisteröityä tyyppiä, esimerkiksi valinnan merkkijonoa, aivan kuten renderöinnissä.
  • Vastaavien laajennusten kentät oletusarvoineen sisällytetään. Ydinlohkon tai kolmannen osapuolen lohkon laajennus lukee vain blockstudio.attributes, kuten renderöinnissä.
  • Palautusmuotoja käytetään, joten valinta, jonka returnFormat on label, antaa selitteen ja tiedostokenttä antaa liitteen tiedot.
  • Käytöstä poistetut ja tyhjät kentät ovat false, kuten mallissa.

null tarkoittaa, ettei lohkoa eikä laajennusta hallinnoi Blockstudio. Blockstudio-lohko, jossa ei ole kenttiä, palauttaa arvon [].

Funktio suorittaa saman muunnoksen kuin renderöinti, joten sillä on samat sivuvaikutukset: tiedostokentät hakevat liitteet, lohkokenttä, joka ei palauta arvoa data, renderöi viitatun lohkon, ja blockstudio/blocks/attributes/render-suodatin suoritetaan jokaiselle arvolle. Funktio ei renderöi lohkon omaa mallia eikä ratkaise arvoja innerBlocks; käy ne läpi itse. Koodikentän luoma %selector%-tunnus vaihtelee kutsujen välillä.

Ratkaisu käyttää nykyistä WordPress-kontekstia. Vain renderöinnissä käytettäviä metatietoja, kuten lohkolaskureita ja innerBlocks, ei luoda; attribuutin renderöintisuodattimet saavat lohkon nimen, eivät täysin renderöidyn lohkon metatietoja.

Tallennetuille arvoille ei ole muunnoksen ohittavaa vaihtoehtoa. Lue ne suoraan attrs-taulukosta tai tarkista ne funktiolla bs_validate_block().

Tyhjät arvot

Attribuuttiarvo palauttaa false, jos kenttä on tyhjä tai mitään vaihtoehtoa ei ole valittu.

PHP

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

Twig

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

Monimutkaiset tyypit

Tiedostot

Oletusarvoisesti (ilman arvoa returnFormat tai arvolla "returnFormat": "object") tiedostokenttä palauttaa taulukon, joka sisältää liitteen tiedot. Arvolla "multiple": true se palauttaa luettelon tällaisista taulukoista. Tiedosto, jonka liitettä ei enää ole, on false.

Avain Kuvaus
ID Liitteen tunnus.
title Liitteen otsikko.
alt Vaihtoehtoinen teksti. Jos se on tyhjä, käytetään liitteen otsikkoa.
caption Kuvateksti.
description Kuvaus.
href Liitesivun pysyvä linkki.
url Tiedoston URL. Koon pudotusvalikolla ("size": true) näytetään valitun koon URL.
sizes Jokaisen rekisteröidyn kuvakoon URL ja mitat, katso alta.

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 sisältää yhden merkinnän kutakin rekisteröityä kuvakokoa kohden sekä full: URL kokoluokan nimen alla ja mitat kohdissa <size>-width ja <size>-height. Jos liitteelle ei ole luotu kokoluokan WordPress, se viittaa alkuperäiseen tiedostoon mittoineen. Jos WordPress ei pysty ratkaisemaan kuvaa tai esikatselua, sizes-avain puuttuu. Esimerkiksi PDF-tiedostolla, jolle ei ole luotu esikatselua, ei ole sizes-arvoa, mutta esikatselun metatiedot sisältävällä PDF-tiedostolla voi olla kuvakokoja. sizes on null, kun rekisteröityjä kuvakokoja ei ole tai kun suodatin files/sizes poistaa ne käytöstä. Suodatin voi myös lyhentää karttaa, joten tarkista esimerkkien tapaan, että koko on olemassa, ennen kuin luet sen mitat.

Objektilla ei ole avaimia width, height, mime, type eikä size. Lue mitat kohteesta sizes tai käytä kohdetta ID funktioiden, kuten wp_get_attachment_image() ja get_post_mime_type(), kanssa.

Palautusmuodot

returnFormat muuttaa kentän palauttamaa arvoa:

returnFormat Arvo
"object" (oletus) Edellä kuvattu taulukko.
"id" Tallennettu liitteen tunnus tai tunnusten luettelo, kun käytössä on "multiple": true.
"url" URL merkkijonona tai URL-osoitteiden luettelo, kun käytössä on "multiple": true. Kuvissa käytetään koolla returnSize määritettyä kokoa (oletus full); muissa tiedostoissa käytetään niiden tiedoston URL.

Linkkikenttä palauttaa objektin, jossa on URL ja attribuutit:

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

Kuvake

Kuvakekenttä palauttaa objektin, jossa on avaimet set, subSet ja icon. Tulosta SVG käyttämällä apufunktioita bs_render_icon() ja 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() tulostaa SVG:n suoraan. bs_icon() palauttaa sen merkkijonona.

Attribuutit

Attribuuttikenttätyyppi palauttaa {attribute, value}-parien taulukon, joka voidaan renderöidä HTML-attribuutteina. Tulosta ne komennolla 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() tulostaa attribuutit suoraan. bs_data_attributes() palauttaa merkkijonon.

Ryhmä

Ryhmäkentissä lapsiattribuuttien tunnisteiden eteen lisätään ryhmän nimi. Poimi ryhmäkentät siistiin taulukkoon komennolla bs_get_group():

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ä poistaa ryhmän etuliitteen attribuuttiavaimista. Esimerkiksi $a['settings_title'] muuttuu muotoon $group['title'].

Apufunktio toimii myös silloin, kun ryhmä tulee uudelleenkäytetystä mukautetusta kentästä:

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>

Toistin

Käy toistimen kohteet läpi:

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

Kenttämallien keittokirja