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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20765 -->
   4 <sect1 id="zend.controller.actionhelpers" xmlns:xi="http://www.w3.org/2001/XInclude">
   5     <title>アクションヘルパー</title>
   6
   7     <sect2 id="zend.controller.actionhelper.introduction">
   8         <title>導入</title>
   9
  10         <para>
  11             アクションヘルパーを使用すると、<classname>Zend_Controller_Action</classname>
  12             を継承した任意のアクションコントローラに対して
  13             実行時やその他必要に応じて機能を追加できます。
  14             アクションヘルパーの狙いは、
  15             アクションコントローラに共通機能を追加するために
  16             いちいち抽象クラスを継承する手間を省くことにあります。
  17         </para>
  18
  19         <para>
  20             アクションヘルパーにはさまざまな使用法があります。
  21             たとえば、<link
  22                 linkend="zend.view.helpers">Zend_View_Helper</link>
  23             や <link
  24                 linkend="zend.controller.plugins">Zend_Controller_Plugin</link>
  25             と同じように、処理の仲買をするために用いることもできます。
  26             アクションヘルパーは (<classname>Zend_View_Helper</classname> と同様に)、
  27             必要になった時点で読み込むこともできますし、
  28             リクエスト時 (起動時) やアクションコントローラの作成時 (<methodname>init()</methodname>)
  29             で読み込むこともできます。詳細は、以下の使用例を参照ください。
  30         </para>
  31     </sect2>
  32
  33     <sect2 id="zend.controller.actionhelper.initialization">
  34         <title>ヘルパーの初期化</title>
  35
  36         <para>
  37             ヘルパーを初期化するにはいくつかの方法があります。
  38             必要に応じて、またそのヘルパーの機能に応じて使い分けましょう。
  39         </para>
  40
  41         <para>
  42             ヘルパーブローカは、<classname>Zend_Controller_Action</classname>
  43             の <varname>$_helper</varname> に格納されます。
  44             このブローカを使用して、ヘルパーを取得したりコールしたりします。
  45             以下のような方法があります。
  46         </para>
  47
  48         <itemizedlist>
  49             <listitem>
  50                 <para>
  51                     明示的に <methodname>getHelper()</methodname> を使用します。
  52                     ヘルパーの名前を指定すると、
  53                     そのヘルパーオブジェクトが返されます。
  54                 </para>
  55
  56                 <programlisting language="php"><![CDATA[
  57 $flashMessenger = $this->_helper->getHelper('FlashMessenger');
  58 $flashMessenger->addMessage('先ほどのリクエストで、あることをしました');
  59 ]]></programlisting>
  60             </listitem>
  61
  62             <listitem>
  63                 <para>
  64                     ヘルパーブローカの <methodname>__get()</methodname> 機能を使用すると、
  65                     まるでブローカのプロパティであるかのようにヘルパーを操作できます。
  66                 </para>
  67
  68                 <programlisting language="php"><![CDATA[
  69 $flashMessenger = $this->_helper->FlashMessenger;
  70 $flashMessenger->addMessage('先ほどのリクエストで、あることをしました');
  71 ]]></programlisting>
  72             </listitem>
  73
  74             <listitem>
  75                 <para>
  76                     たいていのアクションヘルパーは
  77                     <methodname>direct()</methodname> メソッドを実装しており、
  78                     これはそのヘルパーのデフォルトメソッドをコールします。
  79                     <methodname>FlashMessenger</methodname> の例では、
  80                     <methodname>addMessage()</methodname> をコールします。
  81                 </para>
  82
  83                 <programlisting language="php"><![CDATA[
  84 $this->_helper->FlashMessenger('先ほどのリクエストで、あることをしました');
  85 ]]></programlisting>
  86             </listitem>
  87         </itemizedlist>
  88
  89         <note>
  90             <para>これらの例は、すべて同じことを行っています。</para>
  91         </note>
  92
  93         <para>
  94             ヘルパーのインスタンスを明示的に作成したいと考えるかもしれません。
  95             たとえばアクションコントローラ以外からヘルパーを使用したいだとか、
  96             すべてのアクションのヘルパーブローカに同じヘルパーを渡したいだとかいった場合です。
  97             インスタンスを作成する方法は、通常の <acronym>PHP</acronym> のクラスと同じです。
  98         </para>
  99     </sect2>
 100
 101     <sect2 id="zend.controller.actionhelper.broker">
 102         <title>ヘルパーブローカ</title>
 103
 104         <para>
 105             <classname>Zend_Controller_Action_HelperBroker</classname>
 106             がヘルパーオブジェクトやそのパスの登録に関する詳細を処理します。
 107             また、必要に応じてそこからヘルパーを取得できます。
 108         </para>
 109
 110         <para>
 111             ヘルパーをブローカに登録するには
 112             <methodname>addHelper()</methodname> を使用します。
 113         </para>
 114
 115         <programlisting language="php"><![CDATA[
 116 Zend_Controller_Action_HelperBroker::addHelper($helper);
 117 ]]></programlisting>
 118
 119         <para>
 120             もちろん、ヘルパーのインスタンスを作成してそれをブローカに渡すという作業は
 121             時間とリソースを消費します。これらの作業の手間をほんの少し省くためのメソッドとして、
 122             <methodname>addPrefix()</methodname> と
 123             <methodname>addPath()</methodname> が用意されています。
 124         </para>
 125
 126         <itemizedlist>
 127             <listitem>
 128                 <para>
 129                     <methodname>addPrefix()</methodname> はクラスのプレフィックスを受け取り、
 130                     それをもとにヘルパークラスのパスを決定します。
 131                     プレフィックスが、Zend Framework のクラス命名規約に沿っているものとみなして、
 132                     パスを決定します。
 133                 </para>
 134
 135                 <programlisting language="php"><![CDATA[
 136 // My/Action/Helpers/ にある、名前が My_Action_Helpers で始まるヘルパーを追加します
 137 Zend_Controller_Action_HelperBroker::addPrefix('My_Action_Helpers');
 138 ]]></programlisting>
 139             </listitem>
 140
 141             <listitem>
 142                 <para>
 143                     <methodname>addPath()</methodname> は、最初の引数にディレクトリ、
 144                     そして二番目の引数にクラスのプレフィックス
 145                     (デフォルトは '<classname>Zend_Controller_Action_Helper</classname>') を指定します。
 146                     これは、指定したディレクトリにある指定したプレフィックスのクラスを追加します。
 147                 </para>
 148
 149                 <programlisting language="php"><![CDATA[
 150 // Plugins/Helpers/ にある、名前が Helper で始まるヘルパーを追加します
 151 Zend_Controller_Action_HelperBroker::addPath('./Plugins/Helpers',
 152                                              'Helper');
 153 ]]></programlisting>
 154             </listitem>
 155         </itemizedlist>
 156
 157         <para>
 158             これらは静的メソッドなので、コントローラチェイン内の任意の場所で使用できます。
 159             これにより、必要に応じて動的にヘルパーを追加できることになります。
 160         </para>
 161
 162         <para>
 163             内部的には、ヘルパーブローカは <link
 164                 linkend="zend.loader.pluginloader">PluginLoader
 165                 のインスタンス</link> を用いてパスを保持します。静的メソッド
 166             <methodname>getPluginLoader()</methodname> で PluginLoader
 167             を取得することもできますし、また独自の PluginLoader
 168             インスタンスを <methodname>setPluginLoader()</methodname> で設定することもできます。
 169         </para>
 170
 171         <para>
 172             ヘルパークラスがヘルパーブローカ内に存在するかどうかを調べるには
 173             <methodname>hasHelper($name)</methodname> を使用します。<varname>$name</varname>
 174             には、ヘルパーのショートネーム (プレフィックスを除いたもの)
 175             を指定します。
 176         </para>
 177
 178         <programlisting language="php"><![CDATA[
 179 // 'redirector' ヘルパーがブローカに登録されているかどうかを調べます
 180 if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
 181     echo 'Redirector helper registered';
 182 }
 183 ]]></programlisting>
 184
 185         <para>
 186             ヘルパーブローかからヘルパーを取得する静的メソッドには、さらに
 187             <methodname>getExistingHelper()</methodname> と
 188             <methodname>getStaticHelper()</methodname> のふたつがあります。
 189             <methodname>getExistingHelper()</methodname> は、すでに起動されているか、
 190             あるいは明示的にヘルパーブローカに登録されているヘルパーのみを取得します。
 191             存在しない場合は例外をスローします。
 192             <methodname>getStaticHelper()</methodname> は
 193             <methodname>getExistingHelper()</methodname> と同じですが、
 194             ヘルパースタックに登録されていないヘルパーについてはそのインスタンスを作成しようとします。
 195             自分で設定をしたいヘルパーを取得するには
 196             <methodname>getStaticHelper()</methodname> がおすすめです。
 197         </para>
 198
 199         <para>
 200             どちらのメソッドも、引数はひとつだけです。
 201             この引数 <varname>$name</varname>
 202             には、ヘルパーのショートネーム (プレフィックスを除いたもの)
 203             を指定します。
 204         </para>
 205
 206         <programlisting language="php"><![CDATA[
 207 // 'redirector' ヘルパーがブローカに登録されているかどうかを調べ、取得します
 208 if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
 209     $redirector =
 210         Zend_Controller_Action_HelperBroker::getExistingHelper('redirector');
 211 }
 212
 213 // あるいは、登録されているかどうかを気にせずに単純に取得します
 214 $redirector =
 215     Zend_Controller_Action_HelperBroker::getStaticHelper('redirector');
 216 }
 217 ]]></programlisting>
 218
 219         <para>
 220             最後に、登録済みのヘルパーをブローカから削除するには
 221             <methodname>removeHelper($name)</methodname> を使用します。<varname>$name</varname>
 222             には、ヘルパーのショートネーム (プレフィックスを除いたもの)
 223             を指定します。
 224         </para>
 225
 226         <programlisting language="php"><![CDATA[
 227 // 'redirector' ヘルパーがブローカに登録されている場合にはそれを削除します
 228 if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
 229     Zend_Controller_Action_HelperBroker::removeHelper('redirector')
 230 }
 231 ]]></programlisting>
 232     </sect2>
 233
 234     <sect2 id="zend.controller.actionhelper.stockhelpers">
 235         <title>組み込みのアクションヘルパー</title>
 236
 237         <para>
 238             Zend Framework には、いくつかのアクションヘルパーがデフォルトで組み込まれています。
 239             <acronym>AJAX</acronym> のオートコンプリート機能用のレスポンスを作成する <emphasis>AutoComplete</emphasis>、
 240             アクションに応じてレスポンスの形式を変更する <emphasis>ContextSwitch</emphasis> と
 241             <emphasis>AjaxContext</emphasis>、セッション単位のフラッシュメッセージを扱う
 242             <emphasis>FlashMessenger</emphasis>、<acronym>JSON</acronym> 形式へのエンコードとレスポンスの送信を行う
 243             <emphasis>Json</emphasis>、
 244             アプリケーション内から内部あるいは外部へのリダイレクトを実装できるようにする
 245             <emphasis>Redirector</emphasis>、そして
 246             コントローラ内でのビューオブジェクトの設定とビューのレンダリングを自動化する
 247             <emphasis>ViewRenderer</emphasis> です。
 248         </para>
 249
 250         <xi:include href="Zend_Controller-ActionHelpers-ActionStack.xml" />
 251         <xi:include href="Zend_Controller-ActionHelpers-AutoComplete.xml" />
 252         <xi:include href="Zend_Controller-ActionHelpers-ContextSwitch.xml" />
 253         <xi:include href="Zend_Controller-ActionHelpers-FlashMessenger.xml" />
 254         <xi:include href="Zend_Controller-ActionHelpers-Json.xml" />
 255         <xi:include href="Zend_Controller-ActionHelpers-Redirector.xml" />
 256         <xi:include href="Zend_Controller-ActionHelpers-ViewRenderer.xml" />
 257     </sect2>
 258
 259     <sect2 id="zend.controller.actionhelper.writingyourown">
 260         <title>独自のヘルパーの作成</title>
 261
 262         <para>
 263             アクションヘルパーは、抽象クラス
 264             <classname>Zend_Controller_Action_Helper_Abstract</classname>
 265             を継承して作成します。
 266             ここには、基本的なインターフェイスやヘルパーブローカが使用する必須機能などが含まれています。
 267             具体的には、次のようなメソッドです。
 268         </para>
 269
 270         <itemizedlist>
 271             <listitem>
 272                 <para>
 273                     <methodname>setActionController()</methodname>
 274                     を使用して、現在のアクションコントローラを設定します。
 275                 </para>
 276             </listitem>
 277
 278             <listitem>
 279                 <para>
 280                     <methodname>init()</methodname>
 281                     はヘルパーブローカによって起動時に実行され、
 282                     ヘルパーを初期化します。これは、
 283                     アクションチェイン内の複数のコントローラで同一のヘルパーを使用している場合に
 284                     状態をリセットする際などに便利です。
 285                 </para>
 286             </listitem>
 287
 288             <listitem>
 289                 <para>
 290                     <methodname>preDispatch()</methodname>
 291                     はディスパッチアクションの前に実行されます。
 292                 </para>
 293             </listitem>
 294
 295             <listitem>
 296                 <para>
 297                     <methodname>postDispatch()</methodname>
 298                     はディスパッチアクションが終了した後で実行されます。
 299                     <methodname>preDispatch()</methodname> プラグインがアクションの処理をスキップした場合も、
 300                     これは実行されます。後始末などをここで行います。
 301                 </para>
 302             </listitem>
 303
 304             <listitem>
 305                 <para>
 306                     <methodname>getRequest()</methodname>
 307                     は現在のリクエストオブジェクトを取得します。
 308                 </para>
 309             </listitem>
 310
 311             <listitem>
 312                 <para>
 313                     <methodname>getResponse()</methodname>
 314                     は現在のレスポンスオブジェクトを取得します。
 315                 </para>
 316             </listitem>
 317
 318             <listitem>
 319                 <para>
 320                     <methodname>getName()</methodname>
 321                     はヘルパーの名前を取得します。
 322                     クラス名にアンダースコアが含まれる場合は最後のアンダースコア以降の文字、
 323                     そうでない場合はクラス名全体を返します。たとえば、クラス名が
 324                     <classname>Zend_Controller_Action_Helper_Redirector</classname>
 325                     の場合は <emphasis>Redirector</emphasis> を、クラス名が
 326                     <classname>FooMessage</classname> の場合はそのままの名前を返します。
 327                 </para>
 328             </listitem>
 329         </itemizedlist>
 330
 331         <para>
 332             オプションで、ヘルパークラスに <methodname>direct()</methodname>
 333             メソッドを実装することもできます。これを定義しておくと、
 334             ヘルパーブローカのメソッドであるかのようにそのヘルパーを扱えるようになります。
 335             これにより、一度だけ使用するようなヘルパーが扱いやすくなります。
 336             たとえば、<link
 337                 linkend="zend.controller.actionhelpers.redirector">redirector</link>
 338             の <methodname>direct()</methodname> は <methodname>goto()</methodname>
 339             のエイリアスとなっているので、このようにして使用できます。
 340         </para>
 341
 342         <programlisting language="php"><![CDATA[
 343 // /blog/view/item/id/42 にリダイレクトします
 344 $this->_helper->redirector('item', 'view', 'blog', array('id' => 42));
 345 ]]></programlisting>
 346
 347         <para>
 348             内部的には、まずヘルパーブローカの <methodname>__call()</methodname>
 349             メソッドが <emphasis>redirector</emphasis> という名前のヘルパーを探し、
 350             それからそのヘルパーで <methodname>direct()</methodname>
 351             メソッドが定義されているかどうかを調べ、
 352             渡された引数でそのメソッドをコールしています。
 353         </para>
 354
 355         <para>
 356             独自のヘルパークラスを作成した場合は、
 357             上で説明したようにしてそれを利用できるようにしておきましょう。
 358         </para>
 359     </sect2>
 360 </sect1>
 361 <!--
 362 vim:se ts=4 sw=4 et:
 363 -->