Pular para o conteúdo

Filtragem de atributos

Blockstudio oferece dois métodos para filtrar atributos de blocos.

Definições de atributos

blockstudio/blocks/attributes filtra cada definição de campo, enquanto Blockstudio cria e registra um bloco. Use-o para ajustar controles do editor, valores padrão, condições, opções e a definição usada para validar valores durante a renderização.

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);

O código acima define lineNumbers como valor padrão de true e oculta o campo, a menos que language esteja definido como css.

O callback recebe uma definição de campo por chamada, incluindo campos de grupo e repetidor aninhados. Ele é executado durante o registro do bloco, e não uma vez por renderização no frontend.

As definições de opções filtradas também são usadas pelo mapa de atributos da renderização. Por exemplo, uma opção adicionada a um campo select, radio ou checkbox fica disponível no editor e continua válida quando Blockstudio resolve o valor salvo para um modelo:

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 o valor resolvido de um campo imediatamente antes de passá-lo ao modelo do bloco. Ele é executado uma vez para cada campo, portanto um callback recebe o valor, a chave do campo e os dados do bloco.

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);

O exemplo acima substitui qualquer valor salvo no editor para lineNumbers. Registre o callback com três argumentos aceitos (o último argumento de add_filter); caso contrário, WordPress passa apenas o valor.

  • $value: o valor resolvido do campo, no formato recebido pelo modelo como $a[$key]. Retorne o valor que o modelo deve receber.
  • $key: a chave do campo, conforme usada em $a. Dentro de uma linha do repetidor, esse é o ID do campo na linha.
  • $block: a matriz de dados do bloco que os modelos recebem como $block ou $b, com id, name, postId, postType, index, indexTotal, context e os indicadores de ilha. Para extensões de extensões aplicadas a um bloco que não é um bloco Blockstudio, $block contém apenas a entrada blockstudio (attributes e disabled) e não tem name.

O filtro também é executado para atributos que não são campos Blockstudio, como className e anchor, e para o campo complementar <id>__size de um campo de arquivos; por isso, compare $key antes de alterar um valor. O valor de retorno substitui apenas o valor de $key; o filtro não pode adicionar novas chaves a $a.

Use o filtro de definição ao alterar a configuração do campo e o filtro de renderização ao calcular ou substituir valores do modelo para uma solicitação.

Quando os valores são lidos por meio de bs_block_values(), em vez de serem renderizados, esse filtro recebe apenas o nome do bloco em $block. Contadores de renderização e outros metadados exclusivos da renderização não são criados por esse auxiliar.