Contents
Introducción
Este artículo explica con todo lujo de detalles cómo previsualizar cambios del WordPress Customizer usando postMessage en JavaScript. Incluye ejemplos completos (PHP, JS y CSS) que puedes copiar y adaptar a tu tema. Cubriremos la diferencia entre refresh y postMessage, cómo declarar las opciones, cómo enlazar el script de vista previa, y patrones prácticos para actualizar texto, colores e imágenes en tiempo real sin recargar la página.
Conceptos clave
- Transport: Cada setting del Customizer puede usar transport => refresh (recarga la vista previa) o transport => postMessage (envía cambios por mensaje y permite manipular el DOM con JS).
- WP Customizer JS API: En la vista previa puedes usar wp.customize( setting_id, function(value) { value.bind(function(newVal) { … }) }) para recibir cambios en tiempo real.
- Selective Refresh: mecanismo complementario que actualiza sólo partes del DOM vía Ajax, útil cuando el DOM es complejo en este artículo nos centraremos en postMessage puro y daremos una nota sobre selective refresh.
Ventajas de usar postMessage
- Experiencia de usuario más fluida: cambios en vivo sin recargas completas.
- Menos costes en servidor y menos flicker visual.
- Permite animaciones y transiciones suaves aplicadas desde JS.
Flujo general
- Registrar o modificar el setting para que use transport = postMessage (en PHP).
- Encolar un script JS que se cargue solo en la vista previa del Customizer (hook customize_preview_init).
- En el script JS usar la API wp.customize para detectar cambios y actualizar el DOM en tiempo real.
Ejemplo práctico 1 — Título del sitio (blogname) en vivo
Mostramos cómo cambiar la configuración estándar blogname para que se actualice en directo sin recargar.
1) PHP — activar transport a postMessage y encolar script
Coloca este código en functions.php o en un archivo cargado por el tema.
get_setting( blogname ) ) ) {
wp_customize->get_setting( blogname )->transport = postMessage
}
if ( isset( wp_customize->get_setting( blogdescription ) ) ) {
wp_customize->get_setting( blogdescription )->transport = postMessage
}
// Ejemplo de setting personalizado (si quieres añadir uno nuevo)
wp_customize->add_setting( tema_texto_header, array(
default => Texto del header,
sanitize_callback => sanitize_text_field,
transport => postMessage,
) )
wp_customize->add_control( tema_texto_header, array(
label => __( Texto del header, tema ),
section => title_tagline,
type => text,
) )
}
add_action( customize_register, tema_customizer_register )
function tema_customizer_live_preview() {
// Encolar script para la vista previa del Customizer
wp_enqueue_script(
tema-customizer,
get_template_directory_uri() . /assets/js/customizer.js,
array( jquery, customize-preview ),
null,
true
)
}
add_action( customize_preview_init, tema_customizer_live_preview )
?>
2) JavaScript — detectar cambios y actualizar DOM
Archivo: assets/js/customizer.js
( function( ) {
// blogname
wp.customize( blogname, function( value ) {
value.bind( function( newval ) {
// Selector según tu tema
( .site-title a ).text( newval )
} )
} )
// blogdescription
wp.customize( blogdescription, function( value ) {
value.bind( function( newval ) {
( .site-description ).text( newval )
} )
} )
// setting personalizado tema_texto_header
wp.customize( tema_texto_header, function( value ) {
value.bind( function( newval ) {
( .header-text ).text( newval )
} )
} )
} )( jQuery )
Ejemplo práctico 2 — Cambiar color en vivo (CSS dinámico)
Para atributos CSS (por ejemplo color de enlaces), lo más cómodo es actualizar dinámicamente un bloque de estilos en la cabecera o aplicar estilos inline.
1) PHP — registrar setting y control de color
add_setting( tema_link_color, array(
default => #0073aa,
sanitize_callback => sanitize_hex_color,
transport => postMessage,
) )
wp_customize->add_control( new WP_Customize_Color_Control( wp_customize, tema_link_color_control, array(
label => __( Color enlaces, tema ),
section => colors,
settings => tema_link_color,
) ) )
}
add_action( customize_register, tema_color_customizer )
?>
2) JS — actualizar un style tag existente o crearlo
( function( ) {
var styleId = tema-custom-style
function ensureStyleTag() {
var tag = ( # styleId )
if ( tag.length === 0 ) {
tag = ( ltstyle id= styleId gtlt/stylegt ).appendTo( head )
}
return tag
}
wp.customize( tema_link_color, function( value ) {
value.bind( function( newval ) {
var css = .site a, .entry a { color: newval }
ensureStyleTag().text( css )
} )
} )
} )( jQuery )
Ejemplo práctico 3 — Imagen (logo o background) en vivo
Para imágenes, el setting normalmente devuelve la URL. Simplemente actualizas src o background-image.
1) PHP — setting con control de imagen
add_setting( tema_logo, array(
default => ,
sanitize_callback => esc_url_raw,
transport => postMessage,
) )
wp_customize->add_control( new WP_Customize_Image_Control( wp_customize, tema_logo_control, array(
label => __( Logo, tema ),
section => title_tagline,
settings => tema_logo,
) ) )
}
add_action( customize_register, tema_logo_customizer )
?>
2) JS — actualizar imagen en tiempo real
( function( ) {
wp.customize( tema_logo, function( value ) {
value.bind( function( newval ) {
if ( newval ) {
( .site-logo img ).attr( src, newval )
} else {
// Opcional: volver a un placeholder si newval es vacío
( .site-logo img ).attr( src, /wp-content/themes/tema/assets/img/placeholder.png )
}
} )
} )
} )( jQuery )
Nota sobre Selective Refresh
Selective Refresh es un mecanismo intermedio: más robusto que postMessage para cambios complejos del servidor, y más ligero que recargar todo. Si el gráfico o estructura HTML no se puede actualizar solo con JS (porque requiere renderizado PHP), añade un partial. Ejemplo rápido en PHP:
selective_refresh ) ) {
wp_customize->selective_refresh->add_partial( blogname, array(
selector => .site-title a,
render_callback => function() {
bloginfo( name )
},
) )
}
}
add_action( customize_register, tema_selective_refresh )
?>
Buenas prácticas y consejos
- Sanitiza siempre (sanitize_callback) en settings aunque postMessage no entra en el servidor, el valor final almacenado debe ser seguro.
- Usa selectores específicos en JS para evitar colisiones con plugins.
- Mantén el script de customizer ligero y dependiente de customize-preview.
- Comprueba la compatibilidad con navegadores: postMessage aquí es interno de WP y la API es compatible con versiones recientes de WP.
- Para estilos complejos, generar un ltstylegt en head y actualizarlo es más eficiente que aplicar estilos inline a muchos elementos.
- Si el DOM que quieres actualizar se genera por PHP en la plantilla (ej. elementos estructurados por servidor), valora usar selective_refresh en lugar de postMessage.
Problemas comunes y soluciones
- El cambio no se refleja: Asegúrate de que el setting tenga transport => postMessage y que el script esté encolado con el handle customize-preview como dependencia.
- Selector no encontrado: Revisa que el selector usado en JS existe en la página de vista previa (a veces la estructura difiere entre plantilla y preview).
- Cambios correctos en panel pero no en vista previa: Confirma que el script se carga en la vista previa (usa inspector network o console).
- Valores con formato inesperado: Verifica el valor que emite el control (por ejemplo, algunos controles devuelven el ID en vez de la URL). Usa console.log en el bind para inspeccionar.
Resumen final
Usar postMessage junto a la API wp.customize es la forma recomendada para ofrecer previsualización instantánea en el Customizer cuando los cambios pueden aplicarse manipulando el DOM o estilos desde JavaScript. Para cambios que requieren renderizado del servidor, utiliza selective refresh. Sigue las buenas prácticas de saneamiento, selectores concretos y encolado correcto del script.
Recursos útiles
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |