Saltar al contenido

Filtrado de atributos

Blockstudio proporciona dos métodos para filtrar atributos de bloque.

Definiciones de atributos

blockstudio/blocks/attributes filtra la definición de cada campo, mientras que Blockstudio construye y registra un bloque. Se usa para ajustar los controles del editor, los valores predeterminados, las condiciones, las opciones y la definición que valida los valores durante el renderizado.

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (
    ($block['name'] ?? '') === 'my-theme/code-block' &&
    ($attribute['id'] ?? '') === 'lineNumbers'
  ) {
    $attribute['default'] = true;
    $attribute['conditions'] = [
      [
        [
          'id' => 'language',
          'operator' => '==',
          'value' => 'css'
        ]
      ]
    ];
  }

  return $attribute;
}, 10, 2);

El código anterior establece el valor predeterminado de lineNumbers en true y oculta el campo a menos que language esté establecido en css.

La función de retorno recibe una definición de campo por invocación, incluidos los campos de grupo y repetidor anidados. Se ejecuta durante el registro del bloque, no una vez por cada renderizado del frontend.

Las definiciones de opciones filtradas también se usan en el mapa de atributos de renderizado. Por ejemplo, una opción añadida a un campo select, radio o checkbox está disponible en el editor y sigue siendo válida cuando Blockstudio resuelve el valor guardado para una plantilla:

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (
    ($block['name'] ?? '') === 'bsui/button' &&
    ($attribute['id'] ?? '') === 'variant'
  ) {
    $attribute['options'][] = [
      'label' => 'Brand',
      'value' => 'brand',
    ];
  }

  return $attribute;
}, 10, 2);

Valores renderizados

blockstudio/blocks/attributes/render filtra el valor resuelto de un campo justo antes de pasarlo a la plantilla del bloque. Se ejecuta una vez por cada campo, por lo que la función de retorno recibe el valor, la clave del campo y los datos del bloque.

PHP
add_filter('blockstudio/blocks/attributes/render', function($value, $key, $block) {
  if (($block['name'] ?? '') === 'my-theme/code-block' && 'lineNumbers' === $key) {
    return true;
  }
  return $value;
}, 10, 3);

El ejemplo anterior reemplaza cualquier valor guardado en el editor para lineNumbers. Registra la función de retorno con tres argumentos aceptados (el último argumento de add_filter); de lo contrario, WordPress pasa solo el valor.

  • $value: el valor resuelto del campo, con la estructura que recibe la plantilla como $a[$key]. Devuelve el valor que debe recibir la plantilla.
  • $key: la clave del campo, tal como se usa en $a. Dentro de una fila de repetidor, es el ID del campo dentro de la fila.
  • $block: el array de datos del bloque que las plantillas reciben como $block o $b, con id, name, postId, postType, index, indexTotal, context y las marcas de la isla. Para extensiones aplicadas a un bloque que no es un bloque Blockstudio, $block contiene solo la entrada blockstudio (attributes y disabled) y no tiene name.

El filtro también se ejecuta para atributos que no son campos Blockstudio, como className y anchor, y para el campo complementario <id>__size de un campo de archivos, así que compara $key antes de cambiar un valor. El valor devuelto reemplaza únicamente el valor de $key; el filtro no puede añadir claves nuevas a $a.

Usa el filtro de definición al cambiar la configuración de los campos y el filtro de renderizado al calcular o reemplazar valores de plantilla durante una solicitud.

Cuando los valores se leen mediante bs_block_values() en lugar de renderizarse, este filtro recibe solo el nombre del bloque en $block. Ese asistente no crea contadores de renderizado ni otros metadatos exclusivos del renderizado.