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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 21585 -->
   4 <sect1 id="zend.dom.query">
   5     <title>Zend_Dom_Query</title>
   6
   7     <para>
   8         <classname>Zend_Dom_Query</classname> を使用すると、<acronym>XML</acronym> や (X)<acronym>HTML</acronym> ドキュメントに対して
   9         XPath あるいは <acronym>CSS</acronym> セレクタを用いた問い合わせができるようになります。
  10         <acronym>MVC</acronym> アプリケーションの機能テストを支援するために作られたものですが、
  11         スクリーンスクレイパーを手早く作成するためにも使うことができます。
  12     </para>
  13
  14     <para>
  15         <acronym>CSS</acronym> セレクタ記法は、ウェブ開発者にとってはシンプルでなじみのある記法です。
  16         <acronym>XML</acronym> 構造のドキュメントに対する問い合わせに使用できます。
  17         この記法は、スタイルシートを扱ったことのある人ならきっとおなじみでしょうし、
  18         Javascript のツールキットの中にも
  19         <acronym>CSS</acronym> セレクタを使用してノードを選択できる機能を持つものがあります
  20         (<ulink url="http://prototypejs.org/api/utility/dollar-dollar">Prototype の
  21             $$()</ulink> や
  22         <ulink url="http://api.dojotoolkit.org/jsdoc/dojo/HEAD/dojo.query">Dojo の
  23             dojo.query</ulink> をヒントにしてこのコンポーネントを作成しました)。
  24     </para>
  25
  26     <sect2 id="zend.dom.query.operation">
  27         <title>動作原理</title>
  28
  29         <para>
  30             <classname>Zend_Dom_Query</classname> を使用するには、
  31             <classname>Zend_Dom_Query</classname> オブジェクトのインスタンスを作成します。
  32             その際に、問い合わせたいドキュメント (文字列)
  33             をオプションで渡すことができます。
  34             ドキュメントを用意すれば、
  35             <methodname>query()</methodname> メソッドあるいは <methodname>queryXpath()</methodname>
  36             メソッドを使用できます。どちらのメソッドも、
  37             マッチしたノードを含む <classname>Zend_Dom_Query_Result</classname>
  38             オブジェクトを返します。
  39         </para>
  40
  41         <para>
  42             <classname>Zend_Dom_Query</classname> を使うことと
  43             DOMDocument + DOMXPath を使うことの最大の違いは、
  44             <acronym>CSS</acronym> セレクタによる選択が可能かどうかということです。
  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>style 属性</emphasis>: マッチさせたい <acronym>CSS</acronym> style
  56                 属性を指定します。'<command>.error</command>', '<command>div.error</command>', '<command>label.required</command>'
  57                 などです。ひとつの要素に複数のスタイルが定義されている場合は
  58                 指定したスタイルがスタイル宣言のどこかに存在すればマッチします。
  59             </para></listitem>
  60
  61             <listitem><para>
  62                 <emphasis>id 属性</emphasis>: マッチさせたい要素 ID 属性を指定します。
  63                 '#content', 'div#nav' などです。
  64             </para></listitem>
  65
  66             <listitem>
  67                 <para>
  68                     <emphasis>任意の属性</emphasis>:
  69                     マッチさせたい任意の要素属性を指定します。
  70                     以下の 3 種類のマッチ形式を用意しています。
  71                 </para>
  72
  73                 <itemizedlist>
  74                     <listitem><para>
  75                         <emphasis>完全マッチ</emphasis>: その文字列に完全にマッチする属性。
  76                         'div[bar="baz"]' は、"bar" 属性の値が正確に "baz"
  77                         と一致する div 要素にマッチします。
  78                     </para></listitem>
  79
  80                     <listitem><para>
  81                         <emphasis>単語マッチ</emphasis>:
  82                         指定した文字列に一致する単語を含む属性。
  83                         'div[bar~="baz"]' は、"bar" 属性の値に単語 "baz"
  84                         を含む div 要素にマッチします。
  85                         '&lt;div bar="foo baz"&gt;' はマッチしますが、 '&lt;div
  86                                 bar="foo bazbat"&gt;' はマッチしません。
  87                     </para></listitem>
  88
  89                     <listitem><para>
  90                         <emphasis>部分文字列マッチ</emphasis>:
  91                         その文字列を含む属性。'div[bar*="baz"]' は、
  92                         "bar" 属性の値のどこかに文字列 "baz"
  93                         を含む div 要素にマッチします。
  94                     </para></listitem>
  95                 </itemizedlist>
  96             </listitem>
  97
  98             <listitem><para>
  99                 <emphasis>直接の子孫</emphasis>:
 100                 セレクタの間で '&gt;' を使用すると、
 101                 直接の子要素であることを表します。'div > span'
 102                 は、'span' 要素のうち 'div' の直接の子であるものだけを選択します。
 103                 上のセレクタのどれとでも共用できます。
 104             </para></listitem>
 105
 106             <listitem>
 107                 <para>
 108                     <emphasis>子孫</emphasis>:
 109                     複数のセレクタをひとつの文字列にまとめると、
 110                     探す階層を指定できます。
 111                     '<command>div .foo span #one</command>' が探すのは id が 'one'
 112                     である要素です。その要素は、'span'
 113                     要素の子孫 (その間の階層の数は問わない) であり、
 114                     さらにその 'span' 要素はクラス 'foo' の要素の子孫
 115                     (その間の階層の数は問わない) です。
 116                     同様に、そのクラス 'foo' の要素は 'div' 要素の子孫
 117                     (その間の階層の数は問わない) となります。
 118                     これは、たとえば以下のリストにおける単語 'One'
 119                     へのリンクにマッチします。
 120                 </para>
 121
 122                 <programlisting language="html"><![CDATA[
 123 <div>
 124 <table>
 125     <tr>
 126         <td class="foo">
 127             <div>
 128                 Lorem ipsum <span class="bar">
 129                     <a href="/foo/bar" id="one">One</a>
 130                     <a href="/foo/baz" id="two">Two</a>
 131                     <a href="/foo/bat" id="three">Three</a>
 132                     <a href="/foo/bla" id="four">Four</a>
 133                 </span>
 134             </div>
 135         </td>
 136     </tr>
 137 </table>
 138 </div>
 139 ]]></programlisting>
 140             </listitem>
 141         </itemizedlist>
 142
 143         <para>
 144             問い合わせを実行したら、その結果のオブジェクトを用いてノードの情報を取得したり、
 145             そのノード (あるいはノードの内容) を取り出して操作したりできます。
 146             <classname>Zend_Dom_Query_Result</classname> は <classname>Countable</classname>
 147             と <classname>Iterator</classname> を実装しており、内部では結果を
 148             DOMNodes および DOMElements で保持しています。
 149             たとえば、次のようなコードを上の <acronym>HTML</acronym> に対して実行することを考えてみましょう。
 150         </para>
 151
 152         <programlisting language="php"><![CDATA[
 153 $dom = new Zend_Dom_Query($html);
 154 $results = $dom->query('.foo .bar a');
 155
 156 $count = count($results); // マッチした数: 4
 157 foreach ($results as $result) {
 158     // $result は DOMElement です
 159 }
 160 ]]></programlisting>
 161
 162         <para>
 163             <classname>Zend_Dom_Query</classname> では、
 164             <methodname>queryXpath()</methodname> メソッドで
 165             XPath クエリを直接使用することもできます。
 166             XPath クエリとして正しいものならなんでもこのメソッドに渡すことができ、
 167             結果は <classname>Zend_Dom_Query_Result</classname> オブジェクトで返されます。
 168         </para>
 169     </sect2>
 170
 171     <sect2 id="zend.dom.query.methods">
 172         <title>使用可能なメソッド</title>
 173
 174         <para>
 175             <classname>Zend_Dom_Query</classname> 系のクラスでは、次のメソッドが使用できます。
 176         </para>
 177
 178         <sect3 id="zend.dom.query.methods.zenddomquery">
 179             <title>Zend_Dom_Query</title>
 180
 181             <para>
 182                 次のメソッドが
 183                 <classname>Zend_Dom_Query</classname> で使用できます。
 184             </para>
 185
 186             <itemizedlist>
 187                 <listitem><para>
 188                     <methodname>setDocumentXml($document)</methodname>:
 189                     対象となる <acronym>XML</acronym> 文字列を指定します。
 190                 </para></listitem>
 191
 192                 <listitem><para>
 193                     <methodname>setDocumentXhtml($document)</methodname>:
 194                     対象となる <acronym>XHTML</acronym> 文字列を指定します。
 195                 </para></listitem>
 196
 197                 <listitem><para>
 198                     <methodname>setDocumentHtml($document)</methodname>:
 199                     対象となる <acronym>HTML</acronym> 文字列を指定します。
 200                 </para></listitem>
 201
 202                 <listitem><para>
 203                     <methodname>setDocument($document)</methodname>:
 204                     対象となる文字列を指定します。<classname>Zend_Dom_Query</classname>
 205                     がドキュメントの形式を自動判定します。
 206                 </para></listitem>
 207
 208                 <listitem><para>
 209                     <methodname>getDocument()</methodname>:
 210                     オブジェクトに渡した元の文字列を取得します。
 211                 </para></listitem>
 212
 213                 <listitem><para>
 214                     <methodname>getDocumentType()</methodname>:
 215                     オブジェクトに渡したドキュメントの形式を取得します。
 216                     クラス定数 <constant>DOC_XML</constant>、<constant>DOC_XHTML</constant>
 217                     あるいは <constant>DOC_HTML</constant> のいずれかとなります。
 218                 </para></listitem>
 219
 220                 <listitem><para>
 221                     <methodname>query($query)</methodname>:
 222                     <acronym>CSS</acronym> セレクタ記法でドキュメントへの問い合わせを行います。
 223                 </para></listitem>
 224
 225                 <listitem><para>
 226                     <methodname>queryXpath($xPathQuery)</methodname>:
 227                     XPath 記法でドキュメントへの問い合わせを行います。
 228                 </para></listitem>
 229             </itemizedlist>
 230         </sect3>
 231
 232         <sect3 id="zend.dom.query.methods.zenddomqueryresult">
 233             <title>Zend_Dom_Query_Result</title>
 234
 235             <para>
 236                 先ほど説明したように、<classname>Zend_Dom_Query_Result</classname>
 237                 は <classname>Iterator</classname> と
 238                 <classname>Countable</classname> を実装しており、
 239                 <classname>foreach</classname> ループで使用したり
 240                 <methodname>count()</methodname> 関数を利用したりできます。
 241                 さらに、次のメソッドを公開しています。
 242             </para>
 243
 244             <itemizedlist>
 245                 <listitem><para>
 246                     <methodname>getCssQuery()</methodname>:
 247                     その結果を得る元となった <acronym>CSS</acronym> セレクタクエリを
 248                     (もし存在すれば) 返します。
 249                 </para></listitem>
 250
 251                 <listitem><para>
 252                     <methodname>getXpathQuery()</methodname>:
 253                     その結果を得る元となった XPath クエリを返します。
 254                     内部的には、<classname>Zend_Dom_Query</classname> は
 255                     <acronym>CSS</acronym> セレクタクエリを XPath に変換しています。
 256                     そのため、このメソッドは常に結果を返します。
 257                 </para></listitem>
 258
 259                 <listitem><para>
 260                     <methodname>getDocument()</methodname>:
 261                     問い合わせ対象となった DOMDocument を取得します。
 262                 </para></listitem>
 263             </itemizedlist>
 264         </sect3>
 265     </sect2>
 266 </sect1>
 267 <!--
 268 vim:se ts=4 sw=4 et:
 269 -->