documentation/manual/ja/module_specs/Zend_Controller-ActionHelpers-AutoComplete.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20765 -->
   4 <sect3 id="zend.controller.actionhelpers.autocomplete">
   5     <title>AutoComplete</title>
   6
   7     <para>
   8         多くの <acronym>AJAX</acronym> 用 javascript ライブラリでは、
   9         オートコンプリート機能を提供しています。
  10         これは、ユーザがタイプした内容にマッチする可能性のある候補の一覧を表示するものです。
  11         <emphasis>AutoComplete</emphasis> ヘルパーは、
  12         このような場合に使用できるレスポンスを返すためのものです。
  13     </para>
  14
  15     <para>
  16         オートコンプリート機能の実装方法は JS ライブラリによって異なるので、
  17         <emphasis>AutoComplete</emphasis> では多くのライブラリで使用する共通機能を抽象化しています。
  18         そして、個々のライブラリにあわせた実装を用意しています。
  19         返り値の型は、<acronym>JSON</acronym> 形式の文字列の配列か
  20         <acronym>JSON</acronym> 形式の配列の配列
  21         (内部の配列は、選択リストを作成する際に使用するメタデータの連想配列)
  22         あるいは <acronym>HTML</acronym> となります。
  23     </para>
  24
  25     <para>
  26         どの実装についての基本的な使用法は同じです。
  27     </para>
  28
  29         <programlisting language="php"><![CDATA[
  30 class FooController extends Zend_Controller_Action
  31 {
  32     public function barAction()
  33     {
  34         // 何かの処理をします...
  35
  36         // エンコードしたレスポンスを送信します
  37         $this->_helper->autoCompleteDojo($data);
  38
  39         // あるいは明示的に
  40         $response = $this->_helper->autoCompleteDojo
  41                                   ->sendAutoCompletion($data);
  42
  43         // あるいは単純にオートコンプリート用のレスポンスを準備します
  44         $response = $this->_helper->autoCompleteDojo
  45                                   ->prepareAutoCompletion($data);
  46     }
  47 }
  48 ]]></programlisting>
  49
  50     <para>
  51         デフォルトでは以下のような作業を行います。
  52     </para>
  53
  54     <itemizedlist>
  55         <listitem><para>
  56                 レイアウト機能と ViewRenderer を無効にする。
  57         </para></listitem>
  58
  59         <listitem><para>
  60                 適切なレスポンスヘッダを設定する。
  61         </para></listitem>
  62
  63         <listitem><para>
  64                 レスポンスボディにエンコード/フォーマットしたデータを設定する。
  65         </para></listitem>
  66
  67         <listitem><para>
  68                 レスポンスを送信する。
  69         </para></listitem>
  70     </itemizedlist>
  71
  72     <para>
  73         このヘルパーでは次のようなメソッドが使用できます。
  74     </para>
  75
  76     <itemizedlist>
  77         <listitem><para>
  78                 <methodname>disableLayouts()</methodname> は、レイアウト機能と
  79                 ViewRenderer を無効にします。一般に、これは
  80                 <methodname>prepareAutoCompletion()</methodname> の中でコールされます。
  81         </para></listitem>
  82
  83         <listitem><para>
  84                 <methodname>encodeJson($data, $keepLayouts = false)</methodname>
  85                 はデータを <acronym>JSON</acronym> 形式にエンコードし、オプションでレイアウト機能の有効/無効
  86                 を切り替えます。一般に、これは
  87                 <methodname>prepareAutoCompletion()</methodname> の中でコールされます。
  88         </para></listitem>
  89
  90         <listitem><para>
  91                 <methodname>prepareAutoCompletion($data, $keepLayouts = false)</methodname>
  92                 は、各種具象実装にあわせてレスポンスデータをフォーマットし、
  93                 オプションでレイアウト機能の有効/無効を切り替えます。
  94                 返り値は実装によって異なります。
  95         </para></listitem>
  96
  97         <listitem><para>
  98                 <methodname>sendAutoCompletion($data, $keepLayouts = false)</methodname>
  99                 は、各種具象実装にあわせてフォーマットしたレスポンスデータを送信します。
 100                 これは、<methodname>prepareAutoCompletion()</methodname> をコールしたあとでレスポンスを送信します。
 101         </para></listitem>
 102
 103         <listitem><para>
 104                 <methodname>direct($data, $sendNow = true, $keepLayouts =
 105                     false)</methodname> は、このヘルパーをヘルパーブローカのメソッドとしてコールする場合に使用します。
 106                 <varname>$sendNow</varname> フラグは、
 107                 <methodname>sendAutoCompletion()</methodname> と
 108                 <methodname>prepareAutoCompletion()</methodname> のどちらをコールするかを指定するものです。
 109         </para></listitem>
 110     </itemizedlist>
 111
 112     <para>
 113         現在 <emphasis>AutoComplete</emphasis> がサポートしている <acronym>AJAX</acronym>
 114         ライブラリは、Dojo と Scriptaculous です。
 115     </para>
 116
 117     <sect4 id="zend.controller.actionhelpers.autocomplete.dojo">
 118         <title>Dojo でのオートコンプリート</title>
 119
 120         <para>
 121             Dojo には、オートコンプリートのためだけのウィジェットはありません。
 122             しかし、ComboBox と FilteringSelect
 123             のふたつのウィジェットがオートコンプリート機能を持っています。
 124             どちらのウィジェットも、QueryReadStore
 125             を実装したデータを必要とします。詳細は
 126             <ulink url="http://dojotoolkit.org/book/dojo-book-0-9/part-3-programmatic-dijit-and-dojo/data-retrieval-dojo-data-0">dojo.data</ulink>
 127             のドキュメントを参照ください。
 128         </para>
 129
 130         <para>
 131             Zend Framework では、単純な数値添字の配列を
 132             AutoCompleteDojo ヘルパーに渡します。
 133             そうすると、適切な形式の <acronym>JSON</acronym> オブジェクトを返します。
 134         </para>
 135
 136         <programlisting language="php"><![CDATA[
 137 // コントローラのアクション内で
 138 $this->_helper->autoCompleteDojo($data);
 139 ]]></programlisting>
 140
 141         <example id="zend.controller.actionhelpers.autocomplete.dojo.example1">
 142             <title>Zend MVC を使用した、Dojo でのオートコンプリート</title>
 143
 144             <para>
 145                 Zend <acronym>MVC</acronym> で Dojo によるオートコンプリートを使用するには、
 146                 いくつかの準備が必要です。オートコンプリートを使用したい
 147                 ComboBox 用にフォームオブj稀有とを作成し、
 148                 オートコンプリートの結果を提供するためのコントローラアクションを作成し、
 149                 オートコンプリートアクションに接続するための
 150                 独自の QueryReadStore を作成し、
 151                 サーバ側でオートコンプリートを行わせるための javascript
 152                 を作成することになります。
 153             </para>
 154
 155             <para>
 156                 まずは、必要となる javascript を見ていきましょう。
 157                 Dojo は javascript によるオブジェクト指向プログラミングを行うための
 158                 完全なフレームワークで、ちょうど <acronym>PHP</acronym> における Zend Framework
 159                 のようなものです。その中には、
 160                 ディレクトリ構造を用いて擬似的な名前空間を作成する機能もあります。
 161                 ここでは、Dojo の配布ファイルの Dojo
 162                 ディレクトリと同じ階層に 'custom' ディレクトリを作成します。
 163                 そのディレクトリの中に <filename>TestNameReadStore.js</filename>
 164                 という javascript ファイルを作成し、次のようなコードを書きます。
 165             </para>
 166
 167             <programlisting language="javascript"><![CDATA[
 168 dojo.provide("custom.TestNameReadStore");
 169 dojo.declare("custom.TestNameReadStore", dojox.data.QueryReadStore, {
 170     fetch:function (request) {
 171         request.serverQuery = { test:request.query.name };
 172         return this.inherited("fetch", arguments);
 173     }
 174 });
 175 ]]></programlisting>
 176
 177             <para>
 178                 このクラスは、単に Dojo 自身の QueryReadStore
 179                 クラスを継承したものです。継承元のクラス自体は抽象クラスです。
 180                 そこにリクエスト用のメソッドを定義し、'test'
 181                 要素に割り当てています。
 182             </para>
 183
 184             <para>
 185                 次に、オートコンプリートを行うためのフォーム要素を作成します。
 186             </para>
 187
 188             <programlisting language="php"><![CDATA[
 189 class TestController extends Zend_Controller_Action
 190 {
 191     protected $_form;
 192
 193     public function getForm()
 194     {
 195         if (null === $this->_form) {
 196             $this->_form = new Zend_Form();
 197             $this->_form->setMethod('get')
 198                 ->setAction(
 199                     $this->getRequest()->getBaseUrl() . '/test/process'
 200                 )
 201                 ->addElements(array(
 202                     'test' => array('type' => 'text', 'options' => array(
 203                         'filters'        => array('StringTrim'),
 204                         'dojoType'       => array('dijit.form.ComboBox'),
 205                         'store'          => 'testStore',
 206                         'autoComplete'   => 'false',
 207                         'hasDownArrow'   => 'true',
 208                         'label' => 'Your input:',
 209                     )),
 210                     'go' => array('type' => 'submit',
 211                                   'options' => array('label' => 'Go!'))
 212                 ));
 213         }
 214         return $this->_form;
 215     }
 216 }
 217 ]]></programlisting>
 218
 219             <para>
 220                 ここでは、単に 'test' と 'go' メソッドのみを持つフォームを作成します。
 221                 'test' メソッドは、特別な Dojo 固有の属性
 222                 dojoType、store、autoComplete および hasDownArrow
 223                 を追加します。dojoType では、これから ComboBox
 224                 を作成することを指定します。そして、それを 'testStore' のデータストア
 225                 (キー 'store') にリンクします。詳細は後ほど説明します。
 226                 'autoComplete' を <constant>FALSE</constant> に設定することで、
 227                 最初にマッチしたものを自動選択するのではなく
 228                 マッチしたものの一覧を表示するよう Dojo に指示します。
 229                 最後に 'hasDownArrow' でセレクトボックス風の下向き矢印を作ります。
 230                 これで、マッチしたものを表示したり隠したりできるようになります。
 231             </para>
 232
 233             <para>
 234                 では、フォームを表示するためのメソッドと
 235                 オートコンプリートの処理用のエンドポイントを作成してみましょう。
 236             </para>
 237
 238             <programlisting language="php"><![CDATA[
 239 class TestController extends Zend_Controller_Action
 240 {
 241     // ...
 242
 243     /**
 244      * 最初のページ
 245      */
 246     public function indexAction()
 247     {
 248         $this->view->form = $this->getForm();
 249     }
 250
 251     public function autocompleteAction()
 252     {
 253         if ('ajax' != $this->_getParam('format', false)) {
 254             return $this->_helper->redirector('index');
 255         }
 256         if ($this->getRequest()->isPost()) {
 257             return $this->_helper->redirector('index');
 258         }
 259
 260         $match = trim($this->getRequest()->getQuery('test', ''));
 261
 262         $matches = array();
 263         foreach ($this->getData() as $datum) {
 264             if (0 === strpos($datum, $match)) {
 265                 $matches[] = $datum;
 266             }
 267         }
 268         $this->_helper->autoCompleteDojo($matches);
 269     }
 270 }
 271 ]]></programlisting>
 272
 273             <para>
 274                 <methodname>autocompleteAction()</methodname>
 275                 ではいくつかの作業を行っています。
 276                 まず、POST リクエストを受け取ったことを確実にし、
 277                 'format' パラメータの値を 'ajax' に設定します。
 278                 これにより、余計なクエリがアクションに送られることを減らします。
 279                 次に、'test' パラメータの内容を確認し、私たちのデータと比較します
 280                 (ここでは、<methodname>getData()</methodname> の実装は意図的に控えています。
 281                 何らかのデータソースを使用することになるでしょう)。
 282                 最後に、マッチした内容を AutoCompletion ヘルパーに送信します。
 283             </para>
 284
 285             <para>
 286                 これでバックエンド側の準備はすべて整いました。
 287                 次に、ページのビュースクリプト側ではどうすればいいのかを考えてみましょう。
 288                 まず、データストアを用意しなければなりません。
 289                 次にフォームをレンダリングし、最後に適切な Dojo ライブラリ
 290                 (使用するデータストアも含む) を読み込みます。
 291                 ビュースクリプトを見てみましょう。
 292                 適宜コメントを入れてあります。
 293             </para>
 294
 295             <programlisting language="php"><![CDATA[
 296 <?php // データストアの準備 ?>
 297 <div dojoType="custom.TestNameReadStore" jsId="testStore"
 298     url="<?php echo $this->baseUrl() ?>/unit-test/autocomplete/format/ajax"
 299     requestMethod="get"></div>
 300
 301 <?php // フォームのレンダリング ?>
 302 <?php echo $this->form ?>
 303
 304 <?php // Dojo 関連の CSS の、HTML head での読み込み ?>
 305 <?php $this->headStyle()->captureStart() ?>
 306 @import "<?php echo $this->baseUrl()
 307 ?>/javascript/dijit/themes/tundra/tundra.css";
 308 @import "<?php echo $this->baseUrl() ?>/javascript/dojo/resources/dojo.css";
 309 <?php $this->headStyle()->captureEnd() ?>
 310
 311 <?php // 必要な Dojo ライブラリを含む javascript の、
 312    // HTML head での読み込み ?>
 313 <?php $this->headScript()
 314         ->setAllowArbitraryAttributes(true)
 315         ->appendFile($this->baseUrl() . '/javascript/dojo/dojo.js',
 316             'text/javascript',
 317             array('djConfig' => 'parseOnLoad: true'))
 318         ->captureStart() ?>
 319 djConfig.usePlainJson=true;
 320 dojo.registerModulePath("custom","../custom");
 321 dojo.require("dojo.parser");
 322 dojo.require("dojox.data.QueryReadStore");
 323 dojo.require("dijit.form.ComboBox");
 324 dojo.require("custom.TestNameReadStore");
 325 <?php $this->headScript()->captureEnd() ?>
 326 ]]></programlisting>
 327
 328             <para>
 329                 headStyle や headScript といったビューヘルパーのコールに注意しましょう。
 330                 これらはプレースホルダで、ビュースクリプトをレンダリングする際に
 331                 <acronym>HTML</acronym> の head セクションとなります。
 332             </para>
 333
 334             <para>
 335                 これで、Dojo のオートコンプリートを動作させるための準備がすべて整いました。
 336             </para>
 337         </example>
 338     </sect4>
 339
 340     <sect4 id="zend.controller.actionhelpers.autocomplete.scriptaculous">
 341         <title>Scriptaculous でのオートコンプリート</title>
 342         <para>
 343             <ulink url="http://wiki.script.aculo.us/scriptaculous/show/Ajax.Autocompleter">Scriptaculous</ulink>
 344             は、所定の形式の <acronym>HTML</acronym> レスポンスを受け取ることを想定しています。
 345         </para>
 346
 347         <para>
 348             このライブラリで使用するヘルパーは 'AutoCompleteScriptaculous' です。
 349             このヘルパーにデータの配列を渡せば、Ajax.Autocompleter
 350             に対応した形式の <acronym>HTML</acronym> レスポンスができあがります。
 351         </para>
 352     </sect4>
 353 </sect3>
 354 <!--
 355 vim:se ts=4 sw=4 et:
 356 -->