Implementar bloques personalizados con campos ACF

Contents

Implementar bloques personalizados con campos ACF

Los bloques personalizados en Gutenberg han revolucionado la forma de construir contenidos en WordPress. Al combinar la potencia de los Advanced Custom Fields (ACF) con la flexibilidad de la API de bloques, podemos ofrecer interfaces de edición amigables y adaptadas a cada necesidad. En este artículo detallado cubriremos desde los requisitos previos hasta un ejemplo completo, con las mejores prácticas y recursos fiables.

1. Ventajas de usar ACF para bloques

Productividad: menos código JavaScript, más definición en PHP.
Consistencia: campos ACF reutilizables en distintos bloques.
Interfaz amigable: editores intuitivos sin tocar React.
Mantención: API estable y centrada en PHP.

2. Requisitos previos

WordPress 5.8 (o superior) con Gutenberg activo.
Plugin ACF Pro (v5.8 en adelante) instalado y activo.
Conocimientos básicos de PHP, HTML y CSS.
Un tema hijo o plugin propio donde alojar el código del bloque.

3. Estructura de un bloque ACF

Un bloque basado en ACF se compone de dos elementos clave:

Elemento	Descripción
acf_register_block_type()	Función PHP para registrar el bloque y asociar campos ACF.
Grupo de campos ACF	Definición de los campos en el backend de ACF.

4. Registro del bloque en PHP

En el archivo functions.php de tu tema o en un plugin personalizado, añade el siguiente código:


add_action(acf/init, function() {
    if( function_exists(acf_register_block_type) ) {
        acf_register_block_type(array(
            name              =gt mi-bloque-personalizado,
            title             =gt Mi Bloque Personalizado,
            description       =gt Un bloque ejemplo con ACF.,
            render_template   =gt get_template_directory() . /template-parts/blocks/mi-bloque.php,
            category          =gt formatting,
            icon              =gt admin-comments,
            keywords          =gt array(ejemplo, acf, bloque),
            mode              =gt preview,
            supports          =gt array(align => array(wide, full)),
        ))
    }
})

5. Definición de campos ACF

En el administrador de WordPress, ve a Campos personalizados gt Grupos de campos gt Añadir nuevo y crea un grupo asociado al bloque “mi-bloque-personalizado”. Algunos ejemplos de campos:

Título: tipo Texto
Imagen destacada: tipo Imagen
Descripción: tipo Área de texto

En las Reglas de ubicación, selecciona Bloque ≡ Mi Bloque Personalizado.

6. Plantilla de renderizado (PHP)

Crea template-parts/blocks/mi-bloque.php y usa las funciones ACF para extraer los valores:


ltphp
// Obtener valores ACF
titulo      = get_field(titulo)
imagen      = get_field(imagen_destacada)
descripcion = get_field(descripcion)
>

ltdiv class=mi-bloque-container style=border:1px solid #ddd padding:20px margin-bottom:20px border-radius:4pxgt
  lth4 style=margin-top:0 font-size:1.4em color:#222gtltphp echo esc_html(titulo) gtlt/h4gt
  ltphp if( imagen ): gt
    ltimg src=ltphp echo esc_url(imagen[url]) gt alt=ltphp echo esc_attr(imagen[alt]) gt style=max-width:100% height:auto border-radius:2px/gt
  ltphp endif gt
  ltp style=margin-top:10px color:#555gtltphp echo esc_html(descripcion) gtlt/pgt
lt/divgt

7. Personalización de estilos

Para estilos específicos en el editor, registra un archivo CSS de editor:


function mi_bloque_assets() {
    wp_enqueue_style(
        mi-bloque-editor-style,
        get_template_directory_uri() . /template-parts/blocks/editor.css,
        array( wp-edit-blocks ),
        1.0.0
    )
}
add_action(enqueue_block_editor_assets, mi_bloque_assets)

En editor.css podrías poner:


.mi-bloque-container {
  border-color: #ccc
  background: #fafafa
}

8. Ejemplo completo

La estructura de archivos recomendada:

functions.php (registro del bloque)
template-parts/blocks/mi-bloque.php (plantilla PHP)
template-parts/blocks/editor.css (estilos en editor)

Tras activar todo, al editar una entrada verás “Mi Bloque Personalizado” con los campos configurados.

9. Mejores prácticas y consejos

Escapar siempre las salidas con esc_html, esc_url, etc.
Usar transientes o PHP caching si las consultas ACF son pesadas.
Definir block.json para importación automática si prefieres centrar la configuración en JSON.
Separar lógica y presentación en funciones reutilizables.

10. Recursos y enlaces fiables

Con esta guía completa ya cuentas con el conocimiento para implementar bloques personalizados enriquecidos con campos ACF. La combinación de PHP y la interfaz visual de ACF acelera el desarrollo, reduce errores y brinda a los editores una experiencia sólida y consistente.

Acepto donaciones de BAT's mediante el navegador Brave 🙂

Implementar bloques personalizados con campos ACF