documentation/manual/ja/module_specs/Zend_Dojo-View-Dojo.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 21585 -->
   4 <sect2 id="zend.dojo.view.dojo">
   5     <title>dojo() ビューヘルパー</title>
   6
   7     <para>
   8         <methodname>dojo()</methodname> ビューヘルパーは
   9         Dojo 環境のセットアップを簡単に行うためのものです。
  10         次のような機能があります。
  11     </para>
  12
  13     <itemizedlist>
  14         <listitem><para><acronym>CDN</acronym> あるいはローカルパスのどちらの Dojo
  15                 を使用するかの指定</para></listitem>
  16         <listitem><para>カスタム Dojo モジュールへのパスの指定</para></listitem>
  17         <listitem><para><command>dojo.require</command> 文の指定</para></listitem>
  18         <listitem><para>使用する dijit スタイルシートテーマの指定</para></listitem>
  19         <listitem><para><command>dojo.addOnLoad()</command> イベントの指定</para></listitem>
  20     </itemizedlist>
  21
  22     <para>
  23         <methodname>dojo()</methodname> ビューヘルパーの実装は、
  24         プレースホルダの実装の一例です。
  25         中で扱うデータセットはビューオブジェクトを超えて永続化され、
  26         レイアウトスクリプトから直接 echo できます。
  27     </para>
  28
  29     <example id="zend.dojo.view.dojo.usage">
  30         <title>dojo() ビューヘルパーの使用例</title>
  31
  32         <para>
  33             この例では、ローカルパスの Dojo を使うことを想定しています。
  34             またいくつかの dijit を使い、Tundra dijit テーマを使用するものとします。
  35         </para>
  36
  37         <para>
  38             多くのページでは、開発者は Dojo をまったく使用しません。
  39             そこで、Dojo が必要となるビュースクリプトやレイアウトスクリプトだけに注目し、
  40             そこで Dojo 環境を用意してレンダリングすることにします。
  41         </para>
  42
  43         <para>
  44             まず、ビューオブジェクトに Dojo ビューヘルパーのパスを教えてやる必要があります。
  45             これは、起動ファイルあるいは初期に実行されるプラグインで行います。
  46             ビューオブジェクトを取得して次のコードを実行しましょう。
  47         </para>
  48
  49         <programlisting language="php"><![CDATA[
  50 $view->addHelperPath('Zend/Dojo/View/Helper/', 'Zend_Dojo_View_Helper');
  51 ]]></programlisting>
  52
  53         <para>
  54             次はビュースクリプトです。今回の例では、
  55             FilteringSelect を使うことにします。
  56             これは QueryReadStore を継承したカスタムストアを使用します。
  57             今回の例ではこれは 'PairedStore' という名前で、
  58             'custom' モジュールに格納します。
  59         </para>
  60
  61         <programlisting language="php"><![CDATA[
  62 <?php // FilteringSelect 用のデータストアの設定 ?>
  63 <div dojoType="custom.PairedStore" jsId="stateStore"
  64     url="/data/autocomplete/type/state/format/ajax"
  65     requestMethod="get"></div>
  66
  67 <?php // 入力要素 ?>
  68 State: <input id="state" dojoType="dijit.form.FilteringSelect"
  69     store="stateStore" pageSize="5" />
  70
  71 <?php // 必須 dojo 要素の設定
  72 $this->dojo()->enable()
  73              ->setDjConfigOption('parseOnLoad', true)
  74              ->registerModulePath('custom', '../custom/')
  75              ->requireModule('dijit.form.FilteringSelect')
  76              ->requireModule('custom.PairedStore'); ?>
  77 ]]></programlisting>
  78
  79         <para>
  80             レイアウトスクリプトでは、
  81             まず Dojo が有効になっているかどうかを調べ、
  82             有効ならさらに設定を行ってそれを使用します。
  83         </para>
  84
  85         <programlisting language="php"><![CDATA[
  86 <?php echo $this->doctype() ?>
  87 <html>
  88 <head>
  89     <?php echo $this->headTitle() ?>
  90     <?php echo $this->headMeta() ?>
  91     <?php echo $this->headLink() ?>
  92     <?php echo $this->headStyle() ?>
  93 <?php if ($this->dojo()->isEnabled()){
  94     $this->dojo()->setLocalPath('/js/dojo/dojo.js')
  95                  ->addStyleSheetModule('dijit.themes.tundra');
  96     echo $this->dojo();
  97    }
  98 ?>
  99     <?php echo $this->headScript() ?>
 100 </head>
 101 <body class="tundra">
 102     <?php echo $this->layout()->content ?>
 103     <?php echo $this->inlineScript() ?>
 104 </body>
 105 </html>
 106 ]]></programlisting>
 107
 108         <para>
 109             これで、各ファイルが正しい場所にありさえすれば
 110             FilteringSelect を使った処理ができるようになりました!
 111         </para>
 112     </example>
 113
 114     <note>
 115         <title>UTF-8 encoding used by default</title>
 116
 117         <para>
 118             By default, Zend Framework uses <acronym>UTF-8</acronym> as its default encoding, and,
 119             specific to this case, <classname>Zend_View</classname> does as well. Character encoding
 120             can be set differently on the view object itself using the
 121             <methodname>setEncoding()</methodname> method (or the the <property>encoding</property>
 122             instantiation parameter). However, since <classname>Zend_View_Interface</classname> does
 123             not define accessors for encoding, it's possible that if you are using a custom view
 124             implementation with the Dojo view helper, you will not have a
 125             <methodname>getEncoding()</methodname> method, which is what the view helper uses
 126             internally for determining the character set in which to encode.
 127         </para>
 128
 129         <para>
 130             If you do not want to utilize <acronym>UTF-8</acronym> in such a situation, you will
 131             need to implement a <methodname>getEncoding()</methodname> method in your custom view
 132             implementation.
 133         </para>
 134     </note>
 135
 136     <sect3 id="zend.dojo.view.dojo.declarative">
 137         <title>プログラム的および宣言的な Dojo 使用法</title>
 138
 139         <para>
 140             Dojo の機能の多くは、<emphasis>宣言的 (declarative)</emphasis>
 141             な方法および <emphasis>プログラム的 (programmatic)</emphasis>
 142             な方法の両方で使用できます。
 143             <emphasis>宣言的</emphasis> な使用法とは、
 144             標準の <acronym>HTML</acronym> 要素に対して非標準の属性を指定し、
 145             ページの読み込み時にそれをパースするというものです。
 146             これは強力でシンプルな構文のため使用しやすいのですが、
 147             ページの検証時に問題を起こす可能性があります。
 148         </para>
 149
 150         <para>
 151             <emphasis>プログラム的</emphasis> な使用法とは、
 152             既存の要素を ID もしくは <acronym>CSS</acronym> セレクタで取得し、
 153             それを Dojo の適切なオブジェクトのコンストラクタに渡すというものです。
 154             非標準の <acronym>HTML</acronym> 属性を使うことはないので、ページの検証はうまくいきます。
 155         </para>
 156
 157         <para>
 158             実際のところ、どちらの手法を用いたとしても、
 159             javascript が無効になっていたり
 160             Dojo スクリプトリソースが使用できなかったりした場合に機能が低下してしまいます。
 161             標準規格とドキュメントの検証を優先させるため、Zend Framework
 162             ではプログラム的な使用法をデフォルトとしています。
 163             さまざまなビューヘルパーが javascript を生成してそれを
 164             <methodname>dojo()</methodname> ビューヘルパーに渡し、レンダリング時に読み込むのです。
 165         </para>
 166
 167         <para>
 168             この方法を使うと、さまざまなオプションを使用して
 169             プログラム上で独自のデコレーションを行うことができます。
 170             たとえば dijit イベントのハンドラを指定することなども可能です。
 171         </para>
 172
 173         <para>
 174             そのために、宣言的な構文の機能以外にも多くの静的メソッドが用意されており、
 175             全体の振る舞いを設定できます。
 176         </para>
 177
 178         <example id="zend.dojo.view.dojo.declarative.usage">
 179             <title>宣言的、あるいはプログラム的な Dojo の使用法の指定</title>
 180
 181             <para>
 182                 宣言的な使用法を指定するには、静的メソッド
 183                 <methodname>setUseDeclarative()</methodname> をコールします。
 184             </para>
 185
 186             <programlisting language="php"><![CDATA[
 187 Zend_Dojo_View_Helper_Dojo::setUseDeclarative();
 188 ]]></programlisting>
 189
 190             <para>
 191                 プログラム的な使用法を指定するには、静的メソッド
 192                 <methodname>setUseProgrammatic()</methodname> をコールします。
 193             </para>
 194
 195             <programlisting language="php"><![CDATA[
 196 Zend_Dojo_View_Helper_Dojo::setUseProgrammatic();
 197 ]]></programlisting>
 198
 199             <para>
 200                 独自のプログラム的なルールを作成したい場合は、
 201                 プログラム的な使用法を指定する際に値 '-1'
 202                 を渡す必要があります。この場合、
 203                 dijit を装飾するための javascript は生成されません。
 204             </para>
 205
 206             <programlisting language="php"><![CDATA[
 207 Zend_Dojo_View_Helper_Dojo::setUseProgrammatic(-1);
 208 ]]></programlisting>
 209         </example>
 210     </sect3>
 211
 212     <sect3 id="zend.dojo.view.dojo.themes">
 213         <title>テーマ</title>
 214
 215         <para>
 216             Dojo では、dijits (widgets) 用のテーマを作成できます。
 217             テーマを選択するにはモジュールパスにそれを渡します。
 218         </para>
 219
 220         <programlisting language="php"><![CDATA[
 221 $view->dojo()->addStylesheetModule('dijit.themes.tundra');
 222 ]]></programlisting>
 223
 224         <para>
 225             モジュールパスの検索は、'.' をディレクトリ区切り文字として使用し、
 226             リストの最後の名前を <acronym>CSS</acronym> ファイルと見て行います。上の例では、Dojo は
 227             '<filename>dijit/themes/tundra/tundra.css</filename>' のテーマを探します。
 228         </para>
 229
 230         <para>
 231             テーマを使う際に重要なのは、使用するすべての dijit
 232             について、それを囲むコンテナにテーマのクラスを指定することです。
 233             もっともよくある例は、body に指定するものです。
 234         </para>
 235
 236         <programlisting language="html"><![CDATA[
 237 <body class="tundra">
 238 ]]></programlisting>
 239     </sect3>
 240
 241     <sect3 id="zend.dojo.view.dojo.layers">
 242         <title>レイヤーの使用 (カスタムビルド)</title>
 243
 244         <para>
 245             デフォルトでは、<command>dojo.require</command> ステートメントを使用すると
 246             dojo はサーバにリクエストを返し、適切な javascript ファイルを取得します。
 247             たくさんの dijit を使用する場合は、大量のリクエストがサーバに届くことになります。
 248             これはちょっと無駄ですね。
 249         </para>
 250
 251         <para>
 252             これに対する Dojo からの回答はとして用意したのが
 253             <emphasis>カスタムビルド</emphasis>
 254             です。これは、次のようなことを行います。
 255         </para>
 256
 257         <itemizedlist>
 258             <listitem><para>
 259                 必要なファイルを <emphasis>レイヤー</emphasis> にまとめます。
 260                 レイヤーは、すべての必要なファイルをひとつの
 261                 JS ファイルにまとめたものです
 262                 (これが、このセクションの名前の由来です)。
 263             </para></listitem>
 264
 265             <listitem><para>
 266                 digit が使用する javascript 以外のファイル (テンプレートファイルなど)
 267                 をまとめます。
 268                 これらもまた、レイヤーとして同じ JS ファイルにまとめられます。
 269             </para></listitem>
 270
 271             <listitem><para>
 272                 そのファイルを ShrinkSafe に渡します。
 273                 これは、空白文字やコメントを削除して変数名を短くします。
 274             </para></listitem>
 275         </itemizedlist>
 276
 277         <para>
 278             中にはレイヤー化できないファイルもありますが、
 279             ビルドの際にリリース用のディレクトリが作成され、
 280             レイヤーファイルとその他のすべてのファイルが格納されます。
 281             これにより、あなたの作成するサイトやアプリケーションが
 282             必要とするだけの内容に最適化した内容を配布できます。
 283         </para>
 284
 285         <para>
 286             レイヤーを使うために、<methodname>dojo()</methodname> ビューヘルパーには
 287             <methodname>addLayer()</methodname> メソッドが用意されており、
 288             これで必要なレイヤーへのパスを追加します。
 289         </para>
 290
 291         <programlisting language="html"><![CDATA[
 292 $view->dojo()->addLayer('/js/foo/foo.js');
 293 ]]></programlisting>
 294
 295         <para>
 296             独自のビルドを作成するためのさらなる情報は、<ulink
 297                 url="http://dojotoolkit.org/book/dojo-book-0-9/part-4-meta-dojo/package-system-and-custom-builds">
 298             Dojo のビルドのドキュメントを参照ください</ulink>。
 299         </para>
 300     </sect3>
 301
 302     <sect3 id="zend.dojo.view.dojo.methods">
 303         <title>使用できるメソッド</title>
 304
 305         <para>
 306             <methodname>dojo()</methodname> ビューヘルパーは常に、
 307             dojo プレースホルダコンテナのインスタンスを返します。
 308             このコンテナオブジェクトで使用できるメソッドは次のとおりです。
 309         </para>
 310
 311         <itemizedlist>
 312             <listitem><para><methodname>setView(Zend_View_Interface $view)</methodname>:
 313                     コンテナ内のビューインスタンスを設定します。</para></listitem>
 314             <listitem><para><methodname>enable()</methodname>:
 315                     Dojo 統合機能を明示的に有効化します。</para></listitem>
 316             <listitem><para><methodname>disable()</methodname>:
 317                     Dojo 統合機能を無効化します。</para></listitem>
 318             <listitem><para><methodname>isEnabled()</methodname>:
 319                     Dojo 統合機能が有効かどうかを調べます。</para></listitem>
 320             <listitem><para><methodname>requireModule($module)</methodname>:
 321                     <command>dojo.require</command> 文を作成します。</para></listitem>
 322             <listitem><para><methodname>getModules()</methodname>:
 323                     どのモジュールが必要なのかを調べます。</para></listitem>
 324             <listitem><para><methodname>registerModulePath($module, $path)</methodname>:
 325                     独自の Dojo モジュールのパスを登録します。</para></listitem>
 326             <listitem><para><methodname>getModulePaths()</methodname>:
 327                     登録済みのモジュールパスの一覧を取得します。</para></listitem>
 328             <listitem><para><methodname>addLayer($path)</methodname>:
 329                     使用するレイヤー (カスタムビルド) のパスを追加します。</para></listitem>
 330             <listitem><para><methodname>getLayers()</methodname>:
 331                     登録済みのすべてのレイヤー (カスタムビルド) のパスの一覧を取得します。</para></listitem>
 332             <listitem><para><methodname>removeLayer($path)</methodname>:
 333                     <code>$path</code> にマッチするレイヤー (カスタムビルド) を、
 334                     登録済みレイヤーの一覧から削除します。</para></listitem>
 335             <listitem><para><methodname>setCdnBase($url)</methodname>:
 336                     <acronym>CDN</acronym> 用のベース <acronym>URL</acronym> を設定します。一般的には
 337                     <constant>Zend_Dojo::CDN_BASE_AOL</constant> あるいは
 338                     <constant>Zend_Dojo::CDN_BASE_GOOGLE</constant>
 339                     となりますが、これはバージョン番号より前に <acronym>URL</acronym> 文字列に必要となります。</para></listitem>
 340             <listitem><para><methodname>getCdnBase()</methodname>:
 341                     使用するベース <acronym>CDN</acronym> の <acronym>URL</acronym> を取得します。</para></listitem>
 342             <listitem><para><methodname>setCdnVersion($version = null)</methodname>:
 343                     <acronym>CDN</acronym> から使用する Dojo のバージョンを設定します。</para></listitem>
 344             <listitem><para><methodname>getCdnVersion()</methodname>:
 345                     <acronym>CDN</acronym> からどのバージョンの Dojo を使用しているかを取得します。</para></listitem>
 346             <listitem><para><methodname>setCdnDojoPath($path)</methodname>:
 347                     <acronym>CDN</acronym> 上のファイル <filename>dojo.js</filename> あるいは <filename>dojo.xd.js</filename> への相対パスを設定します。一般的には
 348                     <constant>Zend_Dojo::CDN_DOJO_PATH_AOL</constant> あるいは
 349                     <constant>Zend_Dojo::CDN_DOJO_PATH_GOOGLE</constant>
 350                     となりますが、これはバージョン番号の後の <acronym>URL</acronym> 文字列に必要となります。</para></listitem>
 351             <listitem><para><methodname>getCdnDojoPath()</methodname>:
 352                     dojo.js ファイルを指す、<acronym>CDN</acronym> url のパスの最後の部分を取得します。</para></listitem>
 353             <listitem><para><methodname>useCdn()</methodname>:
 354                     コンテナに、<acronym>CDN</acronym> を使用するよう指定します。暗黙的に統合機能を有効化します。</para></listitem>
 355             <listitem><para><methodname>setLocalPath($path)</methodname>:
 356                     コンテナに、ローカルの Dojo インストールパスを指定します
 357                     (サーバからの相対パスで、かつ <filename>dojo.js</filename> ファイル自体も含まなければなりません)。
 358                     暗黙的に統合機能を有効化します。</para></listitem>
 359             <listitem><para><methodname>getLocalPath()</methodname>:
 360                     どのローカルパスの Dojo を使用しているかを取得します。</para></listitem>
 361             <listitem><para><methodname>useLocalPath()</methodname>:
 362                     統合機能がローカルパスの Dojo を使用しているかどうかを調べます。</para></listitem>
 363             <listitem><para><methodname>setDjConfig(array $config)</methodname>:
 364                     dojo または dijit の設定項目を設定します
 365                     (連想配列で指定します)。</para></listitem>
 366             <listitem><para><methodname>setDjConfigOption($option, $value)</methodname>:
 367                     単一の dojo または dijit 設定項目を設定します。</para></listitem>
 368             <listitem><para><methodname>getDjConfig()</methodname>:
 369                     すべての dojo または dijit 設定値を取得します。</para></listitem>
 370             <listitem><para><methodname>getDjConfigOption($option, $default =
 371                     null)</methodname>:
 372                     単一の dojo または dijit 設定値を取得します。</para></listitem>
 373             <listitem><para><methodname>addStylesheetModule($module)</methodname>:
 374                     モジュールのテーマに基づいたスタイルシートを追加します。</para></listitem>
 375             <listitem><para><methodname>getStylesheetModules()</methodname>:
 376                     モジュールのテーマとして登録されたスタイルシートを取得します。</para></listitem>
 377             <listitem><para><methodname>addStylesheet($path)</methodname>:
 378                     Dojo で使用するローカルスタイルシートを追加します。</para></listitem>
 379             <listitem><para><methodname>getStylesheets()</methodname>:
 380                     ローカル Dojo スタイルシートを取得します。</para></listitem>
 381             <listitem><para><methodname>addOnLoad($spec, $function = null)</methodname>:
 382                     <command>dojo.onLoad</command> がコールするラムダ関数を追加します。
 383                     引数をひとつわたした場合は、
 384                     関数名あるいは javascript のクロージャと見なされます。
 385                     引数をふたつわたした場合は、
 386                     最初の引数がオブジェクトのインスタンスを表す変数名、
 387                     二番目の引数がそのオブジェクトのメソッド名あるいは
 388                     そのオブジェクトで使用するクロージャと見なされます。</para></listitem>
 389             <listitem><para><methodname>prependOnLoad($spec, $function = null)</methodname>:
 390                     <methodname>addOnLoad()</methodname> と同じですが、onLoad
 391                     スタックの先頭に追加するという点だけが異なります。</para></listitem>
 392             <listitem><para><methodname>getOnLoadActions()</methodname>:
 393                     コンテナに登録されているすべての <command>dojo.onLoad()</command>
 394                     アクションを取得します。
 395                     これは配列の配列となります。</para></listitem>
 396             <listitem><para><methodname>onLoadCaptureStart($obj = null)</methodname>:
 397                     <command>dojo.onLoad()</command> のラムダ関数として使用するデータをキャプチャします。
 398                     <varname>$obj</varname> が指定された場合は、キャプチャされた JS コードはその
 399                     Javascript オブジェクトで使用するクロージャであると見なします。</para></listitem>
 400             <listitem><para><methodname>onLoadCaptureEnd($obj = null)</methodname>:
 401                     <command>dojo.onLoad()</command> で使用するデータのキャプチャを終了します。</para></listitem>
 402             <listitem><para><methodname>javascriptCaptureStart()</methodname>:
 403                     任意の javascript をキャプチャし、Dojo JS
 404                     (onLoad や require など) として取り込めるようにします。</para></listitem>
 405             <listitem><para><methodname>javascriptCaptureEnd()</methodname>:
 406                     javascript のキャプチャを終了します。</para></listitem>
 407             <listitem><para><methodname>__toString()</methodname>:
 408                     コンテナを文字列にキャストします。すべての <acronym>HTML</acronym> style 要素および
 409                     script 要素をレンダリングします。</para></listitem>
 410         </itemizedlist>
 411     </sect3>
 412 </sect2>
 413 <!--
 414 vim:se ts=4 sw=4 et:
 415 -->