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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.controller.actionhelpers" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>アクションヘルパー</title>

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

        <para>
            アクションヘルパーを使用すると、<classname>Zend_Controller_Action</classname>
            を継承した任意のアクションコントローラに対して
            実行時やその他必要に応じて機能を追加できます。
            アクションヘルパーの狙いは、
            アクションコントローラに共通機能を追加するために
            いちいち抽象クラスを継承する手間を省くことにあります。
        </para>

        <para>
            アクションヘルパーにはさまざまな使用法があります。
            たとえば、<link
                linkend="zend.view.helpers">Zend_View_Helper</link>
            や <link
                linkend="zend.controller.plugins">Zend_Controller_Plugin</link>
            と同じように、処理の仲買をするために用いることもできます。
            アクションヘルパーは (<classname>Zend_View_Helper</classname> と同様に)、
            必要になった時点で読み込むこともできますし、
            リクエスト時 (起動時) やアクションコントローラの作成時 (<methodname>init()</methodname>)
            で読み込むこともできます。詳細は、以下の使用例を参照ください。
        </para>
    </sect2>

    <sect2 id="zend.controller.actionhelper.initialization">
        <title>ヘルパーの初期化</title>

        <para>
            ヘルパーを初期化するにはいくつかの方法があります。
            必要に応じて、またそのヘルパーの機能に応じて使い分けましょう。
        </para>

        <para>
            ヘルパーブローカは、<classname>Zend_Controller_Action</classname>
            の <varname>$_helper</varname> に格納されます。
            このブローカを使用して、ヘルパーを取得したりコールしたりします。
            以下のような方法があります。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    明示的に <methodname>getHelper()</methodname> を使用します。
                    ヘルパーの名前を指定すると、
                    そのヘルパーオブジェクトが返されます。
                </para>

                <programlisting language="php"><![CDATA[
$flashMessenger = $this->_helper->getHelper('FlashMessenger');
$flashMessenger->addMessage('先ほどのリクエストで、あることをしました');
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    ヘルパーブローカの <methodname>__get()</methodname> 機能を使用すると、
                    まるでブローカのプロパティであるかのようにヘルパーを操作できます。
                </para>

                <programlisting language="php"><![CDATA[
$flashMessenger = $this->_helper->FlashMessenger;
$flashMessenger->addMessage('先ほどのリクエストで、あることをしました');
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    たいていのアクションヘルパーは
                    <methodname>direct()</methodname> メソッドを実装しており、
                    これはそのヘルパーのデフォルトメソッドをコールします。
                    <methodname>FlashMessenger</methodname> の例では、
                    <methodname>addMessage()</methodname> をコールします。
                </para>

                <programlisting language="php"><![CDATA[
$this->_helper->FlashMessenger('先ほどのリクエストで、あることをしました');
]]></programlisting>
            </listitem>
        </itemizedlist>

        <note>
            <para>これらの例は、すべて同じことを行っています。</para>
        </note>

        <para>
            ヘルパーのインスタンスを明示的に作成したいと考えるかもしれません。
            たとえばアクションコントローラ以外からヘルパーを使用したいだとか、
            すべてのアクションのヘルパーブローカに同じヘルパーを渡したいだとかいった場合です。
            インスタンスを作成する方法は、通常の <acronym>PHP</acronym> のクラスと同じです。
        </para>
    </sect2>

    <sect2 id="zend.controller.actionhelper.broker">
        <title>ヘルパーブローカ</title>

        <para>
            <classname>Zend_Controller_Action_HelperBroker</classname>
            がヘルパーオブジェクトやそのパスの登録に関する詳細を処理します。
            また、必要に応じてそこからヘルパーを取得できます。
        </para>

        <para>
            ヘルパーをブローカに登録するには
            <methodname>addHelper()</methodname> を使用します。
        </para>

        <programlisting language="php"><![CDATA[
Zend_Controller_Action_HelperBroker::addHelper($helper);
]]></programlisting>

        <para>
            もちろん、ヘルパーのインスタンスを作成してそれをブローカに渡すという作業は
            時間とリソースを消費します。これらの作業の手間をほんの少し省くためのメソッドとして、
            <methodname>addPrefix()</methodname> と
            <methodname>addPath()</methodname> が用意されています。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>addPrefix()</methodname> はクラスのプレフィックスを受け取り、
                    それをもとにヘルパークラスのパスを決定します。
                    プレフィックスが、Zend Framework のクラス命名規約に沿っているものとみなして、
                    パスを決定します。
                </para>

                <programlisting language="php"><![CDATA[
// My/Action/Helpers/ にある、名前が My_Action_Helpers で始まるヘルパーを追加します
Zend_Controller_Action_HelperBroker::addPrefix('My_Action_Helpers');
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <methodname>addPath()</methodname> は、最初の引数にディレクトリ、
                    そして二番目の引数にクラスのプレフィックス
                    (デフォルトは '<classname>Zend_Controller_Action_Helper</classname>') を指定します。
                    これは、指定したディレクトリにある指定したプレフィックスのクラスを追加します。
                </para>

                <programlisting language="php"><![CDATA[
// Plugins/Helpers/ にある、名前が Helper で始まるヘルパーを追加します
Zend_Controller_Action_HelperBroker::addPath('./Plugins/Helpers',
                                             'Helper');
]]></programlisting>
            </listitem>
        </itemizedlist>

        <para>
            これらは静的メソッドなので、コントローラチェイン内の任意の場所で使用できます。
            これにより、必要に応じて動的にヘルパーを追加できることになります。
        </para>

        <para>
            内部的には、ヘルパーブローカは <link
                linkend="zend.loader.pluginloader">PluginLoader
                のインスタンス</link> を用いてパスを保持します。静的メソッド
            <methodname>getPluginLoader()</methodname> で PluginLoader
            を取得することもできますし、また独自の PluginLoader
            インスタンスを <methodname>setPluginLoader()</methodname> で設定することもできます。
        </para>

        <para>
            ヘルパークラスがヘルパーブローカ内に存在するかどうかを調べるには
            <methodname>hasHelper($name)</methodname> を使用します。<varname>$name</varname>
            には、ヘルパーのショートネーム (プレフィックスを除いたもの)
            を指定します。
        </para>

        <programlisting language="php"><![CDATA[
// 'redirector' ヘルパーがブローカに登録されているかどうかを調べます
if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
    echo 'Redirector helper registered';
}
]]></programlisting>

        <para>
            ヘルパーブローかからヘルパーを取得する静的メソッドには、さらに
            <methodname>getExistingHelper()</methodname> と
            <methodname>getStaticHelper()</methodname> のふたつがあります。
            <methodname>getExistingHelper()</methodname> は、すでに起動されているか、
            あるいは明示的にヘルパーブローカに登録されているヘルパーのみを取得します。
            存在しない場合は例外をスローします。
            <methodname>getStaticHelper()</methodname> は
            <methodname>getExistingHelper()</methodname> と同じですが、
            ヘルパースタックに登録されていないヘルパーについてはそのインスタンスを作成しようとします。
            自分で設定をしたいヘルパーを取得するには
            <methodname>getStaticHelper()</methodname> がおすすめです。
        </para>

        <para>
            どちらのメソッドも、引数はひとつだけです。
            この引数 <varname>$name</varname>
            には、ヘルパーのショートネーム (プレフィックスを除いたもの)
            を指定します。
        </para>

        <programlisting language="php"><![CDATA[
// 'redirector' ヘルパーがブローカに登録されているかどうかを調べ、取得します
if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
    $redirector =
        Zend_Controller_Action_HelperBroker::getExistingHelper('redirector');
}

// あるいは、登録されているかどうかを気にせずに単純に取得します
$redirector =
    Zend_Controller_Action_HelperBroker::getStaticHelper('redirector');
}
]]></programlisting>

        <para>
            最後に、登録済みのヘルパーをブローカから削除するには
            <methodname>removeHelper($name)</methodname> を使用します。<varname>$name</varname>
            には、ヘルパーのショートネーム (プレフィックスを除いたもの)
            を指定します。
        </para>

        <programlisting language="php"><![CDATA[
// 'redirector' ヘルパーがブローカに登録されている場合にはそれを削除します
if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
    Zend_Controller_Action_HelperBroker::removeHelper('redirector')
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.controller.actionhelper.stockhelpers">
        <title>組み込みのアクションヘルパー</title>

        <para>
            Zend Framework には、いくつかのアクションヘルパーがデフォルトで組み込まれています。
            <acronym>AJAX</acronym> のオートコンプリート機能用のレスポンスを作成する <emphasis>AutoComplete</emphasis>、
            アクションに応じてレスポンスの形式を変更する <emphasis>ContextSwitch</emphasis> と
            <emphasis>AjaxContext</emphasis>、セッション単位のフラッシュメッセージを扱う
            <emphasis>FlashMessenger</emphasis>、<acronym>JSON</acronym> 形式へのエンコードとレスポンスの送信を行う
            <emphasis>Json</emphasis>、
            アプリケーション内から内部あるいは外部へのリダイレクトを実装できるようにする
            <emphasis>Redirector</emphasis>、そして
            コントローラ内でのビューオブジェクトの設定とビューのレンダリングを自動化する
            <emphasis>ViewRenderer</emphasis> です。
        </para>

        <xi:include href="Zend_Controller-ActionHelpers-ActionStack.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-AutoComplete.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-ContextSwitch.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-FlashMessenger.xml">
            <xi:fallback><xi:include href="../../en/module_specs/Zend_Controller-ActionHelpers-FlashMessenger.xml" /></xi:fallback>
        </xi:include>
        <xi:include href="Zend_Controller-ActionHelpers-Json.xml">
            <xi:fallback><xi:include href="../../en/module_specs/Zend_Controller-ActionHelpers-Json.xml" /></xi:fallback>
        </xi:include>
        <xi:include href="Zend_Controller-ActionHelpers-Redirector.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-ViewRenderer.xml" />
    </sect2>

    <sect2 id="zend.controller.actionhelper.writingyourown">
        <title>独自のヘルパーの作成</title>

        <para>
            アクションヘルパーは、抽象クラス
            <classname>Zend_Controller_Action_Helper_Abstract</classname>
            を継承して作成します。
            ここには、基本的なインターフェイスやヘルパーブローカが使用する必須機能などが含まれています。
            具体的には、次のようなメソッドです。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setActionController()</methodname>
                    を使用して、現在のアクションコントローラを設定します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>init()</methodname>
                    はヘルパーブローカによって起動時に実行され、
                    ヘルパーを初期化します。これは、
                    アクションチェイン内の複数のコントローラで同一のヘルパーを使用している場合に
                    状態をリセットする際などに便利です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>preDispatch()</methodname>
                    はディスパッチアクションの前に実行されます。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>postDispatch()</methodname>
                    はディスパッチアクションが終了した後で実行されます。
                    <methodname>preDispatch()</methodname> プラグインがアクションの処理をスキップした場合も、
                    これは実行されます。後始末などをここで行います。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getRequest()</methodname>
                    は現在のリクエストオブジェクトを取得します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getResponse()</methodname>
                    は現在のレスポンスオブジェクトを取得します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getName()</methodname>
                    はヘルパーの名前を取得します。
                    クラス名にアンダースコアが含まれる場合は最後のアンダースコア以降の文字、
                    そうでない場合はクラス名全体を返します。たとえば、クラス名が
                    <classname>Zend_Controller_Action_Helper_Redirector</classname>
                    の場合は <emphasis>Redirector</emphasis> を、クラス名が
                    <classname>FooMessage</classname> の場合はそのままの名前を返します。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            オプションで、ヘルパークラスに <methodname>direct()</methodname>
            メソッドを実装することもできます。これを定義しておくと、
            ヘルパーブローカのメソッドであるかのようにそのヘルパーを扱えるようになります。
            これにより、一度だけ使用するようなヘルパーが扱いやすくなります。
            たとえば、<link
                linkend="zend.controller.actionhelpers.redirector">redirector</link>
            の <methodname>direct()</methodname> は <methodname>goto()</methodname>
            のエイリアスとなっているので、このようにして使用できます。
        </para>

        <programlisting language="php"><![CDATA[
// /blog/view/item/id/42 にリダイレクトします
$this->_helper->redirector('item', 'view', 'blog', array('id' => 42));
]]></programlisting>

        <para>
            内部的には、まずヘルパーブローカの <methodname>__call()</methodname>
            メソッドが <emphasis>redirector</emphasis> という名前のヘルパーを探し、
            それからそのヘルパーで <methodname>direct()</methodname>
            メソッドが定義されているかどうかを調べ、
            渡された引数でそのメソッドをコールしています。
        </para>

        <para>
            独自のヘルパークラスを作成した場合は、
            上で説明したようにしてそれを利用できるようにしておきましょう。
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->