Help-App

Help-App

Guided Tours

 Einbinden von Guided Tours

Importiere für die Verwendung der Guided Tours-API zunächst eine Javascript-Datei:


<script src="/help/guidedtours/guided-tours.js"></script>

 Registrieren einer Guided Tour

Registriere eine geführte Tour mithilfe des Befehls registerTour(). Rufe den Befehl über das Objekt GuidedTours auf, das sich auf window befindet.

Beispielhafte Registrierung einer geführten Tour


let tour = window.GuidedTours.registerTour({
    id: "app-overview-tour",
    steps: [
        {
            id: "step-1",
            title: "Welcome to the guided tour",
            text: "This tour introduces you to the most important features of the app.",
        },
        {
            id: "step-2",
            title: "Login",
            text: "Login here. Enter your username and password.",
            attachTo: {
                element: "#login-dialog"
            }
        },
        //...
    ]
})

 Parameter der registerTour-Methode

EigenschaftTypPflichtfeldBeschreibung
idStringJaIdentifikator für die geführte Tour. Die ID darf maximal 128 Zeichen lang sein und darf nur die folgenden Zeichen enthalten: (a-z), (A-Z), (0-9), "-", "_"
stepsArrayJaEin Array aus Step-Objekten, das die Schritte der geführten Tour beschreibt.
useModalOverlayBooleanNeinStandardmäßig wird der Hintergrund der Anwendung abgedunkelt, um die geführte Tour hervorzuheben. Lege den Parameter auf false, wenn du die Abdunklung nicht verwenden möchtest.

 Eigenschaften des Step-Objekts

EigenschaftTypPflichtfeldBeschreibung
idStringJaIdentifikator für den Tourschritt.
titleStringJaÜberschrift des Tourschrittes.
textStringJaBeschreibungstext, der auf dem Tooltip angezeigt wird.
linkStringNeinLink zu weiterführenden Informationen. Der Link wird mit dem Text Mehr Erfahren auf dem Tooltip angezeigt. Die URL des Links muss relativ sein.
imgStringNeinURL zu einem Bild oder GIF.
attachTo.elementString oder HTMLElementNeinCSS-Selektor oder HTML-Objekt zu dem Element, an dem der Tooltip angezeigt werden soll. Wenn der Parameter leer geist, wird der Tooltip in der Mitte des Bildschirms angezeigt.
attachTo.onStringNeinBestimmt die Ausrichtung des Tooltips relativ zum zuvor bestimmten Element. Mögliche Werte sind: 'auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'right', 'right-start', 'right-end', 'left', 'left-start', 'left-end'

 Verwenden der Guided Tour

Die registerTour-Methode gibt eine Tourklasse zurück, die zum Beispiel dazu verwendet werden kann, um die geführte Tour zu starten und zu stoppen.

 Attribute der Tourklasse

EigenschaftTypBeschreibung
idString (Readonly)Identifikator für die geführte Tour. Die ID darf maximal 128 Zeichen lang sein und darf nur die folgenden Zeichen enthalten: (a-z), (A-Z), (0-9), "-", "_"
stepsArray (Readonly)Ein Array aus Steps, das die Schritte der geführten Tour beschreibt.
useModalOverlayBoolean (Readonly)Bestimmt, ob der Hintergrund der Anwendung abgedunkelt wird.
statusEnumBeschreibt den aktuellen Status der Tour. Mögliche Werte sind: 'OPEN', 'IN_PROGRESS', 'PAUSED', 'CANCELED', 'COMPLETED'

 Methoden der Tourklasse

MethodeBeschreibung
start(): voidStartet die geführte Tour.
complete(): voidBeendet die geführte Tour.
pause(): voidPausiert die geführte Tour.
continue(): voidFührt die Tour fort, nachdem sie pausiert oder abgebrochen wurde. Die Tour startet beim zuletzt angezeigten Schritt.
next(): voidRuft den nächsten Schritt der Tour auf.
previous(): voidRuft den vorherigen Schritt der Tour auf.
getCurrentStep(): StepGibt den aktuell angezeigten Schritt zurück.

 Attribute der Step-Klasse

Die Attribute der Step-Klasse gleichen den Eigenschaften des Step-Objekts.

 Methoden der Step-Klasse

MethodeBeschreibung
beforeNext(callback: Function, preventDefault: boolean = false)Du kannst der beforeNext()-Methode eine Callback-Funktion hinzufügen, die vor dem Anzeigen des nächsten Schritts aufgerufen wird. Mithilfe des Parameters preventDefault kannst du verhindern, dass der nächste Schritt beim Klick auf "Weiter" angezeigt wird. Rufe in diesem Fall die next()-Methode manuell auf.
beforePrevious(callback: Function, preventDefault: boolean = false)Du kannst der beforePrevious()-Methode ine Callback-Funktion hinzufügen, die vor dem Anzeigen des vorherigen Schritts aufgerufen wird. Mithilfe des Parameters preventDefault kannst du verhindern, dass der vorherige Schritt beim Klick auf "Zurück" angezeigt wird. Rufe in diesem Fall die previous()-Methode manuell auf.

 Anzeigen eines Feature Highlights

Die API der Guided Tour ermöglicht dir, eine Hervorhebung eines Features (Feature-Highlight) anzuzeigen. Die Hervorhebung kannst du verwenden, um z. B. auf neue Funktionen in der App aufmerksamzumachen. Um ein Feature Highlight anzuzeigen, kannst du eine Tour registrieren, die nur einen Schritt enthält. Die API des Feature Highlights ist identisch mit der API der Guided Tour.

Beispielhafte Registrierung eines Feature Highlights


let tour = window.GuidedTours.registerTour({
    id: "feature-highlight",
    steps: [
        {
            id: "step-1",
            title: "Guided Tours",
            text: "You can now start a guided tour that gives you an overview of the app via this button.",
        },
    ]
})

 Abfragen des Status einer Tour

Der Status einer Tour wird User- und App-bezogen abgespeichert. Mithilfe der Methode getTourStatusByID() kannst du den aktuellen Status einer Tour abfragen. Gib hierfür die bei der Registrierung verwendete ID an.

Beispielhafte Abfrage des Tour Status


let status = window.GuidedTours.getTourStatusByID("app-overview-tour")
console.log(status)

Als Rückgabewert erhältst du das folgende Objekt:


{
  id: "app-overview-tour",
  status: "COMPLETED",
}

Mögliche Werte für den Status sind: OPEN, IN_PROGRESS, PAUSED, CANCELED oder COMPLETED.

 Deaktivieren aller Touren für Testsysteme

Auf Testsystemen kann es dazu kommen, dass automatisierte Tests fehlschlagen, da bestimmte Elemente durch eine Guided Tour blockiert werden. Aus diesem Grund kannst du alle Guided Tours deaktivieren. Füge das Cookie DisableGuidedTours=true hinzu.