Renderizar atributos
Dentro de los archivos de plantilla, se puede acceder a todos los atributos mediante las variables $attributes o $a y el ID correspondiente del campo.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Escritura programática de atributos
El editor anida los valores guardados bajo blockstudio.attributes. Cualquier herramienta que escriba un
bloque fuera del editor, como el REST API, WP-CLI, una migración de contenido o
un servidor MCP, descubre el bloque a partir de los atributos que Blockstudio registra en
WP_Block_Type y los escribe en el nivel superior. Ambas estructuras se renderizan:
// 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"}}} /-->' );
Solo se leen del nivel superior los ID declarados por el bloque, por lo que los
atributos propios de WordPress, como anchor, className, lock, metadata y style, nunca se adoptan como valores de campo. Si el mismo ID aparece en ambos lugares, prevalece el valor anidado.
Lectura programática de atributos
El código que se ejecuta fuera de la plantilla, como los datos estructurados en save_post, las exportaciones, la indexación de búsqueda o un filtro render_block, a menudo necesita los valores guardados de un bloque tal como los ve la plantilla. bs_block_values() los devuelve sin renderizar el bloque. Llámelo después de registrar el bloque (init o posterior) con la matriz completa de attrs de 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'] ?? '');
}
El resultado es la matriz de $a de la plantilla, indexada por ID de campo:
- Se aplican los valores predeterminados de los campos y un repetidor con
mintiene sus filas iniciales. - Se combinan los valores de nivel superior y
blockstudio.attributes, y prevalece el valor anidado. Solo se leen del nivel superior los ID declarados, y WordPress descarta un valor de nivel superior que no coincida con el tipo registrado del campo, por ejemplo una cadena de selección, igual que durante el renderizado. - Se incluyen los campos de las extensiones coincidentes, con sus valores predeterminados. Una extensión de un bloque principal o de terceros solo lee
blockstudio.attributes, igual que durante el renderizado. - Se aplican los formatos de retorno, de modo que una selección con
returnFormatdelabeldevuelve la etiqueta y un campo de archivos devuelve los datos del adjunto. - Los campos desactivados y vacíos se
false, como en la plantilla.
null significa que ni el bloque ni una extensión están gestionados por Blockstudio. Un bloque Blockstudio sin campos devuelve [].
La función ejecuta la misma transformación que el renderizado, por lo que tiene los mismos efectos secundarios: los campos de archivos consultan los adjuntos, un campo de bloque que no devuelve data renderiza el bloque referenciado y el filtro blockstudio/blocks/attributes/render se ejecuta para cada valor. No renderiza la propia plantilla del bloque ni resuelve innerBlocks; recórralos usted mismo. Un campo de código conserva un ID %selector% generado que cambia entre llamadas.
La resolución usa el contexto actual de WordPress. No se crea metadata que solo existe durante el renderizado, como los contadores de bloques y innerBlocks; los filtros de renderizado de atributos reciben el nombre del bloque, no la metadata de un bloque completamente renderizado.
No hay ninguna opción para obtener los valores almacenados sin la transformación. Lea directamente la matriz attrs para acceder a ellos, o use bs_validate_block() para comprobarlos.
Valores vacíos
Los valores de los atributos devuelven false si el campo está vacío o no se ha seleccionado ninguna opción.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Tipos complejos
Archivos
De forma predeterminada (sin returnFormat o con "returnFormat": "object"), el campo de archivos devuelve una matriz con los datos del adjunto. Con "multiple": true, devuelve una lista de estas matrices. Un archivo cuyo adjunto ya no existe se false.
| Clave | Descripción |
|---|---|
ID |
El ID del adjunto. |
title |
El título del adjunto. |
alt |
El texto alternativo. Si está vacío, se usa el título del adjunto. |
caption |
El pie de foto. |
description |
La descripción. |
href |
El enlace permanente de la página del adjunto. |
url |
El URL del archivo. Con el menú desplegable de tamaño ("size": true), el URL del tamaño seleccionado. |
sizes |
El URL y las dimensiones de cada tamaño de imagen registrado; consulte más abajo. |
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 tiene una entrada por cada tamaño de imagen registrado, además de full: el URL bajo el nombre del tamaño y las dimensiones bajo <size>-width y <size>-height. Si un tamaño WordPress no se ha generado para un adjunto, se resuelve como el archivo original con sus dimensiones. Si WordPress no puede resolver una imagen o una vista previa, la clave sizes no está presente. Por ejemplo, un PDF sin una vista previa generada no tiene sizes, pero un PDF con metadata de vista previa puede tener tamaños de imagen. sizes es null cuando no hay tamaños de imagen registrados o cuando el filtro files/sizes los desactiva. Ese filtro también puede acortar el mapa, así que compruebe que exista un tamaño antes de leer sus dimensiones, como en los ejemplos anteriores.
El objeto no tiene claves width, height, mime, type ni size. Lea las dimensiones de sizes o use ID con funciones como wp_get_attachment_image() y get_post_mime_type().
Formatos de retorno
returnFormat cambia lo que devuelve el campo:
returnFormat |
Valor |
|---|---|
"object" (predeterminado) |
La matriz descrita arriba. |
"id" |
El ID del adjunto tal como está almacenado, o una lista de ID con "multiple": true. |
"url" |
El URL como cadena, o una lista de URL con "multiple": true. Las imágenes usan el tamaño establecido con returnSize (predeterminado: full); los demás archivos usan su URL. |
Enlace
El campo de enlace devuelve un objeto con URL y atributos:
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 %}
Icono
El campo de icono devuelve un objeto con las claves set, subSet y icon. Usa las funciones auxiliares bs_render_icon() y bs_icon() para mostrar el SVG:
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() imprime el SVG directamente. bs_icon() lo devuelve como cadena.
Atributos
El tipo de campo de atributos devuelve una matriz de pares {attribute, value} para renderizar como atributos HTML. Usa bs_render_data_attributes() para mostrarlos:
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() imprime los atributos directamente. bs_data_attributes() devuelve la cadena.
Grupo
Los campos de grupo anteponen el nombre del grupo a los ID de atributo de sus campos secundarios. Usa bs_get_group() para extraer los campos del grupo en una matriz limpia:
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>
Esto elimina el prefijo del grupo de las claves de atributo. Por ejemplo, $a['settings_title'] se convierte en $group['title'].
La función auxiliar también funciona cuando el grupo procede de un campo personalizado reutilizado:
{
"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>
Repetidor
Recorre los elementos del repetidor:
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 %}