teichmann@7255: =========
teichmann@7255: Datenkorb
teichmann@7255: =========
teichmann@7255: 
teichmann@7255: 
teichmann@7255: .. contents:: Inhalt
teichmann@7255: 
teichmann@7255: Übersicht
teichmann@7255: ---------
teichmann@7255: 
teichmann@7379: Der Datenkorb ist im Kern ein Dive4Elements/River eingebetteter Webdienst,
teichmann@7379: der dazu dient, ein XML-Dokument zu generieren, das seinerseits benutzt
teichmann@7379: werden kann, um Daten so identifizierbar zu machen, dass sie zu
teichmann@7379: Projekten innerhalb von Dive4Elements/River hinzugeladen werden können.
teichmann@7379: 
teichmann@7379: Das vom Datenkorb erzeugte XML-Dokument wird dann vom D4E/River-Client in
teichmann@7379: eine Baumansicht innerhalb der graphischen Benutzeroberfläche
teichmann@7379: transformiert.
teichmann@7379: 
teichmann@7379: Die Grundlage für das XML-Doument, das an die Oberfäche gesandt wird,
teichmann@7379: ist ein XML-Dokument namens ``meta-data.xml``, das im ``conf``-Verzeichnis
teichmann@7379: des Servers als Template für die Ausgabe-XML benutzt wird.
teichmann@7379: 
teichmann@7379: Dieses Referenzhandbuch beschreibt die Strukturen innerhalb von
teichmann@7379: ``metadata.xml``.
teichmann@7379: 
teichmann@7379: Grundstruktur
teichmann@7379: -------------
teichmann@7379: 
teichmann@7379: Das Grundgerüst einer validen ``meta-data.xml`` sieht sieh so aus:
teichmann@7379: 
teichmann@7379: .. code:: xml
teichmann@7379: 
teichmann@7379:   <xml version="1.0" encoding="UTF-8">
teichmann@7379:   <dc:template xmlns:dc="http://www.intevation.org/2011/Datacage">
teichmann@7379:     <datacage>
teichmann@7379:        ...
teichmann@7379:     </datacage>
teichmann@7379:   </dc:template>
teichmann@7379: 
teichmann@7379: Dies erzeugt folgendes Dokument:
teichmann@7379: 
teichmann@7379: .. code:: xml
teichmann@7379: 
teichmann@7379:   <xml version="1.0" encoding="UTF-8">
teichmann@7379:   <datacage>
teichmann@7379:        ...
teichmann@7379:   </datacage>
teichmann@7379: 
teichmann@7379: Elemente, die nicht aus dem Namespace ``dc`` stammen, werden durchkopiert.
teichmann@7379: ``dc``-Elemente dienen der Steuerung des Templating. Generell kann sagen,
teichmann@7379: dass das ``meta-data.xml``-Template mittels einer
teichmann@7379: rekursiven Tiefensuche (siehe http://de.wikipedia.org/wiki/Tiefensuche)
teichmann@7379: über seine Elemente abgearbeitet wird.
teichmann@7379: 
teichmann@7314: Daten
teichmann@7314: -----
teichmann@7314: Im Datenkorb stehen zwei Arten von Daten zur Auswertung zur Verfügung.
teichmann@7314: 
teichmann@7314: ``Datensätze``
teichmann@7314: ~~~~~~~~~~~~~~
teichmann@7314: Datensätze sind Tabellen mit benannten Spalten. Sie werden von Datenquellen
teichmann@7314: erzeugt und in einem Stapel verwaltet. Die konkreten Werte stehen erst durch
teichmann@7314: Auffaltung als Variablen zur Verfügung.
teichmann@7314: 
teichmann@7314: ``Variablen``
teichmann@7314: ~~~~~~~~~~~~~
teichmann@7314: Variablen sind die Werte, die aktuell zur Auswertung zur Verfügung stehen. Sie haben
teichmann@7314: einen Namen und einen Typ (String, Zahl, durch Datenquelle bestimmt).
teichmann@7314: 
teichmann@7314: Textersatz
teichmann@7314: ----------
teichmann@7314: Um die Wertebelegungen in das Ausgabedokument schreiben zu kann an entsprechenden
teichmann@7314: Stellen eine String-Interpolation durchgeführt werden.
teichmann@7314: Hier finden zwei Arten von Textersatz ihren Einsatz.
teichmann@7314: 
teichmann@7314: ``${}-Ersetzungen``
teichmann@7314: ~~~~~~~~~~~~~~~~~~~
teichmann@7314: Die ältere Variante. Innerhalb von Strings werden hier nur Variablen aufgelöst.
teichmann@7314: Beispiel: "**Hallo, ${planet}!**" wird bei planet = 'Welt' zu "**Hallo, Welt!**".
teichmann@7314: 
teichmann@7314: ``{$}-Ersetzungen``
teichmann@7314: ~~~~~~~~~~~~~~~~~~~
teichmann@7314: Die neuere Variante, allerdings noch nicht komplett an allen Stellen einsatzfähig.
teichmann@7314: Innerhalb der geschweiften Klammern können beliebige XPath-Ausdrück stehen, die
teichmann@7314: zu Strings evaluiert werden. Dies orientiert sich an den String-Auswertungen in XSLT.
teichmann@7314: "**{ concat($greet, ', ', $planet, '!') }**" wird bei gesetzten Variablen greet = Hallo
teichmann@7314: und planet = "Welt" zu **Hallo, Welt!** ausgewertet.
teichmann@7314: 
teichmann@7255: Datenkorb-Elemente
teichmann@7255: ------------------
teichmann@7255: 
teichmann@7314: Datensätze erzeugen
teichmann@7314: ~~~~~~~~~~~~~~~~~~~
teichmann@7255: 
teichmann@7315: ``dc:context`` Aufspannen eines Gültigkeitsbereiches eines Datenbankdatensatz
teichmann@7315: .............................................................................
teichmann@7255: 
teichmann@7315: .. code:: xml
teichmann@7315: 
teichmann@7315:     <dc:context connection="Verbindung">
teichmann@7315:       ...
teichmann@7315:     </dc:element>
teichmann@7315: 
teichmann@7315: Spannt einen Gültigkeitsbereich für einen Datensatz auf, der aus der Datenbank
teichmann@7315: kommt. Die adressierte Datenbank wird über das optionale Attribut 'connection'
teichmann@7315: bestimmt. Zur Zeit sind drei Datenbanken angebunden:
teichmann@7315: 
teichmann@7315: - **user**: Die Index-Datenbank des Artefakt-Servers. Hierüber stehen Meta-Informationen
teichmann@7315:   zu alten Berechnungen zur Verfügung.
teichmann@7315: 
teichmann@7315: - **system**: Die FLYS-Datenbank mit den hydrologischen, morphologische und geodätischen
teichmann@7315:   Daten.
teichmann@7315: 
teichmann@7315: - **seddb**: Die Sediment-Datenbank.
teichmann@7315: 
teichmann@7315: In einem `<dc:context>`-Element wird zwingend ein `<dc:statement>`-Element erwartet,
teichmann@7315: um einen Datensatz aus der Datenbank zu holen. Dieser Datensatz steht dann innerhalb des
teichmann@7315: `<dc:context>`-Elementes ein oder mehrfach zur Verfügung. Innerhalb eines
teichmann@7315: `<dc:context>`-Elementes können weitere `<dc:context>`-Elemente eingeschachtelt werden.
teichmann@7315: Ist kein 'connection'-Attribut vorhanden, wird die Datenbank-Verbindung des umgebenen
tom@8388: Kontextes weiterbenutzt. Initial wird je nach Aufrufart des Datenkorbs entweder
teichmann@7315: der **user** oder **system**-Kontext angenommen. Dies richtet sich danach, ob in
tom@8388: der Aufrufumgebung ein Artefakt gesetzt wird oder nicht. Im ersten Fall wird
teichmann@7315: angenommen, dass es sich um einen Ladevorgang für zusätzliche Daten handelt, die
tom@8388: auch alte Berechnungen mit einschließt.
teichmann@7315: 
teichmann@7315: 
teichmann@7315: ``dc:statement`` Holen eines Datensatzes aus einer Datenbank
teichmann@7315: ............................................................
teichmann@7315: 
teichmann@7315: .. code:: xml
teichmann@7315: 
teichmann@7315:     <dc:statement>
teichmann@7315:       SQL-Select-Statement.
tom@8388:     </dc:statement>
teichmann@7315: 
tom@8388: Mittels eines SQL-Select-Statements werden in einem `<dc:context>` Elemente aus
teichmann@7315: der dort definierten Datenbank geholt. Die Spaltennamen der Projektion des SQL-Statements
teichmann@7315: werden übernommen und später beim Auffalten des Datensatzes benutzt.
teichmann@7255: 
teichmann@7379: ``dc:container-context`` Tabellarische Daten aus der Programm-Umgebung
teichmann@7379: ......................................................................
teichmann@7379: 
teichmann@7401: .. code:: xml
teichmann@7255: 
teichmann@7401:     <dc:container-context container="Container">
teichmann@7401:        ...
teichmann@7401:     </dc:container-context>
teichmann@7401: 
teichmann@7401: Dies spannt einen Kontext auf einem Container namens Container auf,
teichmann@7401: einer listen-ähnlichen Struktur, die als externe Datenquellen in
teichmann@7401: Form eines Java-Objekts an den Datenkorb übergeben werden kann.
teichmann@7401: Dies müssen Klassen sein, die das Interface ``java.util.Collection``
teichmann@7401: implementieren. Mit diesem Konstrukt ist es möglich, tabellarische
teichmann@7401: Ergebnisse von außen in die Auswertung des Datenkorbs zu integrieren.
teichmann@7401: Der Container muss hierfür über die Variable ``Container`` zur Verfügung
teichmann@7401: gestellt werden. Die Spalten des Tabelle werden über ``dc:properties``
teichmann@7401: definiert. Der Datensatz selbst kann wie gewohnt mittels ``dc:for-each``
teichmann@7401: realisiert werden.
teichmann@7401: 
teichmann@7401: ``dc:properties`` Spaltendefinitionen für externe Daten aus der Programm-Umgebung
teichmann@7401: .................................................................................
teichmann@7401: 
teichmann@7401: .. code:: xml
teichmann@7401: 
teichmann@7401:     <dc:container-context container="Container">
teichmann@7401:        <dc:properties>
teichmann@7401:           <dc:property name="name" alias="alias"/>
teichmann@7401:        </dc:properties>
teichmann@7401:     </dc:container-context>
teichmann@7401: 
teichmann@7401: Muss innerhalb eines ``dc:container-context`` angegeben werden und enthält eine
teichmann@7401: Liste von Attributen der Java-Objekte, die in den Datenkorb eingeblendet werden sollen.
teichmann@7401: Die Auflösung der Namen auf der Java-Seite funktioniert nach Konvention von Java-Beans,
teichmann@7401: sprich aus ``name`` wird ``getName``. ``alias`` ist optional und weisst explizit einen
teichmann@7401: Spaltennamen aus. Dies entspricht im Wesentlichen einen 'AS' bei einem SQL-Statement.
teichmann@7401: 
teichmann@7401: Ein vollständigeres Beispiel könnte in etwa so aussehen.
teichmann@7401: Die Java-Seite:
teichmann@7401: 
teichmann@7401: .. code:: java
teichmann@7401: 
teichmann@7401:    public class Car {
teichmann@7401: 
teichmann@7401:       private String marke;
teichmann@7401:       private String name;
teichmann@7401: 
teichmann@7401:       public Car(String marke, String name) {
teichmann@7401:           this.marke = marke;
teichmann@7401:           this.name = name;
teichmann@7401:       }
teichmann@7401: 
teichmann@7401:       public String getMarke() {
teichmann@7401:           return marke;
teichmann@7401:       }
teichmann@7401: 
teichmann@7401:       public String getName() {
teichmann@7401:           return name;
teichmann@7401:       }
teichmann@7401:    }
teichmann@7401: 
teichmann@7401:    // Liste befuellen.
teichmann@7401: 
teichmann@7401:    java.util.Container<Car> container = new java.util.ArrayList<Car>();
teichmann@7401: 
teichmann@7401:    container.add(new Car("Volvo", "V80"));
teichmann@7401:    container.add(new Car("Ferrari", "Testarossa"));
teichmann@7401: 
teichmann@7401:    // Dem Datenkorb uebergeben.
teichmann@7401: 
teichmann@7401:    parameters.put("CARS", cars);
teichmann@7401: 
teichmann@7401: Das Datenkorb-Schnipsel
teichmann@7401: 
teichmann@7401: .. code:: xml
teichmann@7401: 
teichmann@7401:     <dc:container-context container="cars">
teichmann@7401:        <dc:properties>
teichmann@7401:           <dc:property name="marke" alias="brand" />
teichmann@7401:           <dc:property name="name" alias="type" />
teichmann@7401:        </dc:properties>
teichmann@7401: 
teichmann@7401:        <cars>
teichmann@7401:          <dc:for-each>
teichmann@7401:            <car type="$type" brand="$brand" />
teichmann@7401:          </dc:for-each>
teichmann@7401:        </cars>
teichmann@7401:     </dc:container-context>
teichmann@7401: 
teichmann@7401: liefert dann folgende Ausgabe:
teichmann@7401: 
teichmann@7401: .. code:: xml
teichmann@7401: 
teichmann@7401:    <cars>
teichmann@7401:      <car type="V80" brand="Volvo" />
teichmann@7401:      <car type="Testarossa" brand="Ferrari" />
teichmann@7401:    </cars>
teichmann@7401: 
teichmann@7401: 
teichmann@7255: 
teichmann@7318: ``dc:virtual-column`` Virtuelle Spalten definieren
teichmann@7318: ..................................................
teichmann@7318: 
teichmann@7318: .. code:: xml
teichmann@7318: 
teichmann@7318:     <dc:virtual-column name="Name" type="Type" expr="XPath-Ausdruck">
teichmann@7318:       ...
teichmann@7318:     </dc:virtual-column>
teichmann@7318: 
teichmann@7318: Definiert eine neue, virtuelle Spalte namens Name für den aktuellen Datensatz.
teichmann@7318: Der Typ wird optional durch Typ festgelegt; ohne Angabe wird der Typ String angenommen.
teichmann@7318: Die Wertebelegung ergibt sich aus der zeilenweisen Auswertung des XPath-Ausdrucks.
teichmann@7318: 
teichmann@7318: Dies sei an folgendem Beispiel illustriert:
teichmann@7318: 
teichmann@7318:  +----+
teichmann@7318:  +Zahl+
teichmann@7318:  +====+
teichmann@7318:  +   1+
teichmann@7318:  +----+
teichmann@7318:  +   2+
teichmann@7318:  +----+
teichmann@7318:  +   3+
teichmann@7318:  +----+
teichmann@7318: 
teichmann@7318: .. code:: xml
teichmann@7318: 
teichmann@7318:     <dc:virtual-column name="Quadrat" type="number" expr="$Zahl * $Zahl">
teichmann@7318:       ...
teichmann@7318:     </dc:virtual-column>
teichmann@7318: 
teichmann@7318: Erzeugt einen neuen Datensatz folgender Struktur:
teichmann@7318: 
teichmann@7318:  +----+-------+
teichmann@7318:  +Zahl+Quadrat+
teichmann@7318:  +====+=======+
teichmann@7318:  +   1+      1+
teichmann@7318:  +----+-------+
teichmann@7318:  +   2+      4+
teichmann@7318:  +----+-------+
teichmann@7318:  +   3+      9+
teichmann@7318:  +----+-------+
teichmann@7318: 
teichmann@7318: Innerhalb eines `virtual-column`-Elementes kann der Datensatz mittel `dc:for-each` wie
teichmann@7319: gewohnt realisiert werden. Wird das `dc:virtual-column`-Element verlassen, gilt wieder
teichmann@7318: der vormalige Datensatz ohne die zusätzlich Spalte.
teichmann@7314: 
teichmann@7314: Datensätze einschränken
teichmann@7314: ~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7314: 
teichmann@7321: ``dc:filter`` Selektieren einzelner Zeilen aus dem aktuellen Datensatz
teichmann@7321: ......................................................................
teichmann@7321: 
teichmann@7321: .. code:: xml
teichmann@7321: 
teichmann@7321:     <dc:filter expr="XPath-Ausdruck">
teichmann@7321:       ...
teichmann@7322:     </dc:filter>
teichmann@7321: 
teichmann@7321: Evaluiert pro Zeile des aktuellen Datensatzes den XPath-Ausdruck 'expr' und erzeugt
teichmann@7321: einen neuen Datensatz, der nur die Zeilen des Originaldatensatzes enthält für den
teichmann@7321: die Auswertung logisch wahr ergab. Im XPath-Ausdruck stehen die aufgefalteten Werte
teichmann@7321: der jeweiligen Zeile zur Verfügung.
teichmann@7321: 
teichmann@7322: Folgends Beispiel soll dies verdeutlichen:
teichmann@7321: 
teichmann@7321:  +----+
teichmann@7321:  +Zahl+
teichmann@7321:  +====+
teichmann@7321:  +   1+
teichmann@7321:  +----+
teichmann@7321:  +   2+
teichmann@7321:  +----+
teichmann@7321:  +   3+
teichmann@7321:  +----+
teichmann@7321:  +   4+
teichmann@7321:  +----+
teichmann@7321: 
teichmann@7321: Zahlen erhalten, die einen Wert kleiner drei haben.
teichmann@7321: 
teichmann@7321: .. code:: xml
teichmann@7321: 
teichmann@7321:     <dc:filter expr="$Zahl &lt; 3">
teichmann@7321:       ...
teichmann@7321:     <dc:filter>
teichmann@7321: 
teichmann@7321: Dies erzeugt folgenden neuen Datensatz:
teichmann@7321: 
teichmann@7321:  +----+
teichmann@7321:  +Zahl+
teichmann@7321:  +====+
teichmann@7321:  +   1+
teichmann@7321:  +----+
teichmann@7321:  +   2+
teichmann@7321:  +----+
teichmann@7321: 
teichmann@7321: Innerhalb des `dc:filter`-Elementes kann der neue Datensatz wie gewohnt mit `dc:for-each`
teichmann@7321: realisiert werden. Nach Verlassen des `dc:filter`-Elementes ist wieder der vormalige
teichmann@7321: Datensatz aktuell.
teichmann@7314: 
teichmann@7410: .. _dc:group:
teichmann@7410: 
tom@8077: ``dc:group`` Datensätze in Gruppen ordnen
teichmann@7322: ..........................................
teichmann@7322: 
teichmann@7322: .. code:: xml
teichmann@7322: 
teichmann@7322:     <dc:group expr="XPath-Ausdruck">
teichmann@7322:       ...
teichmann@7322:     </dc:group>
teichmann@7322: 
tom@8077: Pro Zeile des Originaldatensatzes wird der XPath-Ausdruck 'expr' ausgewertet.
teichmann@7322: Wie bei `dc:filter` stehen hier die aufgefalteten Werte der einzelnen Spalten zur
teichmann@7322: Verfügung. Das Resultat der XPath-Auswertung wird als Schlüssel für zu erzeugende
teichmann@7322: Gruppen benutzt, denen dann die Zeilen zugeordnet werden.
teichmann@7322: Nachdem alle Zeilen ihren entsprechenden Gruppen zugeordnet wurden, wir der
teichmann@7322: Inhalt des `dc:group`-Elements für jede Gruppe durchlaufen. Innerhalb des
teichmann@7322: `dc:group`-Elementes steht der jeweilige Schlüssel der aktuellen Gruppe über
teichmann@7322: die Funktion `dc:group-key()` zur Auswertung zu Verfügung. Innerhalb der
tom@8077: jeweiligen Gruppen kann mittels `dc:for-each` der jeweilige Unterdatensatz
teichmann@7322: realisiert werden.
teichmann@7322: 
teichmann@7322: Zur Verdeutlichung folgendes Beispiel:
teichmann@7322: 
teichmann@7322:  +-------+-----------+
teichmann@7322:  +Marke  +Bezeichnung+
teichmann@7322:  +=======+===========+
teichmann@7322:  +Ferrari+Testarossa +
teichmann@7322:  +-------+-----------+
teichmann@7322:  +Volvo  +V40        +
teichmann@7322:  +-------+-----------+
teichmann@7322:  +Volvo  +780        +
teichmann@7322:  +-------+-----------+
teichmann@7322:  +Ferrari+F40        +
teichmann@7322:  +-------+-----------+
teichmann@7322:  +VW     +Käfer      +
teichmann@7322:  +-------+-----------+
teichmann@7322: 
teichmann@7322: .. code:: xml
teichmann@7322: 
teichmann@7322:     <marken>
teichmann@7322:       <dc:group expr="$Marke">
teichmann@7322:         <marke name="{dc:group-key()}">
teichmann@7322:            <dc:for-each>
teichmann@7322:               <bezeichnung name="$Bezeichnung"/>
teichmann@7322:            </dc:for-each>
teichmann@7322:         </marke>
teichmann@7322:       </dc:group>
teichmann@7322:     </marken>
teichmann@7322: 
teichmann@7322: Dies führt zu folgender Ausgabe:
teichmann@7322: 
teichmann@7322: .. code:: xml
teichmann@7322: 
teichmann@7322:     <marken>
teichmann@7322:       <marke name="Ferrari">
teichmann@7322:         <bezeichnung name="F40"/>
teichmann@7322:         <bezeichnung name="Testarossa"/>
teichmann@7322:       </marke>
teichmann@7322:       <marke name="Volvo">
teichmann@7322:         <bezeichnung name="V40"/>
teichmann@7322:         <bezeichnung name="780"/>
teichmann@7322:       </marke>
teichmann@7322:       <marke name="VW">
teichmann@7322:         <bezeichnung name="Käfer"/>
teichmann@7322:       </marke>
teichmann@7322:     </marken>
teichmann@7314: 
teichmann@7960: Der Expr-Ausdruck kann mittels der Zeichenfolge '#!#' innerhalb des Ausdrucks
teichmann@7960: in mehrere Ausdrücke zerlegt werden. Damit ist es möglich, einen Wert
teichmann@7960: in mehrere Kategorien einzusortieren. Wird z.B. ein Film über den Zeitraum
teichmann@7960: von zwei Jahren gedreht und man möchte eine Liste von Filmen nach ihren
teichmann@7960: Produktionsjahren gruppieren, sollte der Film im Resulat in beiden Jahren auftauchen.
teichmann@7960: 
teichmann@7960: .. code:: xml
teichmann@7960: 
teichmann@7960:     <dc:group expr="$start_jahr #!# $end_jahr">
teichmann@7960: 
teichmann@7314: Datensätze auffalten
teichmann@7314: ~~~~~~~~~~~~~~~~~~~~
teichmann@7314: 
teichmann@7319: ``dc:for-each`` Realisieren eines Datensatzes
teichmann@7319: .............................................
teichmann@7319: 
teichmann@7319: .. code:: xml
teichmann@7319: 
teichmann@7319:     <dc:for-each>
teichmann@7319:       ...
teichmann@7319:     <dc:for-each>
teichmann@7319: 
teichmann@7319: Erzeugt nacheinander alle zeilenweisen Realisationen des aktuellen Datensatzes. Die
teichmann@7319: einzelnen Spaltenwerte sind dann über Variablen erreichbar, die nach den Spaltenbezeichnern
teichmann@7319: des Datenstzes benannt sind.
teichmann@7319: 
teichmann@7319: Folgendes Beispiel soll den Sachverhalt illustieren:
teichmann@7319: 
teichmann@7319:  +----+
teichmann@7319:  +Zahl+
teichmann@7319:  +====+
teichmann@7319:  +   1+
teichmann@7319:  +----+
teichmann@7319:  +   2+
teichmann@7319:  +----+
teichmann@7319:  +   3+
teichmann@7319:  +----+
teichmann@7319: 
teichmann@7319: .. code:: xml
teichmann@7319: 
teichmann@7319:     <zahlen>
teichmann@7319:       <dc:for-each>
teichmann@7319:         <zahl wert="$Zahl"/>
teichmann@7319:       <dc:for-each>
teichmann@7319:     </zahlen>
teichmann@7319: 
teichmann@7319: Dies erzeugt folgende Ausgabe:
teichmann@7319: 
teichmann@7319: .. code:: xml
teichmann@7319: 
teichmann@7319:     <zahlen>
teichmann@7319:         <zahl wert="1"/>
teichmann@7319:         <zahl wert="2"/>
teichmann@7319:         <zahl wert="3"/>
teichmann@7319:     </zahlen>
teichmann@7255: 
teichmann@7255: ``dc:iterate`` **TODO**
teichmann@7255: 
teichmann@7320: Bedingte Ausführung
teichmann@7320: ~~~~~~~~~~~~~~~~~~~
teichmann@7320: 
teichmann@7320: ``<dc:if>`` Einfaches Wenn-Dann ohne Sonst-Fall
teichmann@7320: ...............................................
teichmann@7320: 
teichmann@7320: .. code:: xml
teichmann@7320: 
teichmann@7320:     <dc:if test="XPath-Ausdruck">
teichmann@7320:       ...
teichmann@7320:     </dc:if>
teichmann@7320: 
teichmann@7320: Der innere Teil wird nur dann betreten, wenn der XPath-Ausdruck zu
teichmann@7320: logisch wahr evaluiert wird. Dieses Konstrukt kennt keinen alternativen
teichmann@7320: Pfad, der betreten wird, falls der Ausdruck zu logisch falsch ausgewertet
teichmann@7320: wird. Wird dies benötigt, muss man ``<dc:choose>`` benutzen.
teichmann@7320: ``<dc:if>`` ist in Symmetrie zu ``<xsl:if>`` von XSLT entworfen worden.
teichmann@7320: 
teichmann@7320: ``<dc:choose>`` Ketten von Wenn-Dann-Ausdrücken
teichmann@7320: ...............................................
teichmann@7320: 
teichmann@7320: .. code:: xml
teichmann@7320:     
teichmann@7320:     <dc:choose>
teichmann@7320:        <dc:when test="XPath-Ausdruck 1"> ... </dc:when>
teichmann@7320:        <dc:when test="XPath-Ausdruck 2"> ... </dc:when>
teichmann@7320:        ...
teichmann@7320:        <dc:otherwise> ...  </dc:otherwise>
teichmann@7320:     </dc:choose>
teichmann@7320: 
teichmann@7320: Es werden der Reihe nach von oben nach unter die ``test``-XPath-Ausdrücke der ``dc:when``-Elemente ausgewertet.  Evaluiert ein Ausdruck zu logisch wahr, wird der innere Teil des entsprechenden ``<dc:when>``-Elements betreten. Die verbliebenen
teichmann@7320: ``<dc:when>``- und ``<dc:otherwise>``-Elemente werden dann ignoriert. Evaluiert
teichmann@7320: keiner der ``test``-Ausdrücke zu wahr, wird der innere Teil des
teichmann@7320: ``<dc:otherwise>``-Elements betreten.
teichmann@7320: ``<dc:choose>`` ist in Symmetrie zu ``<xsl:choose>`` von XSLT entworfen worden.
teichmann@7320: 
teichmann@7320: 
teichmann@7320: 
teichmann@7314: Makros
teichmann@7314: ~~~~~~
teichmann@7317: Um innerhalb des Definitionsdokumentes Wiederholungen zu vermeiden, können sogenannte
teichmann@7317: Makros definiert werden, die dann von anderer Stellen aus eingefügt werden können.
teichmann@7255: 
teichmann@7317: ``dc:macro`` Wiederverwendbare Teile definieren
teichmann@7317: ...............................................
teichmann@7255: 
teichmann@7317: .. code:: xml
teichmann@7317: 
teichmann@7317:     <dc:macro name="Name">
teichmann@7317:       ...
teichmann@7317:     </dc:macro>
teichmann@7317: 
teichmann@7317: Definiert ein Makro namens Name. Nach der Definition ist dieses dann unter diesem
teichmann@7317: Namen global innerhalb des Definitionsdokumentes bekannt. Makros können geschachtelt
teichmann@7317: werden. Auch eingeschachtelte Makros sind global sichtbar. Die Makrodefinition und
teichmann@7317: ihre eingeschalteten Elemente werden nicht in das Ausgabedokument übernommen.
teichmann@7317: 
teichmann@7317: ``dc:call-macro`` Makros aufrufen
teichmann@7317: 
teichmann@7317: .. code:: xml
teichmann@7317: 
teichmann@7317:     <dc:call-macro name="Name">
teichmann@7317: 
teichmann@7317: Ruft ein Makro names Name auf. Dieses muss mit `dc:macro` definiert sein. Die Reihenfolge
teichmann@7317: von Definition und Aufruf ist egal.
teichmann@7317: 
teichmann@7317: ``dc:macro-body`` Elemente an ein Makro übergeben
teichmann@7317: .................................................
teichmann@7317: 
teichmann@7317: .. code:: xml
teichmann@7317: 
teichmann@7317:     <dc:macro name="Name">
teichmann@7317:       ...
teichmann@7317:       <dc:macro-body/>
teichmann@7317:       ...
teichmann@7317:     </dc:macro>
teichmann@7317: 
teichmann@7317: Um an Makros weitere Bausteine als Argument übergeben zu können, ist es optional
teichmann@7317: möglich innerhalb einer Makrodefinition ein Element `dc:macro-body` einzufügen.
teichmann@7317: Dieses Element expandiert sich zum Inhalt des `dc:call-macro`-Aufrufs.
teichmann@7317: 
teichmann@7317: .. code:: xml
teichmann@7317: 
teichmann@7317:     <dc:call-macro name="Name">Inhalt von dc:macro-body</dc:call-macro>
teichmann@7317: 
teichmann@7317: Zur Verdeutlichung ein konkretes Beispiel
teichmann@7317: 
teichmann@7317: .. code:: xml
teichmann@7317: 
teichmann@7317:     <dc:macro name="Greetings">
teichmann@7317:       <Hallo>
teichmann@7317:           <dc:macro-body/>
teichmann@7317:       </Hallo>
teichmann@7317:     </dc:macro>
teichmann@7317: 
teichmann@7317:     <dc:call-macro name="Greetings">Welt</dc:call-macro>
teichmann@7317:     <dc:call-macro name="Greetings">Mond</dc:call-macro>
teichmann@7317: 
teichmann@7317: Dies produziert folgende Ausgabe
teichmann@7317: 
teichmann@7317: .. code:: xml
teichmann@7317: 
teichmann@7317:     <Hallo>Welt</Hallo>
teichmann@7317:     <Hallo>Mond</Hallo>
teichmann@7317: 
teichmann@7317: Das Haupteinsatzgebiet dieses Konstruktes ist die transparente Bereitstellung
teichmann@7317: von Kontexten, die dann verschiedentlich ausgewertet werden sollen.
teichmann@7255: 
teichmann@7314: Sonstige Elemente
teichmann@7314: ~~~~~~~~~~~~~~~~~
teichmann@7255: 
teichmann@7314: ``dc:element`` Hinzufügen neuer Elemente in der Ausgabe
teichmann@7314: .......................................................
teichmann@7255: 
teichmann@7314: .. code:: xml
teichmann@7314: 
teichmann@7314:     <dc:element name="Name">
teichmann@7314:       ...
teichmann@7314:     </dc:element>
teichmann@7314: 
teichmann@7314: Erzeugt ein Element namens Name. Für den Namen gelten die `${}-Ersetzungen`_.
teichmann@7314: 
teichmann@7314: 
teichmann@7314: ``dc:attribute`` Hinzufügen neuer Attribute zum umgebenden Ausgabeelement
teichmann@7314: .........................................................................
teichmann@7314: 
teichmann@7314: .. code:: xml
teichmann@7314: 
teichmann@7314:     <dc:attribute name="Name" value="Wert"/>
teichmann@7314: 
teichmann@7314: Fügt dem umgebenden Ausgabeelement ein weiteres Attribut namens Name mit dem
teichmann@7314: Wert von Wert hinzu. Für Namen und Wert gelten die `${}-Ersetzungen`_.
teichmann@7314: Der Einsatz dieses Konstrukts findet häufig im Zusammenhang mit dc:element
teichmann@7314: seinen Einsatz, wenn es ein Ausgabeelement vollständig aus Variablenbelegungen
teichmann@7314: erstellt werden soll.
teichmann@7314: 
teichmann@7315: ``dc:comment`` Kommentare im Beschreibungsdokument
teichmann@7315: ..................................................
teichmann@7316: 
teichmann@7315: .. code:: xml
teichmann@7314: 
teichmann@7315:     <dc:comment>
teichmann@7315:       ...
teichmann@7315:     </dc:comment>
teichmann@7314: 
teichmann@7315: Ein Kommentar auf Ebene des Beschreibungsdokumentes, das keinerlei Ausgabe
teichmann@7315: im Ausgabedokument erzeugt. Eingeschachtelte Elemente werden ebenfalls nicht ausgewertet.
teichmann@7315: Im Gegensatz dazu werden die XML-typischen **<!-- Kommetare -->** in das Ausgabedokument übernommen!
teichmann@7315: 
teichmann@7255: 
teichmann@7316: ``dc:message`` Ausgabe auf die Diagnoseausgabe (Log)
teichmann@7316: ....................................................
teichmann@7255: 
teichmann@7316: .. code:: xml
teichmann@7255: 
teichmann@7316:     <dc:message>
teichmann@7316:       Text für die Diagnose.
teichmann@7316:     </dc:message>
teichmann@7255: 
teichmann@7316: Gibt den Text innerhalb des Elementes aus Ausgabe im Log aus. Dies dient in erster Linie
teichmann@7316: dem Nachvollziehen von Aufrufen innerhalb des Datenkorbdokumentes. Für den Text gelten
teichmann@7316: die `{$}-Ersetzungen`_.
teichmann@7316: 
teichmann@7316: ``dc:variable`` Erzeugung einer kontext-lokalen Variablen
teichmann@7316: .........................................................
teichmann@7316: 
teichmann@7316: .. code:: xml
teichmann@7316: 
teichmann@7316:     <dc:variable name="Name" type="Typ" expr="XPath-Ausdruck"/>
teichmann@7316: 
teichmann@7316: Legt im aktuellen Kontext eine lokale Variable namens Name an. Diese hat den
teichmann@7316: Typ Typ und entsteht durch Auswertung des XPath-Ausdruck expr. Der Typ
teichmann@7316: ist optional. Wird dieser nicht gesetzt, wird das Ergebnis als String interpretiert.
teichmann@7316: Alternativ können hier die Werte 'number' für Zahlen, 'bool' für Boolean-Werte
teichmann@7316: benutzt werden. Für den Namen und den Typ gelten die `${}-Ersetzungen`_.
teichmann@7316: Wird der aktuellen `dc:context` verlassen, ist diese Variable nicht mehr definiert.
teichmann@7316: 
teichmann@7316: 
teichmann@7316: ``dc:convert`` kontext-lokale Konvertierung von Variablen
teichmann@7316: .........................................................
teichmann@7316: 
teichmann@7316: .. code:: xml
teichmann@7316: 
teichmann@7316:     <dc:convert name="Name" type="Typ"/>
teichmann@7316: 
teichmann@7316: Konvertiert die Variable namens Name für die Gültigkeit des aktuellen Kontextes in
teichmann@7316: einen anderen Typ. Für Name und Typ gelten die `${}-Ersetzungen`_. Für die
teichmann@7316: Typen gilt das gleiche wie für die Typen von `dc:variable`.
teichmann@7255: 
teichmann@7255: 
teichmann@7255: Datenkorb-Funktionen
teichmann@7255: --------------------
teichmann@7255: 
teichmann@7410: ``dc:has-result`` Prüfen, ob der aktuelle Datensatz nicht leer ist
teichmann@7410: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7410: 
teichmann@7410: ``dc:has-result()`` liefert logisch wahr zurück, falls der aktuelle
teichmann@7410: Datensatz nicht leer ist, sprich Datenzeilen enthält. Ansonsten wird
teichmann@7410: logisch falsch zurück gegeben. Mittels dieser Funktion können leere
teichmann@7410: Knoten im Resultatdokument verhindert werden. Die typische Nutzung
teichmann@7410: ist daher innerhalb des ``test``-Attributs eines ``<dc:if>``-Elements.
teichmann@7410: 
teichmann@7410: ``dc:contains`` Prüfen, ob Suchbegriff in einer Liste vorhanden ist
teichmann@7410: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7410: 
tom@8431: ``dc:contains(Heuhaufen, Nadel)`` prüft ob das Suchobjekt Nadel in
teichmann@7410: der Liste Heufhaufen zu finden ist. Liefert logisch wahr falls die
teichmann@7410: Nadel gefunden wurde, ansonsten logisch falsch. Typischer Anwendungsfall:
teichmann@7410: ``dc:contains($outs, 'longitudinal-section')`` prüft, ob in der Liste
teichmann@7410: der aktuellen Outs der Eintrag 'longitudinal-section' zu finden ist.
teichmann@7410: 
teichmann@7410: ``dc:replace`` Textersatz in Strings
teichmann@7410: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7410: 
teichmann@7410: ``dc:replace(Heuhaufen, Nadel, Ersatz)`` ersetzt in im String Heuhaufen alle
teichmann@7410: Vorkommen des Strings Nadel durch den String Ersatz. ``dc:replace('Banane', 'a', 'e')``
teichmann@7410: resultiert folglich in dem String ``Benene``.
teichmann@7410: 
teichmann@7410: ``dc:replace-all`` Textersatz in Strings mit regulären Ausdrücken
teichmann@7410: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7410: 
teichmann@7410: ``dc:replace-all(Heuhaufen, Nadel, Ersatz)`` ersetzt in im String Heuhaufen alle
teichmann@7410: Vorkommen des regulären Ausdrucks durch den String Ersatz. Auf im regulären Ausdruck
teichmann@7410: gebildete Gruppen ``()`` kann mit ``$1``, ``$2``, ``$3`` usw. im Ersatztext zurückgegriffen werden.
teichmann@7410: ``dc:replace-all('KlausGabiPeter', '(Klaus|Peter)', '>$1<')`` resultiert demnach
teichmann@7410: in ``>Klaus<Gabi>Peter<``.
teichmann@7410: 
teichmann@7415: ``dc:find-all`` Extraktion von Strings aus einem String anhand eines regulären Ausdrucks
teichmann@7415: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7415: 
teichmann@7415: ``dc:find-all(Nadel, Heuhaufen)`` extrahiert aus einem String Heuhaufen all jene Substrings,
teichmann@7415: die auf den regulären Ausdruck Nadel passen. Das Resultat dieser Funktion ist eine Liste
teichmann@7415: von Strings. Sie ist leer, wenn das Muster nicht gefunden wurde.
teichmann@7415: 
teichmann@7415: ``dc:find-all('\d{4}', '1900 1930 1941 1960')`` liefert dem entsprechend die Liste
teichmann@7415: ``'1900'``, ``'1930'``, ``'1941'``, ``'1960'``.
teichmann@7415: 
teichmann@7415: ``dc:date-format`` Formatierte Ausgabe eines Datums
teichmann@7415: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7415: 
teichmann@7907: ``dc:date-format(Format, Datum)`` liefert für ein Datum einen String, der
teichmann@7415: nach den Formatierungsregeln aus Format formatiert wird. Für die Formatierungen
tom@8460: gelten die in SimpleFormat_ beschriebenen Regeln. ``Datum`` kann dabei ein
tom@8460: Datums-Objekt oder eine Zahl sein. Letztere wird als Millisekunden nach dem
tom@8460: 1.1.1970 00:00:00 GMT interpretiert.
teichmann@7415: 
teichmann@7415: .. _SimpleFormat: http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html
teichmann@7415: 
tom@8119: ``dc:date-format('dd.MM.yyyy', $datum)`` liefert für ein ``$datum``
tom@8119: mit dem Wert 1. Dezember 1941 den String ``01.12.1941``.
teichmann@7415: 
teichmann@7415: 
teichmann@7410: ``dc:group-key`` Wert des aktuellen Gruppierungsschlüssels
teichmann@7410: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7410: 
teichmann@7410: Siehe hierzu `dc:group`_.
teichmann@7410: 
teichmann@7410: ``dc:dump-variables`` Aktuelle Variablenbelegung als String
teichmann@7410: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7410: 
teichmann@7410: ``dc:dump-variables()`` liefert einen String mit der aktuellen Belegung aller Variablen.
teichmann@7410: Dies ist zusammen mit ``dc:message`` nützlich, um eine Ablaufverfolgung zu implementieren.
teichmann@7255: 
teichmann@7415: ``dc:get`` Dynamische Variablenauswertung
teichmann@7415: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7255: 
teichmann@7415: ``dc:get(Variablenname)`` ermöglicht es, eine Variable über ihren Namen als String
teichmann@7415: auszuwerten. Gegenüber der normalen XPath-Variablenauswertung kann die Variable auch
teichmann@7415: null liefern. Bis auf diese Ausnahme ist der Aufruf ``dc:get('a')`` identisch zu ``$a``
teichmann@7415: in XPath-Kontexten.
teichmann@7255: 
teichmann@7416: ``dc:max-number`` Bestimmung des Maximums einer Liste von Zahlen
teichmann@7416: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7255: 
teichmann@7416: ``dc:max-number($liste)`` Ermittelt aus einer Liste von Zahlen das Maximum. Strings werden dabei in Zahlen umgewandelt.
teichmann@7416: 
teichmann@7416: ``dc:max-number(dc:find-all('\d{4}', '1900 1930 1941 1960'))`` liefert also ``1960``.
teichmann@7416: 
teichmann@7416: 
teichmann@7416: ``dc:min-number`` Bestimmung des Minimums einer Liste von Zahlen
teichmann@7416: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
teichmann@7416: 
teichmann@7416: ``dc:min-number($liste)`` Ermittelt aus einer Liste von Zahlen das Minimum. Strings werden dabei in Zahlen umgewandelt.
teichmann@7416: 
teichmann@7416: ``dc:min-number(dc:find-all('\d{4}', '1900 1930 1941 1960'))`` liefert also ``1960``.
teichmann@7416: 
teichmann@7416: 
teichmann@7416: 
teichmann@7255: 
teichmann@7415: ``dc:fromValue`` **TODO**
teichmann@7400: 
teichmann@7415: ``dc:toValue`` **TODO**
teichmann@7415: 
tom@8306: ``dc:coalesce`` **TODO**
tom@8306: