Guía del Personalizador de Temas de WordPress

Qué es el Personalizador de Temas de WordPress

El sistema de personalización de WordPress conocido como Personalizador de Temas es una herramienta integrada que permite personalizar visualmente la apariencia del sitio con una vista previa de los cambios en tiempo real. En lugar de modificar el código del tema o usar páginas de ajustes separadas, el Personalizador ofrece una interfaz unificada donde ves los efectos de cada cambio antes de guardarlo. Se accede a él desde Apariencia, Personalizar en el panel de administración. Si estás empezando, consulta nuestra guía para configurar WordPress. Si todavía no has instalado WordPress, consulta nuestra guía paso a paso de WordPress o accede añadiendo /wp-admin/customize.php a la URL de tu sitio.

El Personalizador se introdujo en WordPress 3.4 y se ha mejorado continuamente con cada nueva versión desde entonces. Utiliza AJAX para la comunicación con el servidor y JavaScript para la vista previa en tiempo real, ofreciendo una experiencia de usuario fluida sin recargas de página. Todos los temas del núcleo de WordPress y la mayoría de los temas de calidad usan el Personalizador para sus ajustes.

Anatomía del Personalizador

Paneles, secciones y controles

El Personalizador está organizado en una estructura jerárquica con tres niveles. Los paneles son la categoría más amplia y sirven para agrupar secciones relacionadas, por ejemplo un panel de Cabecera que contiene secciones para el logotipo, la navegación y la barra superior. Las secciones son grupos de controles relacionados, por ejemplo una sección de Colores que contiene controles para el fondo, el texto y los colores de los enlaces. Los controles son elementos de entrada individuales para ajustes como selectores de color, menús desplegables, campos de texto y controles de subida de imágenes.

Ajustes y transporte

Cada control está vinculado a un ajuste (Setting) que define dónde se almacena el valor y cómo se aplica. Un ajuste puede almacenar su valor en la base de datos como theme_mod u option. El parámetro Transport determina cómo se aplican los cambios: refresh recarga el marco de vista previa en cada cambio, mientras que postMessage usa JavaScript para una aplicación instantánea sin recarga. PostMessage es considerablemente más rápido y ofrece una mejor experiencia de usuario, pero requiere código JavaScript adicional para cada control.

Registrar secciones y controles

Añadir una sección

Las secciones se registran en functions.php usando el hook customize_register. Llamas al método add_section de $wp_customize con un ID único y un array de parámetros que incluye title para el nombre de la sección, description para el texto mostrado en la parte superior de la sección, priority para el orden de visualización donde los números más bajos significan una posición más alta, y panel si quieres colocar la sección dentro de un panel. Un ejemplo es crear una sección de ajustes de cabecera con el título Ajustes de Cabecera, una descripción de la función y prioridad 30.

Añadir ajustes y controles

Para cada ajuste, primero registra el ajuste con el método add_setting donde especificas el valor por defecto, el tipo de transporte y la función sanitize_callback para la validación de la entrada. Después añade un control con el método add_control que define el tipo de control, la etiqueta, la sección a la que pertenece y la prioridad. WordPress ofrece tipos de control integrados como text para campos de texto, textarea para texto de varias líneas, checkbox para casillas de confirmación, radio para botones de opción, select para menús desplegables, dropdown-pages para la selección de páginas y number para campos numéricos.

Controles avanzados

WordPress dispone de controles avanzados integrados para tipos de datos específicos. WP_Customize_Color_Control muestra un selector de color con valor hexadecimal, WP_Customize_Image_Control permite subir o seleccionar una imagen de la biblioteca de medios, WP_Customize_Cropped_Image_Control añade la posibilidad de recortar imágenes a las dimensiones deseadas, y WP_Customize_Media_Control es un control universal para cualquier tipo de medio. Para usar estos controles, instánciales directamente en lugar de llamar a add_control con un tipo, porque son clases PHP con parámetros específicos.

Vista previa en vivo con postMessage

El lado de PHP

Para habilitar la vista previa en vivo sin recarga, establece el parámetro transport en postMessage en la llamada a add_setting. Esto indica al Personalizador que use JavaScript para aplicar los cambios en lugar de recargar toda la página. En el código de salida del tema, usa la función get_theme_mod para leer el valor guardado y aplicarlo al elemento correspondiente mediante CSS en línea o una clase.

El lado de JavaScript

Crea un archivo JavaScript que se cargue solo en la vista previa del Personalizador usando el hook customize_preview_init para encolar el script. En el script, usa la API wp.customize para escuchar los cambios de los ajustes y aplicarlos a los elementos de la vista previa. Para cambiar un color, por ejemplo, escuchas los cambios del ajuste header_bg_color y actualizas la propiedad CSS del elemento correspondiente. Para cambiar el texto, modificas el innerHTML del elemento. PostMessage proporciona retroalimentación visual instantánea sin demora, lo que mejora notablemente la experiencia de usuario.

Selective Refresh

Selective Refresh es un enfoque híbrido introducido en WordPress 4.5 que actualiza solo una parte de la página en lugar de la página entera. Registras un partial con el método add_partial donde especificas un selector (el selector CSS del elemento a actualizar) y una función PHP render_callback que genera el nuevo HTML para ese elemento. Esto es ideal para elementos complejos cuya apariencia depende de múltiples ajustes, porque es más sencillo que escribir JavaScript para cada combinación posible de cambios y más rápido que una recarga completa de la página.

Validación y saneamiento

Sanitize callback

Todo ajuste debe tener una función sanitize_callback que limpie y valide la entrada del usuario antes de guardarla en la base de datos. WordPress ofrece funciones integradas para los casos habituales, como sanitize_text_field para campos de texto, sanitize_email para direcciones de correo electrónico, sanitize_hex_color para colores hexadecimales, absint para enteros positivos, esc_url_raw para URLs y wp_kses_post para contenido HTML con etiquetas permitidas. Nunca almacenes la entrada del usuario sin saneamiento, porque eso expone el sitio a ataques XSS y de otro tipo.

Validate callback

Desde WordPress 4.6 existe validate_callback, que puede devolver un objeto WP_Error con un mensaje de error mostrado al usuario en la interfaz del Personalizador. A diferencia de sanitize_callback, que corrige silenciosamente los valores no válidos, validate_callback notifica explícitamente al usuario que la entrada no es válida. Por ejemplo, puedes validar que una URL sea válida, que un número esté dentro del rango permitido o que el texto no supere la longitud máxima, y mostrar un mensaje de error adecuado.

Paneles y controles personalizados

Crear un control personalizado

Para necesidades que los controles integrados no cubren, puedes crear un control personalizado extendiendo la clase WP_Customize_Control. Sobrescribes el método render_content para definir el HTML del control y el método enqueue para incluir el CSS y JavaScript específicos del control. Ejemplos de controles personalizados son un control deslizante de rango con visualización del valor actual, un interruptor de palanca en lugar de una casilla de verificación, un selector de Google Fonts con vista previa de la fuente, un control de ordenación de elementos por arrastrar y soltar, y un control de configuración del diseño con visualización visual de las opciones.

Crear un panel

Los paneles se registran con el método add_panel y son útiles para organizar muchas secciones en grupos lógicos. Un tema con muchos ajustes podría tener paneles para cabecera, pie de página, blog, colores, tipografía y diseño. Cada panel contiene varias secciones, y cada sección varios controles. No exageres la profundidad de la jerarquía, porque a los usuarios no les gusta navegar por muchos niveles para llegar a un ajuste concreto.

Ajustes condicionales

El parámetro active_callback en secciones y controles permite mostrar controles solo cuando se cumplen ciertas condiciones. Por ejemplo, el control del color de la cabecera se muestra solo si la opción de mostrar cabecera está activada, los ajustes del blog se muestran solo en la página del blog en la vista previa, y las opciones del slider se muestran solo en la página de inicio. Esto hace que la interfaz sea más limpia y menos confusa, porque los usuarios solo ven los ajustes relevantes para el contexto actual.

Integración con los temas de bloques

Con la introducción de la Edición Completa del Sitio en WordPress 5.9, el Personalizador obtuvo una alternativa en forma del Editor del Sitio. Los temas de bloques usan un archivo theme.json para definir los ajustes en lugar de la API del Personalizador. Sin embargo, los temas clásicos y los temas híbridos siguen usando activamente el Personalizador, que continúa siendo una parte importante del ecosistema de WordPress. Si estás desarrollando un tema clásico, el Personalizador sigue siendo la forma recomendada de implementar los ajustes del tema con vista previa en vivo.

Buenas prácticas

• Usa el transporte postMessage siempre que sea posible para una vista previa instantánea de los cambios
• Implementa siempre sanitize_callback para cada ajuste sin excepción
• Organiza los ajustes de forma lógica en secciones y paneles para facilitar la navegación
• Usa valores por defecto sensatos para que el sitio se vea bien sin ninguna personalización
• Añade descripciones a las secciones y controles para que los usuarios comprendan qué hace cada ajuste
• Prueba la vista previa en vivo en distintas páginas, porque el comportamiento puede variar
• Usa active_callback para mostrar los controles solo cuando sean relevantes
• No añadas demasiados ajustes, porque confunde a los usuarios y complica el mantenimiento

Conclusión

El Personalizador de Temas de WordPress es una herramienta potente para crear una interfaz intuitiva de personalización del tema con vista previa en vivo. La jerarquía de paneles, secciones y controles permite una visualización organizada de los ajustes, el transporte postMessage proporciona retroalimentación visual instantánea, y el saneamiento y la validación garantizan la seguridad de los datos. En el hosting para WordPress optimizado, todas las funciones del Personalizador están soportadas con un servidor optimizado para una aplicación rápida de los cambios y un funcionamiento fiable del sitio.