Tutorial: Indexfunktionen für Oxygen XML Frameworks

Auswahl eines Registereintrags in ediarum

Bequeme Auswahl eines Registereintrags und mit dem nächsten Klick wird das entsprechende XML-Element samt ID eingefügt.

Für Wissenschaftler/-innen ist bei der Transkription mit TEI-XML – neben anderem – die Möglichkeit interessant, Personen, Orte, Werke etc. mit einem zentralen Register zu verknüpfen. Dies geschieht über eine eindeutige Identifikationsnummer, die einer Person oder einem Ort etc. zugeordnet ist. Arbeitet man direkt im XML-Code muss man diese Nummer sich händisch raussuchen und dann in den Wert des entsprechenden Attributs kopieren. Das ist unpraktisch und zeitraubend.

Im Rahmen der digitalen Arbeitsumgebung „ediarum“ hat TELOTA nun die Funktionalitäten von Oxygen XML Frameworks so erweitert, dass die Wissenschaftler/-innen nun Textstellen in einem XML-Dokument schnell und bequem mit einem entsprechenden Indexeintrag verknüpfen können. Dafür wurden von TELOTA eigene Javaoperationen programmiert. Sowohl die JAR-Datei als auch der Sourcecode stehen ab sofort unter den Bedingungen der LGPL auf github zum Download zur Vefügung. Dieses Tutorial zeigt, wie Sie damit Indizierungsfunktionen in Oxygen XML Author integrieren können.

Empfohlene Voraussetzungen für dieses Tutorial

Einbindung in das Oxygen-XML-Framework

Im Oxygen-XML-Framework den Klassenpfad zur ediarum.jar eintragen

Im Oxygen-XML-Framework den Klassenpfad zur ediarum.jar eintragen

Wer die Indexfunktionen in seinen Oxygen XML Frameworks nutzen will, kann sich auf github die Datei ediarum.jar herunterladen. Sie muss auf der Festplatte innerhalb des entsprechenden Oxygen-Frameworksordner gespeichert (sofern das Framework extern gespeichert wurde, siehe Schritt 1 im Basis-Tutorial) und dann in der Frameworkdefinition referenziert werden. Letzteres ist sehr einfach: in den Frameworksdefinitionen („Einstellungen > Dokumenttyp-Zuordnungen) muss unter „Klassen-Pfad“ lediglich der Pfad zur JAR-Datei eingetragen werden. Kleiner Tipp: Mit der Editorvariable ${framework} wird direkt der aktuelle Frameworksordner angesprochen. Ist der Pfad zur Datei ediarum.jar korrekt angegeben, stehen ab sofort auch die Javaoperationen von ediarum beim Bauen von Aktionen zur Verfügung.

Zentrale Registerdatei

Alle fünf Indizierungsfunktionen, die mit ediarum.jar bereitgestellt werden, funktionieren nur in Zusammenarbeit mit einer (oder mehreren) zentral(en) Registerdatei(en). „Zentral“ bedeutet in diesem Zusammenhang, dass alle Einträge eines Registers – beispielsweise des Personenregisters – in einer einzigen Datei aufgelistet werden müssen. Es gibt keine Vorgabe, wie die XML-Elemente heißen müssen. Sinnvoll ist vielleicht eine an XHTML angelehnte simple Struktur:

<ul>
	<li id="o322432112">
		<span>Aare (Fluß, Schweiz)</span>
	</li>
	<li id="o3242343">
		<span>Aargau (Schweiz)</span>
	</li>
	<li id="o3245345">
		<span>Abbach (s. Regensburg, Bayern)</span>
	</li>
</ul>

Zu beachten ist hier einzig das zusätzliche span-Element innerhalb eines Listenpunktes. Aus eher historischen Gründen sind die Indexfunktionen so programmiert, dass als Text für die Auswahlliste immer ein Kindelement des Eintragselemtens (hier li) erwartet wird. Daher das eigentlich überflüssige span-Element (das im übrigen auch anders heißen kann).

Möglicherweise steht man jetzt vor dem Problem, dass man für jeden Registereintrag eine eigene XML-Datei erstellt hat. Dann ist es notwendig, aus all diesen Dateien mit Hilfe einer Programmier- bzw. Skriptsprache automatisiert eine einzige Datei zu erstellen, die pro Eintrag zwei Informationen enthält: erstens einen Text, der in einer Auswahlliste angezeigt wird (z.B. der Personenname und die Lebensdaten) und zweitens die eindeutige Identifikationsnummer. Weitere Informationen, die evtl. im Register vorhanden sind, müssen nicht ausgewertet werden.

In der für ediarum verwendeten Datenbanksoftware „eXistdb“ ist so etwas sehr leicht möglich: man schreibt ein kurzes XQuery-Skript, das eine einfache XML-Liste aus den für den Verlinkungsvorgang relevanten Informationen zusammenstellt und in einer einzigen Datei abspeichert. Damit alles automatisch abläuft kann in eXistdb ein „Trigger“ angelegt werden, der das eben beschriebene XQuery automatisch auslöst, sobald in der Collection mit den Registerdateien ein Dokument gespeichert wird. Dadurch ist die zentrale XML-Kurzliste stets aktuell. Ähnliche Lösungen sind mit anderen Programmiersprachen und Systemen aber selbstverständlich auch möglich.

Aktion erstellen

Jetzt ist alles vorbereitet und wir können die entsprechende Aktion im Oxygen XML Framework erstellen. Beim Anlegen einer neuen Aktion stehen uns nun die Javaoperationen von ediarum.jar zur Verfügung, die an dem Namen „org.bbaw.telota.ediarum“ zu erkennen sind. Alle vier Registeroperationen dienen dazu, dass der Benutzer mit Hilfe einer Auswahlliste ein XML-Element in ein XML-Dokument einfügen kann, dass die entsprechende (korrekte) ID eines Registereintrags trägt. Allen Javaoperationen gemeinsam ist das Auswahlmenü; sie unterscheiden nur durch die Art- und Weise wie Elemente bzw. Attribute in das XML-Dokument eingefügt werden:

Insert Register Operation

org.bbaw.telota.ediarum.InsertRegisterOperation
Fügt ein XML-Element mitsamt ID an oder um die markierte Stelle im XML-Dokument herum ein. Benutzen Sie diese Javaoperation, um den Bearbeitern Auszeichnungen von Personennamen, Ortsnamen etc. im Fließtext zu ermöglichen.

Insert Register At Operation

org.bbaw.telota.ediarum.InsertRegisterAtOperation
Fügt ein XML-Element mit der entsprechenden ID an einer per XPath definierten Stelle im Dokument ein. Benutzen Sie diese Javaoperation, um bspw. im teiHeader den Autor des Manuskripts zu notieren.

Insert Register Attribute Operation

org.bbaw.telota.ediarum.InsertRegisterAttributeOperation
Ersetzt bzw. fügt ein Attribut mit der ID des ausgewählten Eintrags in das per XPath definierte XML-Element ein. Benutzen Sie diese Javaoperation, um eine bereits vorhandene Auszeichnung zu verändern.

Insert Index Operation

org.bbaw.telota.ediarum.InsertIndexOperation
Ein oder mehrere Element(e) mit der entsprechenden ID als Attribut werden um die im XML-Dokument markierte Stelle herum eingefügt. Es handelt sich hier nicht um eine simple „SurroundWithFragment“-Operation im Oxygen-XML-Framework. Im Gegenteil: es ist mit dieser Operation möglich, ein Set aus zwei unterschiedlichen XML-Elementen einzufügen, die – neben der ID des Registereintrags – beide eine weitere ID tragen, um auf das jeweils andere Element zu verweisen. Im Ergebnis würde das so aussehen:

<index spanTo="#gfq_j3f_ng" indexName="orte" corresp="#o12345">
	<term>Name/Titel des Registereintrags</term></index> Lorem ipsum dolor sit amet, consetetur sadipscing elitr<anchor type="indexbereich" xml:id="gfq_j3f_ng"/>

Benutzen Sie diese Operation, wenn Sie zwei verschiedene Elemente einfügen wollen, um außerhalb der XML-Baumstruktur einen Textbereich zu indizieren.

Parameter

Durch die Verwendung von Parametern können die mit ediarum.jar zur Verfügung gestellten Javaoperationen in ganz verschiedenen XML-Projekten eingesetzt werden. Alle zu einer Operation gehörenden Parameter können Sie in der Definition des Oxygen-XMLFrameworks sehen und direkt bearbeiten, sobald sie einer Aktion die entsprechende Javaoperation zugewiesen haben.

Die ausführliche Dokumentation mit allen zu setzenden Parametern finden Sie auf github.com im Projektwiki von ediarum.

Link per CSS anzeigen

Eine so eingefügte Verknüpfung kann man mit Hilfe von CSS im Oxygen XML Author als Link gestalten, so dass die Bearbeiter Indizierungen mit einem Klick überprüfen können. Dafür wird die Oxygen-CSS-Eigenschaft link verwendet. In ihr kann die URL zur zentralen Registerdatei mit dem Attributwert als „Fragementidentifier“ (alles hinter der Raute „#“) zusammen gefügt werden:

persName:before {
    content: url('symbol.png');
    link: "http://example.edu/register/personen.xml#" attr(key);
    padding-right: 0.3em;
}

In Oxygen XML Author wird dann das per background-image eingefügte Symbol mit der URL unterlegt. Bei einem Klick darauf öffnet sich die verlinkte Registerdatei im Author und springt direkt zum Eintrag, der die ID trägt, die durch den Fragmentidentifier übergeben wurde. Voraussetzung für letzteres ist allerdings, dass die aufgerufene XML-Registerdatei über ein Schema verfügt, in dem das Attribut @id der Datentype xs:id zugewiesen wurde.

Download

Die für die Verwendung in einem Oxygen-XML-Framework vorgesehene Datei ediarum.jar können Sie sich hier herunterladen. Bitte beachten Sie die Hinweise zur Einbindung in das Framework weiter oben im Tutorial. Auf github finden Sie außerdem den Quellcode der Datei. TELOTA stellt ediarum.jar und seine Quelldateien unter den Bedingungen der LGPL zur freien Verfügung bereit.

Kommentare

2 Kommentare zu “Tutorial: Indexfunktionen für Oxygen XML Frameworks”

  1. Zusätzliche Javaoperationen für Oxygen XML Frameworks veröffentlicht — digiversity am Dezember 16th, 2013 10:44

    […] und können unter diesen Bedingungen genutzt werden. Wie man die Indexfunktionen implementiert wird in  einem neuen Tutorial auf digiversity Schritt für Schritt erklärt. Informationen zu weiteren Funktionen sind außerdem […]

  2. Winnie Scholz am Juni 4th, 2014 22:17

    Hallo Stefan Dumont,

    ich bin begeistert, deine Anleitungen gefunden und gelesen zu haben! Sie haben meinem Grundverständnis zum Thema Oxygen und Dokumententypvorlagen sehr auf die Sprünge geholfen.
    Leider habe ich bisher keine Anleitung gefunden, die ebenso anschaulich erklärt, wie man eine Javaoperation selbst entwickelt – von klein auf.
    Hast du dazu ebenfalls eine kleine Anleitung parat?
    Das würde mir sehr helfen und mich sehr freuen!

    Bitte melde dich doch diesbezüglich.

    Mit freundlichen Grüßen
    Winnie

Schreibe einen Kommentar




Bitte auch die kleine Rechenaufgabe lösen (Spamschutz): *