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.
{
"$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:
Argumentos
Se pueden pasar argumentos personalizados mediante el atributo arguments:
{
"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:
{
"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:
{
"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:
{
"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):
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"]
}
}
]
}
}
Formato de retorno
{
"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:
{
"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:
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:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "custom",
"custom": "customData"
}
}
]
}
}
Datos externos
Obtén datos de una fuente externa:
{
"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.
{
"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.