documentation/manual/ru/module_specs/Zend_Dom-Query.xml

   1 <sect1 id="zend.dom.query">
   2     <title>Zend_Dom_Query</title>
   3
   4     <para>
   5         <code>Zend_Dom_Query</code> предоставляет механизмы для запросов к
   6         документам XML и (X)HTML с использованием селекторов XPath и CSS.
   7         Он был разработан для того, чтобы помочь с функциональным тестированием
   8         приложений MVC, но может также использоваться для быстрой разработки
   9         кода, извлекающего нужные данные из выводимых данных приложения
  10         (например, XHTML-кода, возвращаемого сайтом).
  11     </para>
  12
  13     <para>
  14         Нотация селекторов CSS предоставляется в качестве более простой и
  15         знакомой веб-разработчикам при произведении запросов к
  16         документам с XML-структурой.
  17         Эта нотация должна быть знакома всем, кто разрабатывает каскадные
  18         таблицы стилей или использует инструменты Javascript,
  19         имеющие функционал для получения узлов через селекторы CSS
  20         (именно функции <ulink url="http://prototypejs.org/api/utility/dollar-dollar">
  21             $$()</ulink> из Prototype и
  22         <ulink url="http://api.dojotoolkit.org/jsdoc/dojo/HEAD/dojo.query">
  23             dojo.query</ulink> из Dojo натолкнули автора на создание этой
  24         компоненты).
  25     </para>
  26
  27     <sect2 id="zend.dom.query.operation">
  28         <title>Теория работы</title>
  29
  30         <para>
  31             Для того, чтобы использовать <code>Zend_Dom_Query</code>,
  32             нужно инстанцировать объект <code>Zend_Dom_Query</code>,
  33             при этом можно передавать содержимое документа, к которому должны
  34             производиться запросы, в виде строки.
  35             Установив документ, вы можете использовать методы
  36             <code>query()</code> и <code>queryXpath()</code>. Эти методы будут
  37             возвращать объект <code>Zend_Dom_Query_Result</code>, который
  38             содержит в себе все найденные узлы.
  39         </para>
  40
  41         <para>
  42             Основное отличие использования <code>Zend_Dom_Query</code> от
  43             применения связки DOMDocument + DOMXPath заключается в возможности
  44             извлечения через селекторы CSS. Вы можете использовать все
  45             перечисленное ниже, в любой комбинации:
  46         </para>
  47
  48         <itemizedlist>
  49             <listitem><para>
  50                 <emphasis>селекторы типа</emphasis>: основаны на типе
  51                 элемента: 'div', 'a', 'span', 'h2' и т.д.
  52             </para></listitem>
  53
  54             <listitem><para>
  55                 <emphasis>селекторы класса</emphasis>: соответствуют атрибуту
  56                 class элемента: '.error', 'div.error', 'label.required' и т.д.
  57                 Если для элемента указано более одного класса, то этот элемент
  58                 будет соотвествовать запросу, если указанный в запросе класс
  59                 присутствует в его декларации.
  60             </para></listitem>
  61
  62             <listitem><para>
  63                 <emphasis>id-селекторы</emphasis>: соответствуют ID-атрибуту
  64                 элемента: '#content', 'div#nav' и т.д.
  65             </para></listitem>
  66
  67             <listitem>
  68                 <para>
  69                     <emphasis>селекторы атрибута</emphasis>: соответствуют
  70                     атрибутам элемента. Используется три типа соответствия:
  71                 </para>
  72
  73                 <itemizedlist>
  74                     <listitem><para>
  75                         <emphasis>точное соответствие</emphasis>: значение
  76                         атрибута в точности равно данной строке.
  77                         Запросу 'div[bar="baz"]' должен соответствовать элемент
  78                         div с атрибутом "bar", который имеет значение "baz".
  79                     </para></listitem>
  80
  81                     <listitem><para>
  82                         <emphasis>соответствие слову</emphasis>: атрибут
  83                         содержит слово, которое в точности равно данной строке.
  84                         Запросу 'div[bar~="baz"]' должен соответствовать элемент
  85                         div с атрибутом "bar", который содержит слово "baz".
  86                         Элемент '&lt;div bar="foo baz"&gt;' будет
  87                         соответствовать этому запросу, но
  88                         '&lt;div bar="foo bazbat"&gt;' не будет.
  89                     </para></listitem>
  90
  91                     <listitem><para>
  92                         <emphasis>соответствие подстроке</emphasis>:
  93                         атрибут содержит подстроку. Запросу 'div[bar*="baz"]'
  94                         должен соответствовать элемент div с атрибутом "bar",
  95                         который содержит внутри себя подстроку "baz".
  96                     </para></listitem>
  97                 </itemizedlist>
  98             </listitem>
  99
 100             <listitem><para>
 101                 <emphasis>селекторы прямых потомков</emphasis>: используйте
 102                 '&gt;' между селекторами для указания прямых потомков.
 103                 'div > span' должен отбирать только те элементы 'span', которые
 104                 являются прямыми потомками 'div'. Эти селекторы можно
 105                 использовать с любыми селекторами, перечисленными выше.
 106             </para></listitem>
 107
 108             <listitem>
 109                 <para>
 110                     <emphasis>селекторы потомков</emphasis>: перечисляйте
 111                     селекторы через пробел для обозначения иерархии, вдоль
 112                     которой нужно производить поиск. 'div .foo span #one' должен
 113                     отбирать элемент с идентификатором 'one', который является
 114                     потомком любого уровня элемента 'span', который в свою
 115                     очередь является потомком любого уровня элемента класса
 116                     'foo', который является потомком любого уровня элемента
 117                     'div'. Например, такому запросу будет соответствовать
 118                     ссылка со словом 'One' в листинге ниже:
 119                 </para>
 120
 121                 <programlisting language="html"><![CDATA[
 122 <div>
 123 <table>
 124     <tr>
 125         <td class="foo">
 126             <div>
 127                 Lorem ipsum <span class="bar">
 128                     <a href="/foo/bar" id="one">One</a>
 129                     <a href="/foo/baz" id="two">Two</a>
 130                     <a href="/foo/bat" id="three">Three</a>
 131                     <a href="/foo/bla" id="four">Four</a>
 132                 </span>
 133             </div>
 134         </td>
 135     </tr>
 136 </table>
 137 </div>
 138 ]]>
 139 </programlisting>
 140             </listitem>
 141         </itemizedlist>
 142
 143         <para>
 144             Выполнив запрос, вы можете работать с объектами результата для
 145             получения информации об узлах и извлечения самих узлов либо их
 146             содержимого для их исследования или манипуляций с ними.
 147             <code>Zend_Dom_Query_Result</code> реализует интерфейсы
 148             <code>Countable</code>, <code>Iterator</code>, и
 149             сохраняет результат как узлы DOMNode и элементы DOMElement.
 150             Для примера рассмотрим следующий вызов, который производит выборку
 151             из HTML-кода, приведенного выше:
 152         </para>
 153
 154         <programlisting language="php"><![CDATA[
 155 $dom = new Zend_Dom_Query($html);
 156 $results = $dom->query('.foo .bar a');
 157
 158 $count = count($results); // получение числа соответствий: 4
 159 foreach ($results as $result) {
 160     // переменная $result имеет тип DOMElement
 161 }
 162 ]]>
 163         </programlisting>
 164
 165         <para>
 166             <code>Zend_Dom_Query</code> также позволяет применять запросы
 167             XPath через метод <code>queryXpath()</code>. Вы можете передавать
 168             этому методу любые запросы XPath и в случае корректно составленного
 169             запроса он будет возвращать объект
 170             <code>Zend_Dom_Query_Result</code>.
 171         </para>
 172     </sect2>
 173
 174     <sect2 id="zend.dom.query.methods">
 175         <title>Доступные методы</title>
 176
 177         <para>
 178             Семейство классов <code>Zend_Dom_Query</code> имеет следующие
 179             доступные для использования методы.
 180         </para>
 181
 182         <sect3 id="zend.dom.query.methods.zenddomquery">
 183             <title>Zend_Dom_Query</title>
 184
 185             <para>
 186                 В классе <code>Zend_Dom_Query</code> доступны следующие методы:
 187             </para>
 188
 189             <itemizedlist>
 190                 <listitem><para>
 191                     <code>setDocumentXml($document)</code>: принимает строку
 192                     с содержимым документа HTML, к которому должны производиться
 193                     запросы.
 194                 </para></listitem>
 195
 196                 <listitem><para>
 197                     <code>setDocumentXhtml($document)</code>: принимает строку
 198                     с содержимым документа XHTML, к которому должны
 199                     производиться запросы.
 200                 </para></listitem>
 201
 202                 <listitem><para>
 203                     <code>setDocumentHtml($document)</code>: принимает строку
 204                     с содержимым документа HTML, к которому должны производиться
 205                     запросы.
 206                 </para></listitem>
 207
 208                 <listitem><para>
 209                     <code>setDocument($document)</code>: принимает строку без
 210                     указания типа документа. В этом случае
 211                     <code>Zend_Dom_Query</code> сам попытается определить тип
 212                     документа.
 213                 </para></listitem>
 214
 215                 <listitem><para>
 216                     <code>getDocument()</code>: возвращает исходный документ,
 217                     переданный объекту.
 218                 </para></listitem>
 219
 220                 <listitem><para>
 221                     <code>getDocumentType()</code>: возвращает тип документа,
 222                     переданного объекту. Это должна быть одна из
 223                     следующих констант класса Zend_Dom_Query:
 224                     <code>DOC_XML</code>, <code>DOC_XHTML</code> или
 225                     <code>DOC_HTML</code>.
 226                 </para></listitem>
 227
 228                 <listitem><para>
 229                     <code>query($query)</code>: производит запрос к документу
 230                     с использованием нотации селекторов CSS.
 231                 </para></listitem>
 232
 233                 <listitem><para>
 234                     <code>queryXpath($xPathQuery)</code>: производит запрос
 235                     к документу с использованием нотации XPath.
 236                 </para></listitem>
 237             </itemizedlist>
 238         </sect3>
 239
 240         <sect3 id="zend.dom.query.methods.zenddomqueryresult">
 241             <title>Zend_Dom_Query_Result</title>
 242
 243             <para>
 244                 Как было упомянуто ранее, <code>Zend_Dom_Query_Result</code>
 245                 реализует интерфейсы <code>Iterator</code> и
 246                 <code>Countable</code>, поэтому может использоваться в
 247                 цикле <code>foreach</code> и с функцией <code>count()</code>.
 248                 Кроме того, он предоставляет следующие методы:
 249             </para>
 250
 251             <itemizedlist>
 252                 <listitem><para>
 253                     <code>getCssQuery()</code>: возвращает запрос-селектор CSS,
 254                     который использовался для получения результата (если был).
 255                 </para></listitem>
 256
 257                 <listitem><para>
 258                     <code>getXpathQuery()</code>: возвращает запрос XPath,
 259                     который использовался для получения результата.
 260                     <code>Zend_Dom_Query</code> неявным образом преобразует
 261                     запросы с селекторами CSS в запросы XPath, поэтому это
 262                     значение всегда будет заполняться.
 263                 </para></listitem>
 264
 265                 <listitem><para>
 266                     <code>getDocument()</code>: возвращает объект DOMDocument,
 267                     к которому производился запрос.
 268                 </para></listitem>
 269             </itemizedlist>
 270         </sect3>
 271     </sect2>
 272 </sect1>
 273 <!--
 274 vim:se ts=4 sw=4 et:
 275 -->