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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 17600 -->
<!-- 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
        <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 einfachere 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 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 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 das 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>
<!--
vim:se ts=4 sw=4 et:
-->