Eine geführte Tour mit Shepherd in JavaScript entwickeln

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

What You'll Be Creating

Was Du entwickeln wirst

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

EInführung

Egal wie einfach wir versuchen unsere Web-Anwendungen zu halten – oft ist es hilfreich, neue Nutzer für deren erste Schritte an die Hand zu nehmen. Geführte visuelle Touren, sind hierfür wahrscheinlich mit der einfachste Weg.

Wenn Du meine Envato Tuts+ Serie Building Your Startup With PHP verfolgt hast, kennst Du bereits den Meeting Planner. Nachdem ich beobachtet habe, wie Benutzer mit diesem Tool ihre ersten Meetings geplant haben, beschloß ich, dass es am besten wäre, eine Art Hilfesystem zu entwickeln.

Zuerst wollte ich solch ein System selbst entwickeln, habe dann aber eine Open Source Lösung in Shepherd gefunden.

In unserem heutigen Tutorial, werde ich Dir zeigen, wie Du eine visuelle, geführte Tour für Webseitenbesucher mit Shepherd erstellen kannst. Shepherd einzusetzen geht relativ einfach von der Hand und ich werde Dir zusätzlich zeigen, wie ich selbst noch Code geschrieben habe, der die Texterstellung erheblich vereinfacht.

Shepherd ist eine Open Source Lösung von HubSpot, einem Inbound Marketing Service, welchen ich an dieser Stelle ein großes Lob für diese robuste und gut dokumentierte Bibliothek aussprechen möchte.

Ich nehme in den Disukussion unten auf der Seite ebenfalls teil. Fühle Dich dazu eingeladen, dort Fragen zu stellen und Dein Feedback zu posten. Ich interessiere mich besonders für Deine Erfahrungen mit anderen Tools für geführte Touren. Du kannst mich auch auf Twitter unter @lookahead_io kontaktieren.

Wie Shepherd funktioniert

Betrachten wir ein einfaches Szenario für Shepherd.

Eine einfache geführte Tour mit Shepherd zu implemetieren gestaltet sich sehr simpel. Zuerst wählst eine Vorlagendatei und integrierst deren JavaScript wie folgt:

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

Du kannst die Dateien auf der Shepherd GitHub Seite herunterladen. Ich nutze, wie oben zu sehen, die Datei shepherd-theme-arrows.css, aber Du kannst jede der vorgefertigten Dateien aus der folgenden Liste wählen:

Visual Tour With Shepherd - Default Theme CSS Files

Als nächstes erstellst Du das Tour Objekt:

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

Die Standardoptionen können für jeden Schritt der Tour definiert werden. Die CSS-Klassen beziehen sich auf das von Dir gewählte Theme, wie zum Beispiel shepherd-theme-arrows. Und scrollTo stellt sicher, dass alle Schritte im sichtbaren Bereich des Browsers liegen.

Dann fügst Du die einzelnen Schritte Deiner Tour hinzu:

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
    }
  ]
});

Der text ist, was im Inhaltsbereich Deiner Tour erscheint. attachTo zeigt auf einen CSS Selektor für das Objekt, auf das Du mit dem Tour Pop-Up in diesem Schritt zeigen möchtest. Die buttons erlauben es, einen oder mehrere Buttons inklusive Aktionen zu definieren. Ein Beispiel wäre Next.

Zum Schluß startest Du die Tour:

1	tour.start();

Shepherd nutzt Tether, eine andere HubSpot Open Source Bibliothek, die dabei hilft, Elemente bezogen auf andere Elemente auf der Seite zu positionieren. Tether stellt sicher, dass Deine Schritte niemals über den sichtbaren Bereich Deines Browsers hinausragen oder abgeschnitten werden.

Mit Tether hatte ich soweit keine Probleme. Allerdings stellte Shepherd manchmal Pfeile auf einige Elemente nicht richtig dar. Ich bin hier nicht der einzige mit diesem Problem. Das HubSpot Team hat auch nach zwei Wochen nicht auf meine GitHub anfragen reagiert, was mich etwas enttäuscht hat. Trotzdem ist Shepherd eine tolle JavaScript library.

Tether in Deine Anwendung integrieren

Visual Tour With Shepherd - Demo Scheduling at Meeting Planner

Als ich mit Shepard begann, stellte ich sehr schnell fest, dass Touren mit vielen Schritten sehr schnell sehr umfangreich an Text werden können. Dieses Problems habe ich mich dann mit einer eigenen Implementierung angenommen.

Ich wollte die Texte nicht in einer irgendwann riesigen JavaScript Datei schreiben, die dann mit der Zeit immer schwerer zu pflegen wäre. Stattdessen habe ich mich dazu entschlossen, ein Array zu erstellen und die Buttons automatisch, je nachdem, ob sich der Benutzer am Anfang oder am Ende der Tour befindet, anzupassen.

Ich erstelle zum Beispiel ein steps[] Array und definiere über die einzelnen Einträge die gesamte Tour:

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>']);

Jedes Element des Array besteht wiederum aus drei Einzelelementen:

Das Element, auf das in diesem Schritt gezeigt wird und die Position. Zum Beispiel '#headingWho top'
Der Text für die Überschrift, Zum Beispiel 'When do you want to meet?', also 'Wann treffen wir uns?'
Der Text für die Anweisungen

Dieses Array zu verwalten war viel einfacher für mich, als Buttons für jeden einzelnen Schritt der Tour zu definieren. Dies bedeutete aber auch, dass ich programmatisch die Buttons definieren musste, sobald ich einen Schritt der Tour geladen habe.

Ich habe diesen Code geschrieben, um der Tour Buttons hinzuzufügen und auf Klicks reagieren zu können. Mit jedem Schritt wird ein button Array erstellt, welches ich ansonsten manuell hätte erstellen müssen:

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();
      }
    });
  }

Der erste Schritt hat zum Beispiel keinen Back, also Zurück Button und der letzte Schritt keinen Next, also Nächster Schritt Button. Dafür hat der letzte Schritt einen Close, also Schließen Button.

Danach wird wird jeder step und jeder button meines Arrays zur Tour hinzugefügt.

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,
  });

Weil ich diesen Ansatz gewählt habe, musst ich nicht immer die gleichen Buttons für jeden einzelnen Schritt meiner Tour definieren. Das eröffnet zusätzlich die Möglichkeit, die Tour künftig dynamisch anzupassen.

Mit Yii, meinem Lieblingsframework für PHP, habe ich die nötigen Dateien hinzugefügt. Dieser Abschnitt wird nur auf bestimmten Seiten geladen. Nämlich dann, wenn die Tour benötigt wird. In meinem Fall die Planungsseite für Meetings:

<?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',
    ];
    ...

Hier siehst Du den eingebundenen CSS Code für Shepherd und die JavaScript Dateien für Tether, Shepherd und meinen eigenen Code für die Tour, meeting_tour.js.

Zusätzlich habe ich noch CSS Code eingebunden, der die Tour Pop-Ups auf maximal 40% Breite des Browserfensters beschränkt.

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

Du kannst Dir das Beispiel-Video hierzu oben oder auf Vimeo ansehen. Wenn Du das Beispiel selbst ausprobieren möchtest, melde Dich beim Meeting Planner an und Du wirst sofort zur Tour weitergeleitet.

Andere Dinge, die es zu beachten gilt

Die geführte Tour ausschalten

Ich habe eine Einstellung implementiert die es Benutzern ermöglicht, die Tour auszuschalten. Anstatt bei jedem Schritt einen "Aus" Button anzuzeigen, habe ich einen Link zum Abschalten der Tour im ersten und letzten Schritt eingefügt.

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

Das Ausschalten geschieht über AJAX und zeigt danach einen hilfreichen Link zur Seite für Einstellungen an. Das hilft dem Benutzer dabei, die Seite mit Einstellungen, u.A. für das An- und Ausschalten der Tour, einfach wieder zu finden.

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

Shepherds erweiterte Funktionen

Ich habe Dir nur die Basics von Shepherd gezeigt und erklärt, wie Du diese schnell in Deine eigene Web-Anwendung integrieren kannst. Soweit hat für mich alles gut funktioniert. Bis auf die angesprochene Problematik mit den Pfeilen, die manchmal auftritt. Aber Shepherds bietet noch eine Menge mehr. Viel mehr, als ich hier aufzeigen konnte. Im Speziellen in Sachen Eventverarbeitung und Management. Dadurch kannst Du Deine Tour auf Deine Anwendung und den aktuellen Status Deines Benutzers in individueller Weise anpassen. Auch hierfür gibt es eine sehr gute Dokumentation.

Wenn ein Benutzer zum Beispiel an eine bestimmten Stelle Deiner Seite springt, kannst Du über das Eventsystem automatisch ebenfalls zu einem anderen Schritt Deiner Tour springen. Eventuell werde ich dies in einem zukünftigen Tutorial näher behandeln.

Zum Abschluss

Ich hoffe Dir hat es gefallen, etwas über Shepherd zu lernen. Es ist sicherlich eine schöne und entwicklerfreundliche Bibliothek für geführte Touren, die Du sehr schnell in Deine eigenen Anwendungen integrieren kannst.

Bitte erzähle gerne von Deinen Erfahrungen mit Shepherd und anderen Bibliotheken für geführte Touren in den Kommentaren unten. Stelle auch gerne alle Fragen, die Dich beschäftigen.

Du kannst mich auch immer direkt über @lookahead_io auf Twitter erreichen. Wenn Du weitere meiner Envato Tuts+ Tutorials lesen möchtest, habe ich hier eine Liste von interessanten Artikeln:

Links zum Thema

Shepherd Tour
Shepherd auf GitHub
Meeting Planner (erstelle ein Meeting, um die geführte Tour zu sehen)