Contexto y comunicación entre bloques
La mayoría de los bloques son independientes. Tienen sus propios campos y su propia plantilla, y no les importa lo que los rodea. Sin embargo, algunos componentes son naturalmente jerárquicos: una cuadrícula de tarjetas en la que el bloque principal controla el número de columnas y el espacio entre ellas, una tabla de precios en la que el bloque principal establece la moneda, o un contenedor de sección que indica a sus bloques secundarios si deben usar un tema claro u oscuro.
WordPress proporciona un contexto de bloque API para ello. Un bloque principal expone algunos de sus datos y los bloques secundarios se suscriben a ellos. Cuando cambia el bloque principal, los secundarios se actualizan automáticamente. Blockstudio simplifica mucho este proceso: no tiene que configurar providesContext en absoluto. Cada bloque Blockstudio proporciona automáticamente todos sus atributos como contexto. Los bloques secundarios solo necesitan una línea en su block.json para suscribirse.
Esta guía presenta cuatro patrones de componentes para casos reales que usan contexto, cada uno con una necesidad de comunicación distinta.
Cómo funciona el contexto en Blockstudio
En WordPress estándar, debe asignar explícitamente cada atributo del bloque principal a una clave de contexto en providesContext y, después, incluir esas claves en el usesContext del bloque secundario. Blockstudio elimina por completo el primer paso.
Bloque principal: No requiere configuración. Cada bloque Blockstudio proporciona automáticamente todos sus atributos con el nombre de su bloque.
Bloque secundario: Añada usesContext con el nombre del bloque principal:
{
"usesContext": ["my-theme/parent-block"]
}
Plantilla del bloque secundario: Acceda a los atributos del bloque principal mediante $context (o la forma abreviada $c):
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>
Eso es todo lo que hay que configurar. No hace falta providesContext en el bloque principal, ni asignar atributos ni registrar código. El bloque secundario recibe todos los atributos transformados del bloque principal: los campos multimedia se resuelven en datos adjuntos, los campos de selección respetan returnFormat y los campos repetidores se expanden por completo.
Dos tipos de contexto
Blockstudio proporciona dos variables de contexto en las plantillas, cada una con una función distinta:
| Variable | Contenido | Caso de uso |
|---|---|---|
$context / $c |
Atributos del bloque principal (mediante usesContext) |
Comunicación entre componentes |
$block['context'] / $b['context'] |
Datos del bucle WordPress (postId, postType) |
Bucles de bloques de consulta |
El primero permite que los bloques se comuniquen con sus bloques principales. El segundo sirve para los bloques dentro de un bucle de consulta que necesitan saber qué entrada están mostrando. Esta guía se centra en el primer tipo.
Compatibilidad con el editor
Las actualizaciones del contexto son reactivas en el editor. Cuando un usuario cambia el valor de un campo del bloque principal, todos los bloques secundarios suscritos a su contexto se vuelven a renderizar automáticamente con el nuevo valor. No es necesario actualizar nada manualmente.
Contenedor de sección
El patrón de contexto más habitual: un bloque contenedor que proporciona ajustes de tema a sus bloques secundarios. El bloque principal tiene campos para el color de fondo, el color del texto y el relleno. Los bloques secundarios leen estos valores para aplicar un estilo coherente.
Principal: Sección
{
"name": "my-theme/section",
"title": "Section",
"category": "design",
"icon": "align-wide",
"description": "Section wrapper with theme settings.",
"blockstudio": {
"attributes": [
{
"id": "theme",
"type": "select",
"label": "Theme",
"default": "light",
"options": [
{ "value": "light", "label": "Light" },
{ "value": "dark", "label": "Dark" },
{ "value": "accent", "label": "Accent" }
]
},
{
"id": "spacing",
"type": "select",
"label": "Spacing",
"default": "md",
"options": [
{ "value": "sm", "label": "Small" },
{ "value": "md", "label": "Medium" },
{ "value": "lg", "label": "Large" }
]
}
]
}
}
<?php
$theme_classes = array(
'light' => 'bg-white text-gray-900',
'dark' => 'bg-gray-900 text-white',
'accent' => 'bg-indigo-600 text-white',
);
$spacing_classes = array(
'sm' => 'py-8',
'md' => 'py-16',
'lg' => 'py-24',
);
$classes = ( $theme_classes[ $a['theme'] ] ?? '' ) . ' ' . ( $spacing_classes[ $a['spacing'] ] ?? '' );
?>
<div useBlockProps class="<?php echo esc_attr( $classes ); ?>">
<InnerBlocks
allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/section-heading', 'my-theme/section-text', 'core/columns', 'core/group' ) ) ); ?>'
/>
</div>
Secundario: Encabezado de sección
{
"name": "my-theme/section-heading",
"title": "Section Heading",
"category": "design",
"icon": "heading",
"description": "Heading that adapts to section theme.",
"usesContext": ["my-theme/section"],
"parent": ["my-theme/section"],
"blockstudio": {
"attributes": [
{ "id": "text", "type": "text", "label": "Heading", "default": "Section Title" },
{
"id": "size",
"type": "select",
"label": "Size",
"default": "lg",
"options": [
{ "value": "sm", "label": "Small" },
{ "value": "lg", "label": "Large" },
{ "value": "xl", "label": "Extra Large" }
]
}
]
}
}
<?php
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$color_class = match ( $theme ) {
'light' => 'text-gray-900',
'dark' => 'text-white',
'accent' => 'text-white',
default => 'text-gray-900',
};
$size_class = match ( $a['size'] ) {
'sm' => 'text-2xl',
'lg' => 'text-4xl',
'xl' => 'text-6xl',
default => 'text-4xl',
};
?>
<h2 useBlockProps class="<?php echo esc_attr( "$color_class $size_class font-bold" ); ?>">
<?php echo esc_html( $a['text'] ); ?>
</h2>
Qué demuestra: El encabezado no tiene un campo de color propio. Lee del contexto el valor de theme de la sección y adapta su estilo. Cuando el usuario cambia la sección de «Claro» a «Oscuro» en el editor, el color del texto del encabezado se actualiza de inmediato.
La propiedad parent en el block.json del bloque secundario restringe dónde se puede insertar el bloque. Solo aparece en el insertador cuando el usuario está dentro de un bloque my-theme/section. Es opcional, pero se recomienda para los bloques que solo tienen sentido dentro de un bloque principal específico.
Secundario: Texto de sección
{
"name": "my-theme/section-text",
"title": "Section Text",
"category": "design",
"icon": "text",
"description": "Body text that adapts to section theme.",
"usesContext": ["my-theme/section"],
"parent": ["my-theme/section"],
"blockstudio": {
"attributes": [
{ "id": "text", "type": "textarea", "label": "Text", "default": "Section body text." }
]
}
}
<?php
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$color_class = match ( $theme ) {
'dark', 'accent' => 'text-white/80',
default => 'text-gray-600',
};
?>
<p useBlockProps class="<?php echo esc_attr( "$color_class text-lg leading-relaxed" ); ?>">
<?php echo esc_html( $a['text'] ); ?>
</p>
Ahora tanto el encabezado como el texto responden al tema de la sección. El usuario elige un tema en el bloque principal y todos los bloques secundarios se adaptan.
Cuadrícula de tarjetas
Un bloque principal de cuadrícula que controla los ajustes de diseño de sus tarjetas secundarias. El bloque principal define las columnas y el espacio entre ellas. Los bloques secundarios usan estos valores para conocer el contexto de diseño y adaptar sus estilos según corresponda.
Principal: Cuadrícula de tarjetas
{
"name": "my-theme/card-grid",
"title": "Card Grid",
"category": "design",
"icon": "grid-view",
"description": "Responsive card grid with configurable columns.",
"blockstudio": {
"attributes": [
{
"id": "columns",
"type": "range",
"label": "Columns",
"default": 3,
"min": 1,
"max": 4,
"step": 1
},
{
"id": "gap",
"type": "select",
"label": "Gap",
"default": "md",
"options": [
{ "value": "sm", "label": "Small" },
{ "value": "md", "label": "Medium" },
{ "value": "lg", "label": "Large" }
]
},
{
"id": "cardStyle",
"type": "select",
"label": "Card Style",
"default": "elevated",
"options": [
{ "value": "elevated", "label": "Elevated (shadow)" },
{ "value": "outlined", "label": "Outlined (border)" },
{ "value": "flat", "label": "Flat (no decoration)" }
]
}
]
}
}
<?php
$gap_class = match ( $a['gap'] ) {
'sm' => 'gap-4',
'md' => 'gap-6',
'lg' => 'gap-8',
default => 'gap-6',
};
?>
<div useBlockProps class="grid grid-cols-<?php echo esc_attr( $a['columns'] ); ?> <?php echo esc_attr( $gap_class ); ?>">
<InnerBlocks
allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/card' ) ) ); ?>'
template='<?php echo esc_attr( wp_json_encode( array(
array( 'my-theme/card', array() ),
array( 'my-theme/card', array() ),
array( 'my-theme/card', array() ),
) ) ); ?>'
/>
</div>
Secundario: Tarjeta
{
"name": "my-theme/card",
"title": "Card",
"category": "design",
"icon": "cover-image",
"description": "Card that inherits style from its grid parent.",
"usesContext": ["my-theme/card-grid"],
"parent": ["my-theme/card-grid"],
"blockstudio": {
"attributes": [
{ "id": "image", "type": "files", "label": "Image", "multiple": false },
{ "id": "title", "type": "text", "label": "Title", "default": "Card Title" },
{ "id": "description", "type": "textarea", "label": "Description", "default": "Card description goes here." },
{ "id": "url", "type": "link", "label": "Link" }
]
}
}
<?php
$grid = $context['my-theme/card-grid'] ?? array();
$card_style = $grid['cardStyle'] ?? 'elevated';
$style_class = match ( $card_style ) {
'elevated' => 'bg-white rounded-xl shadow-md',
'outlined' => 'bg-white rounded-xl border border-gray-200',
'flat' => 'bg-gray-50 rounded-xl',
default => 'bg-white rounded-xl shadow-md',
};
?>
<div useBlockProps class="<?php echo esc_attr( "$style_class overflow-hidden" ); ?>">
<?php if ( $a['image'] ) : ?>
<img
src="<?php echo esc_url( $a['image']['url'] ); ?>"
alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
class="w-full aspect-video object-cover" />
<?php endif; ?>
<div class="p-6">
<h3 class="text-lg font-semibold"><?php echo esc_html( $a['title'] ); ?></h3>
<p class="mt-2 text-gray-600"><?php echo esc_html( $a['description'] ); ?></p>
<?php if ( $a['url'] ) : ?>
<a href="<?php echo esc_url( $a['url']['url'] ); ?>" class="mt-4 inline-block text-indigo-600 font-medium">
<?php echo esc_html( $a['url']['title'] ?: 'Learn more' ); ?>
</a>
<?php endif; ?>
</div>
</div>
Qué demuestra: La tarjeta no tiene un campo de estilo propio. Lee cardStyle del bloque principal de cuadrícula. Cuando el usuario cambia el estilo de la cuadrícula de «Elevado» a «Con contorno», todas las tarjetas se actualizan a la vez. Así se mantiene la coherencia visual sin tener que actualizar cada tarjeta por separado.
El atributo template en <InnerBlocks> rellena previamente la cuadrícula con tres tarjetas para que el usuario tenga un punto de partida.
Tabla de precios
Un patrón más avanzado en el que el bloque principal proporciona lógica de negocio compartida (moneda y período de facturación) que los bloques secundarios usan para mostrar la información. Así se evita duplicar los mismos campos en cada nivel de precios.
Principal: Tabla de precios
{
"name": "my-theme/pricing-table",
"title": "Pricing Table",
"category": "text",
"icon": "money-alt",
"description": "Pricing comparison with shared currency and billing settings.",
"blockstudio": {
"attributes": [
{
"id": "currency",
"type": "select",
"label": "Currency",
"default": "usd",
"options": [
{ "value": "usd", "label": "USD ($)" },
{ "value": "eur", "label": "EUR (\u20ac)" },
{ "value": "gbp", "label": "GBP (\u00a3)" }
]
},
{
"id": "period",
"type": "select",
"label": "Billing Period",
"default": "month",
"options": [
{ "value": "month", "label": "Monthly" },
{ "value": "year", "label": "Yearly" }
]
}
]
}
}
<div useBlockProps class="grid grid-cols-3 gap-6 items-start">
<InnerBlocks
allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/pricing-tier' ) ) ); ?>'
template='<?php echo esc_attr( wp_json_encode( array(
array( 'my-theme/pricing-tier', array( 'name' => 'Starter', 'price' => 9 ) ),
array( 'my-theme/pricing-tier', array( 'name' => 'Pro', 'price' => 29, 'highlighted' => true ) ),
array( 'my-theme/pricing-tier', array( 'name' => 'Enterprise', 'price' => 99 ) ),
) ) ); ?>'
/>
</div>
Secundario: Nivel de precios
{
"name": "my-theme/pricing-tier",
"title": "Pricing Tier",
"category": "text",
"icon": "tag",
"description": "Single pricing tier that reads currency from parent.",
"usesContext": ["my-theme/pricing-table"],
"parent": ["my-theme/pricing-table"],
"blockstudio": {
"attributes": [
{ "id": "name", "type": "text", "label": "Tier Name", "default": "Plan" },
{ "id": "price", "type": "number", "label": "Price", "default": 0 },
{ "id": "highlighted", "type": "toggle", "label": "Highlighted", "default": false },
{
"id": "features",
"type": "repeater",
"label": "Features",
"attributes": [
{ "id": "text", "type": "text", "label": "Feature" }
]
}
]
}
}
<?php
$table = $context['my-theme/pricing-table'] ?? array();
$currency = $table['currency'] ?? 'usd';
$period = $table['period'] ?? 'month';
$symbols = array(
'usd' => '$',
'eur' => "\u{20AC}",
'gbp' => "\u{00A3}",
);
$symbol = $symbols[ $currency ] ?? '$';
$period_label = $period === 'year' ? '/year' : '/month';
$border_class = $a['highlighted'] ? 'border-2 border-indigo-600' : 'border border-gray-200';
?>
<div useBlockProps class="<?php echo esc_attr( "rounded-xl p-8 $border_class" ); ?>">
<h3 class="text-lg font-semibold"><?php echo esc_html( $a['name'] ); ?></h3>
<div class="mt-4">
<span class="text-4xl font-bold"><?php echo esc_html( $symbol . $a['price'] ); ?></span>
<span class="text-gray-500"><?php echo esc_html( $period_label ); ?></span>
</div>
<?php if ( ! empty( $a['features'] ) ) : ?>
<ul class="mt-6 space-y-3">
<?php foreach ( $a['features'] as $feature ) : ?>
<li class="flex items-center gap-2">
<span class="text-indigo-600">✓</span>
<?php echo esc_html( $feature['text'] ); ?>
</li>
<?php endforeach; ?>
</ul>
<?php endif; ?>
</div>
Qué demuestra: El símbolo de moneda y el período de facturación se definen una sola vez en la tabla de precios y los hereda cada nivel. Cuando el usuario cambia de USD a EUR, el símbolo de moneda se actualiza simultáneamente en los tres niveles. Sin contexto, tendría que duplicar el campo de moneda en cada nivel y mantenerlos sincronizados manualmente.
Contexto del bucle de consulta
WordPress proporciona otro tipo de contexto dentro de los bucles de bloques de consulta. Cuando un bloque se renderiza dentro de un bucle, $block['context'] (o $b['context']) contiene los datos de la entrada de la iteración actual:
<?php
$loop_post_id = $block['context']['postId'];
$loop_post_type = $block['context']['postType'];
?>
<article useBlockProps>
<h2><?php echo esc_html( get_the_title( $loop_post_id ) ); ?></h2>
<p><?php echo esc_html( get_the_excerpt( $loop_post_id ) ); ?></p>
<a href="<?php echo esc_url( get_permalink( $loop_post_id ) ); ?>">Read more</a>
</article>
Esto es distinto del contexto del bloque principal ($context / $c). El núcleo de WordPress proporciona el contexto del bucle, que solo contiene postId y postType. Para ello, no necesita usesContext en su block.json. Blockstudio suscribe automáticamente cada bloque a postId y postType.
Cuándo resulta útil el contexto del bucle: tarjetas personalizadas para entradas dentro de bloques de consulta, bloques que muestran metadatos de entradas o cualquier bloque que deba mostrar un contenido distinto para cada entrada del bucle.
También puede acceder a los datos de la entrada de la página externa, independientemente del contexto del bucle:
$outer_post_id = $block['postId']; // always the current page
$loop_post_id = $block['context']['postId']; // current loop iteration
Contexto anidado
El contexto se propaga por todo el árbol de bloques, no solo un nivel. Si el bloque A contiene al bloque B y este contiene al bloque C, C puede suscribirse al contexto de A. Esto funciona porque WordPress propaga el contexto por todos los niveles de InnerBlocks.
my-theme/section (theme: "dark")
└── core/columns
└── core/column
└── my-theme/section-heading (reads section context)
El encabezado no tiene que ser un bloque secundario directo de la sección. Puede estar anidado dentro de bloques del núcleo (columnas, grupos, etc.) y seguir recibiendo el contexto de la sección. La suscripción usesContext funciona a cualquier profundidad.
Varios bloques principales
Un bloque secundario puede suscribirse a varios bloques principales:
{
"usesContext": ["my-theme/section", "my-theme/card-grid"]
}
<?php
$section = $context['my-theme/section'] ?? array();
$grid = $context['my-theme/card-grid'] ?? array();
$theme = $section['theme'] ?? 'light';
$cardStyle = $grid['cardStyle'] ?? 'elevated';
?>
Si no se encuentra un bloque principal en el árbol de antecesores, su clave no estará en $context. Al leer valores del contexto, use siempre el operador de fusión con nulo (??) o compruebe isset(), por si el bloque se usa fuera del bloque principal previsto.
Programación defensiva
Los bloques que usan contexto siempre deben contemplar el caso en que falte el bloque principal. Es posible que un usuario inserte el bloque fuera del bloque principal previsto o que el bloque principal no tenga un valor definido para un campo concreto.
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>
Si quiere asegurarse de que un bloque secundario solo aparezca dentro de su bloque principal, añada la propiedad parent:
{
"parent": ["my-theme/section"]
}
Esto quita el bloque del insertador cuando el usuario no está dentro de un bloque my-theme/section. Sin parent, el bloque aparece en todas partes y la plantilla debe gestionar correctamente la falta de contexto.
Use parent para los bloques que no tienen sentido fuera de su contenedor (niveles de precios, elementos de una cuadrícula de tarjetas). Omítalo en los bloques que funcionan de forma independiente, pero se benefician de estilos adicionales de un bloque principal (como los encabezados de sección, que también pueden usarse por separado).
Consejos
El contexto es de solo lectura. Los bloques secundarios no pueden modificar los atributos del bloque principal a través del contexto. Los datos fluyen hacia abajo, nunca hacia arriba. Si un bloque secundario necesita comunicarse con su bloque principal, deberá usar otro método (como el estado compartido del servidor mediante la API de Interactivity o los metadatos de entradas).
Se proporcionan todos los atributos. Blockstudio proporciona todos los atributos del bloque principal, no solo los seleccionados. Esto significa que el bloque secundario puede acceder a cualquier campo definido por el bloque principal. Si este añade un campo más adelante, los bloques secundarios podrán acceder a él automáticamente, sin cambiar la configuración.
Valores transformados. Los valores del contexto pasan por el flujo de transformación de atributos de Blockstudio. Los campos de archivos contienen todos los datos adjuntos (url, alt, width, height), los campos de selección respetan returnFormat y los campos repetidores se expanden de forma recursiva. Obtendrá la misma estructura de datos que $a en la plantilla del bloque principal.
Reactividad del editor. Cuando un usuario cambia un campo del bloque principal en el editor, los bloques secundarios se vuelven a renderizar automáticamente. Esto utiliza la propagación de contexto integrada de WordPress con un React useEffect que detecta cambios en el contexto y activa un nuevo renderizado del bloque secundario en el servidor.
Mantenga el contexto conciso. Aunque Blockstudio proporciona automáticamente todos los atributos del bloque principal, los bloques secundarios solo deben leer los valores que realmente necesitan. No se trata de un problema de rendimiento (los datos ya están disponibles), sino de que el código sea fácil de entender. Documente de qué campos del bloque principal depende cada bloque secundario para que los futuros desarrolladores entiendan la relación.
Próximos pasos
- Referencia del contexto: variables de plantilla, contexto del bucle y estructura de datos de
$block. - InnerBlocks: el componente
<InnerBlocks />,allowedBlocks, las plantillas y el filtro del contenedor de frontend. - Guía de Interactivity: para la reactividad en el cliente entre bloques (Interactivity API gestiona lo que el contexto no puede: la comunicación del bloque secundario al principal, el estado entre bloques y las actualizaciones iniciadas por el usuario).