Liigu sisu juurde

Atribuutide renderdamine

Mallifailides pääseb kõigile atribuutidele juurde muutujate $attributes või $a ning välja vastava ID abil.

PHP

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

Twig

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

Atribuutide kirjutamine programmiliselt

Redaktor paigutab salvestatud väärtused üksuse blockstudio.attributes alla. Redaktorist väljaspool plokki kirjutav lahendus (nt REST API, WP-CLI, sisu migreerimine või MCP-server) leiab ploki atribuudid, mille Blockstudio registreerib üksuses WP_Block_Type, ja kirjutab need ülemisele tasemele. Mõlemad vormingud renderdatakse:

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

Ülemiselt tasemelt loetakse ainult ploki deklareeritud ID-sid, seega ei võeta WordPress enda atribuute (nt anchor, className, lock, metadata ja style) kunagi välja väärtustena üle. Kui sama ID esineb mõlemas kohas, eelistatakse pesastatud väärtust.

Atribuutide programmiliselt lugemine

Malli väliselt käivitatav kood, näiteks struktureeritud andmed save_post-is, eksportimine, otsingu indekseerimine või filter render_block, vajab sageli salvestatud ploki väärtusi sellisel kujul, nagu mall neid näeb. bs_block_values() tagastab need plokki renderdamata. Kutsuge seda pärast ploki registreerimist (init või hiljem), andes sellele täieliku massiivi attrs allikast 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'] ?? '');
}

Tulemuseks on malli $a massiiv, mille võtmeteks on välja ID-d:

  • Väljade vaikeväärtusi rakendatakse ning kordajal min on algsed read.
  • Ülataseme väärtused liidetakse väärtustega blockstudio.attributes ning võidab pesastatud väärtus. Ülatasemelt loetakse ainult määratletud ID-sid ja WordPress jätab kõrvale ülataseme väärtuse, mis ei vasta välja registreeritud tüübile, näiteks valiku stringväärtuse, täpselt nii nagu renderdamisel.
  • Kaasatakse vastava laienduse väljad koos nende vaikeväärtustega. Tuuma või kolmanda osapoole ploki laiendus loeb ainult väärtust blockstudio.attributes, nagu renderdamisel.
  • Rakendatakse tagastusvorminguid, nii et valik, mille returnFormat on label, tagastab sildi ning failiväli tagastab manuse andmed.
  • Keelatud ja tühjad väljad on false, nagu mallis.

null tähendab, et plokki ega laiendust ei halda Blockstudio. Väljadeta Blockstudio plokk tagastab väärtuse [].

Funktsioon rakendab renderdamisega sama teisenduse, seega kaasnevad sellega samad kõrvalmõjud: failiväljad otsivad manuseid, plokiväli, mis ei tagasta väärtust data, renderdab viidatud ploki ning filter blockstudio/blocks/attributes/render käivitatakse iga väärtuse puhul. Ploki enda malli ei renderdata ja innerBlocks ei lahendata; läbige need ise. Koodiväljale jääb genereeritud %selector% ID, mis on eri kutsetel erinev.

Lahendamisel kasutatakse praegust konteksti WordPress. Ainult renderdamisel kasutatavaid metaandmeid, nagu plokiloendurid ja innerBlocks, ei looda; atribuudi renderdusfiltrid saavad ploki nime, mitte täielikult renderdatud ploki metaandmeid.

Salvestatud väärtusi ilma teisenduseta ei saa ühegi valikuga kätte. Lugege neid otse massiivist attrs või kontrollige neid funktsiooniga bs_validate_block().

Tühjad väärtused

Kui väli on tühi või ühtegi valikut pole tehtud, tagastavad atribuudi väärtused false.

PHP

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

Twig

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

Keerukad tüübid

Failid

Vaikimisi (ilma parameetrita returnFormat või parameetriga "returnFormat": "object") tagastab failiväli massiivi manuse andmetega. Parameetriga "multiple": true tagastab see nende massiivide loendi. Fail, mille manust enam ei eksisteeri, tagastatakse kujul false.

Võti Kirjeldus
ID Manuse ID.
title Manuse pealkiri.
alt Alternatiivtekst. Kui see on tühi, kasutatakse manuse pealkirja.
caption Allkiri.
description Kirjeldus.
href Manuse lehe püsilink.
url Faili URL. Suuruse rippmenüüga ("size": true) on see valitud suuruse URL.
sizes Iga registreeritud pildisuuruse URL ja mõõtmed, vt allpool.

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 sisaldab iga registreeritud pildisuuruse ja lisaks full kohta üht kirjet: suuruse nime all on URL ning võtmete <size>-width ja <size>-height all mõõtmed. Manuse jaoks genereerimata suurusega WordPress tagastatakse algne fail koos selle mõõtmetega. Kui WordPress ei suuda pilti või eelvaadet tuvastada, puudub võti sizes. Näiteks genereeritud eelvaateta PDF-il puudub sizes, kuid eelvaate metaandmetega PDF-il võivad pildisuurused olemas olla. sizes on null, kui pildisuurusi pole registreeritud või kui filter files/sizes keelab need. See filter võib ka loendit lühendada, seega kontrollige enne mõõtmete lugemist, kas suurus on olemas, nagu ülaltoodud näidetes.

Objektil pole võtmeid width, height, mime, type ega size. Lugege mõõtmed väärtusest sizes või kasutage ID koos selliste funktsioonidega nagu wp_get_attachment_image() ja get_post_mime_type().

Tagastusvormingud

returnFormat muudab välja tagastatavat väärtust:

returnFormat Väärtus
"object" (vaikimisi) Eespool kirjeldatud massiiv.
"id" Salvestatud manuse ID või parameetriga "multiple": true ID-de loend.
"url" URL stringina või parameetriga "multiple": true URL-ide loend. Piltidel kasutatakse parameetriga returnSize määratud suurust (vaikimisi full), teistel failidel faili URL.

Lingi väli tagastab objekti võtmete ja atribuutidega URL:

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

Ikoon

Ikooni väli tagastab objekti võtmetega set, subSet ja icon. SVG väljastamiseks kasutage abifunktsioone 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() väljastab SVG otse. bs_icon() tagastab selle stringina.

Atribuudid

Atribuutide väljatüüp tagastab renderdamiseks massiivi {attribute, value} paaridest kui HTML atribuute. Nende väljastamiseks kasutage 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() väljastab atribuudid otse. bs_data_attributes() tagastab stringi.

Rühm

Rühmaväljad lisavad tütaratribuutide ID-de ette rühma nime. Rühmaväljade eraldamiseks puhtasse massiivi kasutage 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>

See eemaldab atribuudivõtmetelt rühma eesliite. Näiteks $a['settings_title'] muutub kujule $group['title'].

Abifunktsioon töötab ka siis, kui rühm pärineb taaskasutatavast kohandatud väljast:

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>

Korduvväli

Liikuge tsükliga läbi korduva välja üksuste:

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

Väljade mustrite retseptikogu