Anker-Navigationen automatisch erstellen lassen

Anker-Navigationen automatisch erstellen lassen

Webseiten können sehr umfangreich werden, insbesondere, wenn es um Dokumentation oder Berichte geht. Manchmal lässt sich die Lesbarkeit langer Webseiten dadurch verbessern, dass man sie in Unterseiten aufteilt. Allerdings kann dieses Vorgehen auch kontraproduktiv sein, etwa bei API-Dokumentation, deren Leser nur ungern zwischen mehreren Seiten wechseln möchten, um die zu einem einzigen Thema benötigten Informationen zusammenzutragen.

Die Benutzbarkeit langer Webseiten lässt sich mit Anker-Navigationen deutlich verbessern. Solche Linklisten am Anfang einer Seite (oder wo auch immer sinnvoll) geben dem Leser einen Überblick des Seiteninhalts und ermöglichen es ihm, zu jedem Abschnitt zu springen, der mit einer Überschrift beginnt. Als Redakteur möchte man solche Navigationen natürlich nicht manuell pflegen müssen.

In dieser Anleitung stellen wir Ihnen ein Widget vor, das eine Anker-Navigation automatisch erstellt und aktuell hält. Wird es zu einer Seite hinzugefügt, ermittelt es die darauf enthaltenen Überschriften und erstellt aus deren Inhalten und Anker-IDs eine Linkliste. Redakteure können festlegen, welche Arten von Überschriften berücksichtigt werden sollen (etwa „Heading 2“) und können auch ein paar Styling-Optionen nutzen.

Unser Widget basiert natürlich auf der Scrivito Example App und lässt sich leicht in jede auf Scrivito basierende Web-Anwendung integrieren.

Die Widget-Klasse

Wir beginnen mit der Widget-Klasse und geben dort die Attribute an, über die die Widget-Instanzen verfügen sollen: ein style-Attribut (in Anlehnung an das gleichnamige Attribut des HeadlineWidgets), mit dem die Überschriften nach ihrer Hierarchieebene gefiltert werden, sowie Attribute für die Stile small, bold und bullets, mit denen Redakteure das Erscheinungsbild der Links anpassen können:

Wenn Sie Navigationen auch aus Überschriften erzeugen möchten, die in der Hierarchie weiter unten liegen (beispielsweise „h4“), können Sie sie in der obigen Definition und auch in der folgenden Konfiguration einfach zu der values-Liste des style-Attributs hinzufügen.

Die Konfiguration für Redakteure

Damit Redakteure die obigen Einstellungen verwenden können, benötigen wir als Nächstes eine entsprechende Konfiguration:

Wie Sie sehen, geht aus der obigen Konfiguration der Zweck der Optionen von AnchorNavigationWidget-Instanzen hervor.

Als passendes Miniaturbild im Widget-Auswahldialog können Sie die Datei icon_anchor_navigation_widget.svg herunterladen und im Verzeichnis „src/assets/images“ ablegen, sodass es importiert und genutzt wird.

Die Widget-Komponente implementieren

Kommen wir nun zum wichtigsten Teil, zur Widget-Komponente: Wie zu Beginn angedeutet, ermittelt sie zunächst die Headline-Widgets, die sich auf der betreffenden Seite befinden. Hierfür ruft sie die Funktion getHeadlineWidgets auf.

Alle Widgets auf einer Seite sind üblicherweise in einem Attribut vom Typ widgetlist enthalten. Einem generischen Ansatz folgend, ermittelt getHeadlineWidgets zunächst dieses Attribut mit Hilfe der API-Methode attributeDefinitions. Anschließend durchläuft die Funktion die widgetlist, um jene Headline-Widgets herauszufiltern, die den angegebenen style haben. Trifft getHeadlineWidgets dabei auf weitere widgetlist-Attribute (etwa Spalten- oder andere Container-Widgets) verarbeitet sie sie rekursiv.

Nachdem die Liste der Headline-Widgets mit dem eingestellten style ermittelt und sichergestellt wurde, dass diese Liste nicht leer ist, rendert die Komponente die Überschriften in einem <ul>-Element, in dem sie für jede Überschrift ein verlinktes <li>-Element ausgibt.

Fertig! Ihr “Anchor Navigation”-Widget ist jetzt nutzbar.

Da geht noch mehr…

Das Headline-Widget der Example App nutzt die Funktion kebabCase aus einem Modul namens lodash‑es, um aus den Überschriften Anker-IDs zu erzeugen. Alternativ bietet es sich an, die Anker-IDs von Redakteuren vergeben zu lassen (und zum Beispiel im Attribut anchorId zu speichern) oder beide Ansätze miteinander zu verbinden, also eine solche ID nur dann zu generieren, wenn keine vergeben wurde.

Um nicht nur Überschriften mit einem bestimmten Stil in die Liste aufzunehmen, sondern auch Kombinationen zuzulassen (beispielsweise Überschriften mit <h2> oder <h3> als Stil), können Sie ein multienum-Attribut anstelle eines vom Typ enum verwenden und die style-Bedingung in getHeadlineWidgets entsprechend anpassen.