Pular para o conteúdo

Preenchimento de opções

Em vez de fornecer diferentes tipos de campo, como Posts, Usuários ou Termos, Blockstudio permite preencher dados de forma modular diretamente do block.json. Esse recurso funciona com os tipos de campo select, radio, checkbox, color e gradient.

Os dados podem ser preenchidos de quatro maneiras:

  • Consulta – Retorna resultados de uma consulta de posts, usuários ou termos
  • Busca – Retorna resultados de uma fonte externa
  • Função – Retorna resultados de uma função personalizada
  • Personalizado – Retorna resultados de um conjunto de dados personalizado

Consulta

Ao escolher o modo de consulta, é possível preencher Posts, Usuários ou Termos.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/native",
  "title": "Native Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts"
        }
      }
    ]
  }
}

Os tipos de consulta disponíveis usam internamente estas funções de WordPress:

Consulta Função
posts get_posts
users get_users
terms get_terms

Argumentos

Argumentos personalizados podem ser passados usando o atributo arguments:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "jobs",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

Formato de retorno

Por padrão, Blockstudio retorna:

Consulta Valor Rótulo
posts objeto de post post_title
users objeto de usuário display_name
terms objeto de termo name

Personalize a resposta com returnFormat:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          },
          "returnFormat": {
            "value": "id",
            "label": "post_name"
          }
        }
      }
    ]
  }
}

Modo de busca

Ative a pesquisa dinâmica com a opção fetch:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "fetch": true,
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

Isso ativa stylisedUi e busca inicialmente os primeiros 20 posts. Ao digitar no campo de seleção, os posts são pesquisados usando o argumento s.

Função

Use uma função personalizada para preencher opções:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types"
        }
      }
    ]
  }
}

Argumentos

Passe os argumentos como um array (usa call_user_func_array internamente):

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"]
        }
      }
    ]
  }
}

Formato de retorno

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"],
          "returnFormat": {
            "value": "name",
            "label": "label"
          }
        }
      }
    ]
  }
}

Combinação de opções

Combine opções estáticas com dados preenchidos dinamicamente:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "users",
        "type": "radio",
        "label": "Users",
        "options": [
          {
            "value": "administrators",
            "label": "Administrators"
          },
          {
            "value": "editors",
            "label": "Editors"
          }
        ],
        "populate": {
          "type": "query",
          "query": "users",
          "position": "before"
        }
      }
    ]
  }
}

A opção position (before ou after) controla onde as opções preenchidas aparecem em relação às opções estáticas.

Aviso

Não há suporte para combinar opções e preenchimento de dados no modo fetch.

Dados personalizados

Crie conjuntos de dados reutilizáveis com o filtro blockstudio/blocks/attributes/populate. O filtro recebe um único argumento: um array de todos os conjuntos de dados personalizados, indexados por nome. Adicione seu conjunto de dados usando uma chave e retorne o array:

PHP
add_filter('blockstudio/blocks/attributes/populate', function($options) {
  $options['customData'] = [
    ['value' => '1', 'label' => 'Option 1'],
    ['value' => '2', 'label' => 'Option 2'],
  ];
  return $options;
});

Em seguida, use a chave no seu bloco:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "custom",
          "custom": "customData"
        }
      }
    ]
  }
}

Dados externos

Busque dados de uma fonte externa:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "select",
        "type": "select",
        "label": "Select",
        "multiple": true,
        "populate": {
          "type": "fetch",
          "arguments": {
            "urlSearch": "https://example.com/wp-json/wp/v2/posts?search="
          },
          "returnFormat": {
            "value": "id",
            "label": "title.rendered"
          }
        }
      }
    ]
  }
}

O termo de pesquisa é anexado a urlSearch.

Argumentos dinâmicos

Os argumentos de preenchimento podem fazer referência a outros atributos do bloco usando a sintaxe {attributes.*}. Quando o atributo referenciado muda, o campo busca novamente suas opções automaticamente.

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post Type",
        "options": [
          { "label": "Pages", "value": "page" },
          { "label": "Posts", "value": "post" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Select Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "{attributes.post_type.value}",
            "numberposts": 10
          }
        }
      }
    ]
  }
}

Isso funciona com todos os tipos de preenchimento (query, function, custom). Qualquer valor na configuração de preenchimento que contenha {attributes.*} é resolvido no lado do cliente com o valor atual do atributo antes da execução da consulta.

As referências usam os valores armazenados no editor. Para uma opção de seleção, use {attributes.post_type.value} para obter o valor ou {attributes.post_type.label} para obter o rótulo; returnFormat controla o valor do modelo, não o formato armazenado pelo editor.

Os argumentos aninhados são resolvidos sem serializá-los em uma string de modelo. Um argumento que consiste em um único espaço reservado mantém o tipo referenciado, incluindo números, valores booleanos, matrizes e objetos. Um espaço reservado inserido em outro texto produz uma string. As referências ausentes permanecem inalteradas, e os valores entre aspas ou multilinha são enviados intactos. Os callbacks de função mantêm suas listas de argumentos posicionais. O editor adiciona argumentos de pesquisa WordPress somente a preenchimentos query, não a chamadas de função.

Renderização de seleções dependentes

As opções dependentes não são carregadas quando o bloco é registrado, pois cada instância do bloco pode ter argumentos diferentes. A renderização usa a seleção salva em vez de descartá-la por causa de uma lista de opções vazia. O callback de preenchimento não é executado novamente no frontend.

O returnFormat do campo ainda se aplica:

returnFormat Seleção única Seleção múltipla
value (padrão) O valor salvo, por exemplo "a" Uma matriz de valores salvos, por exemplo ["a", "b"]
label O rótulo salvo Uma matriz de rótulos salvos
both A opção {value, label} salva Uma matriz de opções salvas

Para seleções preenchidas por consulta, os valores ainda são resolvidos para o objeto correspondente de post, usuário ou termo WordPress, a menos que populate.returnFormat.value seja "id". Os rótulos vêm da seleção salva. Se uma seleção importada não tiver rótulo, seu valor será usado como rótulo. Uma opção estática correspondente declarada em options tem precedência sobre a opção salva, portanto o rótulo atual se aplica.

Seleções vazias continuam sendo false (ou o fallback configurado para o campo). Isso não altera a validação de opções estáticas comuns: um valor salvo que não esteja mais na lista de opções estáticas ainda retorna false.

Seleções dinâmicas também preservam as seleções default e fallback enquanto suas opções estão adiadas. Use um valor escalar, uma opção {value, label} ou uma matriz de qualquer um dos dois para uma seleção múltipla. Um escalar usa seu valor como rótulo, a menos que corresponda a uma opção estática declarada. Um objeto de opção preserva o rótulo fornecido; uma opção estática correspondente tem precedência. Nenhum callback de preenchimento é executado no servidor para buscar esses valores padrão.