Initialisierung der eigenen Anwendung

Die folgende Anleitung geht davon aus, dass eine neue Anwendung mit dem Namen skeleton eingerichtet werden soll.

Installation

1. CLI erstellen

Im Arbeitsverzeichnis wird mit dem Kommando mvn clean install die Skeleton Anwendung erstmals gebaut. Danach steht im Verzeichnis skeleton-cli/target ein zip bzw. tar.gz für die MyCoRe-Kommandozeile zur Verfügung. Das zip bzw. tar.gzkann nun in einem beliebigen Projektverzeichnis auf dem Anwendungs-Server entpackt werden.

2. Konfigurieren

Konfigurationsverzeichnis generieren

Zuerst wechselt man das CLI-Verzeichnis der gerade entpackten Anwendung, z.B.:

cd c:\skeleton\skeleton-cli

Anschließend wird das Konfigurationsverzeichnis generiert, indem je nach Betriebssystem das folgende Kommando aufgerufen wird:

Linux:

bin/skeleton.sh create configuration directory

Windows:

bin\skeleton.bat create configuration directory

Linux:

~/.mycore/skeleton

Windows:

c:\Users\<userName>\AppData\Local\MyCoRe\skeleton\

Es ist darauf zu achten, dass der Name des Konfigurationsverzeichnisses dem Namen der Webanwendung entspricht, in diesem Beispiel also skeleton.

Datenbank konfigurieren

Zur Konfiguration der Datenbank muss die Datei resources/META-INF/persistence.xml im MyCoRe-Konfigurationsverzeichnis angepasst werden. Weitere Hinweise dazu befinden sich im Abschnitt Datenbank-JPA.

Solr konfigurieren

Um in der Anwendung suchen und recherchieren wird ein Solr-Suchserver benötigt.
Die Konfigutation wird wim Abschnitt Solr-Integration beschrieben.

Der Solr-Core sollte wie die Anwendung (skeleton) benannt werden und kann mit folgendem Kommando angelegt werden:

 .../solr/bin/solr create -c skeleton -d mycore_main

Abschließend wird in der Datei mycore.properties im MyCoRe-Konfigurationsverzeichnis der Core definiert:

  MCR.Solr.ServerURL=http://localhost:8983/
  MCR.Solr.Core.main.Name=skeleton

3. Anwendung initialisieren

Nun können die Klassifikationen, Nutzer der MyCoRe-Anwendung und und die SOLR-Core-Konfiguration in die DB geladen werden. Dazu wird folgendes Kommando verwendet:

Linux:

bin/skeleton.sh process config/setup-commands.txt

Windows:

bin\skeleton.bat process config\setup-commands.txt

Später kann die Datei setup-commands.txt um anwendungsspezifische Nutzer, Rechte und Klassifikationen ergänzt werden.

4. Anwendung deployen

Abschließend wird jetzt die Webanwendung online gestellt.

Wenn Änderungen am Source-Code oder Konfiguration vorgenommen worden sind, dann muss die Anwendung nocheinmal im Arbeitsverzeichnis mit dem Kommando mvn clean install neu gebaut werden.

Dadurch wird die Datei skeleton-webapp\target\skeleton-{version}.war erzeugt oder aktualisiert. Diese wird in skeleton.war umbenannt und dann in das \webapps-Verzeichnis des Servlet-Containers (Tomcat) kopiert. Der Servlet-Container entpackt und startet die Anwendung.

Herzlichen Glückwunsch! Ihre MyCoRe-Anwendung ist jetzt online:
http://localhost:8080/skeleton

Schritt-für-Schritt zur eigenen Anwendung

Nachdem das Anwendungsskelett eingerichtet und initial gebaut wurde, ist es an der Zeit einen genaueren Blick auf die Verzeichnisse und Dateien zu werfen. Um nun ausgehend von diesem Anwendungsskelett zur eigenen Anwendung zu kommen, ist es notwendig zu verstehen, wo was steht.

In der nachfolgenden Schritt-für-Schritt-Anleitung wird genauer in die einzelnen Bereiche geschaut. Grob kann man jedoch sagen:

skeleton-cli

erstellt die CLI und enthält die Basis-Konfiguration inkl. ACL-Spezifikation, Solr-Konfiguration und den nötigen Klassifikationen

skeleton-module

umfasst die gesamte Anwendungslogik

skeleton-webapp

erstellt das Webarchiv

1. Datenmodell erstellen

Im ersten Schritt muss das eigene Datenmodell basierend auf den MyCoRe-Datentypen spezifiziert werden. Diese Spezifikation erfolgt im skeleton-module unter src/main/datamodel/def. Die dort hinterlegte simpledoc.xml soll als Vorlage für eigene MyCoRe-Objektdefinitionen dienen. Für jedes MyCoRe-Objekt ist eine eigene Datei anzulegen.

Neue Datenmodelldefinitionen müssen in der Konfigurationsdatei src/main/resources/config/skeleton/mycore.properties über das Property MCR.Metadata.Type.{objecttype-name}=true registriert werden. Dabei entspricht der {objecttype-name} dem Dateinamen, der die MyCoRe-Objektdefinition enthält und dem im name-Attribut angegebenen String (wie hier am Beispiel der simpledoc.xml).

1
2
3
4
5
6
7
8

<?xml version="1.0" encoding="UTF-8"?>
<objecttype ...
            name="simpledoc"
            ...>
  <metadata>
    [...]
  </metadata>
</objecttype>

1
2

# in mycore.properties
MCR.Metadata.Type.simpledoc=true

Abschließend muss die Anwendung inkl. der CLI mit mvn clean install neu gebaut werden.

2. Erfassungsmasken

Um eigene Erfasssungsmasken zu erstellen, muss als erstes das HTML-Formular nach eigenen Anforderungen erstellt werden. Dies kann z.B. mit Bootstrap und unter Verwendung des FormBuilder für Bootstrap 3 realisiert werden.

Achtung: Der Formbuilder setzt name-Attribute für Buttons, Input-Felder, etc. Diese kann der XEditor nicht verarbeiten und produziert Fehler. Diese Attribute also bitte unbedingt entfernen!

Nachdem das HTML-Formular fertig ist, muss dies mit den entsprechenden XEditor-Bestandteilen angereichert werden. Alle Details dazu finden sich in der XEditor-Dokumentation.

Die Definitionsdatei für die Erfassungsmaske für simpledoc befindet sich im skeleton-module unter src/main/resources/META-INF/resources/content/publish/simpledoc.xed

3. Anzeige der Daten

Um die Daten auf der Webseite präsentieren, wird mittels XSLT das XML des MyCoRe-Objektes zu HTML transformiert.

Ein Beispiel für die Transformation eines simpledoc-MyCoRe-Objektes befindet sich im skeleton-module unter src/main/resources/xsl/simpledoc.xsl

Eigene Transformationsdateien müssen in der Konfigurationsdatei des skeleton-module, den src/main/resources/config/skeleton/mycore.properties durch Komma separiert ergänzt werden.

1
2
3
4
5
6

##############################################################################
# Datamodel                                                                  #
##############################################################################
MCR.Metadata.Type.simpledoc=true
MCR.Metadata.Type.{objecttype-name}=true
MCR.URIResolver.xslIncludes.objectTypes=%MCR.URIResolver.xslIncludes.objectTypes%,simpledoc.xsl,{objecttype-name}.xsl

4. Konfiguration der Suche

An dieser Stelle können natürlich nicht die vielfältigen Möglichkeiten, die Solr bietet vorgestellt und dokumentiert werden. Dazu verweisen wir auf die Literatur und die Solr Homepage.

Die Informationen hier sollen als Einstiegspunkt dienen und helfen, sich bei der Konfiguration zurechtzufinden. Vor allem sollen die MyCoRe-spezifischen Besonderheiten dargestellt werden.

Suchfeld-Definition im Solr Core

Die Definition erfolgt in der Datei schema.xml im Solr Core Konfigurationsverzeichnis. Wir empfehlen jedoch alle Änderungen im Skeleton Konfigurationsverzeichnis vorzunehmen und die Dateien bei Änderungen in den Solr Core zu kopieren. Dadurch lassen sich auch die Solr Konfigurationsdateien mit den anderen Dateien des eigenen Projektes unter Versionskontrolle verwalten. Die Schema Datei befindet sich unter: skeleton-cli\src\main\config\solr-home\skeleton\conf\schema.xml Die Syntax der Suchfelddefinitionen entnehme man dem Solr Wiki oder einem guten Solr Buch.

1
2

<field name="ds.title" type="text_general" multiValued="true" stored="true" />
            

Das Attribut type referenziert eine an anderer Stelle im Schema definierte Typ-Definition. In dieser ist festgelegt, wie Solr die Daten beim Import und die Terme von Suchanfragen verarbeiten sollen (z.B: Tokenisierung (Zerlegung in Worte), Normalisierung (Umlaute), Stammformreduktion, ...)
Mit dem Attribut multiValued wird angegeben, ob das Indexfeld wiederholbar ist. ID-Werte und Felder nach denen sortiert werden soll, sollte nicht mehrfach vorkommen.
Mit dem Attribut stored wird angegeben, ob neben der Solr-internen Form auch noch die Ausgangsform des Feldwertes gespeichert werden soll. Gespeicherte Felder können z.B. dazu genutzt werden, Trefferlisten direkt aus der XML-Rückgabe einer Solr Anfrage zu generieren, ohne nochmal auf das MyCoRe Datenobjekt zugreifen zu müssen.

Suchfeld-Mapping per XSLT

Die Werte der Suchfelder werden mittels XSLT generiert.

Um ein eigenes XSLT-Stylesheet in die Verabeitungskette zu integrieren, muss in der Datei jspdocportal-module\src\main\resources\config\jspdocportal\mycore.properties das entsprechende Property erweitert werden:

1
2

MCR.URIResolver.xslImports.solr-document
  =%MCR.URIResolver.xslImports.solr-document%,solr/skeleton-solr.xsl

Die XSLT-Transformationen werden in der Datei skeleton-module\src\main\resources\xsl\solr\skeleton-solr.xsl vorgenommen. Diese Datei produziert XML nach folgendem Vorbild:

1

  <field name="feldname">feldwert</field>

Die Feldnamen beziehen sich auf die in der Solr Konfiguration (schema.xml) definierten Felder.

1
2
3

  <xsl:for-each select="mods:titleInfo/*">
    <field name="ds.title"><xsl:value-of select="text()" /></field>
</xsl:for-each> 

5. Anpassung der Suchmasken und Trefferanzeige

Suchmasken können ebenfalls mit dem XEditor-Framework erstellt werden.

Ein Beispiel für die Definition einer einfachen Suchmasken befindet sich im skeleton-module unter:
src/main/resources/META-INF/resources/content/search/simple.xed

TODO: Trefferlisten per XSLT