=========
Datenkorb
=========


.. contents:: Inhalt

Übersicht
---------

Daten
-----
Im Datenkorb stehen zwei Arten von Daten zur Auswertung zur Verfügung.

``Datensätze``
~~~~~~~~~~~~~~
Datensätze sind Tabellen mit benannten Spalten. Sie werden von Datenquellen
erzeugt und in einem Stapel verwaltet. Die konkreten Werte stehen erst durch
Auffaltung als Variablen zur Verfügung.


``Variablen``
~~~~~~~~~~~~~
Variablen sind die Werte, die aktuell zur Auswertung zur Verfügung stehen. Sie haben
einen Namen und einen Typ (String, Zahl, durch Datenquelle bestimmt).

Textersatz
----------
Um die Wertebelegungen in das Ausgabedokument schreiben zu kann an entsprechenden
Stellen eine String-Interpolation durchgeführt werden.
Hier finden zwei Arten von Textersatz ihren Einsatz.

``${}-Ersetzungen``
~~~~~~~~~~~~~~~~~~~
Die ältere Variante. Innerhalb von Strings werden hier nur Variablen aufgelöst.
Beispiel: "**Hallo, ${planet}!**" wird bei planet = 'Welt' zu "**Hallo, Welt!**".

``{$}-Ersetzungen``
~~~~~~~~~~~~~~~~~~~
Die neuere Variante, allerdings noch nicht komplett an allen Stellen einsatzfähig.
Innerhalb der geschweiften Klammern können beliebige XPath-Ausdrück stehen, die
zu Strings evaluiert werden. Dies orientiert sich an den String-Auswertungen in XSLT.
"**{ concat($greet, ', ', $planet, '!') }**" wird bei gesetzten Variablen greet = Hallo
und planet = "Welt" zu **Hallo, Welt!** ausgewertet.

Datenkorb-Elemente
------------------

Datensätze erzeugen
~~~~~~~~~~~~~~~~~~~

``dc:context`` **TODO**

``dc:statement`` **TODO**

``dc:container-context`` **TODO**

``dc:properties`` **TODO**

``dc:virtual-column`` **TODO**

Datensätze einschränken
~~~~~~~~~~~~~~~~~~~~~~~

``dc:filter`` **TODO**

``dc:group`` **TODO**

Datensätze auffalten
~~~~~~~~~~~~~~~~~~~~

``dc:for-each`` **TODO**

``dc:iterate`` **TODO**

Makros
~~~~~~

``dc:macro`` **TODO**

``dc:macro-body`` **TODO**

``dc:call-macro`` **TODO**

Sonstige Elemente
~~~~~~~~~~~~~~~~~

``dc:element`` Hinzufügen neuer Elemente in der Ausgabe
.......................................................

.. code:: xml

    <dc:element name="Name">
      ...
    </dc:element>

Erzeugt ein Element namens Name. Für den Namen gelten die `${}-Ersetzungen`_.


``dc:attribute`` Hinzufügen neuer Attribute zum umgebenden Ausgabeelement
.........................................................................

.. code:: xml

    <dc:attribute name="Name" value="Wert"/>

Fügt dem umgebenden Ausgabeelement ein weiteres Attribut namens Name mit dem
Wert von Wert hinzu. Für Namen und Wert gelten die `${}-Ersetzungen`_.
Der Einsatz dieses Konstrukts findet häufig im Zusammenhang mit dc:element
seinen Einsatz, wenn es ein Ausgabeelement vollständig aus Variablenbelegungen
erstellt werden soll.




``dc:comment`` **TODO**

``dc:message`` **TODO**

``dc:variable`` **TODO**

``dc:convert`` **TODO**


Bedingte Ausführung
~~~~~~~~~~~~~~~~~~~

``<dc:if>`` Einfaches Wenn-Dann ohne Sonst-Fall
...............................................

.. code:: xml

    <dc:if test="XPath-Ausdruck">
      ...
    </dc:if>

Der innere Teil wird nur dann betreten, wenn der XPath-Ausdruck zu
logisch wahr evaluiert wird. Dieses Konstrukt kennt keinen alternativen
Pfad, der betreten wird, falls der Ausdruck zu logisch falsch ausgewertet
wird. Wird dies benötigt, muss man ``<dc:choose>`` benutzen.
``<dc:if>`` ist in Symmetrie zu ``<xsl:if>`` von XSLT entworfen worden.

``<dc:choose>`` Ketten von Wenn-Dann-Ausdrücken
...............................................

.. code:: xml
    
    <dc:choose>
       <dc:when test="XPath-Ausdruck 1"> ... </dc:when>
       <dc:when test="XPath-Ausdruck 2"> ... </dc:when>
       ...
       <dc:otherwise> ...  </dc:otherwise>
    </dc:choose>

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
``<dc:when>``- und ``<dc:otherwise>``-Elemente werden dann ignoriert. Evaluiert
keiner der ``test``-Ausdrücke zu wahr, wird der innere Teil des
``<dc:otherwise>``-Elements betreten.
``<dc:choose>`` ist in Symmetrie zu ``<xsl:choose>`` von XSLT entworfen worden.



Datenkorb-Funktionen
--------------------

``dc:contains`` **TODO**

``dc:fromValue`` **TODO**

``dc:toValue`` **TODO**

``dc:replace`` **TODO**

``dc:replace-all`` **TODO**

``dc:has-result`` **TODO**

``dc:group-key`` **TODO**

``dc:date-format`` **TODO**

``dc:dump-variables`` **TODO**

``dc:get`` **TODO**