IntroJS, mejorando las guías de usuario

• 1. Introducción.
• 2. Entorno.
• 3. Usando metadatos.
• 4. Configuración dinámica.
• 5. Referencias.
• 6. Conclusiones.

Al entregrar cualquier producto de software, por muy intuitiva que sea su interfaz, lo normal es que el usuario
solicite una guía de ayuda para el uso del mismo.

Tenemos muchas opciones para generar e incorporar una guía de usuario, pero tratándose de aplicaciones web lo
más recurrido es generar un PDF con la guía y capturas de pantalla de la interfaz explicando su funcionalidad.
También podríamos implementar la guía de usuario con la misma tecnología con la que esté desarrollada la aplicación web
en una sección ad hoc, pero para explicar su funcionalidad tendríamos que recurrir de nuevo a capturas de pantalla.

Por definición, lo que más cambia es la interfaz de usuario puesto que cualquier requisito adicional que
se solicite es muy probable que requiera añadir algún componente extra a la misma, con lo que esas capturas
de pantalla se quedarán obsoletas muy fácilmente.

Con librerías como IntroJS podemos integrar las ayudas al usuario dentro de la propia página web, haciendo referencia
a las secciones de la página que queremos explicar manteniendo de este modo tanto la interfaz como la propia ayuda
en un único sitio; siendo más díficil también que esa ayuda se quede desactualizada.

Aquí tenemos un ejemplo de uso: ? integrado en esta misma página.

3. Uso vía metadatos.

La configuración pasa por descargar los fuentes e incluir tanto el javascript minificado como las css en nuestro código:

<script type="text/javascript" src="intro.js/intro.js"></script>
<link href="intro.js/introjs.css" rel="stylesheet"></link>

Para incluir las secciones a integrar dentro de la introducción o guía de usuario basta con hacer uso de los atributos
data-intro y data-step dentro de nuestro propio código.

<div data-step="1" data-intro="Esta sección podemos encontrar el índice de contenidos">
...
</div>
<div data-step="2" data-intro="Puede resultarte interesante leer primero la introducción">
...
</div>
...
<button onclick="introJs().start();">?</button>
...

Simplemente con esta configuración podríamos comenzar a montar nuestra ayuda de usuario, aunque la librería
tiene muchas opciones:

• showButtons: mostrar los botones o no,
• showProgress: mostrar una barra de progreso,
• showBullets: mostrar los bullets o no,
• showStepNumbers: mostrar los números de paso.
• …

La recomendación es disponer de una función que configure y arranque la intro y no invocarla directamente desde el botón de ayuda:

function startIntro(){
	intro = introJs();
	intro.setOptions({
		nextLabel: '>', 
		prevLabel: '<', 
		skipLabel: 'Salir', 
		doneLabel: 'Hecho'
	});
	intro.start();
}

Eso nos permitirá, por ejemplo, internacionalizar los botones que aparecen en la ayuda.

4. Configuración dinámica.

Si, por lo que sea, no podemos modificar el código de nuestro html siempre podemos añadir los pasos
de la ayuda de forma dinámica vía javascript.

<script type="text/javascript">
  function startIntro(){
		intro = introJs();
		intro.setOptions({
			disableInteraction: false,
			exitOnEsc: false,
			exitOnOverlayClick: false,
			showBullets: false,
			showButtons: false,
			keyboardNavigation: false,
			steps: [
			{
				element: document.querySelector('#cliente\\:nameInputHelpWrapper'),
				intro: "Por favor, introduzca el nombre del cliente.",
				position: 'left'
			},
			{
				element: document.querySelector('#cliente\\:createdAtInputHelpWrapper'),
				intro: "Por favor, introduzca la fecha de alta en el sistema",
				position: 'left'
			},
			{
				element: '#cliente\\:ageInputHelpWrapper',
				intro: "Por favor, introduzca la edad del cliente",
				position: 'left'
			}
        	]
		});
		intro.start();
	}
	startIntro();
</script>

De este modo podríamos obtener los pasos de ayuda de cualquier servicio o mantenerlos de forma estática también en la propia página, pero debe
existir una referencia al id del componente html.