Skip to main content

Bookmarks

Überblick​

Bookmarks ermöglichen es Anwendern schneller zwischen wichtigen Bereichen innerhalb eines Dokuments zu navigieren. Hierzu werden einzelne Seiten im ersten Schritt mit einem Bookmark versehen. Anschließend kann über spezielle Elemente der grafischen Benutzeroberfläche einfach und schnell zwischen Bookmarks gesprungen werden.

Im Lieferumfang des jadice web toolkit enthalten sind Buttons und Commands, mittels derer Anwender Bookmarks erstellen und löschen sowie zwischen Bookmarks navigieren können. Als Anwendungsbeispiel dient die Enterprise-Demo, in deren rechter Sidebar die Bookmark-Funktionalität integriert ist. Die folgende Abbildung zeigt den zugehörigen Ausschnitt:

Bookmark-Funktionalität aus der Sidebar der Enterprise Demo

Persistierung​

Neben der clientseitigen Erstellung und Verwendung von Bookmarks gibt es die Möglichkeit, clientseitig erstellte Bookmarks zu persistieren, um diese in einem künftigen Bearbeitungsprozess erneut zu verwenden. Um dies zu erreichen, können clientseitig erstellte Bookmarks zunächst an den JWT Server gesendet und anschließend von dort in einem Drittsystem persistiert werden. Wird das zugehörige Dokument in der Zukunft erneut bearbeitet, können die persistierten Bookmarks im Rahmen des Dokument-Ladeprozesses aus dem Drittsystem ausgelesen und dem Dokument auf der Serverseite als Property hinzugefügt werden. Zusammen mit dem Dokument werden diese hierbei an den Client verschickt und stehen dem Anwender nach Abschluss des Ladevorgangs erneut für eine einfache und schnelle Navigation zur Verfügung.

Die Persistierung von Bookmarks lässt sich in 2 Funktionen unterteilen:

  • Speichern von Bookmarks

  • Laden persistierter Bookmarks

Speichern von Bookmarks​

Das Speichern von Bookmarks erfolgt in einer kundenspezifischen Implementierung einer ServerOperation. Details zum zugehörigen Konzept, das die serverseitige Ausführung von kundenspezifischem Code ermöglicht, finden sich im Kapitel Server Operations. Dabei stellt das jadice web toolkit sicher, dass alle Bookmarks während der Ausführung einer ServerOperation in der Methode invoke gemäß des folgenden Codefragments ausgelesen werden können:

@Override
public void invoke(Request<BookmarkPersistencyServerOperationParameters> request,
      ResponseChannel<ShowcaseServerOperationMessage> responseChannel) throws Exception {
    Document doc = request.getDocument();
    
    // retrieve the bookmarks from the document
    for (SerializableBookmark b : ((SerializableBookmarkList) doc.getProperties().get(
        SerializableBookmarkList.PROPERTY_KEY_SERIALIZABLE_BOOKMARK_LIST)).getAll()) {
        // place your logic to persist the bookmark here
    }
}

Laden persistierter Bookmarks​

Das Laden von Bookmarks erfolgt in einer kundenspezifischen Implementierung eines DocumentDataProvider. In der read-Methode wird dabei vor dem Lesevorgang eine Instanz der Klasse SerializableBookmarkList als Document-Property gemäß des folgenden Codefragments erstellt.

@Override
public final void read(Reader reader, final S source) throws JadiceException, IOException {
    // Place your logic to read persisted bookmarks here and create an instance of
    // SerializableBookmark for each of them. For the reason of simplicity we assume 3 persisted
    // bookmarks - on pageIndexes 7, 15 and 31.
    SerializableBookmark b1 = new SerializableBookmark(7);
    SerializableBookmark b2 = new SerializableBookmark(15);
    SerializableBookmark b3 = new SerializableBookmark(31);
    
    // Create a SerializableBookmarkList and add each persisted bookmark to it
    SerializableBookmarkList bms = new SerializableBookmarkList();
    bms.add(b1);
    bms.add(b2);
    bms.add(b3);
    
    // To make sure the bookmarks are transferred to the client the list has to be added as a
    // document property BEFORE calling reader.read()
    reader.getDocument().getProperties().put(SerializableBookmarkList.PROPERTY_KEY_SERIALIZABLE_BOOKMARK_LIST, bms);
    
    // read the document
    ...
    reader.read(in);
}

Die zugehörigen Bookmarks werden beim Aufruf von reader.read() zusammen mit dem Dokument an den Client geschickt und stehen für die clientseitige API zur Verfügung, sobald sich das Client-Dokument im Zustand Document.BasicState.READY befindet.

Ein funktionsfähiges Codebeispiel, das als Vorlage für die Persistierung dienen kann, findet sich in den Showcases.

Serverseitige und clientseitige Bookmark-API​

Zu beachten ist, dass sich die serverseitige und die clientseitige Bookmark-API unterscheiden. Die serverseitige Bookmark-API besteht aus den beiden Klassen SerializableBookmark und SerializableBookmarkList (siehe Codefragmente im Kapitel Persistierung). Diese beiden Klassen dienen ausschließlich als Datencontainer zum Speichern und Laden von Bookmarks.

Die eigentliche Bookmark-Funktionalität wird über die mächtigere clientseitige Bookmark-API zur Verfügung gestellt. Deren Highlevel-Schicht besteht dabei aus den Commands AddBookmarkCommand, NextBookmarkCommand, PreviousBookmarkCommand, RemoveBookmarkCommand, RemoveAllBookmarksCommand und AbstractBookmarkCommand. Darunter verbirgt sich die Lowlevel-Schicht bestehend aus den Klassen BookmarkListFactory und BookmarkFactory für die Erzeugung und den beiden Interfaces BookmarkList und Bookmark für die Verwendung.

Kundenspezifische Bookmarks​

Für die Umsetzung spezifischerer Anforderungen, für deren Abbildung die produkteigenen Commands nicht ausreichend sind, können über die Klassen der Lowlevel Bookmark-API kundenspezifische Bookmark-Commands implementiert werden. Als Orientierungshilfe eignen sich dabei die im Produktumfang enthaltenen Commands (siehe Serverseitige und clientseitige Bookmark-API).

Ein funktionsfähiges Codebeispiel, das als Vorlage für die Implementierung kundenspezifischer Commands dienen kann, findet sich in den Showcases.

Last updated on by Benjamin Albanese