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

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

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

    <para>
        Die CSS Selektor Schreibweise wird als einfachere und für Web Entwickler bekannterer Weg angeboten um
        bei der Anfrage von Dokumenten mit XML 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 SCC 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 <code>query()</code> oder die <code>queryXpath()</code> 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 CSS 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>: CSS 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  das 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 Atribut enthält den String:
                        'div[bar*="baz"]' würde einem Div Element mit einem "bar" Attribut entsprechen das den
                        String "baz" irgendwo in Ihm 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
                Abhängig von 'div' sind. Kann auch mit jedem Selektor darüber verwendet werden.
            </para></listitem>

            <listitem>
                <para>
                    <emphasis>Abhängigkeit</emphasis>: Mehrere Selektoren zusammenschreiben um eine
                    Hirarchie 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 abhängig ist von einer Klase von 'foo', welche in einer
                    beliebigen Tiefe abhängig ist von einem 'div' Element. Der Link zum Wort 'One' im
                    Beispiel anbei würde passen:
                </para>

                <programlisting role="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 role="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
            <code>queryXpath()</code> 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>
                    <code>setDocumentXml($document)</code>: Spezifiziert einen XML String der Abgefragt
                    werden soll.
                </para></listitem>

                <listitem><para>
                    <code>setDocumentXhtml($document)</code>: Spezifiziert einen XHTML String der Abgefragt
                    werden soll.
                </para></listitem>

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

                <listitem><para>
                    <code>setDocument($document)</code>: 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>
                    <code>getDocument()</code>: Empfängt den String des Original Dokuments das an das Objekt
                    übergeben wurde.
                </para></listitem>

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

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

                <listitem><para>
                    <code>queryXpath($xPathQuery)</code>: 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 <code>count()</code> Funktion. Zusätzlich bietet es die
                folgenden Methoden an:
            </para>

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

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

                <listitem><para>
                    <code>getDocument()</code>: Empfängt das DOMDocument auf das die Abfrage ausgeführt wurde.
                </para></listitem>
            </itemizedlist>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->