Saltar al contenido

Rellenar opciones

En lugar de proporcionar distintos tipos de campo, como Entradas, Usuarios o Términos, Blockstudio permite una forma modular de rellenar datos directamente desde block.json. Esta función es compatible con los tipos de campo select, radio, checkbox, color y gradient.

Los datos se pueden rellenar de cuatro formas:

  • Consulta – Devuelve resultados de una consulta de entradas, usuarios o términos
  • Obtención – Devuelve resultados de una fuente externa
  • Función – Devuelve resultados de una función personalizada
  • Personalizado – Devuelve resultados de un conjunto de datos personalizado

Consulta

Al elegir el modo de consulta, se pueden rellenar Entradas, Usuarios o Términos.

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"
        }
      }
    ]
  }
}

Los tipos de consulta disponibles usan internamente estas funciones de WordPress:

Consulta Función
posts get_posts
users get_users
terms get_terms

Argumentos

Se pueden pasar argumentos personalizados mediante el 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

De forma predeterminada, Blockstudio devuelve:

Consulta Valor Etiqueta
posts objeto de entrada post_title
users objeto de usuario display_name
terms objeto de término name

Personaliza la respuesta con 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 obtención

Activa la búsqueda dinámica con la opción fetch:

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

Esto activa stylisedUi y obtiene inicialmente las 20 primeras entradas. Al escribir en el campo de selección, se buscan entradas usando el argumento s.

Función

Usa una función personalizada para rellenar las opciones:

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

Argumentos

Pasa los argumentos como una matriz (usa internamente call_user_func_array):

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"
          }
        }
      }
    ]
  }
}

Combinar opciones

Combina opciones estáticas con datos rellenados:

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"
        }
      }
    ]
  }
}

La opción position (before o after) controla dónde aparecen las opciones rellenadas con respecto a las opciones estáticas.

Advertencia

No se admite combinar opciones con datos rellenados en el modo fetch.

Datos personalizados

Crea conjuntos de datos reutilizables con el filtro blockstudio/blocks/attributes/populate. El filtro recibe un único argumento: una matriz de todos los conjuntos de datos personalizados, indexados por nombre. Añade tu conjunto de datos con una clave y devuelve la matriz:

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

Luego, referencia la clave en tu bloque:

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

Datos externos

Obtén datos de una fuente 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"
          }
        }
      }
    ]
  }
}

El término de búsqueda se añade a urlSearch.

Argumentos dinámicos

Los argumentos para rellenar opciones pueden hacer referencia a otros atributos del bloque mediante la sintaxis {attributes.*}. Cuando cambia el atributo referenciado, el campo vuelve a obtener sus opciones automáticamente.

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

Esto funciona con todos los tipos de relleno (query, function, custom). Cualquier valor de la configuración de relleno que contenga {attributes.*} se resuelve en el cliente con el valor actual del atributo antes de ejecutar la consulta.

Las referencias usan los valores almacenados en el editor. Para una opción de selección, usa {attributes.post_type.value} para su valor o {attributes.post_type.label} para su etiqueta; returnFormat controla el valor de la plantilla, no este formato almacenado en el editor.

Los argumentos anidados se resuelven sin serializarlos en una cadena de plantilla. Un argumento que consta de un solo marcador de posición conserva el tipo al que hace referencia, incluidos números, booleanos, matrices y objetos. Un marcador de posición integrado en otro texto produce una cadena. Las referencias que faltan se dejan sin cambios, y los valores entrecomillados o multilínea se envían intactos. Las funciones de retorno conservan sus listas de argumentos posicionales. El editor añade argumentos de búsqueda WordPress solo a las funciones populate de query, no a las llamadas de función.

Renderizado de selecciones dependientes

Las opciones dependientes no se cargan al registrar el bloque, porque cada instancia del bloque puede tener argumentos distintos. El renderizado usa la selección guardada en lugar de descartarla frente a una lista de opciones vacía. La función populate no se vuelve a ejecutar en la interfaz pública.

El returnFormat del campo sigue aplicándose:

returnFormat Selección única Selección múltiple
value (predeterminado) El valor guardado, por ejemplo "a" Una matriz de valores guardados, por ejemplo ["a", "b"]
label La etiqueta guardada Una matriz de etiquetas guardadas
both La opción {value, label} guardada Una matriz de opciones guardadas

En las selecciones cuyos valores se obtienen mediante consultas, los valores siguen resolviéndose como el objeto de entrada, usuario o término correspondiente de WordPress, a menos que populate.returnFormat.value sea "id". Las etiquetas proceden de la selección guardada. Si una selección importada no tiene etiqueta, se usa su valor como etiqueta. Una opción estática coincidente declarada en options tiene prioridad sobre la opción guardada, por lo que se aplica su etiqueta actual.

Las selecciones vacías siguen siendo false (o el fallback configurado para el campo). Esto no cambia la validación de las opciones estáticas normales: un valor guardado que ya no está en una lista de opciones estáticas sigue devolviendo false.

Las selecciones dinámicas también conservan las selecciones default y fallback mientras se aplaza la carga de sus opciones. Use un valor escalar, una opción {value, label} o una matriz de cualquiera de los dos para una selección múltiple. Un valor escalar usa su valor como etiqueta, a menos que coincida con una opción estática declarada. Un objeto de opción conserva la etiqueta proporcionada; una opción estática coincidente tiene prioridad. En el servidor no se ejecuta ninguna función de retorno de llamada de populate para buscar estos valores predeterminados.