Mit dem ‘Skeleton’ zur eigenen Anwendung

beschreibung der wichtigsten MyCoRe Funktionen.

Zur Entwicklung einer eigenen MyCoRe-Anwendung stellen wir ein Anwendungsgerüst zur Verfügung, das als Einstieg dienen soll.

Installation von “Skeleton”

Das „Skeleton“ ist quasi ein Gerüst zum Erstellen einer eigenen MyCoRe-Anwendung. Diese minimale Webanwendung kann je nach eigenem Bedarf schrittweise um weitere Komponenten und Funktionen erweitert werden. Eigene Anforderungen an das Layout können ebenso einfach realisiert werden, wie Erweiterungen am Datenmodell oder an Klassifikationen. Auch das Rollenmodell lässt sich erweitern und anpassen. Als Vorlage kann die sehr viel umfangreichere Webanwendung „MIR“ verwendet werden. Im Folgenden wird kurz beschrieben, wie das „Skeleton“ verwendet werden kann.

Embedded Shortcode figure/highlight

Es folgt ein Versuch, den {{< highlight >}} shortcode in {{< mcr-figure >}} zu kapseln

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

<realm id="registerUser" setable="false">
  <label xml:lang="de">Registrierung</label>
  <label xml:lang="en">Register</label>
  <login url="../authorization/new-author.xed" redirectParameter="url">
    <label xml:lang="de">Neue Benutzerkennung anlegen</label>
    <label xml:lang="en">Create new User ID</label>
    <info>
      <label xml:lang="de">
        Neuen Benutzer für die Anwendung registrieren.
      </label>
      <label xml:lang="en">
        Register new user for application.
      </label>
    </info>
  </login>
</realm>

Voraussetzungen

Für die Anwendungsentwicklung mit Skeleton benötigen Sie die unter Systemanforderungen beschriebene Software.

1. Quellen herunterladen

Zuerst sollte ein Arbeitsverzeichnis angelegt werden. (z.B. C:\skeleton\workspace oder ~/skeleton/workspace).

Danach wechselt man in dieses Verzeichnis und lädt das aktuelle Release Skeleton 2016.02 mit dem Kommando svn checkout https://server.mycore.de/svn/maven/skeleton/tags/skeleton-2016.02 skeleton herunter (oder alternativ den aktuellen Entwicklungszweig Skeleton Trunk mit svn checkout https://server.mycore.de/svn/maven/skeleton/trunk ).

2. CLI erstellen

Im Arbeitsverzeichnis wird mit dem Kommando mvn clean install die Skeleton Anwendung erstmals gebaut. Nun steht in 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.

3. Konfigurieren

Konfigurationsverzeichnis generieren

Zuerst wechsel man in das gerade erstellte Verzeichnis der CLI, 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

Im Nutzerverzeichnis wird dadurch ein MyCoRe-Konfigurationsverzeichnis generiert, das unter Linux ~/.mycore/skeleton heißt und bei Windows im Verzeichnis c:\Users<userName>\AppData\Local\MyCoRe\skeleton\ zu finden ist.

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 hibernate.cfg.xml im MyCoRe-Konfigurationsverzeichnis angepasst werden (siehe Datenbank / Hibernate ).

Seit 2016.03 wird die Datenbank in der persistence.xml unter resources/META-INF konfiguriert.

Solr konfigurieren

Um in der Anwendung suchen und recherchieren wird ein Solr-Suchserver benötigt.

Dieser läuft als eigene Webanwendung, die in einem Servlet-Container (z.B. Tomcat) deployed und konfiguiert werden muss (siehe Solr-Integration ).

Der Solr-Core collection1 sollte in skeleton umbenannt werden. Dazu muss im Solr-Home-Verzeichnis das Verzeichnis für den Core umbenannt und darin in der Datei core.properties der Name als Propertyname=skeleton gesetzt werden.

Dann kopiert man die Solr-Konfiguration für Skeleton (3 Dateien) aus dem Verzeichnis /config/solr-home der Skeleton-CLI Anwendung in den soeben erstellen Solr-Core

Abschließend wird im MyCoRe-Konfigurationsverzeichnis die URL des Solr-Cores in der Datei mycore.properties gesetzt:

MCR.Module-solr.ServerURL=http://localhost:8080/solr/skeleton

4. Daten laden

Nun können die Klassifikationen und Nutzer 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.

5. Anwendung deployen

Abschließend soll jetzt die Webanwendung online gestellt werden.

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-2015.11.0.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
 9
10
11
12

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


# 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.

##############################################################################
# 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 gutes Solr Buch.

Beispiel

<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:

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:

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

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

Beispiel

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