[PATCH] Datacage doc ref: Explain dc:group

[Wald Commits]

# HG changeset patch
# User Sascha L. Teichmann <teichmann at intevation.de>
# Date 1381761496 -7200
# Node ID 7be4425eaca9caacafdaeacde46ad8811d2e9a4e
# Parent  b33a2a437ab8c087bc4dd54ef853264cee98be10
Datacage doc ref: Explain dc:group

diff -r b33a2a437ab8 -r 7be4425eaca9 artifacts/doc/datacage_ref_de.rst
--- a/artifacts/doc/datacage_ref_de.rst	Mon Oct 14 16:06:36 2013 +0200
+++ b/artifacts/doc/datacage_ref_de.rst	Mon Oct 14 16:38:16 2013 +0200
@@ -156,14 +156,14 @@
 
     <dc:filter expr="XPath-Ausdruck">
       ...
-    <dc:filter>
+    </dc:filter>
 
 Evaluiert pro Zeile des aktuellen Datensatzes den XPath-Ausdruck 'expr' und erzeugt
 einen neuen Datensatz, der nur die Zeilen des Originaldatensatzes enthält für den
 die Auswertung logisch wahr ergab. Im XPath-Ausdruck stehen die aufgefalteten Werte
 der jeweiligen Zeile zur Verfügung.
 
-Folgends Beipiel soll dies verdeutlichen:
+Folgends Beispiel soll dies verdeutlichen:
 
  +----+
  +Zahl+
@@ -199,7 +199,71 @@
 realisiert werden. Nach Verlassen des `dc:filter`-Elementes ist wieder der vormalige
 Datensatz aktuell.
 
-``dc:group`` **TODO**
+``dc:group`` Datensätzen in Gruppen ordnen
+..........................................
+
+.. code:: xml
+
+    <dc:group expr="XPath-Ausdruck">
+      ...
+    </dc:group>
+
+Pro Zeile der Originaldatensatzes wird der XPath-Ausdruck 'expr' ausgewertet.
+Wie bei `dc:filter` stehen hier die aufgefalteten Werte der einzelnen Spalten zur
+Verfügung. Das Resultat der XPath-Auswertung wird als Schlüssel für zu erzeugende
+Gruppen benutzt, denen dann die Zeilen zugeordnet werden.
+Nachdem alle Zeilen ihren entsprechenden Gruppen zugeordnet wurden, wir der
+Inhalt des `dc:group`-Elements für jede Gruppe durchlaufen. Innerhalb des
+`dc:group`-Elementes steht der jeweilige Schlüssel der aktuellen Gruppe über
+die Funktion `dc:group-key()` zur Auswertung zu Verfügung. Innerhalb der
+jeweiligen Gruppen kann mittel `dc:for-each` der jeweilige Unterdatensatz
+realisiert werden.
+
+Zur Verdeutlichung folgendes Beispiel:
+
+ +-------+-----------+
+ +Marke  +Bezeichnung+
+ +=======+===========+
+ +Ferrari+Testarossa +
+ +-------+-----------+
+ +Volvo  +V40        +
+ +-------+-----------+
+ +Volvo  +780        +
+ +-------+-----------+
+ +Ferrari+F40        +
+ +-------+-----------+
+ +VW     +Käfer      +
+ +-------+-----------+
+
+.. code:: xml
+
+    <marken>
+      <dc:group expr="$Marke">
+        <marke name="{dc:group-key()}">
+           <dc:for-each>
+              <bezeichnung name="$Bezeichnung"/>
+           </dc:for-each>
+        </marke>
+      </dc:group>
+    </marken>
+
+Dies führt zu folgender Ausgabe:
+
+.. code:: xml
+
+    <marken>
+      <marke name="Ferrari">
+        <bezeichnung name="F40"/>
+        <bezeichnung name="Testarossa"/>
+      </marke>
+      <marke name="Volvo">
+        <bezeichnung name="V40"/>
+        <bezeichnung name="780"/>
+      </marke>
+      <marke name="VW">
+        <bezeichnung name="Käfer"/>
+      </marke>
+    </marken>
 
 Datensätze auffalten
 ~~~~~~~~~~~~~~~~~~~~