<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.dojo.data">
    <title>Zend_Dojo_Data: dojo.data Envelopes</title>

    <para>
        Dojo bietet Datenabstraktionen für daten-aktivierte Widgets über seine
        <command>dojo.data</command> Komponente. Diese Komponente bietet die Möglichkeit einen
        Datenspeicher hinzuzufügen, einige Metadaten betreffend dem Identifikatorfeld zu liefern und
        optional ein Labelfeld, und eine <acronym>API</acronym> für das Abfragen, Sortieren und
        Empfangen von Einträgen und Sets von Einträgen von der Datenquelle.
    </para>

    <para>
        <command>dojo.data</command> wird oft mit XmlHttpRequest verwendet um dynamisch Daten vom
        Server zu holen. Der primäre Mechanismus hierfür ist die Erweiterung von QueryReadStore um
        auf eine <acronym>URL</acronym> zu zeigen und die Anfrageinformation zu spezifizieren. Die
        Serverseite gibt dann Daten im folgenden <acronym>JSON</acronym> Format zurück:
    </para>

    <programlisting language="javascript"><![CDATA[
{
    identifier: '<name>',
    <label: '<label>',>
    items: [
        { name: '...', label: '...', someKey: '...' },
        ...
    ]
}
]]></programlisting>

    <para>
        <classname>Zend_Dojo_Data</classname> bietet ein einfaches Interface für das
        programmtechnische erstellen solcher Strukturen, der Interaktion mit Ihnen, und deren
        Serialisierung in ein Array oder <acronym>JSON</acronym>.
    </para>

    <sect2 id="zend.dojo.data.usage">
        <title>Verwendung von Zend_Dojo_Data</title>

        <para>
            In seiner einfachsten Form, verlangt <command>dojo.data</command> dass der Name des
            Identifikatorfelds in jedem Element angegeben wird, und ein Set von Elementen (Daten).
            Man kann diese entweder über den Konstruktor übergeben, oder über Mutatoren:
        </para>

        <example id="zend.dojo.data.usage.constructor">
            <title>Initialisierung von Zend_Dojo_Data über den Konstruktor</title>

            <programlisting language="php"><![CDATA[
$data = new Zend_Dojo_Data('id', $items);
]]></programlisting>
        </example>

        <example id="zend.dojo.data.usage.mutators">
            <title>Initialisierung von Zend_Dojo_Data über Mutatoren</title>

            <programlisting language="php"><![CDATA[
$data = new Zend_Dojo_Data();
$data->setIdentifier('id')
     ->addItems($items);
]]></programlisting>
        </example>

        <para>
            Man kann jederzeit ein einzelnes Element hinzufügen, oder Elemente anfügen, indem
            <methodname>addItem()</methodname> und <methodname>addItems()</methodname> verwendet
            wird.
        </para>

        <example id="zend.dojo.data.usage.append">
            <title>Hinzufügen von Daten bei Zend_Dojo_Data</title>

            <programlisting language="php"><![CDATA[
$data = new Zend_Dojo_Data($identifier, $items);
$data->addItem($someItem);

$data->addItems($someMoreItems);
]]></programlisting>
        </example>

        <note>
            <title>Immer einen Identifikator verwenden!</title>

            <para>
                Für jeden <command>dojo.data</command> Datenspeicher muß die Identifikatorspalte
                als Metadaten angegeben werden, inklusive <classname>Zend_Dojo_Data</classname>.
                Fakt ist das, wenn man versucht Elemente ohne Identifikator hinzuzufügen, eine
                Ausnahme geworfen wird.
            </para>
        </note>

        <para>
            Individuelle Elemente können die folgenden sein:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Assoziative Arrays
                </para>
            </listitem>

            <listitem>
                <para>
                    Objekte die eine <methodname>toArray()</methodname> Methode implementieren
                </para>
            </listitem>

            <listitem>
                <para>
                    Jedes andere Objekt (wird über <methodname>get_object_vars()</methodname>
                    serialisiert)
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Man kann Kollektionen der obigen Elemente über <methodname>addItems()</methodname> oder
            <methodname>setItems()</methodname> hinzufügen (überschreibt alle vorher gesetzte
            Elemente); wenn das getan wird, kann man ein einzelnes Argument setzen:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Arrays
                </para>
            </listitem>

            <listitem>
                <para>
                    Objekte die das <classname>Traversable</classname> implementieren, welches die
                    Interfaces <classname>Iterator</classname> und
                    <classname>ArrayAccess</classname> enthält.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Wenn man ein Feld spezifizieren will das als Label für das Element agieren soll, kann
            <methodname>setLabel()</methodname> aufgerufen werden:
        </para>

        <example id="zend.dojo.data.usage.label">
            <title>Spezifizierung eines Labelfeldes in Zend_Dojo_Data</title>

            <programlisting language="php"><![CDATA[
$data->setLabel('name');
]]></programlisting>
        </example>

        <para>
            Letztendlich kann man auch ein <classname>Zend_Dojo_Data</classname> Element von einem
            <command>dojo.data</command> <acronym>JSON</acronym> Array geladen werden, indem die
            <methodname>fromJson()</methodname> Methode verwendet wird.
        </para>

        <example id="zend.dojo.data.usage.populate">
            <title>Zend_Dojo_Data von JSON aus bekanntgeben</title>

            <programlisting language="php"><![CDATA[
$data->fromJson($json);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.dojo.data.metadata">
        <title>Den Containern Metadaten hinzufügen</title>

        <para>
            Einige Dojo Komponenten benötigen zusätzliche Metadaten zusammen mit dem
            <command>dojo.data</command> Payload zurückgegeben werden. Als Beispiel kann
            <command>dojox.grid.Grid</command> Daten dynamisch von einem
            <command>dojox.data.QueryReadStore</command> herausziehen. Damit die
            Seitenweise Darstellung richtig funktioniert, sollte jeder zurückgegebene
            Payload einen <property>numRows</property> Schlüssel mit der kompletten Anzahl
            an Zeilen enthalten, die von der Abfrage zurückgegeben wird. Mit diesen Daten
            weiß der Grid (a) wann er weitere kleine Anfragen an den Server
            abschicken muß für Subsets von Daten, und (b) wann er aufhören soll
            weitere Anfragen zu erstellen (z.B., wenn er die letzte Seite der Daten
            erreicht hat). Diese Technik ist nützlich wenn große Sets an Daten im
            Grid geliefert werden sollen, ohne das man das komplette Set auf einmal
            laden muß.
        </para>

        <para>
            <classname>Zend_Dojo_Data</classname> erlaubt die Zuordnung von Metadaten Eigenschaften
            zum Objekt. Das folgende zeigt die Verwendung:
        </para>

        <programlisting language="php"><![CDATA[
// Setzt "numRows" auf 100
$data->setMetadata('numRows', 100);

// Setzt verschiedene Items auf einmal:
$data->setMetadata(array(
    'numRows' => 100,
    'sort'    => 'name',
));

// Zeigt einen einzelnen Metadaten Wert:
$numRows = $data->getMetadata('numRows');

// Zeigt alle Metadaten:
$metadata = $data->getMetadata();

// Entfernt ein Metadaten Item:
$data->clearMetadata('numRows');

// Entfernt alle Metadaten:
$data->clearMetadata();
]]></programlisting>
    </sect2>

    <sect2 id="zend.dojo.data.advanced">
        <title>Gehobenere Verwendungsfälle</title>

        <para>
            Neben der Funktion als serialisierbarer Datenkontainer bietet
            <classname>Zend_Dojo_Data</classname> auch die Möglichkeit Daten auf verschiedenen Wegen
            zu manipulieren und zu durchlaufen.
        </para>

        <para>
            <classname>Zend_Dojo_Data</classname> implementiert die Interfaces
            <command>ArrayAccess</command>, <command>Iterator</command> und
            <command>Countable</command>. Deshalb kann man die Datenkollektion genauso verwenden
            kann wie wenn Sie ein Array wäre.
        </para>

        <para>
            Alle Elemente werden durch das Identifikatorfeld referenziert. Da Identifikatoren
            eindeutig sein müssen, können die Werte dieses Feldes verwendet werden um individuelle
            Einträge zu holen. Es gibt zwei Wege um das zu tun: mit der
            <methodname>getItem()</methodname> Methode, oder über die Array Schreibweise.
        </para>

        <programlisting language="php"><![CDATA[
// Verwenden von getItem():
$item = $data->getItem('foo');

// Oder verwenden der Array Schreibweise:
$item = $data['foo'];
]]></programlisting>

        <para>
            Wenn man den Identifikator kennt, kann man Ihn verwende um ein Element zu erhalten, es
            upzudaten, es zu löschen, es zu erstellen oder es zu testen:
        </para>

        <programlisting language="php"><![CDATA[
// Updaten oder Erstellen eines Elements:
$data['foo'] = array('title' => 'Foo', 'email' => 'foo@foo.com');

// Löschen eines Elements:
unset($data['foo']);

// Testen eines Elements:
if (isset($data[foo])) {
}
]]></programlisting>

        <para>
            Man kann genauso über alle Elemente iterieren. Intern werden alle Elemente als Arrays
            gespeichert.
        </para>

        <programlisting language="php"><![CDATA[
foreach ($data as $item) {
    echo $item['title'] . ': ' . $item['description'] . "\n";
}
]]></programlisting>

        <para>
            Oder Sie sogar zählen um zu sehen wie viele Elemente man hat:
        </para>

        <programlisting language="php"><![CDATA[
echo count($data), " Elemente gefunden!";
]]></programlisting>

        <para>
            Letztendlich kann man, da die Klasse <methodname>__toString()</methodname>
            implementiert, Sie auch zu <acronym>JSON</acronym> casten indem man Sie einfach ausgibt,
            oder Sie zu einem String castet:
        </para>

        <programlisting language="php"><![CDATA[
echo $data; // Ausgabe als JSON String

$json = (string) $data; // Casten zu einem String == casten zu JSON
]]></programlisting>

        <sect3 id="zend.dojo.data.advanced.methods">
            <title>Vorhandene Methoden</title>

            <para>
                Neben den Methoden die notwendig sind um die oben beschriebenen Interfaces zu
                implementieren sind die folgenden Methoden vorhanden.
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>setItems($items)</methodname>: Setzt mehrere Elemente auf
                        einmal, und überschreibt alle vorher im Objekt gesetzten.
                        <varname>$items</varname> sollte ein Array oder ein
                        <command>Traversable</command> Objekt sein.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>setItem($item, $id = null)</methodname>: Setzt ein
                        individuelles Element, indem optional ein expliziter Identifikator
                        übergeben wird. Überschreibt das Element wenn es bereits in der Kollektion
                        ist. Gültige Elemente enthalten assoziative Arrays, Objekte die
                        <methodname>toArray()</methodname> implementieren, oder jedes Objekt mit
                        öffentlichen Eigenschaften.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>addItem($item, $id = null)</methodname>: Fügt ein individuelles
                        Element hinzu, indem optional ein expliziter Identifikator übergeben wird.
                        Wirft eine Ausnahme wenn das Element bereits in der Kollektion existiert.
                        Gültige Elemente enthalten assoziative Arrays, Objekte die
                        <methodname>toArray()</methodname> implementieren, oder jedes Objekt mit
                        öffentlichen Eigenschaften.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>addItems($items)</methodname>: Fügt mehrere Elemente auf einmal
                        hinzu, indem Sie allen aktuellen Elementen angefügt werden. Wirft eine
                        Ausnahme wenn irgendeines der neuen Elemente einen Identifikator hat der zu
                        einem bereits in der Kollektion vorhandenen Identifikator passt.
                        <varname>$items</varname> sollte ein Array oder ein
                        <command>Traversable</command> Objekt sein.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getItems()</methodname>: Gibt alle Elemente als Array von
                        Arrays zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>hasItem($id)</methodname>: Erkennt ob ein Element mit dem
                        angegebenen Identifikator in der Kollektion existiert oder nicht.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getItem($id)</methodname>: Gibt ein Element mit dem angegebenen
                        Identifikator von der Kollektion zurück; das zurückgegebene Element ist ein
                        assoziatives Array. Wenn kein Element passt, wird ein
                        <constant>NULL</constant> Wert zurückgegeben.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>removeItem($id)</methodname>: Entfernt ein Element mit dem
                        angegebenen Identifikator von der Kollektion.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>clearItems()</methodname>: Entfernt alle Elemente von der
                        Kollektion.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>setIdentifier($identifier)</methodname>: Setzt den Namen des
                        Feldes das den eindeutigen Identifikator repräsentiert für jedes Element
                        in der Kollektion.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getIdentifier()</methodname>: Gibt den Namen des
                        Identifikatorfeldes zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>setLabel($label)</methodname>: Setzt den Namen eines Feldes
                        das als Anzeigelabel für ein Element verwendet wird.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getLabel()</methodname>: Gibt den Namen des Labelfeldes zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>toArray()</methodname>: Castet das Objekt zu einem Array. Das
                        Array enthält mindestens die Schlüssel 'identifier' und 'items', und den
                        Schlüssel 'label' wenn ein Labelfeld im Objekt gesetzt wurde.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>toJson()</methodname>: Castet das Objekt zu einer
                        <acronym>JSON</acronym> Repräsentation.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>
</sect1>