<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 17598 -->
<sect2 id="zend.dojo.view.dojo">
    <title>dojo() ビューヘルパー</title>

    <para>
        <methodname>dojo()</methodname> ビューヘルパーは
        Dojo 環境のセットアップを簡単に行うためのものです。
        次のような機能があります。
    </para>

    <itemizedlist>
        <listitem><para>CDN あるいはローカルパスのどちらの Dojo
                を使用するかの指定</para></listitem>
        <listitem><para>カスタム Dojo モジュールへのパスの指定</para></listitem>
        <listitem><para>dojo.require 文の指定</para></listitem>
        <listitem><para>使用する dijit スタイルシートテーマの指定</para></listitem>
        <listitem><para>dojo.addOnLoad() イベントの指定</para></listitem>
    </itemizedlist>

    <para>
        <methodname>dojo()</methodname> ビューヘルパーの実装は、
        プレースホルダの実装の一例です。
        中で扱うデータセットはビューオブジェクトを超えて永続化され、
        レイアウトスクリプトから直接 echo することができます。
    </para>

    <example id="zend.dojo.view.dojo.usage">
        <title>dojo() ビューヘルパーの使用例</title>

        <para>
            この例では、ローカルパスの Dojo を使うことを想定しています。
            またいくつかの dijit を使い、Tundra dijit テーマを使用するものとします。
        </para>

        <para>
            多くのページでは、開発者は Dojo をまったく使用しません。
            そこで、Dojo が必要となるビュースクリプトやレイアウトスクリプトだけに注目し、
            そこで Dojo 環境を用意してレンダリングすることにします。
        </para>

        <para>
            まず、ビューオブジェクトに Dojo ビューヘルパーのパスを教えてやる必要があります。
            これは、起動ファイルあるいは初期に実行されるプラグインで行います。
            ビューオブジェクトを取得して次のコードを実行しましょう。
        </para>

        <programlisting language="php"><![CDATA[
$view->addHelperPath('Zend/Dojo/View/Helper/', 'Zend_Dojo_View_Helper');
]]></programlisting>

        <para>
            次はビュースクリプトです。今回の例では、
            FilteringSelect を使うことにします。
            これは QueryReadStore を継承したカスタムストアを使用します。
            今回の例ではこれは 'PairedStore' という名前で、
            'custom' モジュールに格納します。
        </para>

        <programlisting language="php"><![CDATA[
<?php // FilteringSelect 用のデータストアの設定 ?>
<div dojoType="custom.PairedStore" jsId="stateStore"
    url="/data/autocomplete/type/state/format/ajax"
    requestMethod="get"></div>

<?php // 入力要素 ?>
State: <input id="state" dojoType="dijit.form.FilteringSelect"
    store="stateStore" pageSize="5" />

<?php // 必須 dojo 要素の設定
$this->dojo()->enable()
             ->setDjConfigOption('parseOnLoad', true)
             ->registerModulePath('custom', '../custom/')
             ->requireModule('dijit.form.FilteringSelect')
             ->requireModule('custom.PairedStore'); ?>
]]></programlisting>

        <para>
            レイアウトスクリプトでは、
            まず Dojo が有効になっているかどうかを調べ、
            有効ならさらに設定を行ってそれを使用します。
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->doctype() ?>
<html>
<head>
    <?php echo $this->headTitle() ?>
    <?php echo $this->headMeta() ?>
    <?php echo $this->headLink() ?>
    <?php echo $this->headStyle() ?>
<?php if ($this->dojo()->isEnabled()){
    $this->dojo()->setLocalPath('/js/dojo/dojo.js')
                 ->addStyleSheetModule('dijit.themes.tundra');
    echo $this->dojo();
   }
?>
    <?php echo $this->headScript() ?>
</head>
<body class="tundra">
    <?php echo $this->layout()->content ?>
    <?php echo $this->inlineScript() ?>
</body>
</html>
]]></programlisting>

        <para>
            これで、各ファイルが正しい場所にありさえすれば
            FilteringSelect を使った処理ができるようになりました!
        </para>
    </example>

    <sect3 id="zend.dojo.view.dojo.declarative">
        <title>プログラム的 (Programmatic) および宣言的 (Declarative) な Dojo の使用法</title>

        <para>
            Dojo の機能の多くは、<emphasis>宣言的 (declarative)</emphasis>
            な方法および <emphasis>プログラム的 (programmatic)</emphasis>
            な方法の両方で使用することができます。
            <emphasis>宣言的</emphasis> な使用法とは、
            標準の HTML 要素に対して非標準の属性を指定し、
            ページの読み込み時にそれをパースするというものです。
            これは強力でシンプルな構文のため使用しやすいのですが、
            ページの検証時に問題を起こす可能性があります。
        </para>

        <para>
            <emphasis>プログラム的</emphasis> な使用法とは、
            既存の要素を ID もしくは <acronym>CSS</acronym> セレクタで取得し、
            それを Dojo の適切なオブジェクトのコンストラクタに渡すというものです。
            非標準の HTML 属性を使うことはないので、ページの検証はうまくいきます。
        </para>

        <para>
            実際のところ、どちらの手法を用いたとしても、
            javascript が無効になっていたり
            Dojo スクリプトリソースが使用できなかったりした場合に機能が低下してしまいます。
            標準規格とドキュメントの検証を優先させるため、Zend Framework
            ではプログラム的な使用法をデフォルトとしています。
            さまざまなビューヘルパーが javascript を生成してそれを
            <methodname>dojo()</methodname> ビューヘルパーに渡し、レンダリング時に読み込むのです。
        </para>

        <para>
            この方法を使うと、さまざまなオプションを使用して
            プログラム上で独自のデコレーションを行うことができます。
            たとえば dijit イベントのハンドラを指定することなども可能です。
        </para>

        <para>
            そのために、宣言的な構文の機能以外にも多くの静的メソッドが用意されており、
            全体の振る舞いを設定することができます。
        </para>

        <example id="zend.dojo.view.dojo.declarative.usage">
            <title>宣言的、あるいはプログラム的な Dojo の使用法の指定</title>

            <para>
                宣言的な使用法を指定するには、静的メソッド
                <methodname>setUseDeclarative()</methodname> をコールします。
            </para>

            <programlisting language="php"><![CDATA[
Zend_Dojo_View_Helper_Dojo::setUseDeclarative();
]]></programlisting>

            <para>
                プログラム的な使用法を指定するには、静的メソッド
                <methodname>setUseProgrammatic()</methodname> をコールします。
            </para>

            <programlisting language="php"><![CDATA[
Zend_Dojo_View_Helper_Dojo::setUseProgrammatic();
]]></programlisting>

            <para>
                独自のプログラム的なルールを作成したい場合は、
                プログラム的な使用法を指定する際に値 '-1'
                を渡す必要があります。この場合、
                dijit を装飾するための javascript は生成されません。
            </para>

            <programlisting language="php"><![CDATA[
Zend_Dojo_View_Helper_Dojo::setUseProgrammatic(-1);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.view.dojo.themes">
        <title>テーマ</title>

        <para>
            Dojo では、dijits (widgets) 用のテーマを作成することができます。
            テーマを選択するにはモジュールパスにそれを渡します。
        </para>

        <programlisting language="php"><![CDATA[
$view->dojo()->addStylesheetModule('dijit.themes.tundra');
]]></programlisting>

        <para>
            モジュールパスの検索は、'.' をディレクトリ区切り文字として使用し、
            リストの最後の名前を <acronym>CSS</acronym> ファイルと見て行います。上の例では、Dojo は
            'dijit/themes/tundra/tundra.css' のテーマを探します。
        </para>

        <para>
            テーマを使う際に重要なのは、使用するすべての dijit
            について、それを囲むコンテナにテーマのクラスを指定することです。
            もっともよくある例は、body に指定するものです。
        </para>

        <programlisting language="html"><![CDATA[
<body class="tundra">
]]></programlisting>
    </sect3>

    <sect3 id="zend.dojo.view.dojo.layers">
        <title>レイヤーの使用 (カスタムビルド)</title>

        <para>
            デフォルトでは、dojo.require ステートメントを使用すると
            dojo はサーバにリクエストを返し、適切な javascript ファイルを取得します。
            たくさんの dijit を使用する場合は、大量のリクエストがサーバに届くことになります。
            これはちょっと無駄ですね。
        </para>

        <para>
            これに対する Dojo からの回答はとして用意したのが
            <emphasis>カスタムビルド</emphasis>
            です。これは、次のようなことを行います。
        </para>

        <itemizedlist>
            <listitem><para>
                必要なファイルを <emphasis>レイヤー</emphasis> にまとめます。
                レイヤーは、すべての必要なファイルをひとつの
                JS ファイルにまとめたものです
                (これが、このセクションの名前の由来です)。
            </para></listitem>

            <listitem><para>
                digit が使用する javascript 以外のファイル (テンプレートファイルなど)
                をまとめます。
                これらもまた、レイヤーとして同じ JS ファイルにまとめられます。
            </para></listitem>

            <listitem><para>
                そのファイルを ShrinkSafe に渡します。
                これは、空白文字やコメントを削除して変数名を短くします。
            </para></listitem>
        </itemizedlist>

        <para>
            中にはレイヤー化できないファイルもありますが、
            ビルドの際にリリース用のディレクトリが作成され、
            レイヤーファイルとその他のすべてのファイルが格納されます。
            これにより、あなたの作成するサイトやアプリケーションが
            必要とするだけの内容に最適化した内容を配布することができます。
        </para>

        <para>
            レイヤーを使うために、<methodname>dojo()</methodname> ビューヘルパーには
            <methodname>addLayer()</methodname> メソッドが用意されており、
            これで必要なレイヤーへのパスを追加します。
        </para>

        <programlisting language="html"><![CDATA[
$view->dojo()->addLayer('/js/foo/foo.js');
]]></programlisting>

        <para>
            独自のビルドを作成するためのさらなる情報は、<ulink
                url="http://dojotoolkit.org/book/dojo-book-0-9/part-4-meta-dojo/package-system-and-custom-builds">
            Dojo のビルドのドキュメントを参照ください</ulink>。
        </para>
    </sect3>

    <sect3 id="zend.dojo.view.dojo.methods">
        <title>使用できるメソッド</title>

        <para>
            <methodname>dojo()</methodname> ビューヘルパーは常に、
            dojo プレースホルダコンテナのインスタンスを返します。
            このコンテナオブジェクトで使用できるメソッドは次のとおりです。
        </para>

        <itemizedlist>
            <listitem><para><methodname>setView(Zend_View_Interface $view)</methodname>:
                    コンテナ内のビューインスタンスを設定します。</para></listitem>
            <listitem><para><methodname>enable()</methodname>:
                    Dojo 統合機能を明示的に有効化します。</para></listitem>
            <listitem><para><methodname>disable()</methodname>:
                    Dojo 統合機能を無効化します。</para></listitem>
            <listitem><para><methodname>isEnabled()</methodname>:
                    Dojo 統合機能が有効かどうかを調べます。</para></listitem>
            <listitem><para><methodname>requireModule($module)</methodname>:
                    <code>dojo.require</code> 文を作成します。</para></listitem>
            <listitem><para><methodname>getModules()</methodname>:
                    どのモジュールが必要なのかを調べます。</para></listitem>
            <listitem><para><methodname>registerModulePath($module, $path)</methodname>:
                    独自の Dojo モジュールのパスを登録します。</para></listitem>
            <listitem><para><methodname>getModulePaths()</methodname>:
                    登録済みのモジュールパスの一覧を取得します。</para></listitem>
            <listitem><para><methodname>addLayer($path)</methodname>:
                    使用するレイヤー (カスタムビルド) のパスを追加します。</para></listitem>
            <listitem><para><methodname>getLayers()</methodname>:
                    登録済みのすべてのレイヤー (カスタムビルド) のパスの一覧を取得します。</para></listitem>
            <listitem><para><methodname>removeLayer($path)</methodname>:
                    <code>$path</code> にマッチするレイヤー (カスタムビルド) を、
                    登録済みレイヤーの一覧から削除します。</para></listitem>
            <listitem><para><methodname>setCdnBase($url)</methodname>:
                    CDN 用のベース <acronym>URL</acronym> を設定します。一般的には
                    <constant>Zend_Dojo::CDN_BASE_AOL</constant> あるいは
                    <constant>Zend_Dojo::CDN_BASE_GOOGLE</constant>
                    となりますが、これはバージョン番号より前に <acronym>URL</acronym> 文字列に必要となります。</para></listitem>
            <listitem><para><methodname>getCdnBase()</methodname>:
                    使用するベース CDN の <acronym>URL</acronym> を取得します。</para></listitem>
            <listitem><para><methodname>setCdnVersion($version = null)</methodname>:
                    CDN から使用する Dojo のバージョンを設定します。</para></listitem>
            <listitem><para><methodname>getCdnVersion()</methodname>:
                    CDN からどのバージョンの Dojo を使用しているかを取得します。</para></listitem>
            <listitem><para><methodname>setCdnDojoPath($path)</methodname>:
                    CDN 上のファイル dojo.js あるいは dojo.xd.js への相対パスを設定します。一般的には
                    <constant>Zend_Dojo::CDN_DOJO_PATH_AOL</constant> あるいは
                    <constant>Zend_Dojo::CDN_DOJO_PATH_GOOGLE</constant>
                    となりますが、これはバージョン番号の後の <acronym>URL</acronym> 文字列に必要となります。</para></listitem>
            <listitem><para><methodname>getCdnDojoPath()</methodname>:
                    dojo.js ファイルを指す、CDN url のパスの最後の部分を取得します。</para></listitem>
            <listitem><para><methodname>useCdn()</methodname>:
                    コンテナに、CDN を使用するよう指定します。暗黙的に統合機能を有効化します。</para></listitem>
            <listitem><para><methodname>setLocalPath($path)</methodname>:
                    コンテナに、ローカルの Dojo インストールパスを指定します
                    (サーバからの相対パスで、かつ dojo.js ファイル自体も含まなければなりません)。
                    暗黙的に統合機能を有効化します。</para></listitem>
            <listitem><para><methodname>getLocalPath()</methodname>:
                    どのローカルパスの Dojo を使用しているかを取得します。</para></listitem>
            <listitem><para><methodname>useLocalPath()</methodname>:
                    統合機能がローカルパスの Dojo を使用しているかどうかを調べます。</para></listitem>
            <listitem><para><methodname>setDjConfig(array $config)</methodname>:
                    dojo/dijit の設定項目を設定します
                    (連想配列で指定します)。</para></listitem>
            <listitem><para><methodname>setDjConfigOption($option, $value)</methodname>:
                    単一の dojo/dijit 設定項目を設定します。</para></listitem>
            <listitem><para><methodname>getDjConfig()</methodname>:
                    すべての dojo/dijit 設定値を取得します。</para></listitem>
            <listitem><para><methodname>getDjConfigOption($option, $default =
                    null)</methodname>:
                    単一の dojo/dijit 設定値を取得します。</para></listitem>
            <listitem><para><methodname>addStylesheetModule($module)</methodname>:
                    モジュールのテーマに基づいたスタイルシートを追加します。</para></listitem>
            <listitem><para><methodname>getStylesheetModules()</methodname>:
                    モジュールのテーマとして登録されたスタイルシートを取得します。</para></listitem>
            <listitem><para><methodname>addStylesheet($path)</methodname>:
                    Dojo で使用するローカルスタイルシートを追加します。</para></listitem>
            <listitem><para><methodname>getStylesheets()</methodname>:
                    ローカル Dojo スタイルシートを取得します。</para></listitem>
            <listitem><para><methodname>addOnLoad($spec, $function = null)</methodname>:
                    dojo.onLoad がコールするラムダ関数を追加します。
                    引数をひとつわたした場合は、
                    関数名あるいは javascript のクロージャと見なされます。
                    引数をふたつわたした場合は、
                    最初の引数がオブジェクトのインスタンスを表す変数名、
                    二番目の引数がそのオブジェクトのメソッド名あるいは
                    そのオブジェクトで使用するクロージャと見なされます。</para></listitem>
            <listitem><para><methodname>prependOnLoad($spec, $function = null)</methodname>:
                    <methodname>addOnLoad()</methodname> と同じですが、onLoad
                    スタックの先頭に追加するという点だけが異なります。</para></listitem>
            <listitem><para><methodname>getOnLoadActions()</methodname>:
                    コンテナに登録されているすべての dojo.onLoad
                    アクションを取得します。
                    これは配列の配列となります。</para></listitem>
            <listitem><para><methodname>onLoadCaptureStart($obj = null)</methodname>:
                    dojo.onLoad() のラムダ関数として使用するデータをキャプチャします。
                    $obj が指定された場合は、キャプチャされた JS コードはその
                    Javascript オブジェクトで使用するクロージャであると見なします。</para></listitem>
            <listitem><para><methodname>onLoadCaptureEnd($obj = null)</methodname>:
                    dojo.onLoad() で使用するデータのキャプチャを終了します。</para></listitem>
            <listitem><para><methodname>javascriptCaptureStart()</methodname>:
                    任意の javascript をキャプチャし、Dojo JS
                    (onLoad や require など) として取り込めるようにします。</para></listitem>
            <listitem><para><methodname>javascriptCaptureEnd()</methodname>:
                    javascript のキャプチャを終了します。</para></listitem>
            <listitem><para><methodname>__toString()</methodname>:
                    コンテナを文字列にキャストします。すべての HTML style 要素および
                    script 要素をレンダリングします。</para></listitem>
        </itemizedlist>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->
