Cómo integrar SmoothState.js en un tema WordPress

() translation by (you can also view the original English article)

En nuestro anterior tutorial, utilizamos la History Web API en un sitio estático para producir suaves transiciones de página. En este tutorial vamos a pasar al siguiente nivel, aplicando lo que aprendimos en un sitio web creado con WordPress. Habrá una diferencia crucial; voy aprovechar SmoothState.js en lugar de construir el nuestro desde cero.

Lo que hará SmoothState.js:

Solicitará páginas de forma asincrónica (AJAX) y sustituirá el actual contenido debidamente.
Actualizará las URLs y el historial de navegación mediante la History Web API.

Elegimos SmoothState.js por varias razones:

Facilidad de uso: es un plugin jQuery extremadamente fácil de usar, que apenas requiere configuración para ponerlo en funcionamiento.
APIs: SmoothState.js viene con métodos, propiedades y ganchos que nos permiten moldearlo para adaptarlo a muchas posibles situaciones.
Extrae y almacena en caché: estas dos características permiten que nuestras transiciones de página sean mucho más suaves y rápidas que lo que habíamos creado en el anterior tutorial.
No condiciona: SmoothState.js no dicta cómo tenemos que aplicar la animación: podemos apoyarnos en CSS, en jQuery, en Vanilla JavaScript o en una librería de animación como Velocity.js.
Probado y testeado: Teniendo en cuenta que se han cerrado más de un centenar de problemas durante su desarrollo, podemos suponer que ya han sido abordados y resueltos numerosos errores.

Requisitos previos

Hay un par de cosas que necesitarás tener preparadas para seguir este tutorial:

WordPress: debes tener un sitio WordPress en ejecución, ya sea de forma local en tu ordenador, o en vivo en un servidor online. Si necesitas ayuda en este paso, consulta Cómo empezar con WordPress de Tom McFarlin para ponerte en marcha e iniciar un sitio WordPress básico.
Un tema: Durante este tutorial vamos a utilizar el último tema predeterminado de WordPress: TwentySixteen. Puedes elegir cualquier otro tema, pero asegúrate de que cumple con los estándares de WordPress.

1. Crear un tema hijo

Usar un "tema hijo" en WordPress (en lugar de trabajar directamente con los archivos originales del tema) nos permite introducir nueva funcionalidad, o anular la predeterminada de forma segura.

Esta es la práctica recomendada siempre que se personaliza un tema, ya que en caso de actualizar el tema principal, cualquier cambio que hayas realizado se conservaría.

En nuestro caso, el tema principal es TwentySixteen. El tema hijo está ubicado en una nueva carpeta "twentysixteen-child" que contiene un archivo "functions.php" y una hoja de estilo "style.css", como puedes ver a continuación.

1	.
2	├── twentysixteen
3	└── twentysixteen-child

La parte más importante de un tema hijo es la notación Template en el encabezado de la hoja de estilos que señala su relación con el tema padre. Especifica en Template el nombre del directorio del tema padre, en nuestro caso twentysixteen

/**
Theme Name: Twenty Sixteen Child
Theme URI: https://webdesign.tutsplus.com
Author: Thoriq Firdaus
Author URI: https://tutsplus.com/authors/tfirdaus
Description: A child theme that adds an extra layer of glam to TwentySixteen
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: twentysixteen

Template: twentysixteen
*/

Una vez hecho esto, activa el tema hijo a través del escritorio de administración de WordPress:

WordPress List of Theme Interface in the Dashboard — El tema hijo TwentySixteen está activado, es posible que desees añadir también una "capturadepantalla.png"

2. Pon en cola los archivos JavaScript

Necesitamos cargar una serie de archivos JavaScript en nuestro tema WordPress. En principio podríamos hacerlo agregando estos JavaScript directamente en la etiqueta head del archivo "header.php" del tema. Sin embargo, siguiendo el estándar de WordPress, es recomendable utilizar la función wp_enqueue_script(), y añadirla en functions.php, para evitar conflictos:

1	wp_enqueue_script( 'smoothstate-js', 'assets/js/smoothstate.js', array( 'jquery' ), '0.5.2' );
2	wp_enqueue_script( 'script-js', 'assets/js/script.js', array( 'jquery', 'smoothstate-js' ), '1.0.0' );

La función también nos permite establecer las dependencias del script. En nuestro caso, "smoothstate.js" depende de jQuery, por lo tanto WordPress cargará jQuery antes de cargar "smoothstate.js".

Nuestro archivo "script.js" depende de ambos scripts, por lo que la secuencia de carga de todos nuestros scripts es la siguiente:

<script type='text/javascript' src='wp-includes/js/jquery/jquery.js'></script>

<script type='text/javascript' src='assets/js/smoothstate.js'></script>

<script type='text/javascript' src='assets/js/script.js'></script>

Echa un vistazo a los siguientes tutoriales para obtener más información sobre cómo poner en cola archivos en WordPress:

3. Implementar SmoothState.js

Vamos a añadir el siguiente código a nuestro "script.js", para poner SmoothState.js en funcionamiento:

( function( $ ) {

	$( function() { // Ready

		var settings = { 
			anchors: 'a'
		};

		$( '#page' ).smoothState( settings );
	} );

})( jQuery );

En el código anterior, seleccionamos #page (el elemento que envolverá el contenido de página del sitio) e implementamos SmoothState.js con su configuración más básica.

Nuestras páginas deben ser servidas sin actualizar por completo la ventana del navegador conforme navegamos a través de nuestro sitio WordPress. Ahora nuestras páginas se sirven de forma asincrónica.

Asynchronoous page loading in action — Perdóname por el poco inspirador falso contenido.

Básicamente, ¡ya lo tenemos listo! Sin embargo, todavía quedan algunos detalles dignos de nuestra atención:

Hay algunas URLs que no deberían cargarse de forma asincrónica, como el enlace dentro de #page que apunta al administrador de WordPress, wp-admin o wp-login.php.
Los vínculos con una almohadilla, por ejemplo #respond, no saltan a las secciones correspondientes de la página.
La carga de nuestra página es muy rápida. Pero todavía no da la sensación de suavidad porque no hemos aplicado ninguna animación para vehicular la transición.

4. Enlaces del escritorio de WordPress

Hay algunos enlaces en la página que apuntan al área de administración de WordPress, como el enlace Editar en cada publicación, el enlace Conectado como administrador y el enlace ¿quieres salir? situados antes del formulario de comentario.

The WordPress post edit link in the front-end — El enlace "Editar" en TwentySixteen aparece cuando hemos iniciado sesión.

Uno de los problemas cuando SmoothState.js solicita el escritorio es que no podremos volver a la página anterior cuando hagamos clic en el botón Retroceder del navegador. Este problema se produce porque el script SmoothState.js no está presente en el área de administración para poder solicitar y servir la página anterior.

WordPress Dashboard — No podemos volver a la página anterior después de visitar el escritorio de WordPress.

Tendremos que evitar que SmoothState.js solicite cualquier URL que apunte a wp-admin o wp-login. Para ello podemos utilizar el parámetro blacklist, de la siguiente manera:

( function( $ ) {
	$( function() { // Ready
		var settings = { 
			anchors: 'a'
			blacklist: '.wp-link'
		};
		$( '#page' ).smoothState( settings );
	} );
})( jQuery );

El parámetro blacklist le indica a SmoothState.js que ignore los vínculos con el selector de clase especificado; y dado el fragmento de código anterior, ignorará los enlaces con la clase wp-link. Este nombre de clase actualmente no existe, así que crearemos una nueva clase y la agregaremos dinámicamente a los vínculos necesarios:

function addBlacklistClass() {
	$( 'a' ).each( function() {
		if ( this.href.indexOf('/wp-admin/') !== -1 || 
			 this.href.indexOf('/wp-login.php') !== -1 ) {
			$( this ).addClass( 'wp-link' );
		}
	});
}

Esta función evalúa cada etiqueta de ancla en la página y, a continuación, añade la clase wp-link si la URL del enlace incluye /wp-admin/ o /wp-login.php.

Ejecutamos esta función dos veces para añadir eficazmente la clase a la página. En primer lugar, en la carga inicial de la página. La segunda tiene lugar después de que SmoothState.js haya servido la nueva página a través de onAfter; un método que se ejecutará cada vez que el nuevo contenido y la animación hayan sido servidos por completo.

function addBlacklistClass() {
	$( 'a' ).each( function() {
		if ( this.href.indexOf('/wp-admin/') !== -1 || 
			 this.href.indexOf('/wp-login.php') !== -1 ) {
			$( this ).addClass( 'wp-link' );
		}
	});
}

$( function() {

	addBlacklistClass();

	var settings = { 
		anchors: 'a',
		blacklist: '.wp-link',
		onAfter: function() {
			addBlacklistClass();
		}
	};

	$( '#page' ).smoothState( settings );
} );

5. Gestionar la almohadilla de enlace

A continuación, tenemos que gestionar los enlaces con una almohadilla al final. En un tema de WordPress, normalmente encontraremos un enlace que nos dirija a la sección de comentarios de una entrada o página.

'Deja un comentario' apunta a la sección de comentarios de la entrada.

Tal como están las cosas, descubrirás que el enlace no nos llevará a la sección de comentarios porque la página ni se carga ni se actualiza realmente. Por lo tanto, necesitamos replicar el comportamiento habitual esperado.

( function( $ ) {
	...
	$( function() {
		...
			onAfter: function() {
				...
				var $hash = $( window.location.hash );

				if ( $hash.length !== 0 ) {

					var offsetTop = $hash.offset().top;

					$( 'body, html' ).animate( {
							scrollTop: ( offsetTop - 60 ),
						}, {
							duration: 280
					} );
				}
			}
		};
	} );
})( jQuery );

Como puedes ver en el fragmento de código anterior, hemos añadido algunas líneas de código bajo el método onAfter. El código recupera la almohadilla de la URL y, a continuación, se desplaza a la sección correspondiente (si está presente en la página) mediante jQuery Animation.

Leave a Comment link scroll in action — Desplázate suavemente hasta la sección Comentarios de la entrada

6. Aplicar la animación de página

Necesitamos hacer que la transición de la página se perciba de forma más vívida. En primer lugar, añadiremos los estilos CSS para animar la página en el archivo "style.css" de nuestro tema hijo de la siguiente manera.

.site-content {
	-webkit-transition: -webkit-transform .28s, opacity .28s;
	-ms-transition: -o-transform .28s, opacity .28s;
	-o-transition: -o-transform .28s, opacity .28s;
	transition: transform .28s, opacity .28s;
}
.slide-out .site-content {
	-webkit-transform: translate3d( 0, 100px, 0 );
	-ms-transform: translate3d( 0, 100px, 0 );
	-o-transform: translate3d( 0, 100px, 0 );
	transform: translate3d( 0, 100px, 0 );
	opacity: 0;
}

.site-content es el nombre de clase que envuelve la entrada principal o el contenido de la página, mientras que .slide-out es una clase adicional que hemos creado para deslizar el contenido.

( function( $ ) {
	...
	$( function() {
		...
		var settings = { 
			...
			onStart: {
				duration: 280, // ms
				render: function ( $container ) {
					$container.addClass( 'slide-out' );
				}
			},
			onAfter: function( $container ) {
				...
				$container.removeClass( 'slide-out' );
			}
		};

		$( '#page' ).smoothState( settings );
	} );

})( jQuery );

Dado el código anterior, utilizamos el método onStart para añadir la clase cuando SmoothState.js comience a extraer nuevo contenido. A continuación, a través de onAfter, quitamos la clase después de que el nuevo contenido haya sido entregado.

¡Y eso es todo! Aún así, hay algo a tener en cuenta con respecto a la compatibilidad con algunos plugins de WordPress.

¿Qué viene después?

Hay disponibles más de 40.000 plugins de WordPress, y eso sin incluir los plugins alojados fuera del repositorio oficial, como CodeCanyon por ejemplo. Hay muchos plugins por ahí que podrían no ser compatibles, e incluso romper, nuestra carga asincrónica, particularmente los que dependen de scripting en cualquier medida.

La siguiente lista es mi estimación aproximada de algunos plugins que posiblemente debas examinar si los utilizas junto a SmoothState.js:

WordPress.com Stat (un módulo Jetpack)
Carousel (un módulo de Jetpack)
Infinite Scroll (un módulo de Jetpack)
Google Analytics for WordPress
Disqus
Lazy Load

Además, JavaScript se utiliza en gran medida en el Personalizador dentro del escritorio de WordPress. Por lo tanto, podrías plantearte no cargar SmoothState.js en el personalizador, en caso de que algo se rompa.

Conclusión

Hemos aprendido a integrar SmoothState.js en WordPress, así como a utilizar un tema hijo como estrategia de desarrollo. ¡Y esto es sólo un comienzo! Podríamos, por ejemplo, extender lo que hemos hecho por medio de un plugin que cuente con opciones de configuración en donde el usuario medio pueda personalizar fácilmente la salida.

Inspiración

Si estás buscando inspiración, echa un vistazo a estos temas multipropósito de WordPress disponibles en Envato Market que utilizan técnicas AJAX similares para la carga de página: