[PATCH] Datacage reference doc: Explain dc:container-context and dc:properties

[Wald Commits]

# HG changeset patch
# User Sascha L. Teichmann <teichmann at intevation.de>
# Date 1382350960 -7200
# Node ID bbf758e594bbe63c8fc013c7857bcf013fa09aa3
# Parent  dd87e0a5f83c5c0ec633e6a6534581c2a938d3d8
Datacage reference doc: Explain dc:container-context and dc:properties.

diff -r dd87e0a5f83c -r bbf758e594bb artifacts/doc/datacage_ref_de.rst
--- a/artifacts/doc/datacage_ref_de.rst	Mon Oct 21 11:43:50 2013 +0200
+++ b/artifacts/doc/datacage_ref_de.rst	Mon Oct 21 12:22:40 2013 +0200
@@ -142,9 +142,102 @@
 ``dc:container-context`` Tabellarische Daten aus der Programm-Umgebung
 ......................................................................
 
-**TODO**
+.. code:: xml
 
-``dc:properties`` **TODO**
+    <dc:container-context container="Container">
+       ...
+    </dc:container-context>
+
+Dies spannt einen Kontext auf einem Container namens Container auf,
+einer listen-ähnlichen Struktur, die als externe Datenquellen in
+Form eines Java-Objekts an den Datenkorb übergeben werden kann.
+Dies müssen Klassen sein, die das Interface ``java.util.Collection``
+implementieren. Mit diesem Konstrukt ist es möglich, tabellarische
+Ergebnisse von außen in die Auswertung des Datenkorbs zu integrieren.
+Der Container muss hierfür über die Variable ``Container`` zur Verfügung
+gestellt werden. Die Spalten des Tabelle werden über ``dc:properties``
+definiert. Der Datensatz selbst kann wie gewohnt mittels ``dc:for-each``
+realisiert werden.
+
+``dc:properties`` Spaltendefinitionen für externe Daten aus der Programm-Umgebung
+.................................................................................
+
+.. code:: xml
+
+    <dc:container-context container="Container">
+       <dc:properties>
+          <dc:property name="name" alias="alias"/>
+       </dc:properties>
+    </dc:container-context>
+
+Muss innerhalb eines ``dc:container-context`` angegeben werden und enthält eine
+Liste von Attributen der Java-Objekte, die in den Datenkorb eingeblendet werden sollen.
+Die Auflösung der Namen auf der Java-Seite funktioniert nach Konvention von Java-Beans,
+sprich aus ``name`` wird ``getName``. ``alias`` ist optional und weisst explizit einen
+Spaltennamen aus. Dies entspricht im Wesentlichen einen 'AS' bei einem SQL-Statement.
+
+Ein vollständigeres Beispiel könnte in etwa so aussehen.
+Die Java-Seite:
+
+.. code:: java
+
+   public class Car {
+
+      private String marke;
+      private String name;
+
+      public Car(String marke, String name) {
+          this.marke = marke;
+          this.name = name;
+      }
+
+      public String getMarke() {
+          return marke;
+      }
+
+      public String getName() {
+          return name;
+      }
+   }
+
+   // Liste befuellen.
+
+   java.util.Container<Car> container = new java.util.ArrayList<Car>();
+
+   container.add(new Car("Volvo", "V80"));
+   container.add(new Car("Ferrari", "Testarossa"));
+
+   // Dem Datenkorb uebergeben.
+
+   parameters.put("CARS", cars);
+
+Das Datenkorb-Schnipsel
+
+.. code:: xml
+
+    <dc:container-context container="cars">
+       <dc:properties>
+          <dc:property name="marke" alias="brand" />
+          <dc:property name="name" alias="type" />
+       </dc:properties>
+
+       <cars>
+         <dc:for-each>
+           <car type="$type" brand="$brand" />
+         </dc:for-each>
+       </cars>
+    </dc:container-context>
+
+liefert dann folgende Ausgabe:
+
+.. code:: xml
+
+   <cars>
+     <car type="V80" brand="Volvo" />
+     <car type="Testarossa" brand="Ferrari" />
+   </cars>
+
+
 
 ``dc:virtual-column`` Virtuelle Spalten definieren
 ..................................................