2018.06 2019.06

Bildbetrachter - MyCoRe-Viewer

Die in einer MyCoRe-Anwendung abgelegten Dokumente können abhängig vom Format direkt aus der Anwendung heraus präsentiert werden. MyCoRe stellt hierfür einen eigenen Bildbetrachter zur Verfügung.

Beschreibung

Der MyCoRe-eigene Bildbetrachter ermöglicht es, unterstütze Dateitypen direkt in der Webseite zu präsentieren. Dies kann eingebettet, im Vollbildmodus oder auf mobilen Endgeräten genutzt werden. Unterstützt werden dabei verschiedene Bild-Formate (u.a. jpg, png, tiff), PDF und seit Version 2019.06 auch eBooks (u.a. ePub).

Screenshot einer MIR-Anwendung mit Bildbetrachter

Abbildung: Screenshot einer MIR-Anwendung mit Bildbetrachter

Aufbau

Der MyCoRe-Viewer besteht aus verschiedenen Komponenten. Jede Komponente hat eine bestimmte Aufgabe. Diese Komponenten werden zu Modulen zusammen gebaut. Jedes Modul entspricht einer Javascript-Datei. Der MyCoRe-Viewer wird standardmäßig mit 9 Modulen ausgeliefert, jedoch lässt er sich einfach um weitere Module erweitern.

Wie binde ich den Viewer ein?

Seit dem 2018.06 Release bietet MyCoRe die Möglichkeit den Viewer über ein einfaches Script einzubinden.

1
 <script src="{$WebApplicationBaseURL}rsc/viewer/{$derivate}{$file}?embedded=true&amp;XSL.Style=js"></script>

Der Viewer benötigt einen Container in dem die Inhalte des Derivats dargestellt werden. Dieser Container muss das Attribut data-viewer mit dem Wert concat($derivate, ':', $file)besitzen.

1
 <div class="viewer" data-viewer="{concat($derivate, ':', $file)}"></div>

Der Viewer setzt vorraus das JQuery in der Seite eingebunden wurde. Der Viewer lädt außerdem ein Bootstrap nach, welches über ein Property festgelegt wird. Falls dieses Bootstrap schon in der Seite vorhanden ist, dann wird es nicht nachgeladen.

1
 MCR.Viewer.bootstrapURL=%WebApplicationBaseURL%/assets/bootstrap/

Konfiguration des Viewers

Wenn die mycore-viewer-Bibliothek eingebunden ist, dann kann der Viewer durch die URL %MyCoReBaseURL%/rsc/viewer/%derivateId%/%bild% geöffnet werden. Diese Seite wird durch die MCRViewerResource gebaut. Die MCRViewerResource benutzt eine MCRViewerConfiguration um den Viewer bereit zu stellen. Diese MCRViewerKonfiguration wird über das Interface MCRViewerConfigurationStategy zur Verfügung gestellt. Welche MCRViewerConfigurationStrategy dafür benutzt wird kann über das Property MCR.Module-iview2.configuration.strategy gesteuert werden. Der Standard-Wert ist MCRViewerDefaultConfigurationStrategy.

Über die Klasse MCRViewerConfiguration kann gesteuert werden welche Script- und CSS-Dateien geladen werden, außerdem können Properties an die Viewer-Instanz gegeben werden. Für alle MyCoRe-Viewer-Module gibt es eine fertige MCRViewerConfiguration. Diese MCRViewerConfigurations erlauben es die Module über einfache MyCoRe-Properties zu steuern und übernehmen das einbinden der richtigen Script- und CSS-Dateien.

Konfiguration über MyCoRe-Properties

Die folgenden Konfigurationen sind in der MCRViewerDefaultConfigurationStrategy> enthalten und können ohne Anpassung genutzt werden:

MCRViewerLogoConfiguration

MCR.Module-iview2.logoURL wenn dieses Property gesetzt ist, dann wird das Logo-Modul automatisch eingebunden und konfiguriert.
MCR.Module-iview2.logo.css dieses Property dient dazu ein Logo in der Toolbar des Viewers einzublenden.

MCRMetadataConfiguration

MCR.Module-iview2.metadata.transformer bestimmt den Transformer der benutzt wird um das Objekt in HTML umzuwandeln. Es existiert ein vorgefertigtes Stylesheet für MODS-Metadaten.

MCRViewerPiwikConfiguration

Die Werte werden eins zu eins aus den MyCoRe-Properties durchgereicht (siehe Piwik-Modul).

Canvas-Konfiguration

MCR.Module-iview2.canvas.overview.enabled disables the mini overview in the bottom right corner.
MCR.Module-iview2.canvas.overview.minVisibleSize this value specifies how large the viewer container must be (in px) to show the overview on startup. If the overview should not be shown by default the value can be set to a large value like 999999.
MCR.Module-iview2.canvas.startup.fitWidth if this property set to true the viewer will fit image width on startup.

Konfiguration über Strategy

Da MyCoRe-Properties statisch sind und man keine Unterscheidung zwischen PDFs, IView und Epub machen kann, bietet MyCoRe eine flexiblere und genauere Möglichkeit den Viewer zu Konfigurieren. Zunächst ist es nötig eine eigene Strategy zu implementieren. Die einfachste und empfohlene Variante ist die Klasse MCRViewerDefaultConfigurationStrategy zu Erweitern. Beispiele dafür sind: MIRViewerConfigurationStrategy, ViewerConfigurationStrategy des collection-modules oder die JPortalIViewConfigurationStrategy. In der Methode MCRViewerConfiguration#get(HttpServletRequest request) hat man Zugriff auf auf den HttpServletRequest aus welchen man Informationen wie User-Agent oder Get-Parameter auslesen kann. Wenn die Klasse MCRViewerDefaultConfigurationStrategy erweitert wird, dann kann über den Aufruf von super.get(request) die Standard-Konfiguration geladen werden. Die Methoden addCSS und addScript können Javascripts und CSS-Dateien hinzufügt werden. Dabei sollte darauf geachtet werden das es sich um absolute Pfade handelt. Die URL der Anwendung kann durch den Methodenaufruf MCRFrontendUtil.getBaseURL(request) ermittelt werden. Es folgt eine Liste der Module des Viewers mit möglichen Konfigurationsparametern die über die Methode setProperty gesetzt werden können.

1. Das Base-Modul (obligatorisch)

Das Base-Modul ist der Kern des Viewers und enthält alle Komponenten die immer im Viewer benötigt werden. Alle anderen Module sind automatisch abhängig vom Base-Modul.

Das Base-Modul bietet folgende Konfigurationsparameter:

mobile (boolean)
gibt an ob die Instanz des Viewers eine Mobile-Version ist.
doctype (string)
gibt an welcher Dokumententyp geladen werden soll (METS oder PDF).
filePath (string)
gibt an welche Datei geladen werden soll. Bei PDF der Link zur PDF-Datei (relativ zum Derivat) und bei METS der Link zum ersten Bild.
derivate (string)
das MyCoRe-Derivat, welches die Datei zum Anzeigen enthält.
i18nURL (string)
die URL zum I18N-Servlet. In der i18nURL kann {lang} als Platzhalter für das Sprachkürzel angegeben werden, z.B. "http://foo.bar/servlets/MCRLocaleServlet/{lang}/component.iview2.*".
lang (string)
gibt an welche Sprache der Viewer verwenden soll, z.B. "de".
webApplicationBaseURL (string)
ist die URL zur MyCoRe-Instanz (damit der Viewer Ressourcen nachladen kann).
onClose (function)
gibt eine Funktion, an die beim Schließen des Viewers ausgeführt werden soll.

Folgende Parameter sind optional:

imageOverview.enabled (boolean)
bestimmt ob die Übersichtsanzeige links neben dem Bild aktiviert ist.
chapter.enabled (boolean)
bestimmt ob die Kapitelübersicht angestellt werden soll.
chapter.showOnStart (boolean)
bestimmt ob die Kapitelübersicht bereits geöffnet werden soll, wenn der Viewer gestartet wird.
permalink.enabled (boolean)
bestimmt ob das Permalink-Feature im Viewer aktiviert werden soll.
permalink.updateHistory (boolean)
wenn das Bild im Viewer gewechselt wird, dann wird auch die URL im Browser geändert.
permalink.viewerLocationPattern (string)
ist das Pattern zum Erstellen des Links zum Viewer, Standardwert ist: {baseURL}rsc/viewer/{derivate}/{file}.
canvas.overview.enabled (boolean)
bestimmt ob die Übersichtsanzeige rechts unten im Viewer angezeigt wird.
canvas.startup.fitWidth (boolean)
legt fest, ob beim Starten des Viewers das Dokument in der Breite eingepasst wird (true) oder an die Viewergröße angepasst wird.

2. Das Desktop-Modul

Das Desktop-Modul wird benötigt um den Viewer auf normalen Desktop-PCs darzustellen. Es orientiert sich an den CSS-Klassen und Javascript-Funktionen von Bootstrap und ist davon abhängig.

Keine Konfigurationsparameter.

3. Das Mobile-Modul

Das Mobile-Modul wird benötigt um den Viewer auf mobilen Geräten darzustellen. Es hat keine zusätzlichen Abhängigkeiten.

Keine Konfigurationsparameter.

4. Das Frame-Modul

Das Frame-Modul ist eine abgespeckte Variante des Desktop-Moduls. Es wurde speziell dafür entworfen den Viewer in eine extra Seite einzubinden.

Keine Konfigurationsparameter.

5. Das METS-Modul

Das Mets-Modul dient zur Anzeige von METS-Dateien und der zugehörigen Digitalisate über das IView2-Interface. Es hat keine zusätzlichen Abhängigkeiten.

Das Mets-Modul bietet folgende Konfigurationsparameter:

metsURL (string)
die absolute URL zum METS-Dokument.
imageXmlPath (string)
die absolute URL zum IView2-Interface.
tileProviderPath (string)
eine Komma getrennte Liste von absoluten URLs zu den IView2-Interfaces.

folgende Parameter sind optional:

pdfCreatorURI (string)
die URL zum METS-printer (siehe z.B. mir-mets-printer).
pdfCreatorStyle (string)
das Stylesheet welches für die Transformation des mets.xml benutzt werden soll.
pageRange (number)
wie viele Seiten gedruckt werden können.

6. Das PDF-Modul

Das PDF-Modul dient zur Anzeige von PDF-Dateien. Das Script PDF.js muss eingebunden werden, da der Viewer von diesem abhängig ist.

pdfProviderURL (string)
die URL zum PDF-Dokument {filePath} und {derivate} können als Platzhalter verwendet werden und werden vom Viewer durch die richtigen Werte ersetzt.
pdfWorkerURL (string)
PDF.js benötigt die pdf.worker.js. Diese wird automatisch nachgeladen und muss nicht extra in die Seite eingebunden werden.

7. Das Metadata-Modul

Das Metadata-Modul dient zur Anzeige von Metadaten überhalb der Strukturübersicht innerhalb des Viewers.

metadataURL (string)
die URL zu den fertig transformierten Metadaten(HTML). In der URL können {objId} und {derivateId} als Platzhalter eingesetzt werden.
objId (string)
die Objekt-ID welche in die metadataURL eingesetzt wird.

8. Das Logo-Modul

Das Logo-Modul ermöglicht die Darstellung eines Logos in der Toolbar.

logoURL (string)
die absolute URL zum Logo welches in der Toolbar angezeigt werden soll.

9. Das Piwik-Modul (neu Matomo)

Das Piwik-Modul bietet eine Anbindung an eine Piwik-Instanz (bzw. Matomo), dadurch kann verfolgt werden welcher Benutzer welches Digitalisat betrachtet hat.

MCR.Piwik.baseurl (string)
die URL zur Piwik/Matomo-Installation.
MCR.Piwik.id (string)
die ID der Website in Piwik/Matomo.

Kacheln als Basis

Wird der MyCoRe-Viewer für die Ansicht von Bildern genutzt, nutzt dieser die Bildkacheln, die standardmäßig beim Speichern der Daten im Hintergrund angelegt werden. Mehr dazu unter Grundlagen -> Derivate -> IView2.

Viewer ohne MyCoRe einbinden

Einfache Beispiele wie man den Viewer mit verschiedenen Konfigurationen einbindet findet man im MyCoRe-Viewer Projekt im Ordner src/main/resources/example/. Diese Konfigurationen lassen sich testen in den man im Basis-Ordner des MyCoRe-Viewer das Kommando mvn clean jetty:run ausführt. Anschließend wird der Viewer kompiliert und ein Jetty-Server gestartet, welcher über den Port 9201 zu erreichen ist. Für das Kompilieren des Viewers ist es nötig dass Maven und Nodejs auf dem System installiert sind.

Für die Einbindung auf der Metadaten-Seite wird empfohlen das Frame-Modul anstelle des Desktop-Moduls zu benutzen.

Download

Der MyCoRe-Viewer ist eine eigene Bibliothek die einzeln heruntergeladen und unabhängig von MyCoRe genutzt werden kann. Die aktuelle Releasversion mit deren Neuerungen kann im Jira eingesehen werden.

Zum Download stehen die jeweiligen Releases bei Maven Central zur Verfügung.