APIs JavaScript del Personalizador: Panel, Sección, y Control

Spanish (Español) translation by Eva Collados Pascual (you can also view the original English article)

Hoy, vamos a resumir nuestro debate sobre la API JavaScript en el Personalizador de WordPress. En el último tutorial, preparamos y cargamos dos archivos JavaScript, customizer-control.js y customizer-preview.js, esto nos permitirá interactuar con la API JavaScript desde el back-end del Personalizador y desde el front-end de la interfaz del Previsualizador. Así que, asegúrate de seguir el último tutorial antes de seguir adelante.

En este tutorial, nos vamos a centrar en la interfaz componiendo el back-end del Personalizador, los Paneles, los Ajustes, y los Controles. Nuevamente, si todo esto es algo nuevo para ti, te recomiendo encarecidamente que leas nuestros tutoriales previos de esta serie: Una Guía del Personalidor de Tema en WordPress.

Interacciones Básicas Con la API JavaScript del Personalizador

Además de la API PHP, con la cual estoy seguro de que algunos de vosotros ya estáis familiarizados, los Paneles, Secciones, y Controles son también accesibles a través de la API JavaScript. Por tanto, también podemos modificarlos. Aquí tienes algunos ejemplos.

Selecciona un control concreto, sección, o panel:

// Select a Control.
wp.customize.control( 'blogname' );

// Select a Section.
wp.customize.section( 'title_tagline' );

// Select a Panel.
wp.customize.panel( 'nav_menus' );

Reorganiza su orden de visualización.

// Change a Control priority
wp.customize.control( 'blogname' ).priority( 30 );

// Change a Section priority
wp.customize.section( 'title_tagline' ).priority( 100 );

// Change a Panel priority
wp.customize.panel( 'nav_menus' ).priority( 200 );

Mueve el control del "Título del Sitio" ha, por ejemplo, la sección de color.

1	wp.customize.control( 'blogname' ).section( 'colors' );

Cambia su visibilidad.

1	// Deactivate / hide 'Site Title' control
2	wp.customize.control( 'blogname' ).toggle();

Puedes incluso analizar el control del árbol del DOM, el cual es algo que de otra forma sería enrevesado hacer con PHP.

1	wp.customize.control( 'blogname' ).container.find( '.customize-control-title' );

Estas son algunas de las cosas que podrías hacer con los Paneles, las Secciones, y Controles en la API JavaScript del Personalizador. Pongamos todo esto junto ahora en una forma más significativa desde la perspectiva de la experiencia del usuario.

Cambiar las Secciones y Controles

En este punto, deberíamos tener cuatro controles en total. Dos controles, el campo para el "Título del Sitio" y la casilla de verificación "Mostrar el Título del Sitio", están en la sección "Identidad del Sitio". Los otros dos son los selectores de color. Estos están ubicados en la sección "Colores", y establecerán el color para el texto "Título del Sitio" y el color de este mismo texto en su estado "hover".

Input Checkbox and Color picker in the Customizer pane — Nuestros cuatro controles en el Personalizador

Nuestro plan pues es mostrar los Controles del color sólo cuando la casilla "Mostrar el título del Sitio" esté activa, ya que no hay razón para mostrarlos cuando realmente el Título del Sitio está inactivo.

Además, este enfoque podría ayudarnos a limpiar el Personalizador eliminando Controles irrelevantes, Secciones, y Paneles de la columna del Personalizador. Esto suena algo que te gustaría lograr, vamos con ello.

Deshabilitar un Control de Campo de Entrada

Para empezar, abre nuestro archivo customizer-control.js. Después, añade las líneas de código en el evento ready del Personalizador:

wp.customize.bind( 'ready', function() { // Ready?

  var customize = this; // Customize object alias.
	customize( 'display_blogname', function( setting ) {

	} );
} );

Después hemos establecido un alias para la palabra clave this, la cual se refiere a la API JavaScript del Personalizador. Después, enganchamos una función anónima en los ajustes display_blogname ya que todas las modificaciones que vamos a hacer en el Personalizador serán relativas al valor de este ajuste en particular.

Siguiendo, seleccionamos el campo input del ajuste "Título del Sitio".

wp.customize.bind( 'ready', function() { // Ready?

	var customize = this; // WordPress customize object alias.
	customize( 'display_blogname', function( setting ) {
		var siteTitleInput = customize.control( 'blogname' ).container.find( 'input' ); // Site Title input.
	} );
} );

Podemos deshabilitar el campo cuando la casilla display_blogname esté desmarcada.

wp.customize.bind( 'ready', function() { // Ready?

	var customize = this; // Customize object alias.
	customize( 'display_blogname', function( value ) {

		var siteTitleInput = customize.control( 'blogname' ).container.find( 'input' ); // Site Title input.

		/**
		 * Disable the Input element
		 */
		// 1. On loading.
		siteTitleInput.prop( 'disabled', !value.get() ); // .get() value

		// 2. Binding to value change.
		value.bind( function( to ) {
			siteTitleInput.prop( 'disabled', !to );
		} );
	} );
} );

Como puedes ver arriba, hemos usado el método jQuery .prop() para establecer la propiedad HTML disabled al elemento input. Usamos el método .get() para extraer el valor actual. Finalmente, usando el método .bind(), escuchamos el cambio de valor y establecemos la propiedad disabled en correspondencia.

Disabled and Enabled input field in customizer — Izquierda: El campo de entrada "Título del Sitio" habilitado. Derecha: Campo de entrada "Título del Sitio" sin habilitar. Observa la casilla de verificación.

Cambiar la Visibilidad

Ahora hemos procedido con el código para cambiar la visibilidad de los selectores de color que establecen los colores del "Título del Sitio". Tal y como planeamos, eliminaremos los selectores de color cuando la casilla de verificación esté desmarcada y lo mostraremos de nuevo cuando lo esté.

Para empezar, agrupamos los IDs de los ajustes del selector de color juntos en un array.

wp.customize.bind( 'ready', function() { // Ready?
	var customize = this; // Customize object alias.
	customize( 'display_blogname', function( value ) {

		// ...previous codes...

		var colorControls = [
			'header_textcolor',
			'header_textcolor_hover'
		];
	} );
} );

Después, iteramos una función sobre los IDs de aquellos Controles que cambiarán su visibilidad usando el método jQuery .toggle().

wp.customize.bind( 'ready', function() { // Ready?
	var customize = this; // Customize object alias.
	customize( 'display_blogname', function( value ) {

		// ...previous codes...

		var colorControls = [
			'header_textcolor',
			'header_textcolor_hover'
		];

		$.each( colorControls, function( index, id ) {
			customize.control( id, function( control ) {
				/**
				 * Toggling function
				 */
				var toggle = function( to ) {
					control.toggle( to );
				};

				// 1. On loading.
				toggle( value.get() );

				// 2. On value change.
				value.bind( toggle );
			} );
		} );
	} );
} );

La estructura del código anterior es similar a nuestro código anterior, el cual deshabilita el elemento del campo entrada. Aquí hemos seleccionado cada control en la cadena usando el método .control() tal y como hemos mostrado anteriormente en este tutorial. Luego, tenemos una función para cambiar cada control usando el método jQuery .toggle(), y ejecutarlo cuando se inicia la página del Personalizador así como cuando el valor es modificado.

Site Title input field is disabled and two color pickers are hidden — Casilla de verificación sin marcar para la "Muestra del Título del Sitio", el campo de entrada del Título del Sitio está coloreado en gris (deshabilitado), y los selectores de color respectivos en la sección de Color están ocultos.

Qué Es Lo Próximo

En este tutorial, te he mostrado un sencillo ejemplo sobre cómo utilizar la API JavaScript del Personalizador para mejorar la experiencia del usuario en el Personalizador del Tema. Y existen algunas pocas cosas más que podemos hacer para mejorar aún más, como eliminar la sección "Colores" en caso de que no existiese ningún control en esta sección, y ajustar el tono de color del encabezado del ajuste "Color del Texto del Encabezado: Hover" siguiendo el valor del ajuste "Color del Texto del Encabezado".

En el próximo tutorial de esta serie, vamos a retarnos a nosotros mismos con un ejemplo un poco más complicado. Vamos a crear un "puente" que permitirá a la ventana de Previsualización del Personalizador interactuar con el panel de Control del back-end. De forma que, cuando un usuario haga clic sobre, por ejemplo, el Título del Sitio en la ventana del Previsualizador, el Personalizador se deslizará al usuario hasta el campo de entrada respectivo.

¡Manténte atento!