Ausblenden von Seiten mit Hilfe des FilteredDocument

Gültig ab jadice web toolkit 5.9.3.6

Dieser Artikel beschreibt die Nutzung der neu geschaffenen Funktionen rund um das FilteredDocument zum Ausblenden von Seiten in Dokumenten.

Ab Version 5.9.4.1 lösen FilteredDocument und ThumbnailPageView.setApplyFilterInView() die bestehende PageFilter-API ab.

Motivation

Fachliche Abläufe machen es mitunter erforderlich, einzelne Seiten eines Dokuments auszublenden - beispielsweise Seiten, die persönliche oder anderweitig sensible Daten enthalten; gleiches gilt für schlichtweg leere Seiten.

Im jadice web toolkit existiert bereits die Möglichkeit, Seiten in der Thumbnail-Ansicht über einen PageFilter auszublenden. Bisher wirkt sich die Filterung nur auf die Thumbnails, nicht jedoch die Hauptansicht des Dokuments aus. Genau dies wird über das hier beschriebene Konzept eines FilteredDocument erreicht.

Grundidee

Der Manipulation der Dokumentstruktur liegt das Prinzip der Filterung zugrunde. So können einzelne Seiten ausgesteuert werden. Grundsätzlich könnten Filter aber auch in allgemeinerer Form genutzt werden, beispielsweise zum Umsortieren eines Dokuments.

In allen Fällen bleibt das Originaldokument unverändert - es wird lediglich ein Filter auf dieses Dokument angewendet, der die Sichtbarkeit der Seiten für die Anzeige bestimmt.

Das FilteredDocument "lebt" dabei ausschließlich auf dem Client. Es ist also Aufgabe der Integration, ggf. persistierte Filtereinstellungen serverseitig beim Laden des Dokuments auszulesen, diese an den Client zu übertragen und anschließend clientseitig den entsprechenden Filter zu setzen. Um es der Integration möglichst einfach zu machen, bietet der DefaultHiddenPagesMatcher Methoden zum Verstecken/Einblenden von Seiten an, die client- und serverseitig genutzt werden können. Details zur Nutzung siehe weiter unten.

Intern nutzt das FilteredDocument eine org.jadice.util.glazedlists.FilterList, so dass dem FilteredDocument über setMatcher() bzw. setMatcherEditor() der anzuwendende Filter (bzw. korrekter der Matcher) gesetzt werden kann. Das Originaldokument ist als Delegate im FilteredDocument enthalten.

Ladevorgang

Ausblenden von Seiten

Nachfolgend betrachten wir den Hauptanwendungsfall, einzelne Seiten in einem Dokument auszublenden. Das jadice web toolkit bringt hierzu die erforderlichen Funktionen mit, so dass ein umfangreiches Szenario damit abgedeckt werden kann:

Der Anwender zeigt ein Dokument an.
Über ein Kontextmenü kann der Anwender einzelne Seiten ausblenden.
Über eine Funktion kann der Anwender zwischen dem gefilterten und dem Originaldokument wechseln.
Der Anwender kann wahlweise das gefilterte oder das Originaldokument drucken.
Der Anwender kann die Filtereinstellung speichern.
Beim nächsten Öffnen des Dokuments wird der Filter geladen und auf das Dokument angewendet.

Die Beschreibung basiert auf den folgenden Showcases, die die unterschiedlichen Varianten abdecken:

Fall 1	Fall 2	Fall 3	Fall 4

Fall 1	Fall 2	Fall 3	Fall 4
Thumbnail-Ansicht und Haupt-PageView zeigen dasselbe, vollständige Dokument an → FilteredDocument with hidden pages: Synchronous Views	Thumbnail-Ansicht und Haupt-PageView zeigen dasselbe, gefilterte Dokument an → FilteredDocument with hidden pages: Synchronous Views	Thumbnail-Ansicht zeigt das gefilterte Dokument an; Haupt-PageView zeigt alle Seiten → FilteredDocument with filtered Thumbnail View	Thumbnail-Ansicht zeigt alle Seiten (ggf. mit grauem Overlay über ausgeblendete Seiten), Haupt-PageView zeigt das gefilterte Dokument an → FilteredDocument with unfiltered Thumbnail View.

Fall 1+2: Synchrone Ansichten in der Thumbnail-Ansicht und Haupt-PageView

→ FilteredDocument with hidden pages: Synchronous Views. Hierfür sind folgende Anpassungen erforderlich:

	Involvierte Klassen	Beschreibung

	Involvierte Klassen	Beschreibung
Laden des Filters (serverseitig)	FilteredClassPathWithAnnoDocumentDataProvider `DefaultHiddenPagesMatcher`	Serverseite: An das ladende Dokument wird in der `DocumentDataProvider`-Implementierung ein DocumentListener gehängt, der bei jedem `pageSegmentAdded()` mittels `DefaultHiddenPagesMatcher.hide(page)` die betreffenden Seiten versteckt. Anstelle des `DefaultHiddenPagesMatcher` kann natürlich auch ein eigener `Matcher` verwendet werden. Für den Standardfall, dass Seiten ausgeblendet werden sollen, lässt sich jedoch ganz einfach der im Lieferumfang des jadice web toolkit enthaltene `DefaultHiddenPagesMatcher` nutzen. Das Datenformat zur Persistierung der Information, welche Seiten ausgeblendet sein sollen, ist frei und kann integrationsseitig definiert werden.
Erzeugen des gefilterten Dokuments	`FilteredDocument` Example.java	Clientseite: Im `AsyncCallback` des clientseitigen Readers wird im Erfolgsfall (onSuccess()) so reagiert, dass ein gefiltertes Dokument erzeugt wird: `filteredDoc = new FilteredDocument((SerializableDocument) result); viewer.getPageView().setDocument(filteredDoc); DefaultHiddenPagesMatcher matcher = new DefaultHiddenPagesMatcher(); filteredDoc.setMatcher(matcher);` Weiterhin muss an das `Document` ein `DocumentListener` gehängt werden, um neu vom Server eintreffende, versteckte Seiten clientseitg korrekt als solche zu behandeln udn in der Ansicht zu verstecken. Hierzu ist bei jedem `propertyChange()`, der von einer `Page` ausgeht, erneut der Matcher zu setzen (siehe Example.java); `filteredDoc.setMatcher(matcher);`
Ein-/Ausschalten des Filters	Example.java	Clientseite: Das Ein- und Ausblenden von Dokumentseiten zur Laufzeit ist gleichbedeutend mit einer Veränderung des Matchers: `// Add button to switch to filter Button b = new Button("Show filtered document"); b.addClickHandler(event -> filteredDoc.setMatcher(new DefaultHiddenPagesMatcher())); // Add button to disable filtering Button b2 = new Button("Show original document"); b2.addClickHandler(event -> filteredDoc.setMatcher(p -> true));`
Seite ein-/ausblenden	HidePagesMenuContributor.java UnhidePagesMenuContributor.java	Clientseite: Wird im Showcase über ein Kontextmenü realisiert (`HidePagesMenuContributor`, `UnhidePagesMenuContributor`), da diese Form der Bedienung am naheliegendsten ist. Hierüber werden die Methoden `DefaultHiddenPagesMatcher.hide(page)` `und DefaultHiddenPagesMatcher.unhide(page)` aufgerufen. Beispiel mit `hide()`: `DefaultHiddenPagesMatcher.hide(mouseEditEvent.getPage()); context.getContext().contextChanged();` Man beachte den `contextChanged()`-Aufruf, um ein Aktualisieren der UI sicherzustellen.
Drucken	FilteredPrintingServerOperation.java FilteredPrintingServerOperationParameters.java FilteredPrintingServerOperationCommand.java Example.java	Clientseite: Beim Ausdrucken oder Export lässt sich per Parameter steuern, ob gefiltert oder ungefiltert exportiert bzw. gedruckt werden soll: `new FilteredPrintingServerOperationCommand(Filtering.NONE)` Serverseite: In der FilteredPrintingServerOperation.java ist zu sehen, wie im Falle `Filtering.ENABLED` über den `DefaultHiddenPagesMatcher` die ausgeblendeten Seiten erkannt werden können: `Filtering filtering = request.getParameters().getFiltering(); // Iterate over all pages of the document if (filtering.equals(Filtering.NONE)) for (Page p : document.getPages()) exporter.getSourcePages().add(p); else if (filtering.equals(Filtering.ENABLED)) { DefaultHiddenPagesMatcher matcher = new DefaultHiddenPagesMatcher(); for (Page p : document.getPages()) { if (matcher.matches(p)) exporter.getSourcePages().add(p); } }`
Speichern		Serverseite: Filter werden (wie auch Annotationen u.ä.) über eine `ServerOperation` gespeichert. Verwendet man den `DefaultHiddenPagesMatcher`, so bietet dieser Methoden zur Abfrage, ob Seiten ausgeblendet sind, die in der Speicher-ServerOperation verwendet werden können. Die Datenstruktur zur persistenten Speicherung der Informationen ist völlig frei und kann von der Integration definiert werden.

Fall 3: Gefilterte Thumbnail-Ansicht, vollständige Haupt-Ansicht

→ FilteredDocument with filtered Thumbnail View. Ergänzend zu den Anpassungen für Fall 1+2 ist folgendes zu konfigurieren:

	Involvierte Klassen	Beschreibung

	Involvierte Klassen	Beschreibung
Haupt-PageView konfigurieren	Example.java	Im Hauptviewer muss das Flag `ApplyFilterInView.NO` gesetzt werden, damit alle Seiten angezeigt werden: `viewer.getPageView().setApplyFilterInView(PageView.ApplyFilterInView.NO);`
ThumbnailView konfigurieren	Example.java	In der Thumbnail-Ansicht muss das Flag `ApplyFilterInView.YES` gesetzt werden, damit nur die gefilterten Seiten angezeigt werden: `viewer.getPageView().setApplyFilterInView(PageView.ApplyFilterInView.YES);`

Fall 4: Ausgegraute Seiten in der Thumbnail-Ansicht

→ FilteredDocument with unfiltered Thumbnail View. Wie man sieht, sind in diesem Showcase die ausgeblendeten Seiten in der Thumbnail-Leiste ausgegraut dargestellt.
Diese Darstellung kann man folgendermaßen erreichen (ergänzend zu den Anpassungen für Fall 1+2 von oben):

	Involvierte Klassen	Beschreibung

	Involvierte Klassen	Beschreibung
ThumbnailView konfigurieren	Example.java	Auf der Thumbnailansicht muss das Flag `ApplyFilterInView.NO` gesetzt werden, damit alle Seiten angezeigt werden: `PageView thumbnailPageView = thumbnailView.getThumbnailPageView(); thumbnailPageView.setApplyFilterInView(PageView.ApplyFilterInView.NO);`
Ausgrauen der ausgeblendeten Seiten	HiddenPagesOverlayTool.java Example.java	Um ausgeblendete Seiten auszugrauen, muss lediglich das `HiddenPagesOverlayTool` eingebunden werden: `thumbnailToolToolManager.register(HiddenPagesOverlayTool.class, true).`