Saltar al contenido

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

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

Twig

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:

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

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():

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'] ?? '');
}

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 min tiene 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 returnFormat de label devuelve 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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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
<?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 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.

El campo de enlace devuelve un objeto con URL y atributos:

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

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
<?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() 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

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() 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
<?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>

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:

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>

Repetidor

Recorre los elementos del repetidor:

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

Recetario de patrones de campos