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 registerTourAsync(). Rufe den Befehl über das Objekt GuidedTours auf, das sich auf window befindet.
Aktuell können maximal 10 Touren gleichzeitig pro App, Mandant und Benutzer persistent registriert werden. Mit der Methode deleteTourAsync kannst du eine Tour wieder löschen, um Platz für neue Touren zu machen. Falls du keine Persistierung benötigst, kannst du das Attribut disablePersistence verwenden.

Beispielhafte Registrierung einer geführten Tour


let tour = await window.GuidedTours.registerTourAsync({
    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 registerTourAsync-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.
maxWidthNumberNeinLegt die maximale Breite des Tooltips fest. Wenn der Wert nicht gesetzt ist, wird eine Breite von 400 verwendet.
disablePersistenceBooleanNeinDeaktiviert die Persistierung des Tour Status. Wenn dieses Attribut aktiviert ist, wird der Status der Tour nach dem Neuladen des Browsers zurückgesetzt.

 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.
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'
attachTo.preventInteractionBooleanNeinVerhindert Benutzerinteraktion mit dem hervorgehobenen Element. Das in attachTo.element angegebene Element erhält das CSS-Attribut pointer-events: none.

 Verwenden der Guided Tour

Die registerTourAsync-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.

 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.
async getStatus(): Promise<TourStatus | undefined>Gibt den aktuellen Status der Tour zurück. Mögliche Werte sind: 'OPEN', 'IN_PROGRESS', 'PAUSED', 'CANCELED', 'COMPLETED'.
async setStatus(value: TourStatus): Promise<void>Setzt den Status der Tour. Mögliche Werte sind: 'OPEN', 'IN_PROGRESS', 'PAUSED', 'CANCELED', 'COMPLETED'.
on(event: string, callback: Function): voidRegistriert eine Callback-Funktion für ein bestimmtes Ereignis. Mögliche Ereignisse sind show, cancel und complete. Die Methode wirft einen Fehler, wenn ein unbekanntes Ereignis angegeben wird.

 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 = await window.GuidedTours.registerTourAsync({
    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.",
        },
    ]
})

 Löschen einer Tour

Aktuell können maximal 10 Touren gleichzeitig pro App, Mandant und Benutzer persistent registriert werden. Um nicht mehr benötigte Touren zu löschen kann die Methode deleteTourAsync(id: string) verwendet werden.

Beispielhaftes Löschen einer Tour


await window.GuidedTours.deleteTourAsync("app-overview-tour")

 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.