repo_zf1/documentation/manual/de/module_specs/Zend_Dom-Query.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 17600 -->
<!-- Reviewed: 17600 -->
<sect1 id="zend.dom.query">
    <title>Zend_Dom_Query</title>

    <para>
        <classname>Zend_Dom_Query</classname> bietet einen Mechanismus für die Abfrage von
        <acronym>XML</acronym> und (X)HTML Dokumenten indem entweder XPath oder
        <acronym>CSS</acronym> Selektoren verwendet werden. Sie wurde entwickelt um bei funktionalem
        Testen von <acronym>MVC</acronym> Anwendungen zu helfen, könnte aber auch für schnelle
        Entwicklung von Screen Scraper verwendet werden.
    </para>

    <para>
        Die <acronym>CSS</acronym> Selektor Schreibweise wird als einfacherer und für Web Entwickler
        bekannterer Weg angeboten um bei der Anfrage von Dokumenten mit <acronym>XML</acronym>
        Strukturen zu helfen. Diese Schreibweise sollte jedem, der Cascading Style Sheets entwickelt
        hat, bekannt sein, oder jedem, der Javascript Toolkits verwendet, die Funktionalität für das
        Auswählen von Knoten bei der Anpassung von <acronym>CSS</acronym> Selektoren anbieten
        (<ulink url="http://prototypejs.org/api/utility/dollar-dollar">Prototype's $$()</ulink> und
        <ulink url="http://api.dojotoolkit.org/jsdoc/dojo/HEAD/dojo.query">Dojo's
            dojo.query</ulink> sind beides Inspirationen für diese Komponente).
    </para>

    <sect2 id="zend.dom.query.operation">
        <title>Theorie der Anwendung</title>

        <para>
            Um <classname>Zend_Dom_Query</classname> zu verwenden muß ein
            <classname>Zend_Dom_Query</classname> Objekt instanziert werden, optional kann ein zu
            parsendes Dokument (ein String) übergeben werden. Sobald man ein Dokument hat, kann die
            <methodname>query()</methodname> oder die <methodname>queryXpath()</methodname> Methode
            verwendet werden; jede Methode gibt ein <classname>Zend_Dom_Query_Result</classname>
            Objekt mit allen passenden Knoten zurück.
        </para>

        <para>
            Der grundsätzliche Unterschied zwischen <classname>Zend_Dom_Query</classname> und der
            Verwendung von DOMDocument + DOMXPath ist die Möglichkeit <acronym>CSS</acronym>
            Selektoren auszuwählen. Alle folgenden Elemente können in jeder Kombination verwendet
            werden:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Element Typen</emphasis>: Bietet einen Elementtypen an, der zu den
                    folgenden passt: 'div', 'a', 'span', 'h2', usw.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Stil Attribute</emphasis>: <acronym>CSS</acronym> Stil Attribute
                    passen zu folgenden: '.error', 'div.error', 'label.required', usw. Wenn ein
                    Element mehr als einen Stil definiert, wird er entsprechen solange der benannte
                    Stil irgendwo in der Stil Definition vorhanden ist.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Id Attribute</emphasis>: ID Attribute von Elementen passen zu
                    folgenden: '#content', 'div#nav', usw.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Andere Attribute</emphasis>: Andere Attribute von Elementen die
                    passen. Drei verschiedene Typen die passen werden angeboten:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <emphasis>Exakte Entsprechung</emphasis>: Das Attribute passt exakt zum
                            String: 'div[bar="baz"]' würde zu einem Div Element mit einem "bar"
                            Attribut passen das exakt den Wert "baz" enthält.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>Wort Entsprechung</emphasis>: Das Attribut enthält ein Wort
                            das dem String entspricht: 'div[bar~="baz"]' würde einem Div Element mit
                            einem "bat" Attribut entsprechen, dass das Wort "baz" enthält.
                            '&lt;div bar="foo baz"&gt;' würde passen, aber
                            '&lt;div bar="foo bazbat"&gt;' würde nicht entsprechen.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>Substring Entsprechung</emphasis>: Das Attribut enthält den
                            String: 'div[bar*="baz"]' würde einem Div Element mit einem "bar"
                            Attribut entsprechen, das den String "baz" irgendwo darin enthält.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Direkt abhängig</emphasis>: Verwende '&gt;' zwischen Selektoren um
                    direkte Abhängigkeit auszudrücken. 'div > span' würde nur 'span' Elemente
                    auswählen, die direkt von 'div' abhängig sind. Kann auch mit jedem Selektor
                    darüber verwendet werden.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Abhängigkeit</emphasis>: Verknüpfung mehrerer Selektoren, um eine
                    Hierarchie zwischen Ihnen auszudrücken nach welcher gesucht werden soll.
                    'div .foo span #one' würde ein Element mit der Id 'one' auswählen, das abhängig
                    ist, in einer beliebigen Tiefe unter einem 'span' Element, welches seinerseits
                    in einer beliebigen Tiefe darunter von einer Klase von 'foo' abhängig ist,
                    welche in einer beliebigen Tiefe von einem 'div' Element abhängig ist. Der Link
                    zum Wort 'One' im Beispiel anbei würde passen:
                </para>

                <programlisting language="html"><![CDATA[
<div>
<table>
    <tr>
        <td class="foo">
            <div>
                Lorem ipsum <span class="bar">
                    <a href="/foo/bar" id="one">One</a>
                    <a href="/foo/baz" id="two">Two</a>
                    <a href="/foo/bat" id="three">Three</a>
                    <a href="/foo/bla" id="four">Four</a>
                </span>
            </div>
        </td>
    </tr>
</table>
</div>
]]></programlisting>
            </listitem>
        </itemizedlist>

        <para>
            Wenn man eine Abfrage ausgeführt hat, kann man mit dem Ergebnis Objekt arbeiten um
            Informationen über die Knoten zu bekommen, sowie um Sie und/oder Ihren Inhalt direkt für
            die Extrahierung und Manipulation herauszuholen.
            <classname>Zend_Dom_Query_Result</classname> implementiert <code>Countable</code> und
            <code>Iterator</code> und speichert die Ergebnisse intern als DOMNodes/DOMElements. Als
            Beispiel nehmen wir erstmal den folgenden Aufruf an der das obige HTML auswählt:
        </para>

        <programlisting language="php"><![CDATA[
$dom = new Zend_Dom_Query($html);
$results = $dom->query('.foo .bar a');

$count = count($results); // Gib die Anzahl an Gefundenen Nodes zurück: 4
foreach ($results as $result) {
    // $result ist ein DOMElement
}
]]></programlisting>

        <para>
            <classname>Zend_Dom_Query</classname> erlaubt auch strenge XPath Abfragen durch
            Verwendung der <methodname>queryXpath()</methodname> Methode; man kann eine gültige
            XPath Abfrage an diese Methode übergeben, und Sie wird ein
            <classname>Zend_Dom_Query_Result</classname> Objekt zurückgeben.
        </para>
    </sect2>

    <sect2 id="zend.dom.query.methods">
        <title>Vorhandene Methoden</title>

        <para>
            Die <classname>Zend_Dom_Query</classname> Familie an Klassen enthält die folgenden
            Methoden.
        </para>

        <sect3 id="zend.dom.query.methods.zenddomquery">
            <title>Zend_Dom_Query</title>

            <para>
                Die folgenden Methoden sind in <classname>Zend_Dom_Query</classname> vorhanden:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>setDocumentXml($document)</methodname>: Spezifiziert einen
                        <acronym>XML</acronym> String der abgefragt werden soll.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>setDocumentXhtml($document)</methodname>: Spezifiziert einen
                        <acronym>XHTML</acronym> String der abgefragt werden soll.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>setDocumentHtml($document)</methodname>: Spezifiziert einen HTML
                        String der abgefragt werden soll.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>setDocument($document)</methodname>: Spezifiziert einen String
                        der abgefragt werden soll; <classname>Zend_Dom_Query</classname> wird
                        anschließend versuchen den Typ des Dokument automatisch herauszufinden.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getDocument()</methodname>: Empfängt den String des Original
                        Dokuments welches an das Objekt übergeben wurde.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getDocumentType()</methodname>: Empfängt den Typ des Dokuments
                        das dem Objekt übergeben wurde; das wird eine der Klassenkonstanten
                        <constant>DOC_XML</constant>, <constant>DOC_XHTML</constant>, oder
                        <constant>DOC_HTML</constant> sein.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>query($query)</methodname>: Abfrage des Dokuments bei Verwendung
                        der <acronym>CSS</acronym> Selektor Schreibweise.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>queryXpath($xPathQuery)</methodname>: Abfrage des Dokuments bei
                        Verwendung der XPath Schreibweise.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.dom.query.methods.zenddomqueryresult">
            <title>Zend_Dom_Query_Result</title>

            <para>
                Wie vorher erwähnt, implementiert <classname>Zend_Dom_Query_Result</classname>
                beide, <code>Iterator</code> und <code>Countable</code>, und kann deswegen in einer
                <code>foreach</code> Schleife verwendet werden wie auch mit der
                <methodname>count()</methodname> Funktion. Zusätzlich bietet es die folgenden
                Methoden an:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>getCssQuery()</methodname>: Gibt die <acronym>CSS</acronym>
                        Selektor Abfrage zurück, die für die Erstellung des Ergebnisses verwendet
                        wurde (wenn vorhanden).
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getXpathQuery()</methodname>: Gibt die XPath Abfrage zurück die
                        für die Erstellung des Ergebnisses verwendet wurde. Intern konvertiert
                        <classname>Zend_Dom_Query</classname> <acronym>CSS</acronym> Selektor
                        Abfragen zu XPath, so das dieser Wert immer angeboten wird.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getDocument()</methodname>: Empfängt das DOMDocument auf das die
                        Abfrage ausgeführt wurde.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>
</sect1>