Saltar al contenido

Recetario de patrones de campos

El sistema de campos de Blockstudio es sencillo por separado: añada un campo a blockstudio.attributes y acceda a él mediante $a en su plantilla. Pero los bloques reales rara vez tienen un solo campo. Incluyen grupos de ajustes relacionados, campos que se muestran u ocultan según otros campos, repetidores con estructuras de fila complejas y datos que deben poder consultarse fuera del editor de bloques.

Esta guía reúne recetas prácticas para patrones de campos habituales. Cada receta muestra la configuración de block.json y el código de plantilla correspondiente. Cópielas directamente en sus bloques y adáptelas según sea necesario.

Campos condicionales

El patrón más habitual: mostrar u ocultar campos según el valor de otro campo. Así, el editor se mantiene ordenado y solo muestra las opciones pertinentes.

Mostrar opciones con un interruptor

Un bloque CTA en el que aparecen ajustes adicionales cuando el usuario activa un botón:

JSON
{
  "name": "my-theme/cta",
  "title": "Call to Action",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "Ready to get started?" },
      { "id": "description", "type": "textarea", "label": "Description" },
      { "id": "showButton", "type": "toggle", "label": "Show Button", "default": true },
      {
        "id": "buttonText",
        "type": "text",
        "label": "Button Text",
        "default": "Get Started",
        "conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
      },
      {
        "id": "buttonUrl",
        "type": "link",
        "label": "Button Link",
        "conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
      }
    ]
  }
}

Los campos de texto y enlace del botón solo aparecen cuando el interruptor está activado. En la plantilla, compruebe el interruptor antes de renderizar:

PHP
<div useBlockProps>
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <?php if ( $a['description'] ) : ?>
    <p><?php echo esc_html( $a['description'] ); ?></p>
  <?php endif; ?>
  <?php if ( $a['showButton'] && $a['buttonUrl'] ) : ?>
    <a href="<?php echo esc_url( $a['buttonUrl']['url'] ); ?>">
      <?php echo esc_html( $a['buttonText'] ); ?>
    </a>
  <?php endif; ?>
</div>

Cambiar conjuntos de campos con un selector

Un bloque principal en el que el tipo de fondo determina qué campos aparecen:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      {
        "id": "bgType",
        "type": "select",
        "label": "Background Type",
        "default": "color",
        "options": [
          { "value": "color", "label": "Solid Color" },
          { "value": "gradient", "label": "Gradient" },
          { "value": "image", "label": "Image" },
          { "value": "video", "label": "Video" }
        ]
      },
      {
        "id": "bgColor",
        "type": "color",
        "label": "Background Color",
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "color" }]]
      },
      {
        "id": "bgGradient",
        "type": "gradient",
        "label": "Background Gradient",
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "gradient" }]]
      },
      {
        "id": "bgImage",
        "type": "files",
        "label": "Background Image",
        "multiple": false,
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "image" }]]
      },
      {
        "id": "bgVideo",
        "type": "files",
        "label": "Background Video",
        "multiple": false,
        "allowedTypes": ["video"],
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "video" }]]
      },
      {
        "id": "overlay",
        "type": "range",
        "label": "Overlay Opacity",
        "default": 50,
        "min": 0,
        "max": 100,
        "conditions": [[{ "id": "bgType", "operator": "!=", "value": "color" }]]
      }
    ]
  }
}

El campo de opacidad de superposición usa != para mostrarse con cualquier fondo que no sea de color sólido. Solo se muestra un campo de fondo a la vez. Un campo color devuelve un array con value, name y slug del color, así que la plantilla lee ['value']:

PHP
<?php
$bg_style = match ( $a['bgType'] ) {
	'color'    => $a['bgColor'] ? "background-color: {$a['bgColor']['value']}" : '',
	'gradient' => $a['bgGradient'] ? "background: {$a['bgGradient']}" : '',
	'image'    => $a['bgImage'] ? "background-image: url({$a['bgImage']['url']})" : '',
	default    => '',
};
?>
<div useBlockProps style="<?php echo esc_attr( $bg_style ); ?>">
  <?php if ( $a['bgType'] === 'video' && $a['bgVideo'] ) : ?>
    <video autoplay muted loop playsinline>
      <source src="<?php echo esc_url( $a['bgVideo']['url'] ); ?>" />
    </video>
  <?php endif; ?>
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
</div>

Condiciones OR

Muestre un campo cuando se cumpla cualquiera de varias condiciones. Cada array interno es un grupo AND; el array externo los combina con OR:

JSON
{
  "id": "caption",
  "type": "text",
  "label": "Caption",
  "conditions": [
    [{ "id": "bgType", "operator": "==", "value": "image" }],
    [{ "id": "bgType", "operator": "==", "value": "video" }]
  ]
}

Esto muestra el campo de subtítulo cuando bgType es “image” o “video”.

Condiciones encadenadas

Varias condiciones en el mismo array interno usan la lógica AND:

JSON
{
  "id": "altText",
  "type": "text",
  "label": "Alt Text",
  "conditions": [[
    { "id": "bgType", "operator": "==", "value": "image" },
    { "id": "bgImage", "operator": "!empty" }
  ]]
}

El campo de texto alternativo solo aparece cuando bgType es “image” y se ha seleccionado una imagen.

Condiciones globales

Muestre campos según el tipo de entrada, el ID de la entrada o el perfil del usuario, en lugar de otros valores de campos:

JSON
{
  "id": "seoTitle",
  "type": "text",
  "label": "SEO Title",
  "conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}

Tipos de condiciones globales disponibles: postType, postId, userRole, userId.

Ajustes organizados

A medida que los bloques se vuelven más complejos, organizar los campos en grupos lógicos facilita el manejo del inspector.

Grupos para organizar visualmente

Los grupos crean secciones plegables en el inspector. Un grupo anónimo (sin id) es puramente visual; se accede a sus campos mediante sus ID sin prefijo:

JSON
{
  "name": "my-theme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "title": "Content",
        "attributes": [
          { "id": "title", "type": "text", "label": "Title" },
          { "id": "description", "type": "textarea", "label": "Description" },
          { "id": "image", "type": "files", "label": "Image", "multiple": false }
        ]
      },
      {
        "type": "group",
        "title": "Link",
        "attributes": [
          { "id": "url", "type": "link", "label": "URL" },
          { "id": "openInNewTab", "type": "toggle", "label": "Open in New Tab" }
        ]
      },
      {
        "type": "group",
        "title": "Appearance",
        "attributes": [
          {
            "id": "style",
            "type": "select",
            "label": "Style",
            "default": "elevated",
            "options": [
              { "value": "elevated", "label": "Elevated" },
              { "value": "outlined", "label": "Outlined" },
              { "value": "flat", "label": "Flat" }
            ]
          },
          { "id": "accentColor", "type": "color", "label": "Accent Color" }
        ]
      }
    ]
  }
}
PHP
<div useBlockProps>
  <h3><?php echo esc_html( $a['title'] ); ?></h3>
  <p><?php echo esc_html( $a['description'] ); ?></p>
</div>

Se accede directamente a los campos: $a['title'], $a['style'], $a['accentColor']. Los grupos solo afectan al diseño del inspector.

Grupos con nombre y bs_get_group

Cuando un grupo tiene un id, se añade un prefijo a los ID de sus campos secundarios. Use bs_get_group() para quitarlo:

JSON
{
  "id": "author",
  "type": "group",
  "title": "Author",
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" },
    { "id": "avatar", "type": "files", "label": "Avatar", "multiple": false }
  ]
}

Sin el ayudante, se accede a los campos como $a['author_name'], $a['author_role'], $a['author_avatar']. Con el ayudante:

PHP
<?php $author = bs_get_group( $a, 'author' ); ?>
<div class="author">
  <?php if ( $author['avatar'] ) : ?>
    <img src="<?php echo esc_url( $author['avatar']['url'] ); ?>" alt="" />
  <?php endif; ?>
  <p><?php echo esc_html( $author['name'] ); ?></p>
  <p><?php echo esc_html( $author['role'] ); ?></p>
</div>

Los grupos con nombre resultan útiles cuando varios grupos tienen campos con los mismos nombres (e.g., author_name y company_name) o cuando quiere pasar el grupo completo a una plantilla parcial.

Diseño en cuadrícula en los grupos

Use la propiedad style para colocar los campos secundarios del grupo uno junto a otro:

JSON
{
  "type": "group",
  "title": "Dimensions",
  "style": {
    "display": "grid",
    "grid-template-columns": "1fr 1fr",
    "grid-gap": "16px"
  },
  "attributes": [
    { "id": "width", "type": "unit", "label": "Width", "default": "100%", "switch": false },
    { "id": "height", "type": "unit", "label": "Height", "default": "auto", "switch": false }
  ]
}

Los dos campos de unidades aparecen uno junto al otro en el inspector, en vez de apilados. Esto funciona bien con pares de dimensiones, valores de margen y relleno, o cualquier par de campos relacionados conceptualmente.

Pestañas para secciones principales

Cuando un bloque tiene muchos ajustes, las pestañas ofrecen una organización más clara que una larga lista de grupos:

JSON
{
  "type": "tabs",
  "tabs": [
    {
      "title": "Content",
      "attributes": [
        { "id": "title", "type": "text", "label": "Title" },
        { "id": "body", "type": "wysiwyg", "label": "Body" }
      ]
    },
    {
      "title": "Media",
      "attributes": [
        { "id": "image", "type": "files", "label": "Image", "multiple": false },
        { "id": "video", "type": "files", "label": "Video", "multiple": false, "allowedTypes": ["video"] }
      ]
    },
    {
      "title": "Settings",
      "attributes": [
        { "id": "layout", "type": "select", "label": "Layout", "options": [
          { "value": "left", "label": "Media Left" },
          { "value": "right", "label": "Media Right" }
        ]},
        { "id": "fullWidth", "type": "toggle", "label": "Full Width" }
      ]
    }
  ]
}

Se accede a los campos de cada pestaña como si fueran campos de nivel superior: $a['title'], $a['image'], $a['layout']. Las pestañas son únicamente un contenedor UI.

Patrones de repetidores

Los repetidores permiten que los usuarios añadan varias filas de campos. Son esenciales para listas, cuadrículas, cronologías y cualquier componente con un número variable de elementos.

Repetidor básico con límites

Una lista de características con entre 1 y 6 elementos:

JSON
{
  "id": "features",
  "type": "repeater",
  "label": "Features",
  "min": 1,
  "max": 6,
  "textButton": "Add Feature",
  "attributes": [
    { "id": "icon", "type": "icon", "label": "Icon" },
    { "id": "title", "type": "text", "label": "Title", "default": "Feature" },
    { "id": "description", "type": "textarea", "label": "Description" }
  ]
}
PHP
<div useBlockProps class="grid grid-cols-3 gap-8">
  <?php foreach ( $a['features'] as $feature ) : ?>
    <div>
      <?php if ( $feature['icon'] ) : ?>
        <?php bs_render_icon( $feature['icon'] ); ?>
      <?php endif; ?>
      <h3><?php echo esc_html( $feature['title'] ); ?></h3>
      <p><?php echo esc_html( $feature['description'] ); ?></p>
    </div>
  <?php endforeach; ?>
</div>

Etiquetas de fila personalizadas

De forma predeterminada, las filas minimizadas del repetidor muestran una etiqueta genérica. Use textMinimized para mostrar el valor de un campo:

JSON
{
  "id": "team",
  "type": "repeater",
  "label": "Team Members",
  "textMinimized": { "id": "name", "fallback": "Team Member" },
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" },
    { "id": "photo", "type": "files", "label": "Photo", "multiple": false }
  ]
}

Al plegar una fila, se muestra el nombre de la persona en vez de “Row 1”. Se usa fallback si el campo del nombre está vacío. También puede añadir cadenas prefix y suffix.

Condicionales dentro de repetidores

Los campos de un repetidor pueden hacer referencia a otros campos de la misma fila usando su id sin prefijo:

JSON
{
  "id": "links",
  "type": "repeater",
  "label": "Links",
  "attributes": [
    { "id": "label", "type": "text", "label": "Label" },
    { "id": "url", "type": "link", "label": "URL" },
    {
      "id": "isExternal",
      "type": "toggle",
      "label": "External Link"
    },
    {
      "id": "externalNote",
      "type": "message",
      "label": "Note",
      "description": "External links open in a new tab with rel=\"noopener\".",
      "conditions": [[{ "id": "isExternal", "operator": "==", "value": true }]]
    }
  ]
}

Referenciar campos externos desde un repetidor

Cuando una condición dentro de un repetidor debe comprobar un campo externo, añada "context": "main":

JSON
{
  "id": "showDescriptions",
  "type": "toggle",
  "label": "Show Descriptions",
  "default": true
},
{
  "id": "items",
  "type": "repeater",
  "label": "Items",
  "attributes": [
    { "id": "title", "type": "text", "label": "Title" },
    {
      "id": "description",
      "type": "textarea",
      "label": "Description",
      "conditions": [[{
        "id": "showDescriptions",
        "operator": "==",
        "value": true,
        "context": "main"
      }]]
    }
  ]
}

Sin "context": "main", la condición buscaría un campo showDescriptions dentro de la fila del repetidor. Con él, la condición comprueba el interruptor del nivel raíz.

Pestañas dentro de repetidores

Las pestañas no están disponibles dentro de los repetidores: un campo tabs dentro de una fila de repetidor muestra un aviso en el editor en lugar de sus campos, y la extensión PHPStan lo indica. Mantén planos los campos de una fila. Para las filas largas, una etiqueta de fila personalizada (textMinimized) facilita la lectura de las filas contraídas, y las condiciones dentro de la fila pueden ocultar los campos que solo necesitan algunas filas, como se muestra en los patrones anteriores.

Establece "minimized": true en un repetidor para que las filas existentes aparezcan contraídas inicialmente. Las filas nuevas se abren de inmediato. Las excepciones expandidas se recuerdan en este navegador aunque se vuelva a cargar el editor; es una preferencia de edición, no contenido guardado de la entrada. Los repetidores sin minimized mantienen el comportamiento actual de mostrarse expandidos de forma predeterminada.

Patrones multimedia

Imagen individual con alternativa

JSON
{
  "id": "image",
  "type": "files",
  "label": "Image",
  "multiple": false
}
PHP
<?php if ( $a['image'] ) : ?>
  <img
    src="<?php echo esc_url( $a['image']['url'] ); ?>"
    alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
    <?php if ( isset( $a['image']['sizes']['full-width'], $a['image']['sizes']['full-height'] ) ) : ?>
      width="<?php echo esc_attr( $a['image']['sizes']['full-width'] ); ?>"
      height="<?php echo esc_attr( $a['image']['sizes']['full-height'] ); ?>"
    <?php endif; ?>
  />
<?php endif; ?>

El returnFormat predeterminado es "object", que proporciona ID, title, alt, caption, description, href, url y sizes. sizes contiene el URL de cada tamaño de imagen registrado (sizes['large']), junto con sus dimensiones (sizes['large-width'], sizes['large-height']). Consulta Atributos de renderizado para ver la lista completa.

JSON
{
  "id": "gallery",
  "type": "files",
  "label": "Gallery",
  "multiple": true,
  "max": 6,
  "allowedTypes": ["image"]
}
PHP
<?php if ( $a['gallery'] ) : ?>
  <div class="grid grid-cols-3 gap-4">
    <?php foreach ( $a['gallery'] as $image ) : ?>
      <img
        src="<?php echo esc_url( $image['url'] ); ?>"
        alt="<?php echo esc_attr( $image['alt'] ); ?>" />
    <?php endforeach; ?>
  </div>
<?php endif; ?>

Imagen desactivable con interruptor

La propiedad switch añade un icono de ojo que permite a los usuarios desactivar el campo sin borrar su valor:

JSON
{
  "id": "logo",
  "type": "files",
  "label": "Logo",
  "multiple": false,
  "switch": true
}
PHP
<?php
$is_disabled = ! empty( $a['_disabled'] ) && in_array( 'logo', $a['_disabled'], true );
if ( $a['logo'] && ! $is_disabled ) : ?>
  <img src="<?php echo esc_url( $a['logo']['url'] ); ?>" alt="" />
<?php endif; ?>

El usuario puede desactivar el logotipo sin eliminar el archivo subido. Al volver a activarlo, aparece el mismo archivo.

Variantes del formato de devolución

Controle lo que devuelve el campo de archivos:

JSON
// Full object (default)
{ "id": "photo", "type": "files", "returnFormat": "object", "multiple": false }
// $a['photo']['url'], $a['photo']['alt'], $a['photo']['sizes']['full-width'], etc.

// Just the ID
{ "id": "photo", "type": "files", "returnFormat": "id", "multiple": false }
// $a['photo'] = 42

// Just the URL
{ "id": "photo", "type": "files", "returnFormat": "url", "multiple": false }
// $a['photo'] = "https://example.com/photo.jpg"

Use "id" cuando necesite llamar a wp_get_attachment_image() manualmente. Use "url" para imágenes de fondo sencillas. Use "object" (el predeterminado) en los demás casos.

Con "returnFormat": "id", una referencia de cadena importada como "buckshair-home" se pasa sin cambios. El editor muestra una tarjeta alternativa sin miniatura, incluso en las filas de repetidores. Abrir o guardar la página no convierte una referencia escalar en una matriz. También funcionan las listas mixtas de IDs de adjuntos y referencias de cadena; solo se buscan en la biblioteca de medios los IDs de adjuntos positivos.

Blockstudio no resuelve referencias de cadena personalizadas a adjuntos. Resuélvelas en tu propio filtro de renderizado o plantilla cuando uses nombres portátiles entre sitios. Al elegir un reemplazo en la biblioteca de medios, se guarda su ID de adjunto como siempre.

Opciones dinámicas

Rellenar a partir de entradas

Un campo de selección que enumera todas las páginas publicadas:

JSON
{
  "id": "linkedPage",
  "type": "select",
  "label": "Linked Page",
  "stylisedUi": true,
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": {
      "post_type": "page",
      "post_status": "publish",
      "posts_per_page": -1
    }
  }
}

El campo se rellena automáticamente con los títulos de las páginas como etiquetas y los ID de las entradas como valores. Use returnFormat en la configuración de rellenado para personalizar la asignación:

JSON
"populate": {
  "type": "query",
  "query": "posts",
  "arguments": { "post_type": "page" },
  "returnFormat": { "value": "ID", "label": "post_title" }
}

Rellenar a partir de términos de taxonomía

JSON
{
  "id": "category",
  "type": "select",
  "label": "Category",
  "stylisedUi": true,
  "populate": {
    "type": "query",
    "query": "terms",
    "arguments": {
      "taxonomy": "category",
      "hide_empty": true
    }
  }
}

Rellenar a partir de una función PHP

JSON
{
  "id": "postType",
  "type": "select",
  "label": "Post Type",
  "populate": {
    "type": "function",
    "function": "get_post_types",
    "arguments": { "public": true }
  }
}

Opciones estáticas con opciones adicionales rellenadas

Combine opciones codificadas con opciones dinámicas. Use position para controlar dónde aparecen las opciones rellenadas:

JSON
{
  "id": "source",
  "type": "select",
  "label": "Source",
  "options": [
    { "value": "manual", "label": "Manual Entry" },
    { "value": "latest", "label": "Latest Posts" }
  ],
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": { "post_type": "page" },
    "position": "after"
  }
}

Primero aparecen las opciones estáticas y, a continuación, las páginas rellenadas dinámicamente.

Almacenamiento de datos para consultas

De forma predeterminada, los valores de los campos se guardan en los atributos de bloque dentro de post_content. No se pueden consultar con WP_Query. Si necesita filtrar o ordenar entradas según el valor de un campo, use el almacenamiento.

Metadatos de entrada para campos consultables

JSON
{
  "id": "featured",
  "type": "toggle",
  "label": "Featured",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "is_featured"
  }
},
{
  "id": "priority",
  "type": "number",
  "label": "Priority",
  "default": 0,
  "min": 0,
  "max": 100,
  "storage": {
    "type": "postMeta",
    "postMetaKey": "priority_score"
  }
}

Ahora puede consultar las entradas destacadas:

PHP
$featured = new WP_Query( array(
    'meta_query' => array(
        array(
            'key'   => 'is_featured',
            'value' => '1',
        ),
    ),
    'orderby'  => 'meta_value_num',
    'meta_key' => 'priority_score',
    'order'    => 'DESC',
) );

Las claves meta se registran automáticamente con show_in_rest, por lo que también están disponibles en REST API.

Almacenamiento dual

Guarde los datos tanto en los atributos del bloque como en los metadatos de la entrada. El atributo del bloque mantiene el valor disponible en las plantillas mediante $a, mientras que los metadatos permiten consultarlo:

JSON
{
  "id": "eventDate",
  "type": "date",
  "label": "Event Date",
  "storage": {
    "type": ["block", "postMeta"],
    "postMetaKey": "event_date"
  }
}

Almacenamiento en opciones para valores globales

Para los ajustes de todo el sitio que deben ser iguales en todas partes, use el almacenamiento en opciones:

JSON
{
  "id": "companyName",
  "type": "text",
  "label": "Company Name",
  "storage": {
    "type": "option",
    "optionKey": "site_company_name"
  }
}

El valor se guarda en wp_options y está disponible en cualquier lugar mediante get_option('site_company_name'). Cuando el usuario edita este campo en cualquier instancia del bloque, el valor se actualiza globalmente.

Definiciones de campos reutilizables

Cuando varios bloques comparten la misma estructura de campos, defínala una vez como campo personalizado y haga referencia a ella en todas partes.

Crear un campo personalizado

Cree un field.json en el directorio blockstudio/fields/ de su tema:

Código
theme/
└── blockstudio/
    └── fields/
        └── cta/
            └── field.json
JSON
{
  "name": "cta",
  "title": "Call to Action",
  "attributes": [
    { "id": "label", "type": "text", "label": "Button Label", "default": "Learn More" },
    { "id": "url", "type": "link", "label": "Button URL" },
    { "id": "style", "type": "select", "label": "Button Style", "default": "primary", "options": [
      { "value": "primary", "label": "Primary" },
      { "value": "secondary", "label": "Secondary" },
      { "value": "outline", "label": "Outline" }
    ]}
  ]
}

Usar el campo personalizado

Haga referencia a él en cualquier bloque con "type": "custom/cta":

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "type": "custom/cta" }
    ]
  }
}

Los campos CTA se integran en el bloque. Acceda directamente a ellos: $a['label'], $a['url'], $a['style'].

Campos personalizados con prefijo e idStructure

Al usar varias veces el mismo campo personalizado, añada idStructure para incluir un prefijo en los ID:

JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/cta", "idStructure": "primary_{id}" },
      { "type": "custom/cta", "idStructure": "secondary_{id}" }
    ]
  }
}

Los campos del primer CTA pasan a ser primary_label, primary_url, primary_style. Los del segundo pasan a ser secondary_label, etc.

Sobrescribir valores predeterminados

Personalice campos específicos al hacer referencia a un campo personalizado:

JSON
{
  "type": "custom/cta",
  "idStructure": "hero_{id}",
  "overrides": {
    "label": { "default": "Get Started", "label": "CTA Label" },
    "style": { "default": "primary" }
  }
}

Las sobrescrituras se aplican sobre la definición original. Puede cambiar los valores predeterminados, las etiquetas, las condiciones o cualquier otra propiedad.

Patrones de renderizado

Comprobaciones de valores vacíos

La mayoría de los tipos de campo devuelven false cuando están vacíos. Compruébelo siempre antes de renderizar:

PHP
<?php if ( $a['title'] ) : ?>
  <h2><?php echo esc_html( $a['title'] ); ?></h2>
<?php endif; ?>

Para los números, 0 es un valor válido. Use una comparación estricta si necesita distinguir entre «vacío» y «cero»:

PHP
<?php if ( $a['count'] !== 0 || $a['count'] !== false ) : ?>
  <span><?php echo esc_html( $a['count'] ); ?></span>
<?php endif; ?>

Selector con returnFormat: both

Cuando necesite tanto el valor (para la lógica) como la etiqueta (para mostrarla):

JSON
{
  "id": "status",
  "type": "select",
  "label": "Status",
  "returnFormat": "both",
  "options": [
    { "value": "active", "label": "Active" },
    { "value": "paused", "label": "On Hold" },
    { "value": "closed", "label": "Closed" }
  ]
}
PHP
<?php if ( $a['status'] ) : ?>
  <span class="badge badge--<?php echo esc_attr( $a['status']['value'] ); ?>">
    <?php echo esc_html( $a['status']['label'] ); ?>
  </span>
<?php endif; ?>

Atributos de datos desde el campo de atributos

El tipo de campo attributes permite a los usuarios añadir atributos de datos personalizados:

JSON
{
  "id": "dataAttrs",
  "type": "attributes",
  "label": "Data Attributes",
  "link": true,
  "media": true
}
PHP
<div useBlockProps <?php bs_render_data_attributes( $a['dataAttrs'] ); ?>>
  Content here.
</div>

Variables CSS de valores de campos

Genere propiedades personalizadas de CSS a partir de los campos seleccionados:

JSON
{
  "id": "textColor", "type": "color", "label": "Text Color"
},
{
  "id": "fontSize", "type": "unit", "label": "Font Size", "default": "1rem"
}
PHP
<div useBlockProps style="<?php bs_render_variables( $a, array( 'textColor', 'fontSize' ) ); ?>">
  <p>Styled content.</p>
</div>

Esto genera style="--text-color: #333; --font-size: 1rem;" (los ID de campo se convierten a kebab-case). Use las variables en su CSS:

CSS
p {
  color: var(--text-color);
  font-size: var(--font-size);
}

Próximos pasos

  • Registro de atributos: las propiedades id, type, label, default, help, position y conditions.
  • Referencia de tipos de campo: referencia generada automáticamente con todas las propiedades de cada tipo de campo.
  • Lógica condicional: operadores, condiciones globales, filtros de condiciones personalizadas y contexto de repetidores.
  • Rellenado de opciones: modos de consulta, función, personalizados y de obtención para campos de opciones dinámicas.
  • Campos personalizados: field.json, rutas de detección, el filtro blockstudio/fields y patrones avanzados de idStructure.
  • Renderizado: $a, $b, $c, valores vacíos y funciones auxiliares.