guide

Guided Touren für TYPO3

Die guided Tourerweiterung (EXT:guide) für TYPO3 bietet Ihnen die Möglichkeit, guided Touren durch das TYPO3 Backend zu erstellen. Diese touren sollten Redakteuren eine Einführung in verschiedene Bereiche und Funktionen geben, damit sie leicht herausfinden, wer TYPO3 einsetzt.

Die verschiedenen guided-Touren werden über die Seite TypoScript (tsconfig) konfiguriert. Die Umrechnungswerte werden wie gewohnt bereitgestellt von XLIFF-Dateien.

Entwickler von Drittanbieter-Erweiterungen haben die Möglichkeit, eigene guided-Touren für ihre Backend-Module anzubieten.

Backend-Modul

Die Tourerweiterung guided verfügt über ein eigenes Backend-Modul, das Sie im Hilfemenü in der oberen Leiste von das TYPO3-Backend. Es listet Ihnen alle (für Ihre aktuellen benutzerfreundlichen) guided-Touren auf. Du kannst jede Tour starten oder setzen Sie Touren fort, die Sie einmal gestartet haben. Zusätzlich können Sie Touren, die Sie als Don't markiert haben, wieder aktivieren wieder anzeigen.

Werfen wir einen Blick darauf, wie die guided-Touren im Detail funktionieren und wie Sie bestehende Touren ändern können oder erstellen Sie Ihre eigenen.

Definition einer guided Tour

Alle Touren müssen auf der Seite TypoScript-Knoten mod.guide.tours definiert werden. Eine Definition einer Tour für das View-Modul würde eine so sein:

mod.guide.tours.ViewModule {
    # hier kommt Ihre guided Tourkonfiguration
}

Der Hauptknoten einer Tour ist auch der interne Name. Dieser Name sollte eine einfache Schnur mit oberem Kamingehäuse sein.

Innerhalb dieses Tour-Knotens benötigen wir einige benötigte Knoten, die so definiert werden können:

mod.guide.tours.ViewModule {
    # Der Titel der Tour. Dieser Titel wird im Backend-Modul angezeigt.
    # Geben Sie einfach etwas Text ein oder verwenden Sie eine LLL-Kennung.
    title = LLL:EXT:guide/Ressourcen/Privat/Sprache/BootstrapTourViewModule.xlf:tx_guide_tour.title
    # Beschreibung der Tour. Diese Beschreibung wird im Backend-Modul angezeigt.
    # Geben Sie einfach etwas Text ein oder verwenden Sie eine LLL-Kennung.
    beschreibung = LLL:EXT:guide/Ressourcen/Privat/Sprache/BootstrapTourViewModule.xlf:tx_guide_tour.description
    # Interner Name des Moduls.
    # Dies ist die gleiche Kennung wie der Modulschlüssel (M-Parameter in Backend-Links)
    # Der ModulNamenskern wird für Touren verwendet, die im oberen Frame ausgeführt werden.
    # Beispiele:
    # Seitenmodul: web_layout (eine Tour, die im Seitenmodul ausgeführt wird)
    # View-Modul: web_ViewpageView (eine Tour, die im View-Modul ausgeführt wird)
    moduleName = Kern
    # Symbolkennung für das Symbol im Backend-Modul.
    # Die Icon-Kennung muss in der Icon-Registry registriert sein.
    iconIdentifier = module-guide-tour-core
    # In den Schritten haben Sie einen Knoten für jedes Popup-Fenster eingefügt, das Sie anzeigen möchten.
    schritte {
        # Der Schlüssel der Schritte sollte numerisch sein und definiert die Reihenfolge der Anzeige des Popups
        10 {
            # ...
        }
        20 {
            # ...
        }
        # Eine Step-Taste kann auch durch einen Tastennamen definiert werden 
        # Dies kann nützlich sein, wenn Sie zu diesem Schritt springen möchten, ohne seine Schrittnummer zu kennen.
        schritt-für-Schlüssel-Name {
            # ...
        }
    }
    # Steps configuration kann einen Pfad zu einer YAML-Datei mit der Step-Konfiguration haben. Dieses Feld ist optional.
    # Indem Sie Ihre Schrittkonfiguration mit diesem Pfad versehen, können Sie bedingte Schritte in Abhängigkeit von TYPO3 bereitstellen 
    # Hauptversion. Zusätzlich werden die Schritte dynanisch neu geladen und das Page-TypoScript (tsconfig) bleibt klein.
    schritteKonfiguration = EXT:guide/Konfiguration/Touren/Touren/Touren/Veranstaltungen

Schrittkonfiguration

Jeder Step-Knoten kann wie folgt konfiguriert werden:

# Der Selektor wird an jQuery übergeben, um das HTML-Element auszuwählen, auf dem das Popover platziert werden soll.
# Dieser Wahlschalter muss im DOM eindeutig sein. Ein Selektor kann auch ein eindeutiges Datenattribut/Wert sein.
# Beispiele:
# selector = #some-id
# selector = .some-unique-class
# selector = .some-multiple-used-class:first
# selector = select[name=\'WebFuncJumpMenu\']:first
# selector = [data-identifier='apps-toolbar-menu-shortcut']]
selector = .typo3-aboutmodules-innerner-docbody
# Das ist der Titel des Popovers.
# Geben Sie einfach einen Text oder eine LLL-Kennung wie:
# title = LLL:EXT:guide/Ressourcen/Privat/Sprache/BootstrapTourPageModule.xlf:tx_guide_tour.0.title
title = Willkommen im TYPO3-Backend
# Dies ist der Inhalt des Popovers.
# Geben Sie einfach einen Text oder eine LLL-Kennung wie:
# title = LLL:EXT:guide/Ressourcen/Privat/Sprache/BootstrapTourPageModule.xlf:tx_guide_tour.0.content
# Sie können auch HTML-Tags wie i, u, b, br oder p verwenden. Zusätzlich gibt es ein img-Tag zur Anzeige von Symbolen, 
# die ein Daten-Icon-Identifier-Attribut mit der Icon-Identifikation aufweisen muss. Eine solche Verwendung von Symbolen könnte so aussehen:
# <img data-icon-identifier="module-web_layout"/>
# Es gibt ein <action> Tag, das es Ihnen erlaubt, Aktionen für den Benutzer zu definieren, die sichtbar gestaltet werden.
# Alle anderen Tags sind nicht erlaubt.
inhalt (
 Diese Tour zeigt Ihnen die ersten Schritte mit TYPO3.<br />.
 Sie beginnen hier im <img data-icon-identifier="module-help_AboutAboutmodules"/> <i>about</i> Modul, 
 die Ihnen Ihre verfügbaren Module anzeigt 
 Diese Module beziehen sich auf die Erteilung von Benutzerberechtigungen.<br />
 <br />
 Klicken Sie auf <i>Next</i> für eine Einführung in die Top-Leiste von TYPO3.<br />.
 <br />
 <i>(Sie können jede Tour mit dem guided Tourenmodul neu starten.)</i>>.
)
# Definiert die Position des Popovers.
# Mögliche Werte sind: oben, unten, links, rechts, rechts, auto
platzierung = oben
# Deaktiviert den Pfeil beim Popover.
# Der Pfeil wird standardmäßig angezeigt.
showArrow = falsch
# Aktiviert einen Hintergrund.
# Dieses Feature befindet sich derzeit in der Inkubationszeit
hintergrund = falsch
# Legen Sie eine Polsterung für den Hintergrund fest
backdropPadding = 0
#
# Die folgenden Knoten können für die Ausführung einiger Aktionen während der Tour verwendet werden 
#
# Der nächste Knoten enthält Aktionen, die durch Anklicken der nächsten Schaltfläche ausgelöst werden
weiter {
    # Mehr Informationen unten.....
}
# Der Show-Knoten enthält Aktionen, die ausgelöst werden, wenn Sie beginnen, diesen Schritt anzuzeigen
zeige {
    # Mehr Informationen unten.....
}
# Der angezeigte Knoten enthält Aktionen, die durch das Beenden ausgelöst werden, um diesen Schritt anzuzeigen
angezeigt {
    # Mehr Informationen unten.....
}
# Der Knoten hide enthält Aktionen, die durch das Ausblenden eines Schrittes ausgelöst werden
ausblenden {
    # Mehr Informationen unten.....
}

Der nächste Knoten

Der nächste Knoten enthält Aktionen, die durch Anklicken der nächsten Schaltfläche ausgelöst werden. So können Sie eine weitere Tour auslösen im letzten Popup-Fenster, indem Sie einfach auf die Schaltfläche Weiter klicken.

# Durch Anklicken von next wird die Tour-Topbar ausgelöst
tour = Topbar
# Die Nummer/Id des Schrittes, der bei der aufgerufenen Tour angezeigt werden soll
schritt = 0
# StepByKey löst die Schrittnummer durch den Schlüssel auf.
# Intern durchläuft es die gewünschte Tour und zählt die Schritte, bis der definierte stepByKey gefunden wird. Endlich ist es soweit
# der gezählte Wert in das Step-Attribut - das bedeutet, wenn Sie stepByKey verwenden, ist das Step-Attribut nicht erforderlich.
stepByKey = Schritt-für-Schritt-für-Schlüsselname

Der Show-Knoten

Der Show-Knoten enthält Aktionen, die ausgelöst werden, wenn Sie beginnen, diesen Schritt anzuzeigen. Das bedeutet im Detail, dass die Aktion ist ausgeführt, bevor die Tour den Anzeigeprozess startet. Mit Hilfe dieses Knotens können Sie Aktionen ausführen, wie z.B. das Hinzufügen oder Entfernen einer CSS-Klasse zu einem Element oder das Öffnen von select boxen, um bestimmte Werte anzuzeigen.

# Benennt das Label der nächsten Schaltfläche des Popups um.
# Dies ist nützlich, wenn Sie eine andere Tour starten, indem Sie auf die Schaltfläche Weiter klicken.
renameNextButton = Nächste Tour starten
# Fügt eine Klasse auf einem Element hinzu. Dies ist nützlich, wenn Sie ein spezielles Element hervorheben möchten.
addClass {
    # jQuery Selektor zur Identifizierung von Elementen, die die Klasse erhalten sollen 
    selektor = #typo3-S3-cms-backend-backd-toolbaritems-usertoolbaritems-usertoolbaritem
    # Klasse, die hinzugefügt werden soll
    # Attention: Wegen eines Schwerpunktthemas, Öffnen eines Dropdown-Menüs 
    # durch Hinzufügen der Klasse open funktioniert nur mit dem angezeigten Ereignis.
    klasse = offen
}
# Entfernt eine Klasse aus einem Element.
removeClass {
    # jQuery-Selektor zur Identifizierung von Elementen, die die Klasse verlieren sollten
    selektor = #typo3-S3-cms-backend-backd-toolbaritems-usertoolbaritems-usertoolbaritem
    # Zu entfernende Klasse
    klasse = offen
}
# Öffnet ein Auswahlfeld mit dem jQuery-Selektor
openSelectBox {
    selektor = wählen[name=\'WebFuncJumpMenu\']:first
}

Der angezeigte Knoten

Der angezeigte Knoten enthält Aktionen, die durch das Beenden ausgelöst werden, um diesen Schritt anzuzeigen. Das bedeutet im Detail, dass die Aktion ist ausgeführt, nachdem das Popup-Fenster vollständig sichtbar ist. Die verfügbaren Aktionen in diesen Knoten sind gleich dem Show-Knoten.

Der Ausblendknoten

Der Knoten hide enthält Aktionen, die durch das Ausblenden eines Schrittes ausgelöst werden. Die verfügbaren Aktionen in diesen Knoten sind gleichbedeutend mit den Show-Knoten.

Ändern Sie bestehende Touren oder erstellen Sie Ihre eigenen

Da guided-Touren durch eine einfache Seite TypoScript (tsconfig) definiert werden, kann man eine bestehende Tour ändern oder eine neue erstellen die Tour kann auf verschiedene Weise durchgeführt werden.

• Wenn Sie eine Tour mit einer eigenen Erweiterung oder einem eigenen Erweiterungsthema versehen möchten, erstellen Sie einfach eine TypoScript-Datei für eine Seite an Ihrem bevorzugten Ort, zum Beispiel in EXT:your_ext/Configuration/PageTS/GuidedTour.pagets. Diese Datei muss von Ihrer Firma eingebunden werden ext_localconf.php:

  <?php
  wenn (!defined('TYPO3_MODE'))) {
      die('Zugriff verweigert.');
  }
  if (TYPO3_MODE ===='BE') {
      / / / Seite Typoskript-Touren hinzufügen
      \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPageTSConfig(
          <INCLUDE_TYPOSCRIPT: source="FILE:EXT:' . $_EXTKEY . Konfiguration/SeitenTS/GuidedTour.pagets">'
      );
  }

  Diese Konfigurationsdatei enthält alle Ihre Änderungen an einer bestehenden Tour oder die Definition einer neuen guided Tour.

• Wenn Sie keine eigene Erweiterung haben, können Sie eine Tour mit dem Benutzer TypoScript ändern. Sie können dies tun, indem Sie die Option Änderungen direkt innerhalb des jeweiligen Benutzers oder, wenn Sie Touren für mehrere Benutzer ändern möchten, innerhalb eines Backends benutzergruppe - so können Sie die gleichen Touren/Tourenänderungen mehreren Benutzern zuordnen.

Beispiel für eine Änderung

Wenn Sie beispielsweise möchten, dass das zweite Popup-Fenster der ViewModule-Tour rechts statt unten angehängt wird, sie würden ein TypoScript wie dieses einfügen:

mod.guide.tours.ViewModule {
    steps.20.placement = rechts
}

Ebenso können Sie neu definierte guided-Touren anbieten.

Hinzufügen neuer Touren mit Hilfe von PHP

Seit der Version 2.0.0 können Sie mit PHP neue Touren definieren. Der Vorteil dabei ist, dass Sie den Schritt auslagern können konfiguration in externe yaml-Dateien und das Page-TypoScript ist nicht so überladen, indem alle Schritte erneut ausgeführt werden und wieder. Diese Definition kann durch einen kurzen Eintrag in deiner ext_localconf.php erfolgen. Das könnte so aussehen:

\Tx\Guide\Utility\GuideUtility::addTour((
    TemplateModule',
    LLL:EXT:guide/Ressourcen/Privat/Sprache/BootstrapTourTourTemplateModule.xlf:tx_guide_tour.title',
    LLL:EXT:guide/Ressourcen/Privat/Sprache/BootstrapTourTourTemplateModule.xlf:tx_guide_tour.description',
    'web_ts',
    module-web_ts',
    EXT:guide/Konfiguration/Touren/''
);

Das \Tx\Guide\Utility\GuideUtility::addTour benötigte die folgenden Parameter:

1. Die Tourkennung entspricht der Definition durch Page-TypoScript.
2. Der Titel der Tour. Dies kann auch eine Lokalisierungskennung sein.
3. Die Beschreibung der Tour. Dies kann auch eine Lokalisierungskennung sein.
4. Der Modul-Key der Tour. Dies ist das gleiche wie der m-Parameter des Moduls.
5. Die Icon-Kennung für die Tour
6. Der Basispfad für Ihre .yaml-Konfigurationsdateien. Bei Verwendung dieser addTour-Methode enthalten die .yaml-Dateien den Schritt konfiguration der Tour

Hinweis:

Wenn Sie Ihre Touren auf diese Weise definieren, können Sie Ihre Tour in Page-TypoScript (tsconfig) überschreiben oder User-TypoScript. Dies verhält sich wie oben beschrieben

Erstellen Sie verschiedene Schritte für verschiedene Hauptversionen von TYPO3

Durch die Bereitstellung Ihrer Schrittkonfiguration mit Hilfe von YAML-Dateien können Sie verschiedene Schritte für verschiedene TYPO3-Anwendungen verwenden versionen. Legen Sie einfach die Einstellung stepsConfiguration in Ihrer Tourkonfiguration auf dem Basisordner Ihrer .yaml-Dateien fest, wie Sie in Touren mit PHP* hinzufügen gesehen haben. In unseren Touren setzen wir es zum Beispiel auf:

EXT:guide/Konfiguration/Touren/Veranstaltungen

Nun benötigt dieser Basisordner einen Unterordner, in dem die Touren für die verschiedenen TYPO3-Versionen gespeichert sind. Jeder Ordner wird einfach nach der Hauptversionsnummer von TYPO3 benannt - zum Beispiel:

EXT:your_ext
- Konfiguration
  - Touren
    - TYPO3-7-7
    - TYPO3-8
    - TYPO3-x

In diesen Ordnern sucht die Tour guided nach YAML-Dateien, die den gleichen Namen wie Ihre Tourkennung haben. Wenn Sie z.B. eine TYPO3 LTS 8.7 betreiben und eine Tour mit dem Identifikator CreatePage definieren möchten, wird der Die Erweiterung guided tours sucht die Konfigurationsdatei der Schritte in Configuration/Tours/TYPO3-8/CreatePage.yaml