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

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

    <para>
        <classname>Zend_Dom_Query</classname> fournit des mécanismes pour requêter dans les
        documents <acronym>XML</acronym> et (X)HTML en utilisant soit XPath ou les sélecteurs <acronym>CSS</acronym>. Il a été développé
        pour faciliter les tests fonctionnels des applications <acronym>MVC</acronym>, mais pourrait également être
        employé pour le développement rapide de "screen scrapers".
    </para>

    <para>
        La notation de type sélecteur <acronym>CSS</acronym> est fournie comme notation plus simple et plus
        familière pour les développeurs Web à utiliser lors de la requête de documents ayant une
        structure de type <acronym>XML</acronym>. La notation devrait être familière pour n'importe qui ayant écrit
        des feuilles de styles <acronym>CSS</acronym> ou ayant utiliser des librairies Javascript qui fournissent pour
        sélectionner des noeuds en utilisant des sélecteurs <acronym>CSS</acronym> (
        <ulink url="http://prototypejs.org/api/utility/dollar-dollar">Prototype's $$()</ulink>et
        <ulink url="http://api.dojotoolkit.org/jsdoc/dojo/HEAD/dojo.query">Dojo's
        dojo.query</ulink>ont tous les deux inspirer ce composant).
    </para>

    <sect2 id="zend.dom.query.operation">
        <title>Aspect théorique</title>

        <para>
            Pour utiliser <classname>Zend_Dom_Query</classname>, vous instanciez un objet
            <classname>Zend_Dom_Query</classname>, en fournissant optionnellement un document à
            analyser (sous la forme d'une chaîne). Une fois que vous avez un document, vous pouvez
            utiliser indifféremment les méthodes <methodname>query()</methodname> ou
            <methodname>queryXpath()</methodname>&#160;; chaque méthode retournera un objet
            <classname>Zend_Dom_Query_Result</classname> avec tout noeud trouvé.
        </para>

        <para>
            La différence principale entre <classname>Zend_Dom_Query</classname> et
            l'utilisation de DOMDocument + DOMXPath est la possibilité de requêter avec les
            sélecteurs <acronym>CSS</acronym>. Vous pouvez utiliser n'importe quel élément suivant, dans n'importe
            quelle combinaison&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>types de l'élément</emphasis>&#160;: fourni un type d'élément à
                    rechercher : "div", "a", "span", "h2", etc.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>attributs de style</emphasis>&#160;: les classes <acronym>CSS</acronym> à
                    rechercher&#160;: ".error", "div.error", "label.required", etc. Si un élément
                    défini plus qu'une classe, la correspondance sera trouvé si la classe est
                    présente quelque part dans la déclaration de l'attribut.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>attribut id</emphasis>&#160;: ID de l'élément à rechercher&#160;:
                    "#content", "div#nav", etc.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>attributs arbitraires</emphasis>&#160;: tout attribut arbitraire de
                    l'élément à rechercher. Trois types de recherche sont possibles&#160;:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <emphasis>correspondance exacte</emphasis>&#160;: l'attribut vaut
                            exactement la chaîne fournie : "div[bar="baz"]" trouvera un élément div
                            qui possède un attribut "bar" dont la valeur vaut exactement
                            "baz".
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>correspondance de mot</emphasis>&#160;: l'attribut contient
                            un mot correspondant à la chaîne fournie&#160;: "div[bar~="baz"]"
                            trouvera un élément div qui possède un attribut "bar" dont la valeur
                            contient le mot "baz". "&lt;div bar="foo baz"&gt;" trouvera, mais pas
                            "&lt;div bar="foo bazbat"&gt;".
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>correspondance de parties de chaînes</emphasis>&#160;:
                            l'attribut contient la chaîne fournie&#160;: "div[bar*="baz"]" trouvera
                            un élément div qui possède un attribut "bar" dont la valeur contient la
                            chaîne "baz".
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Descendants directs</emphasis>&#160;: utilise "&gt;" entre les
                    sélecteurs pour représenter une descendance direct. "div &gt; span" trouvera
                    seulement les éléments "span" qui sont des descendants directs d'un élément
                    "div". Peut aussi être utilisé avec chacun des sélecteurs ci-dessus.
                </para>

            </listitem>

            <listitem>
                <para>
                    <emphasis>Descendants</emphasis>&#160;: une chaîne avec des sélecteurs
                    multiples ensemble pour indiquer hiérarchie à rechercher. "div .foo span #one"
                    trouvera un élément avec un id "one" qui est un descendant avec un profondeur
                    arbitraire d'un élément "span", qui est lui-même un descendant avec un
                    profondeur arbitraire d'un élément ayant une classe "foo", qui est un
                    descendant avec un profondeur arbitraire d'un élément "div". Par exemple, il
                    trouvera le lien vers le mot "One" dans le code ci-dessous&#160;:
                </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>
            Une fois que vous avez réalisé votre recherche, vous pouvez ensuite travailler
            avec l'objet de résultat pour déterminer les informations sur les noeuds, ainsi que
            pour les récupérer eux et/ou leurs contenus directement afin de les examiner et les
            manipuler. <classname>Zend_Dom_Query_Result</classname> implémente
            <code>Countable</code> and <code>Iterator</code>, et stocke le résultat en interne sous
            la forme DOMNodes/DOMElements. En exemple, considérons l'appel suivant sur l'HTML
            ci-dessus&#160;:
        </para>

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

$count = count($results);    // trouvera 4 correspondances
foreach ($results as $result) {
    // $result is a DOMElement
}
]]></programlisting>

        <para>
            <classname>Zend_Dom_Query</classname> permet aussi de faire directement des
            recherches de type XPath en utilisant la méthode <methodname>queryXpath()</methodname> ; vous
            pouvez fournir toute requête XPath valide à cette méthode, et elle retournera un objet
            <classname>Zend_Dom_Query_Result</classname>.
        </para>

    </sect2>

    <sect2 id="zend.dom.query.methods">
        <title>Méthodes disponibles</title>

        <para>
            La famille des classes <classname>Zend_Dom_Query</classname> possèdent les
            méthodes suivantes.
        </para>

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

            <para>
                Ces méthodes sont disponibles pour <classname>Zend_Dom_Query</classname>&#160;:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>setDocumentXml($document)</methodname>&#160;: spécifie une chaîne <acronym>XML</acronym> dans
                        laquelle requêter.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>setDocumentXhtml($document)</methodname>&#160;: spécifie une chaîne <acronym>XHTML</acronym>
                        dans laquelle requêter.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>setDocumentHtml($document)</methodname>&#160;: spécifie une chaîne HTML
                        dans laquelle requêter.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>setDocument($document)</methodname>&#160;: spécifie une chaîne dans
                        laquelle requêter&#160;; <classname>Zend_Dom_Query</classname> tentera
                        alors de détecter automatiquement le type de document.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getDocument()</methodname>&#160;: récupère le document original fourni à
                        l'objet.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getDocumentType()</methodname>&#160;: récupère le type de document fourni à
                        l'objet&#160;; sera une des constantes de classe&#160;:
                        <constant>DOC_XML</constant>, <constant>DOC_XHTML</constant>, ou <constant>DOC_HTML</constant>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>query($query)</methodname>&#160;: recherche dans le document en utilisant
                        la notation de type sélecteur <acronym>CSS</acronym>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>queryXpath($xPathQuery)</methodname>&#160;: recherche dans le document en
                        utilisant la notation XPath.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

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

            <para>
                Comme mentionné auparavant, <classname>Zend_Dom_Query_Result</classname>
                implémente à la fois <code>Iterator</code> et <code>Countable</code>, et en tant
                que tel peut être utilisé dans une boucle <code>foreach</code> ainsi qu'avec la
                fonction <methodname>count()</methodname>. De plus il expose les méthodes suivantes&#160;:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>getCssQuery()</methodname>&#160;: retourne le sélecteur <acronym>CSS</acronym> utilisé pour
                        produire le résultat (si fourni).
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getXpathQuery()</methodname>&#160;: retourne la requête XPath utilisé pour
                        produire le résultat, <classname>Zend_Dom_Query</classname> convertit les
                        recherches de type sélecteur <acronym>CSS</acronym> en notation XPath, donc cette valeur sera
                        toujours présente.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getDocument()</methodname>&#160;: récupère l'élément DOMDocument dans
                        lequel la recherche à été effectuée.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>
</sect1>