En 2018, WordPress introdujo el editor Gutenberg con la versión 5.0, aportando una nueva forma de construir páginas y entradas mediante «bloques». Al principio, estos bloques eran bastante básicos, pero con los años han evolucionado para ofrecer más flexibilidad y una mejor experiencia de edición.
Aun así, hay ocasiones en las que un bloque no hace exactamente lo que necesitas. Tal vez quieras eliminar ciertas funcionalidades, añadir otras nuevas, aplicar un estilo específico por defecto o hacer que algunos ajustes sean más fáciles de acceder. En casos como este, crear un bloque personalizado desde cero puede parecer una opción, pero — seamos sinceros — es excesivo para realizar pequeños ajustes. ¿No sería más fácil si pudieras modificar los bloques que ya existen?
Ahí es donde entra en juego la API de Bloques (Blocks API). Este artículo explica cómo ampliar los bloques principales de WordPress utilizando Blocks API, y proporciona ejemplos prácticos que pueden utilizarse en proyectos reales.
Comprender Blocks API de WordPress
Blocks API de WordPress constituye la base del editor de bloques, permitiendo a los desarrolladores crear, modificar y ampliar bloques. La API proporciona varias formas de interactuar con los bloques. Puedes:
- Modificar la configuración de los bloques — Cambiar los atributos, valores por defecto y comportamientos de los bloques.
- Añadir o eliminar soportes de bloque — Activar o desactivar características como la tipografía, los colores y el espaciado.
- Inyectar controles personalizados — Añadir nuevas opciones dentro del panel de configuración de bloques.
- Crear variaciones de bloques — Crea versiones preconfiguradas de bloques existentes para acelerar la creación de contenidos.
Cada bloque en WordPress, ya sea un bloque Párrafo, Imagen o Botón, se define mediante un conjunto de atributos y ajustes almacenados en un archivo block.json. Este archivo contiene metadatos sobre el bloque, incluyendo su nombre, categoría, atributos predeterminados y las funcionalidades que admite.
WordPress te permite modificar estos valores utilizando PHP o JavaScript, pero este artículo explica cómo utilizar los hooks de filtro en la Blocks API. Esto garantiza que tus modificaciones se registren en el servidor sin necesidad de poner en cola archivos JavaScript adicionales.
Por ejemplo, si quieres activar o desactivar determinadas características de un bloque, la mejor forma de hacerlo es utilizando el filtro register_block_type_args en PHP. Este método te permite ajustar dinámicamente la configuración del bloque sin modificar directamente el archivo block.json.
Modificar los soportes de los bloques
Los bloques de WordPress vienen con soportes predefinidos, que controlan las opciones del editor. Algunos bloques, como el bloque Imagen (core/image), tienen filtros duotono activados por defecto, lo que permite a los usuarios aplicar superposiciones de color.
Sin embargo, el bloque de Medios y Texto (core/media-text) no admite el duotono de forma predeterminada, aunque permite a los usuarios insertar una imagen. Esto significa que, aunque puedes aplicar un filtro duotono a un bloque Imagen independiente, no puedes hacer lo mismo cuando una imagen se coloca dentro de un bloque Medios y Texto.
Dado que el bloque de Medios y texto puede contener una imagen, tiene sentido habilitar los filtros duotono. Podemos hacerlo modificando su array supports y especificando el selector CSS adecuado para que el filtro se aplique correctamente. Esto se habilita mediante el filtro register_block_type_args en PHP.
Añade el siguiente código al archivo functions.php de tu tema:
function enable_duotone_for_media_text_block($args, $block_type) {
// Only modify the Media & Text block
if ( 'core/media-text' === $block_type ) {
$args['supports'] ??= [];
$args['supports']['filter'] ??= [];
$args['supports']['filter']['duotone'] = true;
$args['selectors'] ??= [];
$args['selectors']['filter'] ??= [];
$args['selectors']['filter']['duotone'] = '.wp-block-media-text .wp-block-media-text__media';
}
return $args;
}
add_filter('register_block_type_args', 'enable_duotone_for_media_text_block', 10, 2);El código anterior activa el filtro duotono dentro del array supports y define el selector CSS correcto para aplicar el efecto duotono a las imágenes dentro del bloque Medios y Texto. La función add_filter() utiliza 10 como prioridad (cuando se ejecuta el filtro) y 2 para especificar el número de argumentos pasados ($args, $block_type).
Cuando guardes el archivo y vuelvas a cargarlo, deberías ver los controles Duotono disponibles en la sección Filtros.
Activar el duotono para el bloque Medios y Texto mediante register_block_type_args es una forma eficaz de modificar el comportamiento del bloque dinámicamente. Sin embargo, WordPress proporciona otro método para modificar la configuración del bloque: anular los metadatos del bloque utilizando block_type_metadata.
Ambos métodos te permiten personalizar los bloques, pero funcionan en distintas fases del proceso de registro de bloques.
Por ejemplo, supongamos que queremos ajustar el bloque Párrafo (core/paragraph) para que sólo admita ajustes de margen y deshabilite el relleno. Una forma de hacerlo es utilizando register_block_type_args:
function modify_paragraph_spacing_args($args, $block_type) {
if ($block_type === 'core/paragraph') {
$args['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $args;
}
add_filter('register_block_type_args', 'modify_paragraph_spacing_args', 10, 2);Este método funciona bien en la mayoría de los casos, pero como modifica el bloque después de que ya se haya registrado, a veces puede ser anulado por otros plugins o temas que modifiquen el mismo bloque más adelante en el proceso.
Un enfoque más estructurado en este caso podría ser anular los metadatos del bloque directamente utilizando block_type_metadata:
function mytheme_modify_paragraph_spacing($metadata) {
if ($metadata['name'] === 'core/paragraph') {
$metadata['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $metadata;
}
add_filter('block_type_metadata', 'mytheme_modify_paragraph_spacing');Ninguno de los dos enfoques es intrínsecamente mejor que el otro — sólo depende de cuándo quieras modificar el bloque y de lo persistente que quieras que sea el cambio.
Registrar estilos de bloque
Muchos bloques de WordPress vienen con estilos predefinidos que los usuarios pueden seleccionar en el editor. Un buen ejemplo es el bloque Imagen (core/image), que incluye un estilo Redondeado por defecto. Sin embargo, las esquinas redondeadas por defecto suelen ser demasiado extremas, haciendo que la imagen parezca más un óvalo que un elemento con un estilo limpio.
En lugar de ajustar manualmente el radio del borde de cada imagen, un mejor enfoque es personalizar el estilo redondeado para que aplique un radio de esquina más refinado — quizás añadiendo una sutil sombra para un aspecto moderno. De esta manera, los usuarios pueden simplemente hacer clic en un botón para aplicar un estilo bien diseñado sin necesidad de ajustar manualmente la configuración cada vez.
Tomemos el estilo Redondeado del bloque Imagen y personalicémoslo para que las esquinas queden ligeramente redondeadas en lugar de excesivamente curvadas, y se añada una sutil sombra de caja para darle un aspecto más pulido.
Como el editor de bloques permite registrar y anular el registro de estilos de bloque, podemos eliminar el estilo Redondeado por defecto y sustituirlo por una versión personalizada.
Así es como se hace:
function modify_image_block_rounded_style() {
// Remove the default "Rounded" style
unregister_block_style( 'core/image', 'rounded' );
// Register a new "Rounded" style with custom CSS
register_block_style(
'core/image',
array(
'name' => 'rounded',
'label' => __( 'Rounded', 'your-text-domain' ),
'inline_style' => '
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjust this value */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Optional shadow */
}
',
)
);
}
add_action( 'init', 'modify_image_block_rounded_style' );El código sustituye el estilo predeterminado, demasiado redondeado, por una versión refinada que aplica border-radius: 20px; para esquinas más suaves y box-shadow para un realce sutil.
Utilizar un archivo CSS externo en lugar de estilos inline
Aunque el estilo inline funciona bien para estilos sencillos, no es ideal para su mantenimiento. Un enfoque mejor es definir los estilos en un archivo CSS externo y ponerlo en cola en su lugar.
Para ello, crea un nuevo archivo CSS, por ejemplo, custom-block-styles.css, y añádele esto:
/* Custom Rounded Image Block Style */
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjusted rounded corners */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Subtle shadow */
}A continuación, pon en cola el archivo CSS en functions.php:
function enqueue_custom_block_styles() {
wp_enqueue_style(
'custom-block-styles',
get_template_directory_uri() . '/css/custom-block-styles.css',
array(),
'1.0'
);
}
add_action('wp_enqueue_scripts', 'enqueue_custom_block_styles');
add_action('enqueue_block_editor_assets', 'enqueue_custom_block_styles');Ahora, en lugar de utilizar el estilo inline, puedes registrar el estilo sin incrustar el CSS directamente en PHP:
register_block_style(
'core/image',
array(
'name' => 'rounded',
'label' => __( 'Rounded', 'your-text-domain' ),
'style_handle' => 'custom-block-styles'
)
);De esta forma, puedes modificar los estilos sin tocar PHP.
Registrar variaciones de bloque
Las variaciones de bloque te permiten crear versiones predefinidas de un bloque con ajustes personalizados, facilitando a los usuarios la aplicación de diseños coherentes con un solo clic. En lugar de modificar manualmente la configuración de un bloque cada vez, una variación te permite insertar un bloque que ya tiene aplicados los atributos, estilos o configuraciones adecuados.
De hecho, algunos bloques del core de WordPress funcionan de este modo. El bloque Incrustar no es un bloque único, sino un conjunto de variaciones para diferentes plataformas como YouTube, Twitter y Spotify. El bloque Fila y el bloque Pila también son sólo variaciones del bloque Grupo, cada uno con diferentes configuraciones de diseño.
Este enfoque mantiene las cosas modulares, permitiendo a WordPress proporcionar experiencias a medida mientras utiliza una estructura subyacente compartida.
Crear una variación del bloque Cita para Testimonios
Aunque WordPress no tiene un bloque dedicado a los Testimonios, el bloque Cita (core/quote) puede adaptarse para servir a ese propósito. En lugar de hacer que los usuarios añadan manualmente una imagen, alineen el texto y le den formato a todo, podemos definir una variación del bloque de Cita para Testimonios.
Esta variación incluye automáticamente un bloque Imagen, un bloque Cita y dos bloques Párrafo para el nombre de la persona y la empresa. Esto garantiza que todos los testimonios sigan el mismo formato estructurado sin necesidad de ajustes adicionales.
Para registrar una variación de bloque en WordPress, utilizamos registerBlockVariation() en JavaScript. Dado que las variaciones de bloque se gestionan en el lado del cliente, necesitamos poner en cola un archivo JavaScript que registre nuestra variación personalizada para Testimonios.
Para ello, crea un archivo JavaScript (como custom-block-variations.js) que defina la variación Testimonio (Testimonial) del bloque Cita. Puedes crear este archivo en el directorio assets/js/ de tu tema y añadir el siguiente código:
wp.domReady(() => {
wp.blocks.registerBlockVariation(
'core/quote',
{
name: 'testimonial',
title: 'Testimonial',
description: 'A variation of the Quote block for testimonials.',
category: 'text',
attributes: {
className: 'is-style-testimonial',
},
innerBlocks: [
['core/image', { align: 'center', width: 100, height: 100 }],
['core/quote'],
['core/paragraph', { placeholder: 'Name', align: 'center', fontSize: 'medium', className: 'testimonial-name' }],
['core/paragraph', { placeholder: 'Company / Role', align: 'center', fontSize: 'small', className: 'testimonial-company' }]
],
scope: ['inserter'],
}
);
// Inject inline styles for the editor preview
const style = document.createElement('style');
style.innerHTML = `
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial p {
margin-bottom: 12px;
font-size: 1.1em;
}
.wp-block-quote.is-style-testimonial cite {
font-weight: bold;
display: block;
margin-top: 10px;
color: #0073aa;
}
.wp-block-quote.is-style-testimonial .wp-block-image {
display: flex;
justify-content: center;
margin: 0 auto 12px;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
`;
document.head.appendChild(style);
});En el código anterior, registerBlockVariation() define la variación Testimonio del bloque Cita, precargando un bloque Imagen, un bloque Cita y dos bloques Párrafo para el nombre de la persona y la empresa. El bloque Imagen se centra a 100×100 píxeles para uniformar las fotos de perfil, mientras que el bloque Cita permanece inalterado como texto del testimonio.
Se aplica una clase personalizada (is-style-testimonial) para el estilo, que da al bloque un fondo claro, una sombra sutil y el texto centrado. Se elimina el borde izquierdo por defecto, y la imagen mantiene su relación de aspecto con esquinas ligeramente redondeadas para un aspecto pulido.
A continuación, como el archivo JavaScript debe cargarse dentro del editor de bloques, debemos ponerlo en cola en functions.php.
function enqueue_custom_block_variations() {
wp_enqueue_script(
'custom-block-variations',
get_template_directory_uri() . '/assets/js/custom-block-variations.js',
array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
filemtime( get_template_directory() . '/assets/js/custom-block-variations.js' ),
true
);
}
add_action( 'enqueue_block_editor_assets', 'enqueue_custom_block_variations' );Esto garantiza que la variación del bloque Testimonio aparezca dentro del editor de bloques.
Mientras el código JavaScript garantiza que el bloque tenga un aspecto correcto en el editor, también tenemos que aplicar los estilos en el frontend para que los testimonios se muestren correctamente cuando se publiquen. Añade el siguiente código a functions.php:
function register_testimonial_block_style() {
register_block_style(
'core/quote',
array(
'name' => 'testimonial',
'label' => __( 'Testimonial', 'your-text-domain' ),
'inline_style' => '
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
',
)
);
}
add_action( 'init', 'register_testimonial_block_style' );Ahora, cada vez que un usuario inserte un bloque Testimonio, ya incluirá los campos de imagen, cita, nombre y empresa, todos ellos preformateados y con el estilo correcto. Esto elimina la necesidad de realizar ajustes manuales, garantizando que todos los testimonios sigan la misma estructura limpia y profesional.
En lugar de obligar a los usuarios a crear testimonios desde cero, esta variación de bloque proporciona un flujo de trabajo optimizado que mejora la creación de contenidos, al tiempo que mantiene la coherencia del diseño del sitio.
Caso de uso avanzado: Combinar las APIs de Soportes y Estilos para crear botones de marca
Ahora que sabes lo que puede hacer cada API y cómo funciona, ¿por qué no vamos un poco más allá? En lugar de utilizar la API de Soportes o la API de Estilos por separado, podemos utilizarlas juntas para resolver un único problema: mantener la coherencia del diseño y ofrecer a los usuarios una forma estructurada de aplicar los estilos adecuados.
Consideremos un escenario del mundo real. Una empresa quiere que todos los botones de su sitio sigan unas estrictas directrices de marca. No quieren que los usuarios elijan colores al azar, cambien el relleno o apliquen tipografías extravagantes. Sin embargo, quieren flexibilidad, por lo que los usuarios deben poder elegir entre dos estilos de botón preaprobados:
- Botón principal — El botón principal de llamada a la acción, con un fondo sólido y un estilo llamativo.
- Botón secundario — Un botón más sutil y perfilado que suele utilizarse para acciones secundarias.
Para conseguirlo, necesitamos
- Utilizar la API de Estilos para definir los dos estilos de botón.
- Utilizar la API de Soportes para eliminar los ajustes innecesarios, asegurándonos de que los usuarios no anulan manualmente la marca cambiando los colores, el espaciado o la tipografía.
Combinando ambas APIs, permitimos opciones estructuradas a la vez que evitamos que los usuarios rompan el sistema de diseño.
Paso 1: Definir estilos de botones personalizados
Empieza añadiendo el siguiente código al archivo functions.php:
function register_custom_button_styles() {
register_block_style(
'core/button',
array(
'name' => 'primary-button',
'label' => __( 'Primary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-primary-button .wp-block-button__link {
background-color: #4D4D4D;
color: #ffffff;
padding: 12px 24px;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: 2px 2px 6px rgba(0, 0, 0, 0.1);
}
',
)
);
register_block_style(
'core/button',
array(
'name' => 'secondary-button',
'label' => __( 'Secondary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-secondary-button .wp-block-button__link {
background-color: transparent;
color: #4D4D4D;
padding: 12px 24px;
border: 1px solid #4D4D4D;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: none;
}
',
)
);
}
add_action( 'init', 'register_custom_button_styles' );Ahora, cuando los usuarios inserten un bloque Botón, verán Botón principal y Botón secundario como opciones de estilo.
El botón primario tiene un fondo gris oscuro sólido, mientras que el botón secundario tiene un fondo transparente con un borde. Ambos botones tienen un relleno, un radio de borde y un estilo de fuente coherentes, lo que garantiza un aspecto profesional en todo el sitio.
Paso 2: Restringir la personalización de los botones
Aunque ahora los estilos de los botones están predefinidos, los usuarios aún pueden anularlos manualmente mediante la configuración del editor de bloques de WordPress. Si cambian los colores, el relleno o la tipografía, es posible que los botones ya no se ajusten a las directrices de la marca.
Podemos utilizar la API de Soportes para desactivar estas opciones de personalización, evitando que los usuarios realicen cambios involuntarios. Añade esto a functions.php:
function restrict_button_customization($args, $block_type) {
if ($block_type === 'core/button') {
// Disable specific color settings (text, background, link)
$args['supports']['color'] = [
'text' => false,
'background' => false,
'link' => false,
];
// Disable typography settings (font size, font weight, line height)
$args['supports']['typography'] = false;
// Disable spacing settings (padding, margin)
$args['supports']['spacing'] = false;
}
return $args;
}
add_filter('register_block_type_args', 'restrict_button_customization', 10, 2);Con esto establecido:
- Los usuarios no pueden cambiar los colores de los botones, por lo que todos ellos deben adherirse al esquema de colores de la marca.
- Se eliminan los controles de tipografía, manteniendo la coherencia del formato del texto.
- Se desactivan los ajustes de espaciado, impidiendo que los usuarios modifiquen el relleno y los márgenes.
Ahora, en lugar de dejar que los usuarios creen una mezcla aleatoria de estilos de botón, simplemente elegirán entre los estilos primario y secundario, manteniendo el diseño profesional y estructurado.
Resumen
Solo hemos arañado la superficie de lo que es posible con la personalización de bloques de WordPress. WordPress proporciona una amplia colección de APIs que facilitan la ampliación y personalización de bloques, lo que permite a los desarrolladores adaptar la experiencia del editor a la vez que mantienen las cosas estructuradas y fáciles de usar.
Si te tomas en serio dominar la personalización de bloques, hay mucho más que explorar. Consulta la documentación oficial para desarrolladores de WordPress, asiste a WordCamps y meetups, y sigue aprendiendo de grandes recursos como el blog de Kinsta, donde analizamos regularmente conceptos avanzados de WordPress.
Por supuesto, contar con un proveedor de alojamiento sólido hace que experimentar con estos cambios sea fácil. Tanto si estás probando nuevas modificaciones de bloques como si gestionas un sitio de mucho tráfico, un alojamiento fiable garantiza un rendimiento fluido y una fácil escalabilidad. En Kinsta, hemos construido nuestra plataforma para manejar exactamente eso. De hecho, recientemente hemos sido elegidos como el mejor Alojamiento para WordPress por G2, gracias a más de 930 reviews de clientes.
Esto habla por sí solo: Puedes confiar en nosotros para potenciar tu experiencia WordPress.
