Rendering af attributter
I skabelonfiler kan du få adgang til alle attributter ved hjælp af variablerne $attributes eller $a og feltets tilsvarende id.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Programmatisk skrivning af attributter
Editoren indlejrer gemte værdier under blockstudio.attributes. Alt, der skriver en blok uden for editoren, såsom REST API, WP-CLI, en indholdsmigrering eller en MCP-server, finder blokken ud fra de attributter, som Blockstudio registrerer på WP_Block_Type, og skriver dem på øverste niveau. Begge strukturer kan renderes:
// 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"}}} /-->' );
Kun id’er, som blokken erklærer, læses fra øverste niveau, så WordPress’s egne attributter som anchor, className, lock, metadata og style overtages aldrig som feltværdier. Hvis det samme id findes begge steder, vinder den indlejrede værdi.
Læsning af attributter programmatisk
Kode, der kører uden for skabelonen, såsom strukturerede data på save_post,
eksporter, søgeindeksering eller et render_block-filter, har ofte brug for værdierne fra en
lagret blok, sådan som skabelonen ser dem. bs_block_values() returnerer dem
uden at gengive blokken. Kald den efter blokregistreringen (init eller
senere) med det komplette array af attrs fra parse_blocks():
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'] ?? '');
}
Resultatet er skabelonens array af $a, sorteret efter felt-id:
- Feltstandardværdier anvendes, og en gentager med
minhar sine startrækker. - Værdier på øverste niveau og
blockstudio.attributesflettes sammen, og den indlejrede værdi vinder. Kun definerede id’er læses fra øverste niveau, og WordPress fjerner en værdi på øverste niveau, der ikke matcher feltets registrerede type, for eksempel en selectstreng, præcis som ved gengivelse. - Felterne i matchende udvidelser medtages
sammen med deres standardværdier. En udvidelse af en kerneblok eller tredjepartsblok læser
kun
blockstudio.attributes, præcis som ved gengivelse. - Returformater anvendes, så et selectfelt med
returnFormatpålabelgiver etiketten, og et filfelt giver vedhæftningsdataene. - Deaktiverede og tomme felter er
false, som i skabelonen.
null betyder, at hverken blokken eller en udvidelse administreres af Blockstudio.
En Blockstudio-blok uden felter returnerer [].
Funktionen kører samme transformation som ved gengivelse og har derfor de samme
sideeffekter: Filfelter forespørger efter vedhæftningerne, et blokfelt, der ikke returnerer
data, gengiver den refererede blok, og
blockstudio/blocks/attributes/render-filteret køres for hver værdi. Funktionens egen skabelon for
blokken gengives ikke, og innerBlocks opløses ikke; gennemgå dem
selv. Et kodefelt beholder et genereret %selector%-id, der er forskelligt fra
kald til kald.
Opløsningen bruger den aktuelle WordPress-kontekst. Metadata, der kun oprettes ved
gengivelse, såsom bloktællere og innerBlocks, oprettes ikke; attributfiltre ved
gengivelse modtager bloknavnet, ikke metadata fra en fuldt gengivet blok.
Der er ingen mulighed for at hente de lagrede værdier uden transformationen. Læs
attrs-arrayet direkte for at få dem, eller brug
bs_validate_block() til
at kontrollere dem.
Tomme værdier
Attributværdier returnerer false, hvis feltet er tomt, eller ingen indstilling er valgt.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Komplekse typer
Filer
Som standard (uden returnFormat eller med "returnFormat": "object") returnerer filfeltet
et array med vedhæftningens data. Med "multiple": true returnerer det
en liste med disse arrays. En fil, hvis vedhæftning ikke længere findes, er
false.
| Nøgle | Beskrivelse |
|---|---|
ID |
Vedhæftningens ID. |
title |
Vedhæftningens titel. |
alt |
Alternativteksten. Hvis den er tom, bruges vedhæftningens titel. |
caption |
Billedteksten. |
description |
Beskrivelsen. |
href |
Det permanente link til vedhæftningssiden. |
url |
Filens URL. Med rullemenuen til størrelser ("size": true) returneres den valgte størrelses URL. |
sizes |
URL og dimensionerne for alle registrerede billedstørrelser, se nedenfor. |
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
{% 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 har én post pr. registreret billedstørrelse samt full: URL under
størrelsens navn og dimensionerne under <size>-width og <size>-height. En størrelse,
WordPress, der ikke er blevet genereret for en vedhæftning, henviser til den oprindelige fil med
dens dimensioner. Hvis WordPress ikke kan finde et billede eller en forhåndsvisning, mangler nøglen sizes.
For eksempel har en PDF uden en genereret forhåndsvisning ingen sizes,
men en PDF med metadata for forhåndsvisning kan have billedstørrelser. sizes er null, når
der ikke er registreret nogen billedstørrelser, eller når filteret
files/sizes deaktiverer dem.
Dette filter kan også forkorte oversigten, så kontrollér, at en størrelse findes, før du læser
dens dimensioner, som i eksemplerne ovenfor.
Objektet har ingen nøgler for width, height, mime, type eller size. Hent
dimensionerne fra sizes, eller brug ID sammen med funktioner som
wp_get_attachment_image() og get_post_mime_type().
Returformater
returnFormat ændrer, hvad feltet returnerer:
returnFormat |
Værdi |
|---|---|
"object" (standard) |
Det array, der er beskrevet ovenfor. |
"id" |
Vedhæftningens ID, som det er gemt, eller en liste over ID’er med "multiple": true. |
"url" |
URL som en streng eller en liste over URL’er med "multiple": true. Billeder bruger den størrelse, der er angivet med returnSize (standard full); andre filer bruger deres fil-URL. |
Link
Felttypen link returnerer et objekt med URL og attributter:
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
{% if a.link %}
<a href="{{ a.link.url }}" target="{{ a.link.target }}">
{{ a.link.title }}
</a>
{% endif %}
Ikon
Felttypen icon returnerer et objekt med nøglerne set, subSet og icon. Brug hjælpefunktionerne bs_render_icon() og bs_icon() til at vise SVG’en:
PHP
<?php if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
Twig
{% if a.icon %}
<div class="icon">
{{ bs_icon(a.icon) }}
</div>
{% endif %}
bs_render_icon() skriver SVG’en direkte ud. bs_icon() returnerer den som en streng.
Attributter
Felttypen attributes returnerer et array med {attribute, value}-par, der kan renderes som HTML-attributter. Brug bs_render_data_attributes() til at vise dem:
PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
Content
</div>
bs_render_data_attributes() skriver attributterne direkte ud. bs_data_attributes() returnerer strengen.
Gruppe
Gruppefelter sætter gruppenavnet foran deres underordnede attribut-id’er. Brug bs_get_group() til at udtrække gruppefelter til et ryddeligt array:
PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
Dette fjerner gruppepræfikset fra attributnøglerne. Eksempelvis bliver $a['settings_title'] til $group['title'].
Hjælpefunktionen virker også, når gruppen kommer fra et genbrugt brugerdefineret felt:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
Gentager
Gå gennem gentagerelementerne:
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
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}