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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20765 -->
   4 <sect3 id="zend.controller.actionhelpers.contextswitch">
   5     <title>ContextSwitch および AjaxContext</title>
   6
   7     <para>
   8         <emphasis>ContextSwitch</emphasis> アクションヘルパーは、
   9         リクエストに対してさまざまなレスポンスを返す機能を実現するためのものです。
  10         <emphasis>AjaxContext</emphasis> ヘルパーは
  11         <emphasis>ContextSwitch</emphasis> をより特化したもので、
  12         レスポンスを XmlHttpRequests で返す機能を提供します。
  13     </para>
  14
  15     <para>
  16         いずれかを有効にするには、コントローラに対して
  17         「どのアクションがどのコンテキストに対応するのか」
  18         を教えてやる必要があります。
  19         やってきたリクエストがそのアクションで有効なコンテキストである場合、
  20         ヘルパーが行う処理は次のようになります。
  21     </para>
  22
  23     <itemizedlist>
  24         <listitem><para>
  25                 レイアウト機能が有効な場合に、それを無効にする。
  26         </para></listitem>
  27
  28         <listitem><para>
  29                 別のビューサフィックスを設定し、
  30                 コンテキストに応じて別のビュースクリプトを効率よく扱えるようにする。
  31         </para></listitem>
  32
  33         <listitem><para>
  34                 コンテキストに応じて適切なレスポンスヘッダを送信する。
  35         </para></listitem>
  36
  37         <listitem><para>
  38                 オプションで、指定したコールバックを実行して
  39                 コンテキストの設定や後処理を行う。
  40         </para></listitem>
  41     </itemizedlist>
  42
  43     <para>
  44         たとえば、次のようなコントローラを考えてみましょう。
  45     </para>
  46
  47     <programlisting language="php"><![CDATA[
  48 class NewsController extends Zend_Controller_Action
  49 {
  50     /**
  51      * トップページは listAction() に転送します
  52      */
  53     public function indexAction()
  54     {
  55         $this->_forward('list');
  56     }
  57
  58     /**
  59      * ニュースの一覧
  60      */
  61     public function listAction()
  62     {
  63     }
  64
  65     /**
  66      * ニュースの閲覧
  67      */
  68     public function viewAction()
  69     {
  70     }
  71 }
  72 ]]></programlisting>
  73
  74     <para>
  75         ここで、<methodname>listAction()</methodname>
  76         の結果を <acronym>XML</acronym> 形式でも返せるようにしたくなったとしましょう。
  77         わざわざ別のアクションを作らなくても、
  78         <acronym>XML</acronym> でレスポンスを返すように指示できます。
  79     </para>
  80
  81     <programlisting language="php"><![CDATA[
  82 class NewsController extends Zend_Controller_Action
  83 {
  84     public function init()
  85     {
  86         $contextSwitch = $this->_helper->getHelper('contextSwitch');
  87         $contextSwitch->addActionContext('list', 'xml')
  88                       ->initContext();
  89     }
  90
  91     // ...
  92 }
  93 ]]></programlisting>
  94
  95     <para>
  96         これが何を行っているかというと、
  97     </para>
  98
  99     <itemizedlist>
 100         <listitem><para>
 101                 レスポンスヘッダ 'Content-Type' を '<filename>text/xml</filename>' にします。
 102         </para></listitem>
 103
 104         <listitem><para>
 105                 ビューのサフィックスを '<filename>xml.phtml</filename>' (あるいは別のサフィックスをを使っているなら
 106                 'xml.[your suffix]') に変更します。
 107         </para></listitem>
 108     </itemizedlist>
 109
 110     <para>
 111         さて、次は新しいビュースクリプト '<filename>news/list.xml.phtml</filename>'
 112         を作成しましょう。これが <acronym>XML</acronym> の作成とレンダリングを行います。
 113     </para>
 114
 115     <para>
 116         あるリクエストがコンテキストスイッチを起動するかどうかを判断するために、
 117         このヘルパーはリクエストオブジェクト内のトークンを調べます。
 118         デフォルトでは 'format' というパラメータを調べることになっていますが、
 119         これは変更することもできます。つまり、
 120         ほとんどの場合は、リクエストに 'format' パラメータを追加するだけで
 121         コンテキストスイッチを行えるということです。
 122     </para>
 123
 124     <itemizedlist>
 125         <listitem><para>
 126                 <acronym>URL</acronym> のパラメータで指定する場合: <filename>/news/list/format/xml</filename>
 127                 (デフォルトのルーティング方式では、アクションに続けて任意の
 128                 キー/値 のペアを指定できたことを思い出しましょう)
 129         </para></listitem>
 130
 131         <listitem><para>
 132                 <constant>GET</constant> パラメータで指定する場合: <command>/news/list?format=xml</command>
 133         </para></listitem>
 134     </itemizedlist>
 135
 136     <para>
 137         <emphasis>ContextSwitch</emphasis> では任意のコンテキストを指定できます。
 138         つまり (もし存在するなら) サフィックスを自由に変更したり
 139         送信するレスポンスヘッダを任意のものに変更したり、
 140         任意のコールバックで初期化や後処理を行ったりができるということです。
 141     </para>
 142
 143     <sect4 id="zend.controller.actionhelpers.contextswitch.contexts">
 144         <title>デフォルトで使用できるコンテキスト</title>
 145
 146         <para>
 147             <emphasis>ContextSwitch</emphasis> ヘルパーで
 148             使用できるデフォルトのコンテキストは、json と xml のふたつです。
 149         </para>
 150
 151         <itemizedlist>
 152             <listitem>
 153                 <para>
 154                     <emphasis><acronym>JSON</acronym></emphasis>。<acronym>JSON</acronym> コンテキストは、
 155                     'Content-Type' レスポンスヘッダを '<filename>application/json</filename>' に設定し、
 156                     ビュースクリプトのサフィックスを '<filename>json.phtml</filename>' とします。
 157                 </para>
 158
 159                 <para>
 160                     しかし、デフォルトではビュースクリプトは不要です。
 161                     これは、すべてのビュー変数を単純にシリアライズして
 162                     <acronym>JSON</acronym> レスポンスを直接発行するものです。
 163                 </para>
 164
 165                 <para>
 166                     自動 <acronym>JSON</acronym> シリアライズ機能を使わないようにすることもできます。
 167                 </para>
 168
 169                 <programlisting language="php"><![CDATA[
 170 $this->_helper->contextSwitch()->setAutoJsonSerialization(false);
 171 ]]></programlisting>
 172             </listitem>
 173
 174             <listitem>
 175                 <para>
 176                     <emphasis><acronym>XML</acronym></emphasis>。<acronym>XML</acronym> コンテキストは、
 177                     'Content-Type' レスポンスヘッダを '<filename>text/xml</filename>' に設定し、
 178                     ビュースクリプトのサフィックスを '<filename>xml.phtml</filename>' とします。
 179                     このコンテキスト用に、新しいビュースクリプトを作成する必要があります。
 180                 </para>
 181             </listitem>
 182         </itemizedlist>
 183     </sect4>
 184
 185     <sect4 id="zend.controller.actionhelpers.contextswitch.custom">
 186         <title>独自のコンテキストの作成</title>
 187
 188         <para>
 189             デフォルトのコンテキストだけでは対応しきれないこともあるでしょう。
 190             たとえば結果を <acronym>YAML</acronym> で返したり、<acronym>PHP</acronym> のシリアライズ文字列で返したり、
 191             あるいは <acronym>RSS</acronym> や <acronym>ATOM</acronym> フィードで返したりといったようにです。
 192             <emphasis>ContextSwitch</emphasis> を使用すればそれも可能です。
 193         </para>
 194
 195         <para>
 196             新たなコンテキストを追加する最も簡単な方法は
 197             <methodname>addContext()</methodname> メソッドを使用することです。
 198             このメソッドの引数は 2 つで、コンテキストの名前と
 199             設定の配列を指定します。設定には、以下のうちのひとつあるいは複数を指定します。
 200         </para>
 201
 202         <itemizedlist>
 203             <listitem>
 204                 <para><emphasis>suffix</emphasis>:
 205                 ViewRenderer で登録されているデフォルトのビューサフィックスの
 206                 前に追加するサフィックス。</para>
 207             </listitem>
 208
 209             <listitem>
 210                 <para><emphasis>headers</emphasis>: ヘッダ/値
 211                     のペアの配列で、レスポンスとともに送信したいもの。</para>
 212             </listitem>
 213
 214             <listitem>
 215                 <para><emphasis>callbacks</emphasis>:
 216                 キー 'init' や 'post' を含む配列で、それぞれ
 217                 コンテキストの初期化や後処理の際に使用する
 218                 <acronym>PHP</acronym> コールバックを指定します。</para>
 219
 220                 <para>初期化コールバックは、<emphasis>ContextSwitch</emphasis> が
 221                 コンテキストを検出した場合に実行されます。
 222                 これを使用して、任意のロジックを実行できます。
 223                 たとえば <acronym>JSON</acronym> コンテキストでは、
 224                 このコールバックを使用して
 225                 自動 <acronym>JSON</acronym> シリアライズが有効な場合に ViewRenderer
 226                 を無効化しています。</para>
 227
 228                 <para>後処理はアクションの <methodname>postDispatch()</methodname>
 229                 で発生します。これを使用して、任意のロジックを実行できます。
 230                 たとえば <acronym>JSON</acronym> コンテキストでは、このコールバックを使用して
 231                 自動 <acronym>JSON</acronym> シリアライズ機能が有効か無効かを調べています。
 232                 有効な場合はビュー変数を <acronym>JSON</acronym> にシリアライズしてレスポンスに送信し、
 233                 無効な場合は ViewRenderer を再度有効にします。</para>
 234             </listitem>
 235         </itemizedlist>
 236
 237         <para>
 238             コンテキストを操作するメソッドには次のようなものがあります。
 239         </para>
 240
 241         <itemizedlist>
 242             <listitem><para>
 243                 <methodname>addContext($context, array $spec)</methodname>:
 244                 新しいコンテキストを追加する。
 245                 そのコンテキストが既に存在する場合は例外をスローします。
 246             </para></listitem>
 247
 248             <listitem><para>
 249                 <methodname>setContext($context, array $spec)</methodname>:
 250                 新しいコンテキストを追加、あるいは既存のコンテキストを上書きする。
 251                 <methodname>addContext()</methodname> と同じように指定します。
 252             </para></listitem>
 253
 254             <listitem><para>
 255                 <methodname>addContexts(array $contexts)</methodname>:
 256                 複数のコンテキストを一度に追加する。配列 <varname>$contexts</varname>
 257                 は、コンテキスト/設定 のペアの配列となります。
 258                 既に存在するコンテキストを指定した場合は例外をスローします。
 259             </para></listitem>
 260
 261             <listitem><para>
 262                 <methodname>setContexts(array $contexts)</methodname>:
 263                 新しいコンテキストを追加、あるいは既存のコンテキストを上書きする。
 264                 <methodname>addContexts()</methodname> と同じように指定します。
 265             </para></listitem>
 266
 267             <listitem><para>
 268                 <methodname>hasContext($context)</methodname>:
 269                 そのコンテキストが存在する場合に <constant>TRUE</constant>、存在しない場合に
 270                 <constant>FALSE</constant> を返します。
 271             </para></listitem>
 272
 273             <listitem><para> <methodname>getContext($context)</methodname>:
 274                     指定した名前のコンテキストを取得する。
 275                     <methodname>addContext()</methodname> で使用する設定とあわせた配列を返します。
 276             </para></listitem>
 277
 278             <listitem><para>
 279                 <methodname>getContexts()</methodname>: すべてのコンテキストを取得する。
 280                 コンテキスト/設定 のペアの配列を返します。
 281             </para></listitem>
 282
 283             <listitem><para>
 284                 <methodname>removeContext($context)</methodname>:
 285                 指定した名前のコンテキストを削除する。成功した場合に <constant>TRUE</constant>、
 286                 そのコンテキストが見つからない場合に <constant>FALSE</constant> を返します。
 287             </para></listitem>
 288
 289             <listitem><para>
 290                 <methodname>clearContexts()</methodname>: すべてのコンテキストを削除する。
 291             </para></listitem>
 292         </itemizedlist>
 293     </sect4>
 294
 295     <sect4 id="zend.controller.actionhelpers.contextswitch.actions">
 296         <title>アクションごとのコンテキストの設定</title>
 297
 298         <para>
 299             使用するコンテキストの設定には 2 通りの方法があります。
 300             コントローラ内で手動で配列を作成する方法、
 301             そして <emphasis>ContextSwitch</emphasis> のメソッドでそれを作成する方法です。
 302         </para>
 303
 304         <para>
 305             アクションとコンテキストの関連を追加するメソッドは
 306             <methodname>addActionContext()</methodname> です。
 307             このメソッドには 2 つの引数を指定します。
 308             ひとつはコンテキストを追加したいアクション、
 309             もうひとつはコンテキスト名あるいはコンテキスト名の配列です。
 310             たとえば、次のようなコントローラクラスを考えてみましょう。
 311         </para>
 312
 313         <programlisting language="php"><![CDATA[
 314 class FooController extends Zend_Controller_Action
 315 {
 316     public function listAction()
 317     {
 318     }
 319
 320     public function viewAction()
 321     {
 322     }
 323
 324     public function commentsAction()
 325     {
 326     }
 327
 328     public function updateAction()
 329     {
 330     }
 331 }
 332 ]]></programlisting>
 333
 334         <para>
 335             ここで、'list' アクションに <acronym>XML</acronym> コンテキストを、
 336             そして 'comments' アクションに <acronym>XML</acronym> コンテキストと <acronym>JSON</acronym>
 337             コンテキストを追加してみることにします。これは
 338             <methodname>init()</methodname> メソッドで行います。
 339         </para>
 340
 341         <programlisting language="php"><![CDATA[
 342 class FooController extends Zend_Controller_Action
 343 {
 344     public function init()
 345     {
 346         $this->_helper->contextSwitch()
 347              ->addActionContext('list', 'xml')
 348              ->addActionContext('comments', array('xml', 'json'))
 349              ->initContext();
 350     }
 351 }
 352 ]]></programlisting>
 353
 354         <para>
 355             あるいは、単純に配列プロパティ
 356             <varname>$contexts</varname> を設定することもできます。
 357         </para>
 358
 359         <programlisting language="php"><![CDATA[
 360 class FooController extends Zend_Controller_Action
 361 {
 362     public $contexts = array(
 363         'list'     => array('xml'),
 364         'comments' => array('xml', 'json')
 365     );
 366
 367     public function init()
 368     {
 369         $this->_helper->contextSwitch()->initContext();
 370     }
 371 }
 372 ]]></programlisting>
 373
 374         <para>
 375             このほうがオーバーヘッドが少なくなりますが、
 376             書き間違える可能性もあります。
 377         </para>
 378
 379         <para>
 380             コンテキストの関連付けを行うメソッドには次のようなものがあります。
 381         </para>
 382
 383         <itemizedlist>
 384             <listitem>
 385                 <para>
 386                     <methodname>addActionContext($action, $context)</methodname>:
 387                     ひとつあるいは複数のコンテキストを、あるアクションで使用できるようにする。
 388                     関連付けがすでに設定されている場合は、それに追記します。
 389                     <varname>$context</varname> は、単一のコンテキストか
 390                     コンテキストの配列となります。
 391                 </para>
 392
 393                 <para>
 394                     コンテキストとして <constant>TRUE</constant> を指定すると、
 395                     すべてのコンテキストをそのアクションで使用できるようにします。
 396                 </para>
 397
 398                 <para>
 399                     <varname>$context</varname> に空の値を指定すると、
 400                     そのアクションではどのコンテキストも使用できないようにします。
 401                 </para>
 402             </listitem>
 403
 404             <listitem><para>
 405                     <methodname>setActionContext($action, $context)</methodname>:
 406                     ひとつあるいは複数のコンテキストを、あるアクションで使用できるようにする。
 407                     関連付けがすでに設定されている場合は、指定したものでそれを置き換えます。
 408                     <varname>$context</varname> は、単一のコンテキストか
 409                     コンテキストの配列となります。
 410             </para></listitem>
 411
 412             <listitem><para>
 413                     <methodname>addActionContexts(array $contexts)</methodname>:
 414                     いくつかの アクション/コンテキスト のペアを一度に追加する。
 415                     <varname>$contexts</varname> は、アクション/コンテキスト
 416                     のペアの連想配列です。これは <methodname>addActionContext()</methodname>
 417                     へのプロキシとなります。つまり、既に別のペアが登録されている場合は
 418                     そこに追記します。
 419             </para></listitem>
 420
 421             <listitem><para>
 422                     <methodname>setActionContexts(array $contexts)</methodname>:
 423                     <methodname>addActionContexts()</methodname> と同様だが、既存の
 424                     アクション/コンテキスト のペアは上書きする。
 425             </para></listitem>
 426
 427             <listitem><para>
 428                     <methodname>hasActionContext($action, $context)</methodname>:
 429                     特定のアクションにそのコンテキストが存在するかどうかを調べる。
 430             </para></listitem>
 431
 432             <listitem><para>
 433                     <methodname>getActionContexts($action = null)</methodname>:
 434                     指定したアクションのすべてのコンテキスト、
 435                     あるいはすべての アクション/コンテキスト のペアを返す。
 436             </para></listitem>
 437
 438             <listitem><para>
 439                     <methodname>removeActionContext($action, $context)</methodname>:
 440                     ひとつあるいは複数のコンテキストを、指定したアクションから削除する。
 441                     <varname>$context</varname> は、単一のコンテキストか
 442                     コンテキストの配列となります。
 443             </para></listitem>
 444
 445             <listitem><para>
 446                     <methodname>clearActionContexts($action = null)</methodname>:
 447                     すべてのコンテキストを、指定したアクションから削除する。
 448                     あるいはすべてのアクションのすべてのコンテキストを削除する。
 449             </para></listitem>
 450         </itemizedlist>
 451     </sect4>
 452
 453     <sect4 id="zend.controller.actionhelpers.contextswitch.initcontext">
 454         <title>コンテキストスイッチの初期化</title>
 455
 456         <para>
 457             コンテキストスイッチを初期化するには、アクションコントローラで
 458             <methodname>initContext()</methodname> をコールする必要があります。
 459         </para>
 460
 461         <programlisting language="php"><![CDATA[
 462 class NewsController extends Zend_Controller_Action
 463 {
 464     public function init()
 465     {
 466         $this->_helper->contextSwitch()->initContext();
 467     }
 468 }
 469 ]]></programlisting>
 470
 471         <para>
 472             時には、使用するコンテキストを決めてしまいたいこともあるでしょう。
 473             たとえば、コンテキストスイッチが起動したときには
 474             <acronym>XML</acronym> コンテキストだけを使わせたいという場合などです。
 475             その場合は、そのコンテキストを
 476             <methodname>initContext()</methodname> に渡します。
 477         </para>
 478
 479         <programlisting language="php"><![CDATA[
 480 $contextSwitch->initContext('xml');
 481 ]]></programlisting>
 482     </sect4>
 483
 484     <sect4 id="zend.controller.actionhelpers.contextswitch.misc">
 485         <title>追加機能</title>
 486
 487         <para>
 488             さまざまなメソッドを使用することで、
 489             <emphasis>ContextSwitch</emphasis> ヘルパーの挙動を変更できます。
 490             たとえば次のようなメソッドが存在します。
 491         </para>
 492
 493         <itemizedlist>
 494             <listitem>
 495                 <para>
 496                     <methodname>setAutoJsonSerialization($flag)</methodname>:
 497                     デフォルトでは、<acronym>JSON</acronym> コンテキストはビュー変数をすべてシリアライズし、
 498                     <acronym>JSON</acronym> 記法にしたものをレスポンスとして返します。
 499                     レスポンスを自分で作成したい場合はこれをオフにしなければなりません。
 500                     これは、<methodname>initContext()</methodname> をコールする前に行う必要があります。
 501                 </para>
 502
 503                 <programlisting language="php"><![CDATA[
 504 $contextSwitch->setAutoJsonSerialization(false);
 505 $contextSwitch->initContext();
 506 ]]></programlisting>
 507
 508                 <para>
 509                     このフラグの値を取得するには
 510                     <methodname>getAutoJsonSerialization()</methodname> を使用します。
 511                 </para>
 512             </listitem>
 513
 514             <listitem>
 515                 <para>
 516                     <methodname>setSuffix($context, $suffix,
 517                         $prependViewRendererSuffix)</methodname>:
 518                     このメソッドは、指定したコンテキストに対して
 519                     別のサフィックスを設定します。
 520                     3 番目の引数を使用すると、
 521                     ViewRenderer のサフィックスの前に
 522                     新しいサフィックスをつけるのかどうかを指定できます。
 523                     このフラグはデフォルトで有効になっています。
 524                 </para>
 525
 526                 <para>
 527                     サフィックスに空の値を指定すると、
 528                     ViewRenderer のサフィックスのみを使用します。
 529                 </para>
 530             </listitem>
 531
 532             <listitem>
 533                 <para>
 534                     <methodname>addHeader($context, $header, $content)</methodname>:
 535                     指定したコンテキストにレスポンスヘッダを追加します。
 536                     <varname>$header</varname> はヘッダの名前で、
 537                     <varname>$content</varname> はそのヘッダに渡す値となります。
 538                 </para>
 539
 540                 <para>
 541                     各コンテキストは複数のヘッダを持つことができます。
 542                     <methodname>addHeader()</methodname> は、
 543                     そのヘッダをコンテキストのヘッダスタックに追加します。
 544                 </para>
 545
 546                 <para>
 547                     指定した <varname>$header</varname> がそのコンテキストに既に存在する場合は、
 548                     例外をスローします。
 549                 </para>
 550             </listitem>
 551
 552             <listitem>
 553                 <para>
 554                     <methodname>setHeader($context, $header, $content)</methodname>:
 555                     <methodname>setHeader()</methodname> は
 556                     <methodname>addHeader()</methodname> とほぼ同じですが、
 557                     既存のコンテキストヘッダを上書きします。
 558                 </para>
 559             </listitem>
 560
 561             <listitem>
 562                 <para>
 563                     <methodname>addHeaders($context, array $headers)</methodname>:
 564                     指定したコンテキストに一度に複数のヘッダを追加します。
 565                     <methodname>addHeader()</methodname> へのプロキシとして動作するので、
 566                     そのヘッダがすでに存在する場合は例外をスローします。
 567                     <varname>$headers</varname> は ヘッダ/コンテキスト
 568                     のペアの配列です。
 569                 </para>
 570             </listitem>
 571
 572             <listitem>
 573                 <para>
 574                     <methodname>setHeaders($context, array $headers.)</methodname>:
 575                     <methodname>addHeaders()</methodname> と似ていますが、これは
 576                     <methodname>setHeader()</methodname> へのプロキシとして動作し、
 577                     既存のヘッダは上書きします。
 578                 </para>
 579             </listitem>
 580
 581             <listitem>
 582                 <para>
 583                     <methodname>getHeader($context, $header)</methodname>:
 584                     指定したコンテキストのヘッダの値を取得します。
 585                     見つからない場合は <constant>NULL</constant> を返します。
 586                 </para>
 587             </listitem>
 588
 589             <listitem>
 590                 <para>
 591                     <methodname>removeHeader($context, $header)</methodname>:
 592                     指定したコンテキストの単一のヘッダを削除します。
 593                 </para>
 594             </listitem>
 595
 596             <listitem>
 597                 <para>
 598                     <methodname>clearHeaders($context, $header)</methodname>:
 599                     指定したコンテキストのすべてのヘッダを削除します。
 600                 </para>
 601             </listitem>
 602
 603             <listitem>
 604                 <para>
 605                     <methodname>setCallback($context, $trigger, $callback)</methodname>:
 606                     指定したコンテキストにおける指定したトリガーのコールバックを設定します。
 607                     トリガーに指定できる値は 'init' あるいは 'post'
 608                     (それぞれ、コンテキストの初期化時と postDispatch 時を表します) です。
 609                     <varname>$callback</varname> は <acronym>PHP</acronym> のコールバックとして正しい形式でなければなりません。
 610                 </para>
 611             </listitem>
 612
 613             <listitem>
 614                 <para>
 615                     <methodname>setCallbacks($context, array $callbacks)</methodname>:
 616                     指定したコンテキストに複数のコールバックを設定します。
 617                     <varname>$callbacks</varname> は トリガー/コールバック
 618                     のペアとなります。実際のところ、登録できるコールバックは
 619                     ほとんどふたつだけで、初期化用のものと後処理用のものです。
 620                 </para>
 621             </listitem>
 622
 623             <listitem>
 624                 <para>
 625                     <methodname>getCallback($context, $trigger)</methodname>:
 626                     指定したコンテキストにおける指定したトリガーのコールバックを取得します。
 627                 </para>
 628             </listitem>
 629
 630             <listitem>
 631                 <para>
 632                     <methodname>getCallbacks($context)</methodname>:
 633                     指定したコンテキストにおけるすべてのコールバックを取得します。
 634                     トリガー/コールバック のペアを返します。
 635                 </para>
 636             </listitem>
 637
 638             <listitem>
 639                 <para>
 640                     <methodname>removeCallback($context, $trigger)</methodname>:
 641                     指定したコンテキストにおける指定したトリガーのコールバックを削除します。
 642                 </para>
 643             </listitem>
 644
 645             <listitem>
 646                 <para>
 647                     <methodname>clearCallbacks($context)</methodname>:
 648                     指定したコンテキストにおけるすべてのコールバックを削除します。
 649                 </para>
 650             </listitem>
 651
 652             <listitem>
 653                 <para>
 654                     <methodname>setContextParam($name)</methodname>:
 655                     コンテキストスイッチが要求されたかどうかを調べるための
 656                     リクエストパラメータを設定します。デフォルトは
 657                     'format' ですが、このアクセサを使用することで変更できます。
 658                 </para>
 659
 660                 <para>
 661                     <methodname>getContextParam()</methodname>
 662                     で、現在の値を取得できます。
 663                 </para>
 664             </listitem>
 665
 666             <listitem>
 667                 <para>
 668                     <methodname>setAutoDisableLayout($flag)</methodname>:
 669                     デフォルトでは、コンテキストスイッチが発生したときには
 670                     レイアウト機能が無効になります。これは、
 671                     レイアウト機能は通常は普通のレスポンスの時に使用するものであって
 672                     それ以外のコンテキストでは無意味だからです。
 673                     しかし、時にはレイアウト機能を使いたいこともあるでしょう
 674                     (新しいコンテキスト用のレイアウトがある場合など)。
 675                     その場合は、<methodname>setAutoDisableLayout()</methodname>
 676                     に <constant>FALSE</constant> を渡します。これは、
 677                     <methodname>initContext()</methodname> をコールするより
 678                     <emphasis>前に</emphasis> 行わなければなりません。
 679                 </para>
 680
 681                 <para>
 682                     このフラグの現在の値を取得するには、アクセサ
 683                     <methodname>getAutoDisableLayout()</methodname> を使用します。
 684                 </para>
 685             </listitem>
 686
 687             <listitem>
 688                 <para>
 689                     <methodname>getCurrentContext()</methodname> を使うと、
 690                     現在のコンテキストを取得できます。
 691                     コンテキストスイッチが発生していない場合や
 692                     <methodname>initContext()</methodname> の起動前にコールした場合は
 693                     <constant>NULL</constant> を返します。
 694                 </para>
 695             </listitem>
 696         </itemizedlist>
 697     </sect4>
 698
 699     <sect4 id="zend.controller.actionhelpers.contextswitch.ajaxcontext">
 700         <title>AjaxContext の機能</title>
 701
 702         <para>
 703             <emphasis>AjaxContext</emphasis> ヘルパーは
 704             <emphasis>ContextSwitch</emphasis> を継承したものです。
 705             <emphasis>ContextSwitch</emphasis> の機能はすべて使用できます。
 706             しかし、いくつか重要な違いがあります。
 707         </para>
 708
 709         <para>
 710             まず、コンテキストを決めるアクションコントローラのプロパティは
 711             <varname>$ajaxable</varname> となります。これにより、
 712             <acronym>AJAX</acronym> 用と通常の <acronym>HTTP</acronym> リクエスト用で別のコンテキストを使用できるようになります。
 713             <emphasis>AjaxContext</emphasis> の *<emphasis>ActionContext()</emphasis>*
 714             系のメソッドは、このプロパティに書き込みます。
 715         </para>
 716
 717         <para>
 718             次に、これは XmlHttpRequest が発生した場合にのみ起動します。
 719             リクエストオブジェクトの <methodname>isXmlHttpRequest()</methodname>
 720             メソッドで判断します。したがって、たとえコンテキストパラメータ
 721             ('format') をリクエストで渡したとしても、そのリクエストが
 722             XmlHttpRequest でない場合はコンテキストスイッチが発生しません。
 723         </para>
 724
 725         <para>
 726             3 番目に、<emphasis>AjaxContext</emphasis> は <acronym>HTML</acronym> コンテキストを追加します。
 727             このコンテキストでは、サフィックスを '<filename>ajax.phtml</filename>'
 728             として通常のリクエストのコンテキストと区別しています。
 729             追加のヘッダは返しません。
 730         </para>
 731
 732         <example id="zend.controller.actionhelpers.contextswitch.ajaxcontext.example">
 733             <title>Ajax リクエストに対してアクションに応答させる</title>
 734
 735             <para>
 736                 この例では、アクション 'view'、'form' および 'process'
 737                 に対する <acronym>AJAX</acronym> リクエストにレスポンスを返させるようにしています。
 738                 最初のふたつ 'view' および 'form' では、<acronym>HTML</acronym>
 739                 コード片を返してページを更新させます。最後の 'process'
 740                 については <acronym>JSON</acronym> を返しています。
 741             </para>
 742
 743             <programlisting language="php"><![CDATA[
 744 class CommentController extends Zend_Controller_Action
 745 {
 746     public function init()
 747     {
 748         $ajaxContext = $this->_helper->getHelper('AjaxContext');
 749         $ajaxContext->addActionContext('view', 'html')
 750                     ->addActionContext('form', 'html')
 751                     ->addActionContext('process', 'json')
 752                     ->initContext();
 753     }
 754
 755     public function viewAction()
 756     {
 757         // 単一のコメントを表示します
 758         // AjaxContext の場合は comment/view.ajax.phtml
 759         // を使用します
 760     }
 761
 762     public function formAction()
 763     {
 764         // 新規コメントの追加フォームをレンダリングします
 765         // AjaxContext の場合は comment/form.ajax.phtml
 766         // を使用します
 767     }
 768
 769     public function processAction()
 770     {
 771         // 新規コメントを処理します
 772         // 結果を JSON で返します。結果をビュー変数に格納するだけで、
 773         // JSON でそれを返してくれます
 774     }
 775 }
 776 ]]></programlisting>
 777
 778             <para>
 779                 クライアント側では、<acronym>AJAX</acronym> ライブラリからエンドポイント
 780                 '<filename>/comment/view</filename>'、'<filename>/comment/form</filename>' そして
 781                 '<filename>/comment/process</filename>' へリクエストを送ることになります。
 782                 その際に、'format' パラメータを
 783                 '<filename>/comment/view/format/html</filename>'、'<filename>/comment/form/format/html</filename>' そして
 784                 '<filename>/comment/process/format/json</filename>' のように指定します
 785                 (あるいはクエリ文字列で "?format=json" のようにしてもかまいません)。
 786             </para>
 787
 788             <para>
 789                 ライブラリ側で 'X-Requested-With:
 790                 XmlHttpRequest' ヘッダが設定されていれば、
 791                 このアクションは適切な形式でレスポンスを返します。
 792             </para>
 793         </example>
 794     </sect4>
 795 </sect3>
 796 <!--
 797 vim:se ts=4 sw=4 et:
 798 -->