[GENERIC] Zend_Translate:

[zend.git] / documentation / manual / ja / module_specs / Zend_Controller-ActionHelpers-ViewRenderer.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 20765 -->
<sect3 id="zend.controller.actionhelpers.viewrenderer">
    <title>ViewRenderer</title>

    <sect4 id="zend.controller.actionhelper.viewrenderer.introduction">
        <title>導入</title>

        <para>
            <emphasis>ViewRenderer</emphasis> ヘルパーは、
            以下のような要件を満たすために作られたものです。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    コントローラ内でいちいちビューオブジェクトのインスタンスを
                    作成しなくても済むようにする。
                    ビューオブジェクトは自動的にコントローラに登録されます。
                </para>
            </listitem>

            <listitem>
                <para>
                    ビュースクリプトやヘルパー、そしてフィルタのパスを
                    現在のモジュールに基づいて自動的に設定し、
                    モジュール名をヘルパーやフィルタのクラス名の先頭に自動的に関連付ける。
                </para>
            </listitem>

            <listitem>
                <para>
                    すべてのコントローラとアクションで使用できる
                    グローバルなビューオブジェクトを作成する。
                </para>
            </listitem>

            <listitem>
                <para>
                    すべてのコントローラで使用する、
                    デフォルトのビューレンダリングオプションを設定できるようにする。
                </para>
            </listitem>

            <listitem>
                <para>
                    何も指定しなくても、
                    自動的にビュースクリプトをレンダリングできる機能を追加する。
                </para>
            </listitem>

            <listitem>
                <para>
                    ビューの基底パスやビュースクリプトのパスを
                    独自に指定できるようにする。
                </para>
            </listitem>
        </itemizedlist>

        <note>
            <para>
                <methodname>_forward()</methodname> や <methodname>redirect()</methodname>、
                あるいは手動での <methodname>render()</methodname> を行う場合は、
                自動レンダリングは不要です。これらの処理を行う場合は、
                出力を自前で行うことを <emphasis>ViewRenderer</emphasis>
                に対して指示します。
            </para>
        </note>

        <note>
            <para>
                <emphasis>ViewRenderer</emphasis> はデフォルトで有効になっています。
                これを無効にするには、フロントコントローラのパラメータ
                <emphasis>noViewRenderer</emphasis> を指定する
                (<command>$front->setParam('noViewRenderer', true);</command>) か、
                あるいはヘルパーブローカからヘルパーを削除
                (<methodname>Zend_Controller_Action_HelperBroker::removeHelper('viewRenderer')</methodname>)
                します。
            </para>

            <para>
                フロントコントローラでのディスパッチ処理の前に
                <emphasis>ViewRenderer</emphasis> の設定を変更したい場合は、
                次のいずれかの方法を使用します。
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        独自の <emphasis>ViewRenderer</emphasis> のインスタンスを作成し、
                        ヘルパーブローカにそれを渡して登録する。
                    </para>

                    <programlisting language="php"><![CDATA[
$viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer();
$viewRenderer->setView($view)
             ->setViewSuffix('php');
Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
]]></programlisting>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>ViewRenderer</emphasis> オブジェクトを、
                        ヘルパーブローカから必要に応じて作成、取得する。
                    </para>

                    <programlisting language="php"><![CDATA[
$viewRenderer =
    Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
$viewRenderer->setView($view)
             ->setViewSuffix('php');
]]></programlisting>
                </listitem>
            </itemizedlist>
        </note>
    </sect4>

    <sect4 id="zend.controller.actionhelper.viewrenderer.api">
        <title>API</title>

        <para>
            もっとも基本的な使用法は、単に <emphasis>ViewRenderer</emphasis>
            のインスタンスを作成してそれをヘルパーブローカに渡すというものです。
            インスタンスの作成と登録を一度に行うには、ヘルパーブローカの
            <methodname>getStaticHelper()</methodname> メソッドを使用するのがいちばん簡単です。
        </para>

        <programlisting language="php"><![CDATA[
Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
]]></programlisting>

        <para>
            アクションコントローラのインスタンスが最初に作成されたときに、
            <emphasis>ViewRenderer</emphasis> がビューオブジェクトのインスタンスを作成します。
            コントローラのインスタンスが作成されるたびに、<emphasis>ViewRenderer</emphasis>
            の <methodname>init()</methodname> が呼び出されます。
            ここでアクションコントローラのビュープロパティを設定し、
            現在のモジュールからの相対パスを指定して
            <methodname>addScriptPath()</methodname> を呼び出します。
            これは現在のモジュール名に基づいたプレフィックスをクラス名の先頭につけて呼び出されるので、
            ヘルパーやフィルタのクラスをモジュール内で効率的に管理できます。
        </para>

        <para>
            <methodname>postDispatch()</methodname> が呼び出されるたびに、現在のアクションの
            <methodname>render()</methodname> を自動的に呼び出します。
        </para>

        <para>
            例として、次のようなクラスを考えてみましょう。
        </para>

        <programlisting language="php"><![CDATA[
// foo モジュールのコントローラクラス
class Foo_BarController extends Zend_Controller_Action
{
    // デフォルトで bar/index.phtml をレンダリングするので、特に何もする必要はありません
    public function indexAction()
    {
    }

    // 変数 'foo' の値を 'bar' に設定して bar/populate.phtml をレンダリングします
    // ビューオブジェクトは既に preDispatch() で定義されているので、既に使用可能です
    public function populateAction()
    {
        $this->view->foo = 'bar';
    }
}

...

// ビュースクリプトの中では、たとえば次のように書きます
$this->foo(); // Foo_View_Helper_Foo::foo() を呼び出します
]]></programlisting>

        <para>
            <emphasis>ViewRenderer</emphasis> には、
            ビューのオプションを取得したり設定したりするためのメソッドも豊富に用意されています。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setView($view)</methodname>
                    は <emphasis>ViewRenderer</emphasis> が使用するビューオブジェクトを設定します。
                    これは、クラスのプロパティ <varname>$view</varname> の値を設定します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setNeverRender($flag = true)</methodname>
                    を使用すると、自動レンダリング機能を全体的に
                    （すべてのコントローラに対して）無効にしたり有効にしたりできます。
                    <constant>TRUE</constant> を指定すると、そのコントローラの <methodname>postDispatch()</methodname>
                    では <methodname>render()</methodname> を呼び出さなくなります。
                    <methodname>getNeverRender()</methodname> は、現在の設定を取得します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setNoRender($flag = true)</methodname>
                    を使用すると、自動レンダリングを無効にしたり有効にしたりできます。
                    <constant>TRUE</constant> を指定すると、現在のコントローラの <methodname>postDispatch()</methodname>
                    では <methodname>render()</methodname> を呼び出さなくなります。
                    この設定は、<methodname>preDispatch()</methodname>
                    が呼び出されるたびにいったんリセットされます
                    (つまり、自動レンダリングを無効にしたいすべてのコントローラで
                    個々にこれを設定する必要があるということです)。
                    <methodname>getNoRender()</methodname> は、現在の設定を取得します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setNoController($flag = true)</methodname>
                    を使用すると、<methodname>render()</methodname>
                    がコントローラ名のサブディレクトリにあるアクションスクリプトを
                    読みにいかなくできます (デフォルトでは読みにいきます)。
                    <methodname>getNoController()</methodname> は、現在の設定を取得します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setNeverController($flag = true)</methodname>
                    は <methodname>setNoController()</methodname> と似ていますが、
                    こちらは全体に影響を与えます。つまり、
                    ディスパッチ処理を行っても設定はリセットされません。
                    <methodname>getNeverController()</methodname> は、現在の設定を取得します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setScriptAction($name)</methodname>
                    を使用すると、レンダリングするアクションスクリプトを指定できます。
                    <varname>$name</varname> は、スクリプト名から拡張子を除いたもの
                    (そして、<emphasis>noController</emphasis> が指定されていない限り、
                    コントローラのディレクトリ名も除いたもの) となります。
                    指定しなかった場合は、リクエストオブジェクト内のアクションに基づいた名前の
                    ビュースクリプトを探します。
                    <methodname>getScriptAction()</methodname> は、現在の設定を取得します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setResponseSegment($name)</methodname>
                    を使用すると、レンダリング結果を出力する
                    レスポンスオブジェクトのセグメント名を指定できます。
                    指定しなかった場合は、デフォルトのセグメントにレンダリングします。
                    <methodname>getResponseSegment()</methodname> は、現在の設定を取得します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>initView($path, $prefix, $options)</methodname>
                    は、ビューの基底パスを指定します。
                    また、ヘルパースクリプトとフィルタスクリプトの先頭につけるクラスプレフィックスや
                    <emphasis>ViewRenderer</emphasis> のオプションも設定します。
                    オプションには、
                    <emphasis>neverRender</emphasis>、<emphasis>noRender</emphasis>、
                    <emphasis>noController</emphasis>、<emphasis>scriptAction</emphasis>
                    および <emphasis>responseSegment</emphasis>
                    のいずれかのフラグを指定します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setRender($action = null, $name = null, $noController
                        = false)</methodname>
                    を使用すると、<emphasis>scriptAction</emphasis> や <emphasis>responseSegment</emphasis>
                    そして <emphasis>noController</emphasis> のいずれかまたは複数を
                    一度に指定できます。<methodname>direct()</methodname>
                    はこのメソッドのエイリアスで、コントローラ内から簡単にコールできます。
                </para>

                <programlisting language="php"><![CDATA[
// 現在のアクションスクリプトではなく 'foo' をレンダリングします
$this->_helper->viewRenderer('foo');

// form.phtml の内容をレスポンスセグメント 'html' にレンダリングします。
// コントローラのビュースクリプト用サブディレクトリは使用しません。
$this->_helper->viewRenderer('form', 'html', true);
]]></programlisting>

                <note><para>
                        <methodname>setRender()</methodname> および <methodname>direct()</methodname>
                        は、実際にはビュースクリプトをレンダリングしません。
                        実際にレンダリングを行うのは <methodname>postDispatch()</methodname>
                        や <methodname>render()</methodname> で、
                        それらのメソッドに対するヒントを指示するだけです。
                </para></note>
            </listitem>
        </itemizedlist>

        <para>
            コンストラクタのオプションとして、
            ビューオブジェクトを渡したり <emphasis>ViewRenderer</emphasis>
            のオプションを渡したりできます。
            このオプションで指定できるのは、<methodname>initView()</methodname>
            で説明したフラグと同じものです。
        </para>

        <programlisting language="php"><![CDATA[
$view    = new Zend_View(array('encoding' => 'UTF-8'));
$options = array('noController' => true, 'neverRender' => true);
$viewRenderer =
    new Zend_Controller_Action_Helper_ViewRenderer($view, $options);
]]></programlisting>

        <para>
            さらに追加のメソッドがあり、
            ビューオブジェクトで使用するビューの基底パスを変更できます。
            また、ビュースクリプトが自動レンダリングを行う際に使用するパスも変更できます。
            これらのメソッドでは、以下のプレースホルダのいずれかあるいは複数が使用できます。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>:moduleDir</emphasis> は、現在のモジュールの基底ディレクトリを指します
                    (規約では、これはモジュールのコントローラディレクトリの親ディレクトリとなります)。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>:module</emphasis> は、現在のモジュール名を指します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>:controller</emphasis> は、現在のコントローラ名を指します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>:action</emphasis> は、現在のアクション名を指します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>:suffix</emphasis> は、ビュースクリプトのサフィックス
                    (<methodname>setViewSuffix()</methodname> で設定したもの) を指します。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            パス指定を制御するメソッドは次のとおりです。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setViewBasePathSpec($spec)</methodname>
                    は、ビューオブジェクトを追加する際に使用する基底パスを
                    決める際に使用するパス指定を変更します。
                    デフォルトの設定は <filename>:moduleDir/views</filename> です。
                    現在の設定を取得するには
                    <methodname>getViewBasePathSpec()</methodname> を使用します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setViewScriptPathSpec($spec)</methodname>
                    は、個々のビュースクリプトのパス
                    (からビュースクリプトの基底パスを除いた部分)
                    を決める際に使用するパス指定を変更します。
                    デフォルトの設定は <filename>:controller/:action.:suffix</filename> です。
                    現在の設定を取得するには
                    <methodname>getViewScriptPathSpec()</methodname> を使用します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setViewScriptPathNoControllerSpec($spec)</methodname>
                    は、<emphasis>noController</emphasis> が有効な場合に
                    個々のビュースクリプトのパス
                    (からビュースクリプトの基底パスを除いた部分)
                    を決める際に使用するパス指定を変更します。
                    デフォルトの設定は <filename>:action.:suffix</filename> です。
                    現在の設定を取得するには
                    <methodname>getViewScriptPathNoControllerSpec()</methodname> を使用します。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            パス指定をよりきめ細かく行うには、
            <link linkend="zend.filter.inflector">Zend_Filter_Inflector</link>
            を使用します。実は、<emphasis>ViewRenderer</emphasis>
            はパスのマッピングを行う際に既にインフレクタを使用しています。
            インフレクタに手を入れたい (独自のインフレクタを使用したり、
            デフォルトのインフレクタに手を加えたりしたい) 場合は、
            以下のメソッドを使用します。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getInflector()</methodname> は、インフレクタを取得します。
                    まだ <methodname>ViewRenderer</methodname> にインフレクタが存在しない場合は、
                    デフォルトの規則にもとづいたインフレクタを作成します。
                </para>

                <para>
                    デフォルトでは、サフィックスやモジュールディレクトリへの参照に静的ルールを使用します。
                    また静的な対象を使用します。これにより、さまざまな
                    <emphasis>ViewRenderer</emphasis> のプロパティから
                    動的にインフレクタを変更できるようになります。
                </para>
            </listitem>

            <listitem><para>
                    <methodname>setInflector($inflector, $reference)</methodname> は、
                    <emphasis>ViewRenderer</emphasis> で使用する独自のインフレクタを設定します。
                    <varname>$reference</varname> が <constant>TRUE</constant> の場合は、
                    対象だけでなくサフィックスやモジュールディレクトリも
                    <emphasis>ViewRenderer</emphasis> のプロパティへの静的な参照とします。
            </para></listitem>
        </itemizedlist>

        <note>
            <title>デフォルトの検索方式</title>

            <para>
                <emphasis>ViewRenderer</emphasis> は、
                パスの正規化を行ってビュースクリプトによる検索を簡単にします。
                デフォルトのルールは次のようなものです。
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>:module</emphasis>:
                        MixedCase および camelCase 形式の単語がダッシュで分割され、
                        すべて小文字になります。たとえば
                        "FooBarBaz" は "foo-bar-baz" となります。
                    </para>

                    <para>
                        内部的には、インフレクタはフィルタ
                        <classname>Zend_Filter_Word_CamelCaseToDash</classname> および
                        <classname>Zend_Filter_StringToLower</classname> を使用します。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>:controller</emphasis>:
                        MixedCase および camelCase 形式の単語がダッシュで分割され、
                        アンダースコアはディレクトリ区切り文字に変換され、
                        すべて小文字になります。たとえば
                        "<classname>FooBar</classname>" は "foo-bar" となり、そして "<classname>FooBar_Admin</classname>"
                        は "<filename>foo-bar/admin</filename>" となります。
                    </para>

                    <para>
                        内部的には、インフレクタはフィルタ
                        <classname>Zend_Filter_Word_CamelCaseToDash</classname>、
                        <classname>Zend_Filter_Word_UnderscoreToSeparator</classname> および
                        <classname>Zend_Filter_StringToLower</classname> を使用します。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>:action</emphasis>:
                        MixedCase および camelCase 形式の単語がダッシュで分割され、
                        英数字以外の文字はダッシュに変換され、
                        すべて小文字になります。たとえば
                        "fooBar" は "foo-bar" となり、"foo-barBaz"
                        は "foo-bar-baz" となります。
                    </para>

                    <para>
                        内部的には、インフレクタはフィルタ
                        <classname>Zend_Filter_Word_CamelCaseToDash</classname>、
                        <classname>Zend_Filter_PregReplace</classname> および
                        <classname>Zend_Filter_StringToLower</classname> を使用します。
                    </para>
                </listitem>
            </itemizedlist>
        </note>

        <para>
            <emphasis>ViewRenderer</emphasis> <acronym>API</acronym> の最後に紹介するのは、
            実際にビュースクリプトのパスを決定するメソッドと
            ビューのレンダリングを行うメソッドです。以下をご覧ください。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>renderScript($script, $name)</methodname>
                    は、指定したパスのスクリプトをレンダリングします。
                    オプションで、パスセグメントの名前を指定することもできます。
                    このメソッドを使用する際には、<emphasis>ViewRenderer</emphasis>
                    はスクリプト名を自動的に決定することはありません。
                    そのかわりに、<varname>$script</varname> で指定された内容を直接
                    ビューオブジェクトの <methodname>render()</methodname> メソッドに渡します。
                </para>

                <note><para>
                    レスポンスオブジェクトにビューがレンダリングされると、
                    自動的に <emphasis>noRender</emphasis> を設定します。
                    これにより、同じビュースクリプトを間違って複数回レンダリングしてしまうことを防ぎます。
                </para></note>

                <note>
                    <para>
                        デフォルトでは、
                        <methodname>Zend_Controller_Action::renderScript()</methodname>
                        は <emphasis>ViewRenderer</emphasis> の
                        <methodname>renderScript()</methodname> メソッドへのプロキシとなります。
                    </para>
                </note>
            </listitem>

            <listitem>
                <para>
                    <methodname>getViewScript($action, $vars)</methodname>
                    は、渡されたアクションや <varname>$vars</varname>
                    で指定した変数の値に基づいてビュースクリプトのパスを作成します。
                    <varname>$vars</varname> 配列のキーは、パスを指定するためのキー
                    ('moduleDir'、'module'、'controller'、'action' および 'suffix')
                    のいずれかとなります。渡された変数の値をもとにしてパスを作成します。
                    なにも渡されなかった場合は、現在のリクエストの内容をもとにしてパスを作成します。
                </para>

                <para>
                    <methodname>getViewScript()</methodname>
                    は、<emphasis>noController</emphasis> フラグの内容によって
                    <emphasis>viewScriptPathSpec</emphasis> あるいは
                    <emphasis>viewScriptPathNoControllerSpec</emphasis> のいずれかを使用します。
                </para>

                <para>
                    モジュール名やコントローラ名、アクション名にあらわれる
                    単語の区切りは、ダッシュ ('-') に置き換えられます。
                    したがって、たとえばコントローラ名が '<command>foo.bar</command>'
                    でアクション名が '<command>baz:bat</command>' だったとすると、
                    デフォルトのパス指定をもとにしたビュースクリプトのパスは
                    '<filename>foo-bar/baz-bat.phtml</filename>' となります。
                </para>

                <note>
                    <para>
                        デフォルトでは、
                        <methodname>Zend_Controller_Action::getViewScript()</methodname>
                        は <emphasis>ViewRenderer</emphasis> の
                        <methodname>getViewScript()</methodname> メソッドへのプロキシとなります。
                    </para>
                </note>
            </listitem>

            <listitem>
                <para>
                    <methodname>render($action, $name, $noController)</methodname>
                    は、まず <varname>$name</varname> あるいは
                    <varname>$noController</varname> が指定されているかどうかを調べます。
                    指定されている場合は、ViewRenderer の対応するフラグ
                    (それぞれ responseSegment と noController) を設定します。
                    次に、<varname>$action</varname> 引数が指定されていれば、
                    それを <methodname>getViewScript()</methodname> に渡します。
                    最後に、取得したビュースクリプトのパスを
                    <methodname>renderScript()</methodname> に渡します。
                </para>

                <note>
                    <para>
                        <methodname>render()</methodname> を使用する際には、その副作用に注意しましょう。
                        レスポンスセグメント名や noController
                        フラグに指定した内容は、そのオブジェクト内で残り続けます。
                        さらに、レンダリングが完了した際に noRender
                        も設定されます。
                    </para>
                </note>

                <note>
                    <para>
                        デフォルトでは、
                        <methodname>Zend_Controller_Action::render()</methodname> は
                        <emphasis>ViewRenderer</emphasis> の <methodname>render()</methodname>
                        メソッドへのプロキシとなります。
                    </para>
                </note>
            </listitem>

            <listitem>
                <para>
                    <methodname>renderBySpec($action, $vars, $name)</methodname>
                    は、パス指定用の変数を渡してビュースクリプトのパスを決定します。
                    <varname>$action</varname> および <varname>$vars</varname> の内容を
                    <methodname>getScriptPath()</methodname> に、そしてその結果得られたスクリプトのパスと
                    <varname>$name</varname> を <methodname>renderScript()</methodname> に渡します。
                </para>
            </listitem>
        </itemizedlist>
    </sect4>

    <sect4 id="zend.controller.actionhelper.viewrenderer.basicusage">
        <title>基本的な使用例</title>

        <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-1">
            <title>基本的な使用法</title>

            <para>
                最も基本的な使用法は、起動ファイル内で <emphasis>ViewRenderer</emphasis>
                を作成してヘルパーブローカに登録し、
                アクションメソッドで変数の値を設定するというものです。
            </para>

            <programlisting language="php"><![CDATA[
// 起動ファイル内で
Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');

...

// 'foo' モジュールの 'bar' コントローラ
class Foo_BarController extends Zend_Controller_Action
{
    // デフォルトで bar/index.phtml をレンダリングするので、特に何もする必要はありません
    public function indexAction()
    {
    }

    // 変数 'foo' の値を 'bar' に設定して bar/populate.phtml をレンダリングします
    // ビューオブジェクトは既に preDispatch() で定義されているので、既に使用可能です
    public function populateAction()
    {
        $this->view->foo = 'bar';
    }

    // 何もレンダリングせずに別のアクションに転送します
    // 転送先のアクションで何らかのレンダリングを行います
    public function bazAction()
    {
        $this->_forward('index');
    }

    // 何もレンダリングせず別の場所にリダイレクトします
    public function batAction()
    {
        $this->_redirect('/index');
    }
}
]]></programlisting>
        </example>

        <note>
            <title>命名規約: コントローラ名やアクション名の単語の区切り</title>
            <para>
                コントローラやアクションの名前が複数の単語からなるものである場合、
                ディスパッチャには、特定のパスや区切り文字を使用して単語を区切った
                <acronym>URL</acronym> を指定しなければなりません。
                <emphasis>ViewRenderer</emphasis> は、コントローラ名の中にあるパス区切り文字を
                実際のパス区切り文字 ('/') に置き換え、単語区切り文字をダッシュ
                ('-') に置き換えてパスを作成します。したがって、
                アクション <filename>/foo.bar/baz.bat</filename> をコールすると
                <filename>FooBarController.php</filename> の
                <methodname>FooBarController::bazBatAction()</methodname> へディスパッチされ、
                <filename>foo-bar/baz-bat.phtml</filename> をレンダリングすることになります。
                また、アクション <filename>/bar_baz/baz-bat</filename> をコールすると
                <filename>Bar/BazController.php</filename> (パス区切り文字に注意) の
                <methodname>Bar_BazController::bazBatAction()</methodname>
                へディスパッチされ、<filename>bar/baz/baz-bat.phtml</filename>
                をレンダリングすることになります。
            </para>

            <para>
                二番目の例では、モジュールはデフォルトモジュールのままであることに注意しましょう。
                しかし、パス区切り文字があるために、
                <filename>Bar/BazController.php</filename> にある
                <classname>Bar_BazController</classname> を受け取ることになります。
                ビューレンダラはコントローラのディレクトリ階層を模倣します。
            </para>
        </note>

        <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-2">
            <title>自動レンダリングの無効化</title>

            <para>
                アクションやコントローラによっては、自動レンダリングを無効にしたいこともあるでしょう。
                たとえば、HTML 以外 (<acronym>XML</acronym> や <acronym>JSON</acronym> など) を出力したい場合や
                単に何も出力したくない場合などです。
                そんな場合には以下のいずれかの方法を使用します。
                つまり、すべての自動レンダリングを無効にする
                (<methodname>setNeverRender()</methodname>) か、あるいは現在のアクションでだけ
                自動レンダリングを無効にする (<methodname>setNoRender()</methodname>) かです。
            </para>

            <programlisting language="php"><![CDATA[
// Bar モジュールの Baz コントローラクラス
class Bar_BazController extends Zend_Controller_Action
{
    public function fooAction()
    {
        // このアクションでは自動レンダリングを行いません
        $this->_helper->viewRenderer->setNoRender();
    }
}

// Bar モジュールの Bat コントローラクラス
class Bar_BatController extends Zend_Controller_Action
{
    public function preDispatch()
    {
        // このコントローラのアクションでは決して自動レンダリングを行いません
        $this->_helper->viewRenderer->setNoRender();
    }
}
]]></programlisting>
        </example>

        <note>
            <para>
                たいていの場合は、自動レンダリングを全体で無効にする
                (<methodname>setNeverRender()</methodname>) のは無意味です。
                なぜなら、<emphasis>ViewRenderer</emphasis> の唯一の存在意義が、
                ビューオブジェクトを自動的に設定することだからです。
            </para>
        </note>

        <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-3">
            <title>別のビュースクリプトの選択</title>

            <para>
                アクション名から自動的に決まるスクリプトではなく、
                それ以外のものをレンダリングしたくなる場合もあるでしょう。
                たとえば、add アクションと edit アクションのふたつを持つコントローラがあったとしましょう。
                どちらのアクションも同じ 'form' ビューを表示しますが、
                そこに設定する値が異なります。
                そんな場合に、それぞれでスクリプト名を変えるのは簡単です。
                <methodname>setScriptAction()</methodname> や <methodname>setRender()</methodname>
                を使用するか、あるいはヘルパーをメソッドとして呼び出します。
                これは <methodname>setRender()</methodname> を起動します。
            </para>

            <programlisting language="php"><![CDATA[
// Foo モジュールの Bar コントローラクラス
class Foo_BarController extends Zend_Controller_Action
{
    public function addAction()
    {
        // 'bar/add.phtml' ではなく 'bar/form.phtml' をレンダリングします
        $this->_helper->viewRenderer('form');
    }

    public function editAction()
    {
        // 'bar/edit.phtml' ではなく 'bar/form.phtml' をレンダリングします
        $this->_helper->viewRenderer->setScriptAction('form');
    }

    public function processAction()
    {
        // 何かのチェックをした後で...
        if (!$valid) {
            // 'bar/process.phtml' ではなく 'bar/form.phtml' をレンダリングします
            $this->_helper->viewRenderer->setRender('form');
            return;
        }

        // その他の処理を続けます...
    }

}
]]></programlisting>
        </example>

        <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-4">
            <title>登録されているビューの変更</title>

            <para>
                ビューオブジェクトの設定を変更したくなったとしましょう。
                たとえば、ヘルパーのパスやエンコーディングを変更したくなったらどうしますか?
                そんな場合は、コントローラに設定されているビューオブジェクトを変更するか、
                あるいは <emphasis>ViewRenderer</emphasis> の外部からビューオブジェクトを取得します。
                どちらも同じオブジェクトへの参照を取得することになります。
            </para>

            <programlisting language="php"><![CDATA[
// Foo モジュールの Bar コントローラクラス
class Foo_BarController extends Zend_Controller_Action
{
    public function preDispatch()
    {
        // ビューのエンコーディングを変更します
        $this->view->setEncoding('UTF-8');
    }

    public function bazAction()
    {
        // ビューオブジェクトを取得し、エスケープ用のコールバックを 'htmlspecialchars' に設定します
        $view = $this->_helper->viewRenderer->view;
        $view->setEscape('htmlspecialchars');
    }
}
]]></programlisting>
        </example>
    </sect4>

    <sect4 id="zend.controller.actionhelper.viewrenderer.advancedusage">
        <title>高度な使用例</title>

        <example id="zend.controller.actionhelper.viewrenderer.advancedusage.example-1">
            <title>パスの指定方法の変更</title>

            <para>
                場合によっては、デフォルトのパス指定があなたのサイトに
                うまく当てはまらないこともあるでしょう。
                たとえば、すべてのテンプレートを単一のディレクトリ配下にまとめ、
                デザイナにはそのディレクトリに対するアクセス権だけを与えたいといった場合です
                (<ulink url="http://smarty.php.net/">Smarty</ulink>
                を使用する場合などにありがちです)。
                そんな場合は、ビューの基底パスをハードコーディングし、
                それをアクションのビュースクリプトのパスとして使用することになります。
            </para>

            <para>
                この例では、ビューの基底パスを '<filename>/opt/vendor/templates</filename>'
                とし、ビュースクリプトのパスは '<filename>:moduleDir/:controller/:action.:suffix</filename>'
                となるようにします。<emphasis>noController</emphasis>
                フラグが設定されている場合は、サブディレクトリ ('<filename>:action.:suffix</filename>')
                からではなくトップディレクトリからのパスとして探すことになります。
                最後に、ビュースクリプトのファイルの拡張子として
                'tpl' を設定します。
            </para>

            <programlisting language="php"><![CDATA[
/**
 * 起動ファイル
 */

// 別のビュー実装を使用します
$view = new ZF_Smarty();

$viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer($view);
$viewRenderer->setViewBasePathSpec('/opt/vendor/templates')
             ->setViewScriptPathSpec(':module/:controller/:action.:suffix')
             ->setViewScriptPathNoControllerSpec(':action.:suffix')
             ->setViewSuffix('tpl');
Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
]]></programlisting>
        </example>

        <example id="zend.controller.actionhelper.viewrenderer.advancedusage.example-2">
            <title>単一のアクションから複数のビュースクリプトをレンダリングする例</title>

            <para>
                時には、複数のビュースクリプトをひとつのアクションで処理したいこともあるでしょう。
                これは、非常に直感的な方法で実現できます。単に
                <methodname>render()</methodname> を必要なだけコールすればいいのです。
            </para>

            <programlisting language="php"><![CDATA[
class SearchController extends Zend_Controller_Action
{
    public function resultsAction()
    {
        // $this->model に現在のモデルが設定されているものとします
        $this->view->results =
            $this->model->find($this->_getParam('query', '');

        // render() は、デフォルトでは ViewRenderer へのプロキシとなります。
        // まず form を、そして results をレンダリングします
        $this->render('form');
        $this->render('results');
    }

    public function formAction()
    {
        // 何もしなくても、ViewRenderer が自動的にビュースクリプトをレンダリングします
    }
}
]]></programlisting>
        </example>
    </sect4>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->