La introducción de la edición completa del sitio (FSE) en WordPress destaca la creciente importancia del archivo theme.json. Ahora hay toda una nueva jerarquía y estructura que comprender, además de las distintas propiedades que te ayudarán a crear tus diseños. En particular, la propiedad blocks de theme.json es esencial si quieres crear temas de WordPress modernos y flexibles con Bloques únicos.
En esta guía, exploramos los entresijos de la propiedad blocks en theme.json para que puedas trabajar con Bloques, diseñarlos y darles estilo para crear experiencias de WordPress más dinámicas y personalizables.
Comprender la propiedad blocks en theme.json
Antes de sumergirnos en los entresijos de la propiedad blocks, entendamos primero su papel dentro de theme.json y del desarrollo de temas de WordPress.
En primer lugar, theme.json es el archivo de configuración que te permite definir estilos y ajustes globales para tus temas. Este «eje central» te permite controlar varios aspectos de la apariencia y el comportamiento de tu tema, como la tipografía, los colores y las opciones de diseño. Sin embargo, puede hacer más que simplemente darte ajustes programáticos estéticos.
La propiedad blocks te permite aplicar un control granular sobre tipos de Bloques individuales en lugar de sobre el sitio en su conjunto. Puedes definir estilos, ajustes y comportamientos predeterminados para Bloques específicos, lo que garantiza la coherencia en todo tu tema y la flexibilidad para los propietarios del sitio.
La relación entre la propiedad blocks y la edición completa del sitio
FSE es un enfoque más visual para construir tu sitio con Bloques como núcleo. En el front end, tienes la mayoría de las opciones de estilo y personalización disponibles para todo tu sitio:
La propiedad blocks es una parte crucial del archivo theme.json por varias razones:
- Proporciona una forma estandarizada de definir estilos y configuraciones de bloques.
- Puedes crear sistemas de diseño cohesivos a partir de una base programática.
- Puedes ofrecer un mayor control sobre la apariencia de los Bloques sin necesidad de CSS personalizado.
- La propiedad te ayuda a crear patrones y plantillas de Bloques.
Los desarrolladores pueden utilizar la propiedad blocks para crear temas que aprovechen al máximo la edición completa del sitio.
Cómo estructurar la propiedad blocks (y su sintaxis)
La estandarización que proporciona la propiedad blocks ayuda cuando se trata de la estructura y la sintaxis. Siempre la anidarás dentro del objeto settings:
{
"version": 3,
"settings": {
"blocks": {
"core/paragraph": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "13px"
},
{
"name": "Medium",
"slug": "medium",
"size": "20px"
}
]
…El ejemplo anterior define tamaños de fuente personalizados para un Bloque de Párrafo. Desglosar los componentes clave es sencillo:
- Anidas la propiedad
blocksbajo el objetosettings. - Cada tipo de bloque tiene un espacio de nombres y un nombre (
core/paragraphaquí). - A continuación, especificas la configuración del Bloque dentro del objeto.
Los ajustes incluyen la mayoría de los elementos disponibles para los estilos globales. Por ejemplo, pueden incluir tipografía, color, espaciado y muchos otros.
Configurar los ajustes globales del bloque
Veamos cómo definir los ajustes globales y luego cómo afecta esto a la propiedad blocks. Así establecerás una base de diseño coherente en todo tu tema.
{
"version": 3,
"settings": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "13px"
},
{
"name": "Medium",
"slug": "medium",
"size": "20px"
}
…En este ejemplo, definimos los tamaños de fuente globales disponibles para todos los bloques. Dentro del Editor de Sitios de WordPress, puedes encontrar estas opciones como parte de la pantalla Tipografía > Elementos > Texto:
Cada tamaño de fuente que definas en theme.json se correlaciona con una de las opciones de tamaño aquí:
Por supuesto, hay muchas otras formas de personalizar tu tema desde aquí. La idea es crear un diseño global que funcione en el 80% de los casos de uso.
Utilizando la propiedad blocks, puedes anular esos estilos centrales del Bloque para cubrir el 20% final. La pantalla Estilos del Editor de Sitios también te permite personalizar los ajustes de diseño de cada Bloque:
Esto es excelente para los usuarios finales, pero tiene menos valor para un desarrollador. Nos centraremos en utilizar theme.json para trabajar con la propiedad blocks.
Cómo personalizar tipos de Bloques individuales
Aunque la configuración global es importante para ayudar a mantener la coherencia, el verdadero poder reside en el alcance de la propiedad blocks para la personalización. Esta configuración a nivel granular te permite adaptar la apariencia y el comportamiento de bloques específicos para que coincidan con el diseño de tu tema, al igual que el Editor de Sitios.
Veamos un ejemplo de personalización del bloque Encabezado para tu tema:
{
"version": 3,
"settings": {
"blocks": {
"core/heading": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "20px"
},
{
"name": "Medium",
"slug": "medium",
"size": "30px"
},
{
"name": "Large",
"slug": "large",
"size": "40px"
}
],
"fontWeight": "bold"
},
"color": {
"palette": [
{
"name": "Heading Primary",
"slug": "heading-primary",
"color": "#333333"
},
{
"name": "Heading Secondary",
"slug": "heading-secondary",
"color": "#666666"
}
]
…Puedes ver que los atributos reflejan cómo harías cambios globales. Resumamos lo que estamos haciendo:
- Definimos tamaños de fuente específicos para los encabezados y los asignamos a etiquetas de tamaño.
- El peso de la fuente para todos los encabezados será simplemente negrita.
- Esos encabezados también tendrán una paleta de colores personalizada.
Esto garantiza que nuestros encabezados tendrán un aspecto coherente en todo el diseño. También conseguimos controlar estos elementos cuando no sabemos cómo los aplicará el usuario final, lo que beneficia aún más la coherencia del diseño.
Utilizar la combinación correcta de espacio de nombres y slug
Cuando llames a tipos de Bloque, es crucial que utilices la combinación correcta de espacio de nombres y slug. Sin ella, tus cambios no se aplicarán a los Bloques a los que quieras dirigirte.
Cada bloque tiene un espacio de nombres y un slug. Los Bloques del core de WordPress suelen tener el espacio de nombres core. El slug será el nombre del bloque:
…
"blocks": {
"core/image": {
…Si necesitas conocer el slug de un Bloque, puedes consultar su archivo específico block.json. Puedes encontrarlo en el directorio wp-includes/blocks. Aquí tendrás varias carpetas, cada una de las cuales contiene un archivo block.json. Dentro de cada uno de ellos, el espacio de nombres y el slug del Bloque deben estar cerca de la parte superior del archivo:
Si navegas por estos directorios, te darás cuenta de que el directorio wp-includes tiene su propio archivo theme.json. Aunque esto pueda parecer confuso, es sencillo de explicar.
Por qué theme.json incluye por defecto la configuración personalizada de los Bloques
El propio archivo theme.json de WordPress al principio puede parecer extraño, sobre todo porque no es un tema. Sin embargo, esto no es casual. La razón principal es soportar la compatibilidad con versiones anteriores de WordPress.
Por ejemplo, el Bloque Botón establece un radio de borde:
…
"blocks": {
"core/button": {
"border": {
"radius": true
}
},
…Otros Bloques tendrán ajustes similares para ayudar a la coherencia entre distintas versiones de WordPress. Sin embargo, esto puede causar problemas más adelante si es algo de lo que no eres consciente.
Si intentas definir ajustes globales y te preguntas por qué esos cambios no se aplican a Bloques específicos, la compatibilidad con versiones anteriores podría ser la respuesta. Por supuesto, puedes anular estos ajustes en tu propio archivo theme.json sin ningún problema.
Desarrollar Bloques personalizados con theme.json
El archivo theme.json es ideal para personalizar Bloques existentes, pero sus capacidades se extienden también al desarrollo de Bloques personalizados. Puedes aprovechar theme.json para definir estilos y ajustes predeterminados para cualquiera de tus Bloques personalizados. Esto te ayuda a ofrecer una integración perfecta con el diseño de tu tema.
Sin embargo, primero tienes que construir el propio Bloque. Esto va más allá del alcance de este artículo, pero en resumen, existen unas cuantas fases:
- Creación de la estructura base del Bloque. Esto implica configurar un entorno de desarrollo local y crear la estructura de archivos de todo el Bloque.
- Actualización del archivo
block.json. Aquí tendrás que cambiar la identidad del Bloque y añadir supports. Estos últimos son formas de declarar la compatibilidad con funcionalidades específicas de WordPress. Por ejemplo, puedes manejar la alineación, implementar campos de anclaje, trabajar con varios ajustes de tipografía y mucho más. - Modifica los archivos JavaScript del Bloque. Tanto
index.jscomoedit.jsnecesitan código para indicar a WordPress cómo funciona el Bloque y para que aparezca en el Editor de Sitios.
Puede que también necesites editar render.php, añadir renderizado estático y toda una serie de otras tareas. En este punto, puedes aplicar cualquier cambio de estilo a theme.json como con cualquier otro Bloque. Por ahora, echemos un vistazo más de cerca a block.json.
El archivo block.json
Este archivo es lo que el equipo de desarrollo de WordPress denomina la forma «canónica» de registrar Bloques tanto para el servidor como para el cliente. Los metadatos que incluyes aquí le dicen a WordPress todo sobre el tipo de Bloque y sus archivos de soporte:
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "my-plugin/notice",
"title": "Notice",
"category": "text",
"parent": [ "core/group" ],
"icon": "star",
"description": "Shows warning, error or success notices...",
"keywords": [ "alert", "message" ],
"version": "1.0.3",
"textdomain": "my-plugin",
"attributes": {
"message": {
"type": "string",
"source": "html",
"selector": ".message"
}
},
…Es similar a los metadatos que colocarías al principio de un archivo PHP para temas y plugins. Aunque el archivo utiliza exclusivamente datos JSON, puedes seguir usando código a través de PHP, JavaScript y CSS:
…
"editorScript": "file:./index.js",
"script": "file:./script.js",
"viewScript": [ "file:./view.js", "example-shared-view-script" ],
"editorStyle": "file:./index.css",
"style": [ "file:./style.css", "example-shared-style" ],
"viewStyle": [ "file:./view.css", "example-view-style" ],
"render": "file:./render.php"
…Volveremos sobre esto más adelante en la sección sobre variaciones. Para terminar esta sección, necesitas saber cómo establecer tu Bloque personalizado como predeterminado en WordPress. Hay varias formas de conseguirlo. La forma clásica es registrar un tipo de entrada personalizado e incluir allí los Bloques. Sin embargo, existen otro par de métodos.
Por ejemplo, puedes actualizar un tipo de entrada existente para añadir una plantilla de Bloque. Aquí tienes un ejemplo sencillo:
…
function load_post_type_patterns() {
// Define an initial pattern for the 'HypnoToad' post type
$post_type_object = get_post_type_object( 'hypnoToad' );
$post_type_object->template = array(
array(
'core/block',
…Otra forma es llamar al hook default_content y definir el Bloque utilizando el marcado:
function toad_content( $content, $post ) {
if ( $post->post_type === 'hypnoToad' ) {
$content ='
<div class="is-layout-flex wp-container-1 wp-block-columns"><!-- wp:column →
<div class="wp-block-column">
<p></p>
</div>
<div class="is-layout-flow wp-block-column">
<p></p>
</div>
</div>
';
}
return $content;
}
add_filter( 'default_content', 'toad_content', 10, 2 );Por supuesto, no sólo utilizarás JSON, HTML y PHP. También utilizarás otros lenguajes para ayudar con el diseño y la interactividad. La buena noticia es que WordPress te ofrece una forma sencilla de hacerlo.
Usar propiedades CSS personalizadas para tus Bloques
Puedes conseguir mucho utilizando las propiedades, atributos y objetos existentes de theme.json, pero no cubrirá todos los casos de uso. El archivo te proporciona la propiedad custom que te ayudará a crear propiedades CSS relevantes:
{
"version": 3,
"settings": {
"custom": {
"toad": "hypno"
}
}
}Aquí, das un par clave-valor, que se convierte en una variable CSS en el front-end:
body {
--wp--custom--toad: hypno;
}Ten en cuenta que la variable utilizará guiones dobles para separar sus elementos. En general, siempre verás --wp--custom--, que etiquetará la clave al final. A veces, definirás variables y propiedades con mayúsculas y minúsculas:
{
"version": 3,
"settings": {
"custom": {
"hypnoToad": "active"
}
}
}En este caso, WordPress utilizará guiones para separar las palabras:
body {
--wp--custom--hypno-toad: active;
}Entre la propiedad custom y block.json, tienes total libertad para construir tus Bloques como mejor te parezca, incluyendo cualquier variación que quieras incluir.
Un vistazo rápido al Bloque, al estilo y a las variaciones del estilo de Bloque
Antes de pasar al estilo mediante la propiedad blocks, echemos un vistazo a las variaciones. Tienes unos cuantos tipos de variaciones diferentes para tus diseños, y las convenciones de nomenclatura podrían hacer que utilizaras el tipo equivocado para tus necesidades. Aquí tienes un desglose de las diferencias:
- Variaciones de bloque. Si tu Bloque tiene versiones alternativas (piensa en un Bloque que mostrará muchos enlaces personalizados establecidos por el usuario), se trata de una variación de Bloque. El Bloque de Redes Sociales es un buen ejemplo de ello.
- Variaciones de estilo. Son versiones alternativas de
theme.jsonque funcionan en tu sitio global. No lo tratamos aquí, pero la mayoría de los temas de Block las ofrecen para diversas paletas de colores y configuraciones tipográficas. - Variaciones de estilo en bloque. Esto toma la funcionalidad básica de las variaciones de estilo y te permite crear diseños alternativos para un Bloque.
Puede que te preguntes si utilizar una variación de Bloque o una variación de estilo de Bloque; la respuesta no es complicada. Si los cambios que quieres hacer pueden producirse dentro de theme.json o utilizando CSS, crea una variación de estilo de Bloque. Cualquier otra cosa requiere una variación de Bloque.
Variaciones de bloques
Con las variaciones de bloques, las registrarás utilizando JavaScript. Crear un archivo dentro del directorio de un tema es una buena idea, pero puede ir en cualquier lugar. Basta una línea para registrar una variación dentro de tu archivo JavaScript:
const registerBlockVariation = ( blockName, variation )Para el objeto blockName, también tendrás que especificar aquí el espacio de nombres, como harías con la propiedad blocks. Dentro del objeto variation, añadirás el nombre, el título, la descripción, si la variación está activa por defecto, etc. Para cargar el archivo en el Editor de Sitios, simplemente llama al hook enqueue_block_editor_assets y pon en cola tu script dentro de él.
Variaciones de estilo de bloque
Cuando se trata de variaciones de estilo de bloque, tienes dos opciones:
- Utilizar la función
register_block_style()con PHP. - Crear un archivo JavaScript
block-editor.js, utilizar la funciónregisterBlockStyle()de forma similar a las variaciones en bloque y poner en cola el script.
Una vez que registres una variación de estilo de Bloque, puedes dirigirte al Bloque utilizando la propiedad variations:
…
"styles": {
"blocks": {
"core/button": {
"variations": {
"outline": {
"border": {
"color": "var:preset|color|black",
"radius": "0",
"style": "solid",
"width": "3px"
},
…Esto significa que puede que no necesites ningún CSS personalizado: casi todos los aspectos del diseño de un Bloque son posibles a través de la propiedad blocks.
Dar estilo a un Bloque predeterminado utilizando la propiedad blocks de principio a fin
Para demostrar cómo funciona la propiedad blocks, veamos un ejemplo real. Nuestro sitio utiliza el tema Twenty Twenty-Four, y está usando la variación de estilo por defecto:
Por ahora, nos parece ideal — aunque los títulos y el cuerpo del texto parecen tener un color demasiado similar. Queremos cambiar uno o ambos colores para diferenciarlos. Como usuario final o propietario del sitio, podemos arreglar esto dentro de la barra lateral Estilos del Editor de Sitios. Si te diriges a Bloques > Encabezado, puedes hacer clic en el elemento Texto y cambiar el color a algo más adecuado:
Sin embargo, como desarrollador, puedes hacerlo dentro de theme.json. Como con cualquier otro tema, lo mejor es crear un tema hijo para conservar los cambios que hagas. Una segunda ventaja es que tu archivo theme.json tendrá un aspecto más limpio.
Crearemos un directorio dentro de wp-content/themes/ y lo llamaremos twentytwentyfour-child. Aquí, añade un archivo style.css válido y un archivo theme.json en blanco.
Desde aquí, puedes abrir el archivo JSON y ponerte a trabajar.
Crear y rellenar un archivo theme.json para el tema hijo
La principal diferencia entre crear un tema padre y un tema hijo con respecto a theme.json es la estructura del archivo. No tendrás que indicar el esquema ni poner necesariamente todo dentro del objeto settings. En nuestro caso, tenemos que utilizar la propiedad styles:
{
"version": 3,
"styles": {
"blocks": {}
}
}A continuación, tenemos que encontrar el espacio de nombres y el slug para el Bloque de Encabezamiento. La Guía de Referencia oficial de Core Blocks enumera todo esto e incluso nos dirá qué atributos y propiedades admite el Bloque. La guía nos dice que podemos ajustar los valores background, gradient, link, y text para la propiedad color.
"blocks": {
"core/heading": {
"color": {}
}
}Con la estructura completa, podemos empezar a averiguar cómo cambiar el estilo del texto.
Encontrar un esquema de color y aplicar los cambios
Ahora necesitamos un color que se adapte a nuestras necesidades. La variación por defecto de Twenty Twenty-Four tiene una paleta excelente, y revisarla en un comprobador de contraste específico nos da algunas ideas:
A continuación, podemos añadir la elección de color para nuestro Bloque a theme.json. Como el tema padre Twenty Twenty-Four utiliza propiedades CSS personalizadas para definir los estilos de paleta, también podemos llamarlo aquí:
…
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" },
…Si necesitas saber el nombre de un color de paleta, puedes encontrarlo en el Editor de Sitios desde el selector de colores:
Una vez guardados los cambios, actualiza tu sitio y deberías ver la nueva paleta de colores en su sitio. Si no es así, comprueba que estás anidando la propiedad blocks dentro del objeto correcto, ya que éste es un punto de fricción habitual.
Si observamos el sitio, el texto es menos contrastado y más fácil de leer. Sin embargo, aún queremos ver algo de definición entre el Bloque de Párrafos y los encabezados circundantes. La paleta predeterminada del tema tiene otros colores más llamativos. Vamos a probar el color Acento / 3 para el Bloque de Encabezamiento:
"blocks": {
"core/heading": {
"color": { "text": "var(--wp--preset--color--accent-3)" }
},
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" }
}
}Después de guardar los cambios y actualizar el front-end, verás que el Bloque de Encabezamiento tiene más definición:
Esto no tiene por qué ser el final de la edición. Incluso puedes personalizar las opciones del Editor de Sitios desde theme.json.
Añadir opciones de atributo a los Bloques
Los ‘supports’ de cada Bloque determinan sus opciones dentro del Editor del Sitio. Por ejemplo, el Bloque de Párrafo tiene por defecto deshabilitada la funcionalidad de letra capital.
Podemos volver a activarlo en el archivo theme.json y en la propiedad blocks. Si nos fijamos en el material de referencia, podemos aprovechar la propiedad tipografía para activar las mayúsculas:
…
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" },
"typography": { "dropCap": true }
…Una vez que guardemos esos cambios y actualicemos el editor, tendrás disponible la opción de activar las mayúsculas:
El archivo theme.json no es simplemente un archivo de configuración para el diseño. También puede ayudar a añadir y eliminar funciones del Editor de Sitios.
Cómo el alojamiento administrado de Kinsta puede ayudarte a desarrollar temas para WordPress
Las complejidades del desarrollo de temas y theme.json dependen de soluciones de calidad en toda la cadena de desarrollo para aprovechar el potencial de mejora del rendimiento.
Un entorno de desarrollo local es crucial, ya que te permite crear, gestionar y retocar sitios de WordPress en tu máquina local. DevKinsta puede ayudarte en este sentido.
DevKinsta ofrece muchas ventajas:
- Se ejecuta en contenedores Docker, lo que significa que aíslas tu instalación del resto de tu máquina. Como tal, puedes probar tus configuraciones de
theme.jsony tus Bloques personalizados sin preocupaciones. - Puedes hacer iteraciones rápidas en tu archivo
theme.jsony ver los resultados inmediatamente en tu entorno local. - Crear varios sitios locales para probar tu tema en diferentes versiones y configuraciones de WordPress es pan comido.
Es más, no utilizarás ninguno de los recursos de tu servidor hasta que estés satisfecho y preparado. Los entornos de staging de Kinsta son el siguiente paso ideal. Puedes crear una copia de tu sitio de producción rápidamente e incluso bajarla a tu entorno local para seguir trabajando.
Es una forma estupenda de realizar pruebas de rendimiento de tu tema, sobre todo si combinas el staging con la herramienta de Monitorización del Rendimiento de las Aplicaciones (APM) de Kinsta.
También puedes aprovechar la integración Git de Kinsta en todos tus entornos. Esto te permite enviar y extraer cambios a los repositorios y desplegarlos también desde allí.
Resumen
Comprender la propiedad blocks en theme.json es un paso necesario para todos los desarrolladores de temas. Esta propiedad puede tomar un diseño global y hacerlo más único, cohesivo y relevante. Disponer de todas las posibilidades para trabajar con los ajustes individuales del core y de los bloques personalizados ayuda a todos los usuarios a aprovechar las capacidades de la edición completa del sitio. Además, tener estas opciones disponibles en el Editor de Sitios significa que los usuarios finales pueden hacer sus propios cambios sin código mientras tú presentas opciones predeterminadas estelares.
¿Tienes alguna pregunta sobre el uso de la propiedad blocks con el archivo theme.json? Pregunta en la sección de comentarios más abajo
Deja una respuesta