Cómo Elaborar un Recorrido del Usuario Con Shepherd en JavaScript

Spanish (Español) translation by Javier Salesi (you can also view the original English article)

What You'll Be Creating

Lo Que Vas A Crear

Visual Tour With Shepherd - Example of Shepherd Tour with Default Theme

Introducción

Sin importar qué tan sencillas tratamos de hacer nuestras aplicaciones web, es a menudo útil guiar a los nuevos usuarios a través de su primera experiencia. Los recorridos visuales son probablemente la manera más fácil.

Si has seguido mi serie Creando Tu Startup Con PHP de Envato Tuts+, estás familiarizado con Meeting Planner. Después de ver a los usuarios programar su primera reunión, decidí que sería mejor elaborar alguna clase de guía.

Al principio, considerá crear la mía, pero luego encontré una opción de código abierto, Shepherd.

En el tutorial de hoy, te introduciré a la creación de un recorrido visual del usuario con Shepherd. Usar Shepherd es relativamente sencillo, y revisaré algo de mi propio código que usé para agilizar el proceso de autoría.

Shepherd es una oferta de código abierto de HubSpot, un servicio de mercadotecnia de atracción. Felicítalos por ofrecer una robusta biblioteca con buena documentación.

Yo sí participo en la sección de comentarios abajo, así que por favor con toda confianza formula preguntas y comparte tu respuesta. Especialmente estaría interesado en tu experiencia con otras soluciones de la guía del recorrido visual. También puedes contactarme en Twitter @lookahead_io.

Cómo Funciona Shepherd

Transitemos por un sencillo escenario para Shepherd.

Integrar un recorrido básico con Shepherd a tu aplicación es sencillo. Primero, eliges un archivo de tema e integras su JavaScript así:

1	<link rel="stylesheet" href="shepherd-theme-arrows.css" />
2	<script src="tether.min.js"></script>
3	<script src="shepherd.min.js"></script>

Puedes descargar los archivos de la página de Shepherd en Github. Estoy usando el shepherd-theme-arrows.css arriba, pero puedes elegir cualquiera de los predeterminados abajo y personalizarlos:

Visual Tour With Shepherd - Default Theme CSS Files

A continuación, creas un objeto tour (recorrido):

var tour;
 
tour = new Shepherd.Tour({
  defaults: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});

Los defaults (predeterminados) pueden ser definidos para todos los pasos cuando creas el recorrido. Las clases se refieren a las definiciones de tema que usaste, por ejemplo, shepherd-theme-arrows. Y scrollTo afortunadamente asegura que todos los pasos aparezcan en la ventana gráfica visible.

Luego, agregas pasos individuales al recorrido:

tour.addStep('example-step', {
  text: 'This step is attached to the bottom of the <code>.
         example-css-selector</code> element.',
  attachTo: '.example-css-selector bottom',
  classes: 'example-step-extra-class',
  buttons: [
    {
      text: 'Next',
      action: tour.next
    }
  ]
});

El text es lo que aparece en el cuerpo del recorrido visual. attachTo apunta a un selector CSS para el elemento que quieres que apunte la ventana emergente del recorrido en éste paso. El buttons te permite definir uno o más botones y sus acciones, por ejemplo Next.

Y finalmente, comienzas el recorrido:

1	tour.start();

Shepherd se elabora a partir de Tether, otra oferta de código abierto de HubSpot, que ayuda a colocar elementos a otros elementos en una página. Tether asegura que tus pasos nunca se desborden en la pantalla o se corten.

Mientras que no tuve ningún problema con Tether, no encontré problemas con Shepherd al no mostrar adecuadamente flechas en algunos elementos. Ésto ocurrió aleatoriamente, y no soy el único con éste problema. El equipo de HubSpot no ha respondido a cualquiera de mis peticiones en Github después de dos semanas, lo cual es un poco decepcionante. Aún, Shepherd es en general una gran biblioteca JavaScript.

Integrando Tether En Tu Propia Aplicación

Visual Tour With Shepherd - Demo Scheduling at Meeting Planner

Como comencé a experimentar con Shepherd, descubrí rápidamente que crear una guía con muchos pasos podría ser algo muy extenso. Ésto es algo que abordé en mi propia implementación.

No quería crear el recorrido con un paquete largo de código JavaScript que necesitara ser mantenido con el paso del tiempo. Mejor, elegí crear un array (arreglo) y programáticamente personalizar los botones en base a si los usuarios estaban al principio o al final del tour.

Por ejemplo, creo un array steps[] y definí el recorrido al llenar el array:

var tour;
var steps =[];
steps.push(['.nav-tabs top','Welcome','Allow me to show you how to plan a '+title+'. <p>If you prefer, you can <a href="javascript::return false;" onclick="turnOffGuide();">turn off this guide</a>.<br /><br />']);
steps.push(['#headingWho top','Who would you like to invite?','You can add one person or a group of people to your '+title+'. <p>Click the person button to add participants.</p>']);
steps.push(['#invitation-url bottom','Inviting by email','Alternately, you can email the meeting link to your participant(s)']);
steps.push(['#headingWhat bottom','What is your meeting about?','You can customize the subject of your '+title+'. We\'ll use it for the invitation and reminder emails.<p>Click the pencil button to edit the subject.</p>']);
if ($('#headingActivity').length>0) {
  steps.push(['#headingActivity top','What do you want to do?','You can suggest one or more activity ideas. With multiple ideas, your participants can help you select their favorite. <p>Click the plus button to suggest activities.</p>']);
}
steps.push(['#headingWhen top','When do you want to meet?','Suggest one or more dates and times for your '+title+'. With more than one, your participants can help you choose. <p>Click the + button to add them.</p>']);
steps.push(['#headingWhere top','Where do you want to meet?','Suggest one or more places for your '+title+'. With multiple places, your participants can help you choose. <p>We use Google Places to simplify adding them. Click the + button to begin.</p>']);
steps.push(['.virtualThing top','Is this a virtual meeting?','Switch between <em>in person</em> and <em>virtual</em> '+title+'s such as phone calls or online conferences.']);
steps.push(['#actionSend top','Sending invitations','Scheduling is collaborative. After you add times and places, you can <strong>Invite</strong> participants to select their favorites. <em>A place isn\'t necessary for virtual '+title+'\s.</em>']);
steps.push(['#actionFinalize right','Finalizing the plan','Once you choose a time and place, you can <strong>Complete</strong> the plan. We\'ll email the invitations and setup reminders.']);
steps.push(['#tourDiscussion left','Share messages with participants ','You can write back and forth with participants on the <strong>Messages</strong> tab. <p>Messages are delivered via email.</p>']);    
steps.push(['.container ','Ask a question','Need help? <a href="'+$('#url_prefix').val()+'/ticket/create">Ask a question</a> and we\'ll respond as quickly as we can. <p>If you prefer, you can <a href="'+$('#url_prefix').val()+'/user-setting?tab=guide">turn off the guide</a> in settings.</p>']);

Cada elemento del array que agregué incluía tres elementos:

El elemento visual CSS al que apunta éste paso y donde, por ejemplo '#headingWho top'
Texto para la cabecera, por ejemplo '¿Cuándo quieres reunirte?'
Texto para la instrucción

Mantener éste array fue mucho más sencillo para mí que definir los botones para cada paso del tutorial. Sin embargo, ésto significó que necesitaba programáticamente definir botones cuando cargaba los pasos en el recorrido.

Esribí éste código para añadir y responder a botones para el recorrido adecuadamente. Con cada paso, crea un array button, que de otra manera tendría que definir manualmnete:

for (i = 0; i < steps.length; i++) {
  buttons=[];
  // no back button at the start
  if (i>0) {
    buttons.push({
      text: 'Back',
      classes: 'shepherd-button-secondary',
      action: function() {
        return tour.back();
      }
    });
  }
  // no next button on last step
  if (i!=(steps.length-1)) {
    buttons.push({
      text: 'Next',
      classes: 'shepherd-button-primary',
      action: function() {
        return tour.next();
      }
    });
  } else {
    buttons.push({
      text: 'Close',
      classes: 'shepherd-button-primary',
      action: function() {
        return tour.hide();
      }
    });
  }

Por ejemplo, el primer paso no tiene botón Back, y el último paso no tiene botón Next. Pero el último paso si tiene un botón Close.

Luego, cada step de mi array y cada array button es agregado al recorrido.

tour.addStep('step_'+i,{
    text: steps[i][2],
    title: steps[i][1],
    attachTo: steps[i][0],
    //classes: 'shepherd shepherd-open shepherd-theme-arrows shepherd-transparent-text',
    buttons: buttons,
  });

Usando éste planteamiento, no tuve que redefinir reiteradamente los mismos buttons (botones) para cada paso de mi tutorial. También ofrece alguna capacidad programática para personalizar el recorrido dinámicamente para el futuro.

Usando Yii, mi elegido framework para programar en PHP, agregué los necesarios archivos a mi archivo asset. Éste se carga en páginas particulares donde el recorrido es necesario. En mi caso, la página para programar la reunión:

<?php
namespace frontend\assets;
use yii\web\AssetBundle;

class MeetingAsset extends AssetBundle
{
    public $basePath = '@webroot';
    public $baseUrl = '@web';
    public $css = [
      ...
      'css/shepherd-theme-arrows.css',      
    ];
    public $js = [
      'js/meeting.js',
      ...
      'js/tether.min.js',
      'js/shepherd.min.js',
      'js/meeting_tour.js',
    ];
    ...

Verás arriba el CSS para el tema Shepherd y el JavaScript para Tether, Shepherd y el archivo de definición de mi recorrido, meeting_tour.js.

También agregué CSS para controlar la anchura general de la ventana emergente de mi recorrido a 40% de la ventana gráfica.

1	.shepherd-element.shepherd-theme-arrows {
2	max-width: 40%;
3	}

Puedes observar el video del recorrido de ejemplo arriba o en Vimeo. Si quisieras probarlo tú mismo, regístrate en Meeting Planner e inmediatamente serás llevado al recorrido de programación.

Otras Cosas a Considerar

Desactivando el Recorrido Visual

Creé una configuración de usuario para que las personas rápidamente desacativaran el recorrido. En lugar de incuir un botón Off que distrae en cada paso, agregué un enlace a turn of the guide (desacativar la guía) en el primero y en el último paso del recorrido:

Visual Tour with Shepherd - Turning off the guide via AJAX and seeing link to settings

Desactivarlo ocurre interactivamente vía AJAX y muestra un útil vínculo a la página de ajustes abajo. Ésto ayuda a los nuevos usuarios a encontrar fácilmente cómo volver a activar el recorrido:

Visual Tour with Shepherd - User setting for turning the tour on and off

Las Capacidades Avanzadas de Shepherd

Acabo de mostrarte las bases de Sheherd y cómo integrarlo rápidamente en tu aplicación web. Hasta ahora, funcionó bien para mí aparte de los problemas ocasionales con las flechas. Sin embargo, Shepherd ofrece mucho más de lo que he revisado, específicamente en cuanto al proceso y la gestión del evento. Ésto te permite adaptar tu recorrido a tu aplicación y el estado actual del usuario de una manera más personalizada. También tienen muy buena documentación.

Por ejemplo, si un usuario ingresa a algún área de tu página web, puedes tener que el evento automáticamente desencadene un salto a otro paso del recorrido. Podría ahondar en ésto en un futuro tutorial.

Concluyendo

Espero que hayas disfrutado aprendiendo sobre Shepherd. Ciertamente es un recorrido visual amigable con el desarrollador y visualmente pulcro que puedes rápidamente integrar en cualquier aplicación.

Por favor comparte tu experiencia con Shepherd y otras librerías para recorridos visuales en los comentarios. Y con toda confianza formula preguntas.

También siempre puedes contactarme en Twitter @lookahead_io directamente. Si quisieras leer más de mis tutoriales en Envato Tuts+, aquí están algunos interesantes:

Enlaces Relacionados

Recorrido Shepherd
Shepherd en GitHub
Meeting Planner (crea tu primera reunión par ver el recorrido visual)